Python tool for aircraft Doppler audio geolocation using historical ADS-B flight data (Source-available)
Python acoustic-geolocationads-baircraft-trackingairplaneaudio-forensicsdoppler-effectdoppler-shiftgeolocationosintsignal-processing
Set up PyPI distribution and trusted publishing (#394)
Cinna Davis32d74c84afab
diff --git a/.github/workflows/python-package.yml b/.github/workflows/python-package.ymlnew file mode 100644index 0000000..aa467ad--- /dev/null+++ b/.github/workflows/python-package.yml@@ -0,0 +1,208 @@+name: Python distribution and PyPI++on:+ push:+ branches: [main]+ paths:+ - pyproject.toml+ - setup.py+ - MANIFEST.in+ - README.md+ - src/**+ - docs/PYPI.md+ - .github/workflows/python-package.yml+ pull_request:+ paths:+ - pyproject.toml+ - setup.py+ - MANIFEST.in+ - README.md+ - src/**+ - docs/PYPI.md+ - .github/workflows/python-package.yml+ workflow_dispatch:+ release:+ types: [published]++permissions:+ contents: read++concurrency:+ group: python-package-${{ github.ref }}+ cancel-in-progress: ${{ github.event_name == 'pull_request' }}++jobs:+ package-smoke:+ name: Build and install the source distribution+ runs-on: ubuntu-24.04+ timeout-minutes: 20+ steps:+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1+ with:+ persist-credentials: false+ fetch-depth: 0+ - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0+ with:+ python-version: "3.12"+ - name: Require release commit to be on main+ if: github.event_name == 'release'+ run: |+ git merge-base --is-ancestor "$GITHUB_SHA" origin/main ||+ { echo "Release commit is not on main"; exit 1; }+ - name: Require release tag to match the package version+ if: github.event_name == 'release'+ env:+ RELEASE_TAG: ${{ github.event.release.tag_name }}+ run: |+ python - <<'PY'+ import os+ from pathlib import Path+ import tomllib++ project = tomllib.loads(Path("pyproject.toml").read_text())["project"]+ expected = f"v{project['version']}"+ assert os.environ["RELEASE_TAG"] == expected, (+ f"Release tag must be {expected}; got {os.environ['RELEASE_TAG']}"+ )+ PY+ - name: Build distributions and check PyPI metadata+ run: |+ python -m pip install --upgrade build twine+ python -m build+ python -m twine check --strict dist/*+ - name: Verify wheel contents+ run: |+ python - <<'PY'+ from pathlib import Path+ from zipfile import ZipFile++ wheel, = Path("dist").glob("*.whl")+ with ZipFile(wheel) as archive:+ names = archive.namelist()+ metadata_name = next(name for name in names if name.endswith(".dist-info/METADATA"))+ metadata = archive.read(metadata_name).decode()+ assert "License-Expression: PolyForm-Noncommercial-1.0.0" in metadata+ assert "Description-Content-Type: text/markdown" in metadata+ for filename in ("index.html", "app.js", "style.css", "leaflet.js", "leaflet.css", "leaflet-license.txt"):+ assert f"dopplergeist/web/{filename}" in names, filename+ for prefix in ("licenses/LICENSE", "licenses/licenses/MIT-legacy.txt"):+ assert any(name.endswith("/" + prefix) for name in names), prefix+ for module in ("ridge", "acoustic", "cpa", "index"):+ assert any(f"dopplergeist/_native_{module}." in name and name.endswith(".so") for name in names), module+ PY+ - name: Install built wheel and verify the CLI+ run: |+ python -m pip install dist/*.whl+ python -m pip check+ dopplergeist --version+ dopplergeist --help+ python -I - <<'PY'+ from importlib import metadata, resources+ from dopplergeist import _native_acoustic, _native_cpa, _native_index, _native_ridge+ assert metadata.version("dopplergeist")+ web = resources.files("dopplergeist.web")+ for name in ("index.html", "app.js", "style.css", "leaflet.js", "leaflet.css", "leaflet-license.txt"):+ assert web.joinpath(name).read_bytes(), name+ PY++ sdist:+ if: github.event_name == 'release' || github.event_name == 'workflow_dispatch'+ needs: package-smoke+ runs-on: ubuntu-24.04+ steps:+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1+ with:+ persist-credentials: false+ - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0+ with:+ python-version: "3.12"+ - run: |+ python -m pip install --upgrade build twine+ python -m build --sdist+ python -m twine check --strict dist/*+ - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7+ with:+ name: pypi-sdist+ path: dist/*.tar.gz+ if-no-files-found: error+ retention-days: 7++ wheels:+ if: github.event_name == 'release' || github.event_name == 'workflow_dispatch'+ needs: package-smoke+ name: Wheels / ${{ matrix.platform }}+ runs-on: ${{ matrix.runner }}+ timeout-minutes: 60+ strategy:+ fail-fast: false+ matrix:+ include:+ - platform: linux-x86_64+ runner: ubuntu-24.04+ arch: x86_64+ - platform: linux-aarch64+ runner: ubuntu-24.04-arm+ arch: aarch64+ - platform: macos-x86_64+ runner: macos-15-intel+ arch: x86_64+ - platform: macos-arm64+ runner: macos-15+ arch: arm64+ - platform: windows-amd64+ runner: windows-2025+ arch: AMD64+ steps:+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1+ with:+ persist-credentials: false+ - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0+ with:+ python-version: "3.12"+ - name: Build and smoke-test binary wheels+ env:+ CIBW_ARCHS: ${{ matrix.arch }}+ run: |+ python -m pip install "cibuildwheel==3.4.1"+ python -m cibuildwheel --output-dir wheelhouse+ - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7+ with:+ name: pypi-wheels-${{ matrix.platform }}+ path: wheelhouse/*.whl+ if-no-files-found: error+ retention-days: 7++ publish:+ if: github.event_name == 'release' && github.repository == '1337isnot1337/DOPPLERGEIST'+ needs: [package-smoke, sdist, wheels]+ runs-on: ubuntu-24.04+ environment: pypi+ permissions:+ id-token: write+ steps:+ - name: Download verified release files+ uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8+ with:+ pattern: pypi-*+ path: dist/+ merge-multiple: true+ - name: Check distribution set before uploading+ env:+ RELEASE_TAG: ${{ github.event.release.tag_name }}+ run: |+ python - <<'PY'+ import os+ from pathlib import Path++ version = os.environ["RELEASE_TAG"].removeprefix("v")+ files = list(Path("dist").iterdir())+ wheels = [f for f in files if f.suffix == ".whl"]+ sdists = [f for f in files if f.name.endswith(".tar.gz")]+ assert len(wheels) == 20, f"Expected 20 platform/version wheels; found {len(wheels)}"+ assert len(sdists) == 1, f"Expected one source archive; found {len(sdists)}"+ assert all(f.name.startswith(f"dopplergeist-{version}-") for f in wheels), wheels+ assert sdists[0].name == f"dopplergeist-{version}.tar.gz", sdists+ print(f"Validated {len(wheels)} wheels and one sdist for {version}")+ PY+ - name: Publish to PyPI using GitHub OIDC+ uses: pypa/gh-action-pypi-publish@release/v1diff --git a/README.md b/README.mdindex 95e6f88..dd11289 100644--- a/README.md+++ b/README.md@@ -38,6 +38,17 @@ The integrated application and command-line workflow are available on `main`. Se## Quickstart+**PyPI distribution:** Once the first PyPI release is published, install the CLI without cloning the repository:++```bash+pipx install dopplergeist+dopplergeist --help+```++To use the Python package in an existing environment instead, run `python -m pip install dopplergeist`. Install **FFmpeg** separately; `ffmpeg` and `ffprobe` must be available on `PATH`. See [PyPI release status and setup](docs/PYPI.md). The examples below use `.venv/bin/dopplergeist`; users of the `pipx` installation can run `dopplergeist` directly.++**Source checkout (available now):**+Requirements: **Python 3.11+**, **FFmpeg** (`ffmpeg` and `ffprobe` on `PATH`), and Git. These commands target Linux and macOS:```bashdiff --git a/docs/PYPI.md b/docs/PYPI.mdnew file mode 100644index 0000000..e870114--- /dev/null+++ b/docs/PYPI.md@@ -0,0 +1,32 @@+# PyPI publication++The PyPI distribution name is `dopplergeist`. The Python package and console command are also named `dopplergeist`. The current distribution version is in `pyproject.toml`; the first planned PyPI release is **0.1.1** (Git tag `v0.1.1`). The existing `v0.1.0` GitHub release predates the PyPI workflow and does not trigger it retroactively.++## One-time setup++1. Sign in to [PyPI account publishing](https://pypi.org/manage/account/publishing/). Create a **pending GitHub trusted publisher** with these exact fields:+ - PyPI project: `dopplergeist`+ - GitHub owner: `1337isnot1337`+ - Repository: `DOPPLERGEIST`+ - Workflow filename: `python-package.yml`+ - GitHub environment: `pypi`+2. In the GitHub repository, open **Settings → Environments**. Create an environment named `pypi`. Restrict deployment to release tags (for example `v*`) and consider required reviewers. Only the publication job uses this environment or requests OIDC credentials.+3. From **Actions → Python distribution and PyPI → Run workflow** on `main`, verify that the smoke build, one source archive, and five-platform binary-wheel matrix all pass. Manual runs **do not upload to PyPI**.++PyPI pending publishers do not reserve the project name. The first successful upload creates the project. No API token or long-lived secret is required.++## Release++1. Land the intended code, tests, and version bump on `main`; update `pyproject.toml` to a version not previously uploaded to PyPI. This project's release workflow accepts only a GitHub release tag of the form `v<project.version>`.+2. In [GitHub Releases](https://github.com/1337isnot1337/DOPPLERGEIST/releases), create and publish a release tagged exactly `v0.1.1` (for the initial PyPI release). Point it to the tested commit. Do not republish or move an existing version tag.+3. The `Python distribution and PyPI` workflow runs the package smoke check, builds 20 platform-specific wheels (CPython 3.11–3.14 on Linux x86_64/aarch64, macOS x86_64/arm64 and Windows amd64), and builds one source archive. It validates names/version and publishes with `pypa/gh-action-pypi-publish` using GitHub OIDC only if all required jobs pass.+4. Verify the published distribution at [PyPI](https://pypi.org/project/dopplergeist/). In a fresh environment install with `pipx install dopplergeist` or `python -m pip install dopplergeist` and run `dopplergeist --help`.++Releases are immutable on PyPI: if an artifact was already uploaded, do not attempt to overwrite it. Bump the version and create a new tag instead. If publication failed *before* any files were uploaded, fix the cause and rerun the failed workflow; no new version is required.++## Packaging notes++- `ffmpeg` and `ffprobe` are executable system dependencies, not supplied by the PyPI wheel.+- Optional native C accelerators are built as platform/CPython-specific wheels. The source archive supports building from source where a compatible toolchain and required dependencies are available.+- The bundled web application assets and PolyForm Noncommercial/MIT-legacy notices must be included in the distributions.+- PyPI does not grant any additional rights to commercial use. See [commercial licensing](../COMMERCIAL-LICENSING.md).diff --git a/docs/PYPI_README.md b/docs/PYPI_README.mdnew file mode 100644index 0000000..623f19b--- /dev/null+++ b/docs/PYPI_README.md@@ -0,0 +1,64 @@+# DOPPLERGEIST++++**DOPPLERGEIST** is a Python CLI and local web application for aircraft Doppler audio geolocation. It detects candidate flyover signals in recordings, retrieves historical ADS-B flight tracks, models acoustic propagation, and ranks possible recording locations.++++The illustrated real-recording experiment ranked a location 476 m from an *inferred* reference within a constrained search. The reference was not surveyed ground truth; independent blind geolocation accuracy has not been established. [Read the experiment](https://github.com/1337isnot1337/DOPPLERGEIST/blob/main/docs/LIVERMORE_DEMO.md).++## Install++Requires **Python 3.11+**. Install **FFmpeg** separately so that both `ffmpeg` and `ffprobe` are on your `PATH`.++For the CLI:++```sh+pipx install dopplergeist+dopplergeist --help+```++For a Python environment:++```sh+python -m pip install dopplergeist+```++## Use++Detect candidate acoustic events without flight-data downloads:++```sh+dopplergeist discover recording.mp3 --output results/discovery+```++Launch the locally hosted upload interface:++```sh+dopplergeist serve --jobs jobs --online --port 8765+```++Open `http://127.0.0.1:8765`. For historical flight matching, a **defensible UTC window for the first audio sample** is required; the recording upload timestamp is not sufficient. Geographic searches can consume substantial time, storage, and downloaded aircraft/terrain data.++For CLI analysis with an independently supported recording clock:++```sh+dopplergeist analyze recording.mp3 --jobs jobs \+ --start-utc "2026-01-01T00:00:00Z" \+ --end-utc "2026-01-01T00:10:00Z" \+ --time-source "replace with independently supported clock evidence" \+ --online+```++## Documentation++- [Source code and full README](https://github.com/1337isnot1337/DOPPLERGEIST)+- [Installation and reproducibility](https://github.com/1337isnot1337/DOPPLERGEIST/blob/main/docs/SETUP.md)+- [How the geolocation pipeline works](https://github.com/1337isnot1337/DOPPLERGEIST/blob/main/docs/METHODOLOGY.md)+- [Validation and limitations](https://github.com/1337isnot1337/DOPPLERGEIST/blob/main/docs/CONFIDENCE.md)+- [Issues and feature requests](https://github.com/1337isnot1337/DOPPLERGEIST/issues)++## License++**PolyForm Noncommercial License 1.0.0.** Noncommercial uses are permitted under the terms of that license; commercial uses that are not otherwise authorized need a separate agreement with the applicable copyright holders. Earlier MIT-licensed releases retain the permissions originally granted for those versions. [Commercial licensing details](https://github.com/1337isnot1337/DOPPLERGEIST/blob/main/COMMERCIAL-LICENSING.md).diff --git a/docs/SETUP.md b/docs/SETUP.mdindex 8f7877a..b384cde 100644--- a/docs/SETUP.md+++ b/docs/SETUP.md@@ -11,7 +11,17 @@## Install the CLI without a checkout-For normal use, install the command into an isolated environment with `pipx`:+After the initial PyPI release has been published, the shortest supported installation is:++```bash+pipx install dopplergeist+dopplergeist --version+dopplergeist --help+```++Or install the Python distribution into an existing environment with `python -m pip install dopplergeist`. The [PyPI publication guide](PYPI.md) describes the first-release setup and status. FFmpeg and ffprobe must be installed separately.++Until that first PyPI upload, or to install the latest source commit directly, use `pipx` with the GitHub repository:```bashpipx install 'git+https://github.com/1337isnot1337/DOPPLERGEIST.git'diff --git a/pyproject.toml b/pyproject.tomlindex af88d87..dde0792 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -4,13 +4,35 @@ build-backend = "setuptools.build_meta"[project]name = "dopplergeist"-version = "0.1.0"-description = "Reproducible physics-based aircraft acoustic geolocation"+version = "0.1.1"+description = "Aircraft Doppler audio geolocation using historical flight tracks"+readme = "docs/PYPI_README.md"+keywords = ["aircraft", "doppler", "acoustic-geolocation", "audio-forensics", "ads-b", "signal-processing"]+classifiers = [+ "Development Status :: 4 - Beta",+ "Environment :: Console",+ "Intended Audience :: Science/Research",+ "Programming Language :: Python :: 3",+ "Programming Language :: Python :: 3.11",+ "Programming Language :: Python :: 3.12",+ "Programming Language :: Python :: 3.13",+ "Programming Language :: Python :: 3.14",+ "Programming Language :: Python :: Implementation :: CPython",+ "Topic :: Scientific/Engineering :: Physics",+ "Topic :: Multimedia :: Sound/Audio :: Analysis",+]license = "PolyForm-Noncommercial-1.0.0"license-files = ["LICENSE", "licenses/MIT-legacy.txt", "src/dopplergeist/web/leaflet-license.txt"]requires-python = ">=3.11"dependencies = ["numpy", "scipy", "pandas", "soundfile", "pyproj", "rasterio", "matplotlib", "requests", "pyarrow", "shapely>=2.0"]+[project.urls]+Homepage = "https://github.com/1337isnot1337/DOPPLERGEIST"+Documentation = "https://github.com/1337isnot1337/DOPPLERGEIST/tree/main/docs"+Source = "https://github.com/1337isnot1337/DOPPLERGEIST"+Issues = "https://github.com/1337isnot1337/DOPPLERGEIST/issues"+Releases = "https://github.com/1337isnot1337/DOPPLERGEIST/releases"+[project.optional-dependencies]test = ["pytest>=8"]@@ -25,3 +47,8 @@ where = ["src"][tool.pytest.ini_options]testpaths = ["tests"]++[tool.cibuildwheel]+build = "cp311-* cp312-* cp313-* cp314-*"+skip = "*-musllinux_*"+test-command = "dopplergeist --help && python -c \"from importlib.resources import files; assert files('dopplergeist.web').joinpath('index.html').is_file()\""