pointclouds 0.0.0__tar.gz

pointclouds-0.0.0/.gitattributes

@@ -0,0 +1,20 @@
+# SCM syntax highlighting & preventing 3-way merges
+# pixi.lock is machine-generated and ~10k lines. `merge=binary` stops git from
+# attempting a three-way merge on it: a conflict there is never worth resolving
+# by hand - take one side and re-run `pixi lock` against the merged manifest.
+# The linguist hints keep it out of the repo's language statistics and collapse
+# it in GitHub diffs. `text eol=lf` matters on Windows, where core.autocrlf=true
+# is the norm: without it the lock is checked out with CRLF, pixi rewrites it
+# with LF on the next `pixi lock`, and all 10 805 lines show up as a diff nobody
+# made.
+pixi.lock merge=binary text eol=lf linguist-language=YAML linguist-generated=true
+
+# Notebooks are LF-normalised JSON, which is what the nbstripout pre-commit hook
+# produces. Nothing here tracks a notebook yet - the rule is in place so the
+# first one under `docs/examples/` arrives correct rather than as a full-file
+# diff on its first Windows checkout.
+*.ipynb text eol=lf
+
+# The committed LAS/LAZ fixtures are binary: never touch their line endings.
+*.las binary
+*.laz binary

pointclouds-0.0.0/.github/ISSUE_TEMPLATE/ISSUE_TEMPLATE.md

@@ -0,0 +1,18 @@
+* pointclouds version:
+* Extras installed (`gis` / `cloud` / none):
+* laspy version:
+* pyramids-gis version (only if the `gis` extra is installed):
+* Python version:
+* Operating System:
+
+### Description
+
+Describe what you were trying to get done.
+Tell us what happened, what went wrong, and what you expected to happen.
+
+### What I Did
+
+```
+Paste the command(s) you ran and the output.
+If there was a crash, please include the traceback here.
+```

pointclouds-0.0.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,32 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+1. Go to '...'
+2. Click on '....'
+3. Scroll down to '....'
+4. See error
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Environment**
+- pointclouds version, extras installed (`gis` / `cloud` / none), Python version, OS.
+- If the file matters: format (LAS / LAZ / COPC / EPT), LAS point format and version, and roughly
+  how many points.
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem.
+
+**Additional context**
+Add any other context about the problem here.

pointclouds-0.0.0/.github/ISSUE_TEMPLATE/custom.md

@@ -0,0 +1,8 @@
+---
+name: Custom issue template
+about: Describe this issue template's purpose here.
+title: ''
+labels: ''
+assignees: ''
+
+---

pointclouds-0.0.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,25 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Which layer does it belong to?**
+`pointclouds` owns point clouds; `pyramids` owns raster and vector (ADR-0001). If the request is
+really about rasters or vectors, it belongs upstream. Note too whether it would need a new optional
+dependency - the core is GDAL-free and stays that way.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

pointclouds-0.0.0/.github/gitleaks.toml

@@ -0,0 +1,21 @@
+# Gitleaks configuration for the CI secret scan (`gitleaks dir` in
+# .github/workflows/lint.yml, which passes it as `-c .github/gitleaks.toml`). gitleaks is the repo's single secret scanner,
+# matching pyramids, pyramids-eo and pyramids-mesh. There is no local gitleaks
+# pre-commit hook here, so this file is read only by that job. It keeps
+# gitleaks' full built-in ruleset and only allowlists paths that are registries
+# or fixtures rather than source secrets.
+title = "pointclouds"
+
+[extend]
+useDefault = true
+
+[allowlist]
+description = "Non-source paths: working notes and lockfile hashes"
+paths = [
+  # Planning / review notes are working documents, not shipped code.
+  '''(^|/)planning/''',
+  # PR review artifacts written into the repo root are working documents.
+  '''pr-diff-review-.*\.md$''',
+  # The dependency lockfile is package hashes, not credentials.
+  '''pixi\.lock$''',
+]

pointclouds-0.0.0/.github/pull_request_template.md

