Publish palace-util and palace-opds to PyPI on release (PP-4076) (#3238)

## Description

Two things:

1. **Dynamic versioning** for both workspace packages. Each package's
`pyproject.toml` now declares `dynamic = ["version"]` and sources the
version from a committed `_version.py` stub via hatchling's built-in
`regex` version source. The stub carries a dev placeholder
(`0.0.0.dev0`, `__commit__ = None`) so `uv build --package …` works
out-of-box for local and CI builds without an explicit version override.
The release workflow overwrites `_version.py` with real dunamai-computed
values right before `uv build`, so the wheel metadata picks up the real
version.

2. **`publish-pypi.yml` workflow** triggered by published GitHub
Releases. Matrix-builds both packages in parallel, uses PyPI's [Trusted
Publishing (OIDC)](https://docs.pypi.org/trusted-publishers/) flow. The
workflow also pins the intra-workspace dep, so `palace-opds` always
depends on the most recent palace-util.

## Motivation and Context

With `palace-util` and `palace-opds` extracted as standalone packages,
they should be installable from PyPI so downstream Palace services (and
the wider OPDS-consuming community for `palace-opds`) can depend on them
without pulling in the `palace-manager` monorepo. `palace-manager`
itself is intentionally NOT published here — it needs additional work
first (alembic and friends prevent a clean wheel build).

## One-time PyPI setup

~~I need to setup trusted publishing in pypi before we cut a release
with this. This is a work in progress. 🚧~~
This setup is complete now.

## How Has This Been Tested?

I set this up in my own fork, and published test packages to
test.pypi.org. Using the same workflow they published correctly for me:
- https://github.com/jonathangreen/circulation/actions/runs/24460001637
- https://test.pypi.org/project/palace-opds/
- https://test.pypi.org/project/palace-util/

## Checklist

- [x] I have updated the documentation accordingly.
- [x] All new and existing tests passed.

Author: jonathangreen

.github/workflows/publish-pypi.yml

@@ -0,0 +1,83 @@
+name: Publish to PyPI
+
+# Publishes `palace-util` and `palace-opds` when a GitHub Release is
+# published. Each package is built and uploaded independently via PyPI's
+# Trusted Publishing (OIDC) flow. https://docs.pypi.org/trusted-publishers/
+#
+# No action is needed on new releases beyond publishing a GitHub Release with
+# a tag that dunamai can parse as semver (e.g. `v1.0.0` or `1.0.0`).
+
+on:
+  release:
+    types: [published]
+
+env:
+  PYTHON_VERSION: "3.12"
+
+jobs:
+  publish:
+    name: Publish ${{ matrix.package }} to PyPI
+    runs-on: ubuntu-24.04
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - package: palace-util
+            source_dir: packages/palace-util/src/palace/util
+          - package: palace-opds
+            source_dir: packages/palace-opds/src/palace/opds
+    permissions:
+      # Required for PyPI Trusted Publishing (OIDC).
+      id-token: write
+      contents: read
+
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+          # dunamai needs the full tag history.
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.0.0
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+          python-version: ${{ env.PYTHON_VERSION }}
+          activate-environment: true
+
+      - name: Install Dunamai
+        run: uv sync --frozen --only-group ci
+
+      - name: Compute version metadata
+        id: version
+        run: |
+          echo "version=$(dunamai from git --style semver)" >> "$GITHUB_OUTPUT"
+          echo "commit=$(dunamai from git --format '{commit}' --full-commit)" >> "$GITHUB_OUTPUT"
+
+      - name: Write _version.py
+        # hatch reads __version__ from this file via [tool.hatch.version]
+        # regex source; overwriting it here is how the release version lands
+        # in the wheel metadata.
+        run: |
+          cat > ${{ matrix.source_dir }}/_version.py <<EOF
+          __version__ = "${{ steps.version.outputs.version }}"
+          __commit__: str | None = "${{ steps.version.outputs.commit }}"
+          EOF
+
+      - name: Pin intra-workspace dependency
+        # uv build preserves workspace deps as bare names in Requires-Dist
+        # (e.g. `palace-util` with no version). For PyPI we need an exact pin
+        # so a consumer installing palace-opds resolves the matching
+        # palace-util version.
+        if: matrix.package == 'palace-opds'
+        run: uv add --package palace-opds "palace-util==${{ steps.version.outputs.version }}"
+
+      - name: Build ${{ matrix.package }}
+        run: uv build --package ${{ matrix.package }}
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist
+          print-hash: true

packages/palace-opds/pyproject.toml

@@ -11,11 +11,11 @@ dependencies = [
     "uritemplate==4.2.0",
 ]
 description = "Pydantic models for OPDS 2.0, RWPM, ODL, LCP, and Palace Project extensions."
+dynamic = ["version"]
 license = "Apache-2.0"
 name = "palace-opds"
 readme = "README.md"
 requires-python = ">=3.12,<4"
-version = "0"
 
 [project.urls]
 Homepage = "https://thepalaceproject.org"
@@ -24,6 +24,9 @@ Repository = "https://github.com/ThePalaceProject/circulation"
 [tool.hatch.build.targets.wheel]
 packages = ["src/palace"]
 
+[tool.hatch.version]
+path = "src/palace/opds/_version.py"
+
 [tool.isort]
 combine_as_imports = true
 known_first_party = ["palace.opds"]

packages/palace-opds/src/palace/opds/__init__.py

@@ -0,0 +1,3 @@
+from palace.opds._version import __commit__, __version__
+
+__all__ = ["__commit__", "__version__"]

packages/palace-opds/src/palace/opds/_version.py

@@ -0,0 +1,6 @@
+# WARNING!
+# This file is dynamically generated during the CI build process.
+# Any changes made here will be overwritten. Do not edit this file manually.
+
+__version__ = "0.0.0.dev0"
+__commit__: str | None = None

packages/palace-util/pyproject.toml

@@ -8,11 +8,11 @@ dependencies = [
     "python-dateutil>=2.8,<3",
 ]
 description = "Shared utilities for Palace Project packages."
+dynamic = ["version"]
 license = "Apache-2.0"
 name = "palace-util"
 readme = "README.md"
 requires-python = ">=3.12,<4"
-version = "0"
 
 [project.urls]
 Homepage = "https://thepalaceproject.org"
@@ -21,6 +21,9 @@ Repository = "https://github.com/ThePalaceProject/circulation"
 [tool.hatch.build.targets.wheel]
 packages = ["src/palace"]
 
+[tool.hatch.version]
+path = "src/palace/util/_version.py"
+
 [tool.isort]
 combine_as_imports = true
 known_first_party = ["palace.util"]

packages/palace-util/src/palace/util/__init__.py

@@ -0,0 +1,3 @@
+from palace.util._version import __commit__, __version__
+
+__all__ = ["__commit__", "__version__"]

packages/palace-util/src/palace/util/_version.py

@@ -0,0 +1,6 @@
+# WARNING!
+# This file is dynamically generated during the CI build process.
+# Any changes made here will be overwritten. Do not edit this file manually.
+
+__version__ = "0.0.0.dev0"
+__commit__: str | None = None