feat: Add publish pypi (#9)

Author: AndyRae

.github/workflows/publish-pypi.yml

@@ -0,0 +1,94 @@
+name: Upload Python Package
+
+on:
+  workflow_call:
+    inputs:
+      python-version:
+        description: 'Python version to build with'
+        required: false
+        default: '3.x'
+        type: string
+      package-name:
+        description: 'PyPI package name, used to construct the PyPI URL (e.g. my-package)'
+        required: true
+        type: string
+      environment-name:
+        description: 'GitHub environment to use for the PyPI publish job'
+        required: false
+        default: 'pypi'
+        type: string
+      working-directory:
+        description: 'Working directory for the build, relative to the repo root. Useful for monorepos.'
+        required: false
+        default: '.'
+        type: string
+      use-uv:
+        description: 'Use uv to build the package instead of pip + build'
+        required: false
+        default: false
+        type: boolean
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    # Apply working-directory to all run steps in this job
+    defaults:
+      run:
+        working-directory: ${{ inputs.working-directory }}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      # When using uv, Python is managed by uv itself via the python-version input.
+      # When using pip, setup-python handles it instead.
+      - name: Set up Python
+        if: ${{ !inputs.use-uv }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ inputs.python-version }}
+
+      - name: Set up uv
+        if: inputs.use-uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ inputs.python-version }}
+
+      - name: Install build dependencies
+        if: ${{ !inputs.use-uv }}
+        run: |
+          python -m pip install --upgrade pip
+          pip install build
+
+      - name: Build package
+        run: ${{ inputs.use-uv && 'uv build' || 'python -m build' }}
+
+      - name: Store the distribution packages
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          # upload-artifact paths are relative to the workspace root, not working-directory,
+          # so we need to include the working-directory prefix explicitly.
+          path: ${{ inputs.working-directory }}/dist/
+
+  publish-to-pypi:
+    name: Publish Python distribution to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: ${{ inputs.environment-name }}
+      url: https://pypi.org/p/${{ inputs.package-name }}
+    permissions:
+      id-token: write # required for OIDC-based PyPI publishing (no API token needed)
+
+    steps:
+      - name: Download all the dists
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish distribution to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

docs/publish-pypi.md

@@ -0,0 +1,61 @@
+# Publish Python Package to PyPI
+
+Reusable workflow that builds a Python package and publishes it to [PyPI](https://pypi.org) using OIDC trusted publishing (no API token required).
+
+The workflow has two jobs:
+
+1. **Build** — runs `python -m build` and uploads the resulting `dist/` as a workflow artifact
+2. **Publish** — downloads the artifact and publishes to PyPI via `pypa/gh-action-pypi-publish`
+
+## Inputs
+
+| Input                | Required | Default  | Description                                                                          |
+|----------------------|----------|----------|--------------------------------------------------------------------------------------|
+| `package-name`       | Yes      | —        | PyPI package name, used to construct the PyPI URL (e.g. `my-package`).              |
+| `python-version`     | No       | `'3.x'`  | Python version to build with.                                                        |
+| `environment-name`   | No       | `'pypi'` | GitHub environment to use for the publish job.                                       |
+| `working-directory`  | No       | `'.'`    | Directory containing the package, relative to repo root. Useful for monorepos.       |
+| `use-uv`             | No       | `false`  | Use `uv build` instead of `pip + build`. Faster builds; uv manages Python itself.   |
+
+## PyPI Trusted Publishing (OIDC)
+
+This workflow uses [PyPI trusted publishing](https://docs.pypi.org/trusted-publishers/) rather than an API token. Before using this workflow you must configure a trusted publisher on PyPI for your package:
+
+- **Publisher:** GitHub Actions
+- **Repository:** your repo (e.g. `Health-Informatics-UoN/my-repo`)
+- **Workflow filename:** the caller workflow filename (e.g. `release.yml`)
+- **Environment:** matches the `environment-name` input (default: `pypi`)
+
+## Usage
+
+Typically chained after `semantic-release` so publishing only happens on a new release:
+
+```yaml
+jobs:
+  release:
+    uses: health-informatics-uon/workflows/.github/workflows/semantic-release.yml@main
+    secrets: inherit
+
+  publish-pypi:
+    needs: release
+    if: needs.release.outputs.release-created == 'true'
+    uses: health-informatics-uon/workflows/.github/workflows/publish-pypi.yml@main
+    with:
+      package-name: my-package
+```
+
+### With uv
+
+```yaml
+    with:
+      package-name: my-package
+      use-uv: true
+```
+
+### Monorepo
+
+```yaml
+    with:
+      package-name: my-package
+      working-directory: packages/my-package
+```