@@ -0,0 +1,43 @@
+# Description
+
+- Please include a summary of the change and which issue is fixed.
+- Please also include relevant motivation and context.
+- List any dependencies that are required for this change.
+
+# Issues
+
+- Closes # (issue)
+
+## Type of change
+
+Check relevant points.
+
+- [ ] Bug fix (non-breaking change which fixes an issue)
+- [ ] New feature (non-breaking change which adds functionality)
+- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
+- [ ] This change requires a documentation update
+
+# How Has This Been Tested?
+
+- Please describe the tests that you ran to verify your changes.
+- Provide instructions so we can reproduce.
+- Please also list any relevant details for your test configuration
+
+- [ ] `pixi run -e dev main` (the GDAL-free core)
+- [ ] `pixi run -e full test-all` (full suite, with the `gis` / `cloud` extras)
+- [ ] `pixi run -e full notebooks` (notebooks)
+- [ ] `pixi run -e dev typecheck` and `pre-commit run --all-files`
+
+# Checklist:
+
+- [ ] I have added tests that prove my fix is effective or that my feature works.
+- [ ] New and existing unit tests pass locally with my changes.
+- [ ] Public symbols I added or changed carry Google-style docstrings.
+- [ ] The documentation is updated (reference page, guide, or notebook as applicable).
+- [ ] `docs/change-log.md` records the change.
+- [ ] The core stays GDAL-free: only `src/pointclouds/convert.py` imports `pyramids`, behind a
+      guarded in-function import naming the `[gis]` extra, and
+      `tests/test_core_has_no_gdal.py` is still green.
+- [ ] The change stays on this package's side of the boundary (ADR-0001): `pointclouds` owns point
+      clouds, `pyramids` owns raster and vector. Anything belonging upstream is reported there
+      instead of reimplemented here.

pointclouds-0.0.0/.github/workflows/github-pages-mkdocs.yml

@@ -0,0 +1,91 @@
+name: Deploy MkDocs
+
+permissions:
+  contents: write
+  pages: write
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - '**'
+  release:
+      types:
+        - published
+  workflow_run:
+    workflows: ['github-release']
+    types: [completed]
+
+jobs:
+  deploy-pr:
+      if: github.event_name == 'pull_request'
+      runs-on: ubuntu-latest
+      steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0
+        with:
+          fetch-depth: 0
+
+      # serapeum-org/github-actions is a monorepo: one commit carries the release tag
+      # for every action in it, so 38c11108 is the dereferenced commit for pixi/v1.2.1,
+      # mkdocs/v1.3.1, github-release/v1.5.0 and pypi-release/v1.0.3 alike. Several
+      # different actions pinned to one SHA reads like a copy-paste error and is not;
+      # verify with
+      #   git ls-remote --tags https://github.com/serapeum-org/github-actions
+      - uses: serapeum-org/github-actions/actions/mkdocs-deploy@38c111084f99d5ff5f4a1e63bedce48fe33a10c0 # mkdocs/v1.3.1
+        with:
+          trigger: 'pull_request'
+          package-manager: 'pixi'
+          package-manager-version: 'v0.73.0'
+          install-groups: 'docs'
+          deploy-token: ${{ secrets.ACTIONS_DEPLOY_TOKEN }}
+
+  deploy-main:
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0
+      with:
+        fetch-depth: 0
+    - uses: serapeum-org/github-actions/actions/mkdocs-deploy@38c111084f99d5ff5f4a1e63bedce48fe33a10c0 # mkdocs/v1.3.1
+      with:
+        trigger: 'main'
+        package-manager: 'pixi'
+        package-manager-version: 'v0.73.0'
+        install-groups: 'docs'
+        deploy-token: ${{ secrets.ACTIONS_DEPLOY_TOKEN }}
+
+  deploy-release:
+    # Security: when triggered via `workflow_run`, require that the upstream
+    # workflow ran from the base repository (not a fork) so we can never run
+    # untrusted code in a context that holds `ACTIONS_DEPLOY_TOKEN`.
+    if: >-
+      github.event_name == 'release' ||
+      (github.event_name == 'workflow_run'
+       && github.event.workflow_run.conclusion == 'success'
+       && github.event.workflow_run.head_repository.fork == false)
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0
+      with:
+        fetch-depth: 0
+        # Pin to the immutable SHA recorded on the originating run, not the
+        # mutable `head_branch` label (CWE-829: actions/untrusted-checkout).
+        ref: ${{ github.event.workflow_run.head_sha || github.ref }}
+
+    - name: Extract version from pyproject.toml
+      id: version
+      run: |
+        VERSION=$(grep -m1 '^version' pyproject.toml | sed 's/.*"\(.*\)"/\1/')
+        echo "tag=$VERSION" >> $GITHUB_OUTPUT
+
+    - uses: serapeum-org/github-actions/actions/mkdocs-deploy@38c111084f99d5ff5f4a1e63bedce48fe33a10c0 # mkdocs/v1.3.1
+      with:
+        trigger: 'release'
+        package-manager: 'pixi'
+        package-manager-version: 'v0.73.0'
+        install-groups: 'docs'
+        deploy-token: ${{ secrets.ACTIONS_DEPLOY_TOKEN }}
+        release-tag: ${{ github.event.release.tag_name || steps.version.outputs.tag }}
+        mike-alias: 'latest'

