Add publish to pypi workflow

.github/workflows/publish-pypi.yml

@@ -0,0 +1,32 @@
+name: Publish to PyPi
+
+on:
+  workflow_dispatch:
+
+jobs:
+  publish:
+    name: Build, verify, & upload package to PyPi
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+      - name: Prepare common Python build environment
+        uses: ./.github/actions/python-build-env-setup
+        with:
+          python-version: "3.13"
+
+      - name: Pip cache
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/pip
+          key: ${{ runner.os }}-pip
+          restore-keys: |
+            ${{ runner.os }}-pip
+
+      - name: Build, verify, and upload to PyPI
+        run: |
+          pip install --upgrade nox
+          nox -s build publish_pypi
+        env:
+          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}

noxfile.py

@@ -1,7 +1,10 @@
+from pathlib import Path
 import nox
+import shutil
 
 nox.options.stop_on_first_error = True
 nox.options.reuse_existing_virtualenvs = False
+BUILD_DIRS = ["build", "dist"]
 
 # Default sessions - all tests, but not packaging
 nox.options.sessions = [
@@ -31,3 +34,74 @@ def lint(session):
         "uv", "tool", "run", "black", "--verbose", "--check", "--diff", "--color", "."
     )
     session.run("uv", "tool", "run", "ruff", "--verbose", "check", ".")
+
+
+@nox.session
+def watch(session):
+    """Build and serve live docs for editing"""
+    session.install("-e", ".[docs]")
+
+    session.run("mkdocs", "serve")
+
+
+@nox.session
+def examples(session):
+    session.install("-e", ".[test]")
+
+    options = session.posargs
+
+    # Because these example scripts can be long-running, output the
+    # example's stdout so we know what's happening
+    session.run("pytest", "--no-cov", "examples/", "-s", *options)
+
+
+@nox.session
+def build(session):
+    """Build package"""
+    # check preexisting
+    exist_but_should_not = [p for p in BUILD_DIRS if Path(p).is_dir()]
+    if exist_but_should_not:
+        session.error(
+            f"Pre-existing {', '.join(exist_but_should_not)}. "
+            "Run clean session and try again"
+        )
+
+    session.install("build", "twine", "check-wheel-contents")
+
+    session.run(*"python -m build --sdist --wheel".split())
+    session.run("check-wheel-contents", "dist")
+
+
+@nox.session
+def clean(session):
+    """Remove build directories"""
+    to_remove = [Path(d) for d in BUILD_DIRS if Path(d).is_dir()]
+    for p in to_remove:
+        shutil.rmtree(p)
+
+
+@nox.session
+def publish_testpypi(session):
+    """Publish to TestPyPi using API token"""
+    _publish(session, "testpypi")
+
+
+@nox.session
+def publish_pypi(session):
+    """Publish to PyPi using API token"""
+    _publish(session, "pypi")
+
+
+def _publish(session, repository):
+    missing = [p for p in BUILD_DIRS if not Path(p).is_dir()]
+    if missing:
+        session.error(
+            f"Missing one or more build directories: {', '.join(missing)}. "
+            "Run build session and try again"
+        )
+
+    session.install("twine")
+
+    files = [str(f) for f in Path("dist").iterdir()]
+    session.run("twine", "check", *files)
+    session.run("twine", "upload", f"--repository={repository}", "-u=__token__", *files)