Skip to content

Python tool for aircraft Doppler audio geolocation using historical ADS-B flight data (Source-available)

Set up PyPI distribution and trusted publishing (#394)

Cinna Davis32d74c84afab
diff --git a/.github/workflows/python-package.yml b/.github/workflows/python-package.yml
new file mode 100644
index 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/v1
diff --git a/README.md b/README.md
index 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:
```bash
diff --git a/docs/PYPI.md b/docs/PYPI.md
new file mode 100644
index 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.md
new file mode 100644
index 0000000..623f19b
--- /dev/null
+++ b/docs/PYPI_README.md
@@ -0,0 +1,64 @@
+# DOPPLERGEIST
+
+![DOPPLERGEIST — aircraft Doppler audio geolocation](https://raw.githubusercontent.com/1337isnot1337/DOPPLERGEIST/main/assets/dopplergeist-banner.svg)
+
+**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.
+
+![Automatic MP3 flyover analysis and ranked aircraft search](https://raw.githubusercontent.com/1337isnot1337/DOPPLERGEIST/main/assets/livermore-automatic-mp3.png)
+
+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.md
index 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:
```bash
pipx install 'git+https://github.com/1337isnot1337/DOPPLERGEIST.git'
diff --git a/pyproject.toml b/pyproject.toml
index 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()\""