pointclouds-0.0.0/.github/workflows/github-release.yml

@@ -0,0 +1,97 @@
+name: github-release
+
+permissions:
+  contents: read
+
+on:
+  workflow_dispatch:
+    inputs:
+      release-branch:
+        description: "Branch to create release from"
+        required: false
+        default: "main"
+      increment:
+        description: "Version increment type"
+        required: false
+        type: choice
+        options:
+          - patch
+          - minor
+          - major
+        default: "patch"
+      prerelease_type:
+        description: "Prerelease type"
+        required: false
+        type: choice
+        options:
+          - none
+          - alpha
+          - beta
+          - rc
+        default: "none"
+      draft:
+        description: "Create as draft release"
+        required: false
+        type: boolean
+        default: false
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0
+        with:
+          fetch-depth: 0
+          ref: ${{ inputs.release-branch }}
+
+      - name: Check actor is a repository admin
+        run: |
+          PERMISSION=$(gh api repos/${{ github.repository }}/collaborators/${{ github.actor }}/permission --jq '.permission')
+          echo "Permission level for ${{ github.actor }}: $PERMISSION"
+          if [ "$PERMISSION" != "admin" ]; then
+            echo "::error::${{ github.actor }} is not a repository admin. Only admins can trigger releases."
+            exit 1
+          fi
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Create GitHub Release with Commitizen
+        # serapeum-org/github-actions is a monorepo: one commit carries the release tag
+        # for every action in it, so 38c11108 is the dereferenced commit for pixi/v1.2.1,
+        # mkdocs/v1.3.1, github-release/v1.5.0 and pypi-release/v1.0.3 alike. Several
+        # different actions pinned to one SHA reads like a copy-paste error and is not;
+        # verify with
+        #   git ls-remote --tags https://github.com/serapeum-org/github-actions
+        uses: serapeum-org/github-actions/actions/release/github@38c111084f99d5ff5f4a1e63bedce48fe33a10c0 # github-release/v1.5.0
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          increment: ${{ github.event.inputs.increment }}
+          prerelease-type: ${{ github.event.inputs.prerelease_type }}
+          draft: ${{ github.event.inputs.draft }}
+          package-manager: pixi
+          # Must match the pixi pinned in tests.yml and lint.yml: this job
+          # installs from pixi.lock, which is format v7 and unreadable to older
+          # pixi.
+          package-manager-version: v0.73.0
+          install-groups: "dev"
+
+      # There is deliberately no `pixi lock` + commit step here, unlike the uv
+      # setup this replaced. uv.lock recorded the project's own version, so a
+      # `cz bump` genuinely invalidated it; pixi.lock does not record it:
+      #
+      #   $ grep -A2 '^- pypi: \./' pixi.lock
+      #   - pypi: ./
+      #     name: pointclouds
+      #     requires_dist:            <- no `version:` field
+      #   $ sed -i 's/^version = "0.1.0"/version = "0.2.0"/' pyproject.toml
+      #   $ pixi lock --check
+      #   Lock-file was already up-to-date
+      #
+      # So a `pixi lock` after the bump can never be committing the bump. It can
+      # only commit an unrelated re-solve caused by upstream channel churn -
+      # pushed straight to the release branch, unreviewed, by a bot, moments
+      # after the tag. The lock is kept fresh by the normal PR flow instead,
+      # where every job runs with `verify-lock` and fails on drift.

pointclouds-0.0.0/.github/workflows/lint.yml

