From 272b2b5819df8b8d1bf60baad91b1209f398800f Mon Sep 17 00:00:00 2001
From: Alex Ezell <alex@fly.io>
Date: Fri, 10 Jul 2026 10:17:37 -0500
Subject: [PATCH 1/2] Add PyPI publishing for the Python package

Pushing a vX.Y.Z tag now builds and publishes the client_signals Python
package to PyPI via trusted publishing (OIDC, no tokens). Builds from the
python/ subdirectory, stamps the tag version into pyproject.toml (which
ships a 0.0.0 placeholder), and runs the unittest suite as a gate.
Final-release tags only; prerelease tags are excluded (non-PEP 440 format).
---
 .github/workflows/publish-python.yml | 48 ++++++++++++++++++++++++++++
 README.md                            | 11 +++++--
 2 files changed, 57 insertions(+), 2 deletions(-)
 create mode 100644 .github/workflows/publish-python.yml

diff --git a/.github/workflows/publish-python.yml b/.github/workflows/publish-python.yml
new file mode 100644
index 0000000..a88a4d4
--- /dev/null
+++ b/.github/workflows/publish-python.yml
@@ -0,0 +1,48 @@
+name: Publish Python to PyPI
+
+on:
+  push:
+    tags:
+      # Final releases only. Prerelease tags (vX.Y.Z-pre-N) use a format PyPI
+      # rejects under PEP 440, so they are intentionally not published here.
+      - 'v[0-9]+.[0-9]+.[0-9]+'
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    name: Build and publish client-signals to PyPI
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write   # OIDC for PyPI trusted publishing (no API tokens)
+    defaults:
+      run:
+        working-directory: python
+    steps:
+      - uses: actions/checkout@v7.0.0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Stamp version from tag
+        run: |
+          # Strip the leading 'v'; python/pyproject.toml ships a 0.0.0 placeholder.
+          VERSION="${GITHUB_REF_NAME#v}"
+          echo "Publishing client-signals ${VERSION}"
+          sed -i "s/^version = \".*\"/version = \"${VERSION}\"/" pyproject.toml
+
+      - name: Install build tooling and run tests
+        run: |
+          python -m pip install --upgrade pip build
+          python -m unittest
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: python/dist/
diff --git a/README.md b/README.md
index 22ec4c1..6cc4d3e 100644
--- a/README.md
+++ b/README.md
@@ -67,5 +67,12 @@ See [docs/signals.md](docs/signals.md) for signal rationale and
 
 ## Releases
 
-The existing tag workflow creates a GitHub release. npm, PyPI, and Hex
-publishing are not automated yet.
+Pushing a `vX.Y.Z` tag creates a GitHub release and publishes the Python
+package to PyPI (`.github/workflows/publish-python.yml`, via PyPI trusted
+publishing — no API tokens). The workflow stamps the tag's version into
+`python/pyproject.toml` at build time. npm and Hex publishing are not
+automated yet.
+
+Publishing requires a one-time [PyPI trusted publisher](https://docs.pypi.org/trusted-publishers/)
+for the `client-signals` project pointing at `superfly/client-signals` and
+workflow `publish-python.yml`.

From 6339f79d7e42fd5ab8a122e2de1066584f2ebea5 Mon Sep 17 00:00:00 2001
From: Alex Ezell <alex@fly.io>
Date: Fri, 10 Jul 2026 11:00:42 -0500
Subject: [PATCH 2/2] Drop trusted-publisher setup note from README

---
 README.md | 4 ----
 1 file changed, 4 deletions(-)

diff --git a/README.md b/README.md
index 6cc4d3e..a0a92df 100644
--- a/README.md
+++ b/README.md
@@ -72,7 +72,3 @@ package to PyPI (`.github/workflows/publish-python.yml`, via PyPI trusted
 publishing — no API tokens). The workflow stamps the tag's version into
 `python/pyproject.toml` at build time. npm and Hex publishing are not
 automated yet.
-
-Publishing requires a one-time [PyPI trusted publisher](https://docs.pypi.org/trusted-publishers/)
-for the `client-signals` project pointing at `superfly/client-signals` and
-workflow `publish-python.yml`.