@@ -0,0 +1,106 @@
+name: Lint
+
+permissions:
+  contents: read
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  pre-commit:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
+        with:
+          python-version: "3.12"
+
+      - uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9  # v6.1.0
+        with:
+          path: ~/.cache/pre-commit
+          key: pre-commit-${{ hashFiles('.pre-commit-config.yaml') }}
+          restore-keys: pre-commit-
+
+      - run: python -m pip install pre-commit==4.5.1
+
+      # No pixi environment is set up for this job on purpose: the only hook
+      # that needs the package importable is mypy, a `language: system` hook,
+      # and it is skipped below - the `static` job runs it in the real dev
+      # environment instead. ruff, nbstripout and the pre-commit-hooks set all
+      # run in pre-commit's own isolated environments and read their config
+      # from pyproject.toml.
+      - name: Run pre-commit hooks
+        run: pre-commit run --all-files --show-diff-on-failure --color=always
+        env:
+          # no-commit-to-branch is a local commit guard that misfires in CI,
+          # which legitimately runs on main: on a push event actions/checkout
+          # creates a real local branch (`-B main`), so the hook sees `main` and
+          # exits 1. pyramids, pyramids-eo and earthlens skip it for the same
+          # reason. mypy runs in the `static` job below.
+          SKIP: mypy,no-commit-to-branch
+
+  # Type check and src doctests. Both need an importable package, so they get a
+  # real pixi environment - but neither is platform- or version-sensitive, so
+  # one runner covers them. It runs on `py314` rather than the identical `dev`
+  # environment so CI never caches that 654 MB set twice under two names.
+  static:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        # serapeum-org/github-actions is a monorepo: one commit carries the release tag
+        # for every action in it, so 38c11108 is the dereferenced commit for pixi/v1.2.1,
+        # mkdocs/v1.3.1, github-release/v1.5.0 and pypi-release/v1.0.3 alike. Several
+        # different actions pinned to one SHA reads like a copy-paste error and is not;
+        # verify with
+        #   git ls-remote --tags https://github.com/serapeum-org/github-actions
+        uses: serapeum-org/github-actions/actions/python-setup/pixi@38c111084f99d5ff5f4a1e63bedce48fe33a10c0  # pixi/v1.2.1
+        with:
+          environments: py314
+          activate-environment: py314
+          cache: true
+          # Must match the pixi pinned in tests.yml and github-release.yml:
+          # pixi.lock is lock-file format v7, which older pixi refuses to read.
+          version: v0.73.0
+
+      - name: Type check (mypy)
+        run: pixi run -e py314 typecheck
+
+      - name: Doctests (src)
+        run: pixi run -e py314 doctest
+
+  # The repo's secret gate. gitleaks is the single secret scanner (matching
+  # pyramids, pyramids-eo and pyramids-mesh). There is no local gitleaks
+  # pre-commit hook here, so this job is the only thing that runs it: it scans
+  # the whole working tree - every tracked file, notebooks included - with the
+  # .github/gitleaks.toml allowlist.
+  gitleaks:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+
+      - name: Scan for secrets (gitleaks)
+        # Pinned binary + SHA256 verification (avoids the gitleaks-action
+        # org-license requirement). `gitleaks dir` exits non-zero on a leak,
+        # which fails the job.
+        run: |
+          VER=8.30.0
+          SHA=79a3ab579b53f71efd634f3aaf7e04a0fa0cf206b7ed434638d1547a2470a66e
+          curl -sSL --proto "=https" --proto-redir "=https" -o gitleaks.tar.gz \
+            "https://github.com/gitleaks/gitleaks/releases/download/v${VER}/gitleaks_${VER}_linux_x64.tar.gz"
+          echo "${SHA}  gitleaks.tar.gz" | sha256sum -c -
+          tar -xzf gitleaks.tar.gz gitleaks
+          ./gitleaks dir . -c .github/gitleaks.toml --redact --no-banner

pointclouds-0.0.0/.github/workflows/pip-audit.yml

@@ -0,0 +1,80 @@
+name: pip-audit
+
+permissions:
+  contents: read
+
+on:
+  pull_request:
+  schedule:
+    - cron: "0 6 * * 1"
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  pip-audit:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        # Four environments, because each pixi environment is one concrete
+        # resolution and an unaudited environment is an unaudited dependency:
+        #   py311 / py314 - the two ends of the interpreter range, which resolve
+        #                   different versions of numpy, scipy and pyproj.
+        #   full          - the only environment carrying the `gis` and `cloud`
+        #                   features, so pyramids-gis, fsspec and s3fs are
+        #                   audited at all.
+        #   docs          - mkdocs-material and the mkdocstrings stack, ~80
+        #                   packages that no other environment installs.
+        # Together these cover every runtime dependency, extra and dependency
+        # group the project declares.
+        environment: [py311, py314, full, docs]
+
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        # serapeum-org/github-actions is a monorepo: one commit carries the release tag
+        # for every action in it, so 38c11108 is the dereferenced commit for pixi/v1.2.1,
+        # mkdocs/v1.3.1, github-release/v1.5.0 and pypi-release/v1.0.3 alike. Several
+        # different actions pinned to one SHA reads like a copy-paste error and is not;
+        # verify with
+        #   git ls-remote --tags https://github.com/serapeum-org/github-actions
+        uses: serapeum-org/github-actions/actions/python-setup/pixi@38c111084f99d5ff5f4a1e63bedce48fe33a10c0  # pixi/v1.2.1
+        with:
+          environments: ${{ matrix.environment }}
+          activate-environment: ${{ matrix.environment }}
+          cache: true
+          # Must match the pixi pinned in tests.yml and github-release.yml:
+          # pixi.lock is lock-file format v7, which older pixi refuses to read.
+          version: v0.73.0
+
+      # The inventory comes from `pixi list`, not `pip freeze`, for two reasons:
+      # `pip` is only in the `dev` dependency group, so `python -m pip freeze`
+      # in the `docs` environment prints nothing and the job would audit an
+      # empty file and pass; and pip reads the user site-packages, so it reports
+      # packages the environment does not contain. `pixi list` is the manager's
+      # own record and needs nothing installed inside the environment.
+      #
+      # Only `kind == "pypi"` entries with a version survive: pip-audit resolves
+      # names against PyPI, where the conda packages (python, openssl, ...) are
+      # not projects, and the editable self-install carries no version.
+      #
+      # `test -s` is the guard that matters - an empty requirements file makes
+      # pip-audit report success, so a mis-piped command would look like a clean
+      # scan. `--no-deps` keeps the result independent of whichever interpreter
+      # pipx picks: the file is fully pinned, so pip-audit looks each package up
+      # in the advisory DB instead of resolving the set in a throwaway venv.
+      - name: Audit dependencies with pip-audit
+        run: |
+          pixi list -e ${{ matrix.environment }} --json \
+            | python -c "import json,sys; [print(p['name']+'=='+p['version']) for p in sorted(json.load(sys.stdin), key=lambda q: q['name']) if p.get('kind')=='pypi' and p.get('version')]" \
+            > "${RUNNER_TEMP}/pip-audit-reqs.txt"
+          test -s "${RUNNER_TEMP}/pip-audit-reqs.txt"
+          echo "Auditing $(wc -l < "${RUNNER_TEMP}/pip-audit-reqs.txt") pinned packages from the ${{ matrix.environment }} environment"
+          pipx run pip-audit --requirement "${RUNNER_TEMP}/pip-audit-reqs.txt" --no-deps --desc

pointclouds-0.0.0/.github/workflows/pypi-release.yml

@@ -0,0 +1,55 @@
+# Build and publish the Python package to PyPI using the shared composite action.
+
+name: pypi-release
+
+on:
+  workflow_dispatch:
+    inputs:
+      ref:
+        description: "Tag, branch, or SHA to publish to PyPI (e.g. 0.1.0)"
+        required: true
+        type: string
+  workflow_run:
+    workflows: ['github-release']
+    types: [completed]
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    # Security: when triggered via `workflow_run`, require that the upstream
+    # workflow ran from the base repository (not a fork) so a fork can never
+    # reach a context holding `PYPI_PUBLISH`.
+    if: >-
+      github.event_name == 'workflow_dispatch' ||
+      (github.event.workflow_run.conclusion == 'success'
+       && github.event.workflow_run.head_repository.fork == false)
+
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0
+        with:
+          fetch-depth: 0
+          # On workflow_run, pin to the immutable SHA recorded on the
+          # originating run, not the mutable `head_branch` label
+          # (CWE-829: actions/untrusted-checkout).
+          ref: ${{ github.event_name == 'workflow_dispatch' && inputs.ref || github.event.workflow_run.head_sha }}
+
+      - name: Build and publish to PyPI
+        # serapeum-org/github-actions is a monorepo: one commit carries the release tag
+        # for every action in it, so 38c11108 is the dereferenced commit for pixi/v1.2.1,
+        # mkdocs/v1.3.1, github-release/v1.5.0 and pypi-release/v1.0.3 alike. Several
+        # different actions pinned to one SHA reads like a copy-paste error and is not;
+        # verify with
+        #   git ls-remote --tags https://github.com/serapeum-org/github-actions
+        uses: serapeum-org/github-actions/actions/release/pypi@38c111084f99d5ff5f4a1e63bedce48fe33a10c0 # pypi-release/v1.0.3
+        with:
+          pypi-username: __token__
+          pypi-password: ${{ secrets.PYPI_PUBLISH }}
+          package-manager: 'pixi'
+          package-manager-version: 'v0.73.0'
+          install-groups: 'dev'
+          # The version bump that precedes this run rewrites pyproject.toml, so
+          # the lock is one commit behind by design here.
+          verify-lock: 'false'