psyexp-core 0.5.1__tar.gz

psyexp_core-0.5.1/.github/workflows/publish.yml

@@ -0,0 +1,70 @@
+name: publish
+
+# Publishes psyexp-core to PyPI when a GitHub Release is published.
+#
+# Publishing is deliberately tied to the *Release* event, NOT to pushing a tag.
+# A tag only runs release-check.yml (tests + version/changelog/lock checks, then a
+# DRAFT Release), so tags can be created, moved, or deleted freely while iterating
+# without ever touching PyPI. A version ships only when a human publishes the draft.
+#
+# Auth uses PyPI Trusted Publishing (OIDC) — no API token is stored as a secret.
+# The `pypi` environment scopes the OIDC trust and gates publishes behind a
+# required-reviewer approval. One-time setup: see docs/ci-setup.md.
+on:
+  release:
+    types: [published]
+
+jobs:
+  # Gate the release on the full test matrix (reuses tests.yml).
+  tests:
+    uses: ./.github/workflows/tests.yml
+
+  build:
+    needs: tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+
+      # Never ship a wheel whose version disagrees with the release tag.
+      - name: Verify release tag matches pyproject version
+        run: |
+          set -euo pipefail
+          tag="${GITHUB_REF_NAME#v}"
+          version="$(uv version --short)"
+          echo "Release tag: $tag   pyproject version: $version"
+          if [ "$tag" != "$version" ]; then
+            echo "::error::Release tag ($tag) does not match pyproject version ($version)."
+            exit 1
+          fi
+
+      - name: Build sdist + wheel
+        run: uv build
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  pypi:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/psyexp-core/
+    permissions:
+      id-token: write   # mint the OIDC token for Trusted Publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          # Tolerate re-running a Release whose version is already on PyPI
+          # (PyPI versions are immutable): skip instead of hard-failing.
+          skip-existing: true

psyexp_core-0.5.1/.github/workflows/release.yml

@@ -0,0 +1,112 @@
+name: release-check
+
+# On a version tag: run the test matrix, verify the version/changelog/lock all
+# agree, and create a DRAFT GitHub Release with notes from CHANGELOG.md. Tagging
+# does not publish anything — a human reviews and publishes the draft, which then
+# triggers publish.yml (PyPI). See docs/releasing.md.
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  # Tests must pass before we accept a release tag.
+  tests:
+    uses: ./.github/workflows/tests.yml
+
+  version-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Verify version bump and lockfile
+        run: |
+          set -euo pipefail
+
+          tag="${GITHUB_REF_NAME#v}"
+          echo "Tag version:      $tag"
+
+          pyproject_version="$(uv version --short)"
+          echo "pyproject version: $pyproject_version"
+
+          # Project's own pinned version inside the lockfile.
+          lock_version="$(
+            awk '
+              /^name = "psyexp-core"$/ { found = 1; next }
+              found && /^version = / {
+                sub(/^version = "/, ""); sub(/"$/, ""); print; exit
+              }
+            ' uv.lock
+          )"
+          echo "uv.lock version:   $lock_version"
+
+          if [ "$pyproject_version" != "$tag" ]; then
+            echo "::error::pyproject.toml version ($pyproject_version) does not match tag ($tag). Bump the version before tagging."
+            exit 1
+          fi
+
+          if [ "$lock_version" != "$tag" ]; then
+            echo "::error::uv.lock version ($lock_version) does not match tag ($tag). Run 'uv lock' and commit the result."
+            exit 1
+          fi
+
+          # Ensure the lockfile is fully consistent with pyproject.toml
+          # (catches dependency drift as well as a stale self-version).
+          uv lock --check
+
+          # CHANGELOG.md must document this version (the draft Release notes are
+          # extracted from it below).
+          if ! awk -v ver="$tag" '
+            /^## / { heading = $0; gsub(/[][]/, "", heading); if (index(heading, ver)) found = 1 }
+            END { exit found ? 0 : 1 }
+          ' CHANGELOG.md; then
+            echo "::error::CHANGELOG.md has no section for $tag. Add a '## v$tag' entry before tagging."
+            exit 1
+          fi
+
+          echo "Version $tag is consistent across pyproject.toml, uv.lock, and CHANGELOG.md."
+
+  # After the gates pass, draft a GitHub Release with notes from CHANGELOG.md.
+  # The draft is NOT published, so nothing reaches PyPI until a human publishes it.
+  draft-release:
+    needs: [tests, version-check]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v5
+
+      # Pull the section for this tag out of CHANGELOG.md: the heading containing
+      # the version (without the leading "v") through to the next "## " heading.
+      - name: Extract release notes
+        id: notes
+        run: |
+          version="${GITHUB_REF_NAME#v}"
+          notes_file="$(mktemp)"
+          awk -v ver="$version" '
+            $0 ~ "^## " {
+              if (found) exit
+              heading = $0
+              gsub(/[][]/, "", heading)
+              if (index(heading, ver)) { found = 1; next }
+            }
+            found { print }
+          ' CHANGELOG.md > "$notes_file"
+
+          if [ ! -s "$notes_file" ]; then
+            printf 'Release %s\n' "$GITHUB_REF_NAME" > "$notes_file"
+          fi
+
+          echo "file=$notes_file" >> "$GITHUB_OUTPUT"
+
+      - name: Create draft GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          name: ${{ github.ref_name }}
+          body_path: ${{ steps.notes.outputs.file }}
+          draft: true
+          # Mark as prerelease when the tag carries an rc/alpha/beta suffix.
+          prerelease: ${{ contains(github.ref_name, '-rc') || contains(github.ref_name, '-alpha') || contains(github.ref_name, '-beta') }}

psyexp_core-0.5.1/.github/workflows/tests.yml

@@ -0,0 +1,44 @@
+name: tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_call:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      # The tested surface (manifest, recording, diagnostics, rundir) is
+      # PsychoPy-free, so we skip the heavy GL/PsychoPy stack and install the
+      # project without its runtime deps plus the dev tooling only.
+      - name: Install
+        run: |
+          uv venv --python ${{ matrix.python-version }}
+          uv pip install --no-deps -e .
+          uv pip install pytest ruff
+
+      # Use --no-sync so `uv run` does not re-resolve and install the full
+      # dependency tree (which includes PsychoPy/wxPython and fails to build on
+      # CI). We rely on the no-deps venv set up above instead.
+      - name: Lint
+        run: uv run --no-sync ruff check .
+
+      - name: Test
+        run: uv run --no-sync pytest

psyexp_core-0.5.1/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.py[cod]
+.venv/
+.pytest_cache/
+.ruff_cache/
+*.egg-info/
+build/
+dist/
+.DS_Store
+.idea/

psyexp_core-0.5.1/CHANGELOG.md

@@ -0,0 +1,68 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+See [docs/releasing.md](docs/releasing.md) for the release process.
+
+## v0.5.1
+
+### Added
+
+- PyPI publishing on a published GitHub Release via Trusted Publishing (OIDC; no
+  stored token).
+- Draft GitHub Release creation on tag push, with notes pulled from this file.
+- This changelog and a release guide ([docs/releasing.md](docs/releasing.md)).
+- `[project.urls]` for the PyPI project page.
+
+## v0.5.0
+
+### Added
+
+- Timed-press + keyboard-clock API in `keyboard`: `get_presses` (name + reaction
+  time), `reset_clock_on_flip`, `reset_clock`, `clock_time`, and the `KeyPress`
+  dataclass — so timing-critical response windows can read frame-accurate RT
+  through the shared abstraction.
+
+### Fixed
+
+- `keyboard` imports PsychoPy lazily, so the module (and its PsychoPy-free
+  timed-press / clock helpers) stays importable and unit-testable in headless/CI
+  environments without the PsychoPy stack.
+
+## v0.4.0
+
+### Changed
+
+- Instruction-pager page type uses a generic, so callers keep their own page type.
+
+### Added
+
+- Makefile for release automation.
+
+## v0.3.0
+
+### Added
+
+- Loud warning when psychtoolbox is unavailable and the keyboard falls back to
+  PsychoPy's focus-dependent `event` backend.
+
+## v0.2.0
+
+### Fixed
+
+- Poll for keyboard input rather than blocking, so the window keeps flipping (and
+  can come to the foreground to receive keys) on macOS.
+
+### Added
+
+- Co-development instructions for overlaying an editable checkout over a git pin.
+
+## v0.1.0
+
+Initial release: the task-agnostic harness — `screen` (fullscreen window +
+frame-timing calibration), `diagnostics`, `rundir`, `manifest`, `recording`
+(`CsvWriter`), `wizard` setup primitives, the `instructions` pager, and the
+`keyboard` PTB/event abstraction — with the version resolved from `pyproject.toml`
+and CI for tests and release checks.

psyexp_core-0.5.1/Makefile

@@ -0,0 +1,30 @@
+.PHONY: release bump-patch bump-minor bump-major version
+
+# Current version, read straight from pyproject.toml.
+VERSION := $(shell grep -m1 '^version = ' pyproject.toml | cut -d'"' -f2)
+
+version:
+	@echo $(VERSION)
+
+# Cut a release: bump pyproject.toml to $(TO), commit, and tag v$(TO).
+# Usage: make release TO=0.4.0
+release:
+	@test -n "$(TO)" || { echo "usage: make release TO=X.Y.Z"; exit 1; }
+	@test -z "$$(git status --porcelain)" || { echo "working tree is dirty; commit or stash first"; exit 1; }
+	@git rev-parse -q --verify "refs/tags/v$(TO)" >/dev/null && { echo "tag v$(TO) already exists"; exit 1; } || true
+	sed -i '' 's/^version = ".*"/version = "$(TO)"/' pyproject.toml
+	uv lock
+	git add pyproject.toml uv.lock
+	git commit -m "chore: release v$(TO)"
+	git tag -a "v$(TO)" -m "v$(TO)"
+	@echo "tagged v$(TO) — run 'git push && git push --tags' to publish"
+
+# Convenience wrappers that compute the next version from the current one.
+bump-patch:
+	@$(MAKE) release TO=$(shell echo $(VERSION) | awk -F. '{printf "%d.%d.%d", $$1, $$2, $$3+1}')
+
+bump-minor:
+	@$(MAKE) release TO=$(shell echo $(VERSION) | awk -F. '{printf "%d.%d.0", $$1, $$2+1}')
+
+bump-major:
+	@$(MAKE) release TO=$(shell echo $(VERSION) | awk -F. '{printf "%d.0.0", $$1+1}')

psyexp_core-0.5.1/PKG-INFO

@@ -0,0 +1,92 @@
+Metadata-Version: 2.4
+Name: psyexp-core
+Version: 0.5.1
+Summary: Task-agnostic harness for PsychoPy experiments: screen/frame-timing setup, run manifests, CSV writers, setup-wizard primitives, instruction pager, and keyboard abstraction.
+Project-URL: Homepage, https://github.com/HAPNlab/psyexp-core
+Project-URL: Repository, https://github.com/HAPNlab/psyexp-core
+Author: Eric Wang
+Requires-Python: >=3.11
+Requires-Dist: prompt-toolkit>=3.0
+Requires-Dist: psychopy>=2025.1
+Requires-Dist: pyobjc-framework-quartz>=10; sys_platform == 'darwin'
+Requires-Dist: questionary>=2.0
+Requires-Dist: rich>=14.3.3
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# psyexp-core
+
+Task-agnostic harness for PsychoPy experiments, shared across the lab's task
+repos (`heat-task`, `mid-task`, `mid-task-deterministic`). It owns the *plumbing*
+that every task duplicates; each task repo keeps only its own stimuli, trial
+logic, and record schemas.
+
+## What's in here
+
+| Module | Responsibility |
+| --- | --- |
+| `screen` | `setup_screen()` — open a fullscreen PsychoPy window, enable VSYNC, run a frame-timing calibration, and return a `ScreenDiagnostics`. |
+| `diagnostics` | The `ScreenDiagnostics` dataclass (import-light; no PsychoPy). |
+| `rundir` | `make_run_dir(data_dir, label, session_time)` — timestamped output directory. |
+| `manifest` | `write_manifest(...)` + `system_info()` — JSON run manifest with system/display/process diagnostics and the resolved `psyexp_core_version`. App-specific fields are injected via `header` / `study_params`. |
+| `recording` | `CsvWriter` base class (maps a dataclass record onto a fixed column schema). |
+| `wizard` | questionary / prompt_toolkit setup-wizard primitives: shared styles, `ask_text` / `ask_select` / `ask_confirm`, `PosFloatValidator`, `prompt_unique_name`, `quit_app`. |
+| `instructions` | `page_through(...)` — a self-paced, keypress-driven instruction pager. |
+| `keyboard` | PTB / PsychoPy-event keyboard abstraction: `build_keyboard` / `get_keys` / `wait_for_keys` / `clear_events`, plus the timed-press API for response windows — `get_presses` (name + rt), `reset_clock_on_flip` / `reset_clock` / `clock_time`. |
+
+## Use from a task repo
+
+Add it as a dependency. For day-to-day development, point at a local checkout so
+edits are live without reinstalling:
+
+```toml
+# your-task/pyproject.toml
+dependencies = ["psyexp-core"]
+
+[tool.uv.sources]
+psyexp-core = { path = "../psyexp-core", editable = true }
+```
+
+For a reproducible release build, pin a tagged ref instead:
+
+```toml
+[tool.uv.sources]
+psyexp-core = { git = "ssh://git@github.com/<you>/psyexp-core.git", tag = "v0.1.0" }
+```
+
+`write_manifest` records the resolved `psyexp_core_version` so each run is
+traceable back to a core version.
+
+### Co-developing core while a task repo keeps the git pin
+
+Lab task repos (e.g. `heat-task`) commit the **git-tag** source above so clones
+reproduce exactly, then overlay a local editable install for development:
+
+```bash
+uv pip install -e ../psyexp-core
+```
+
+**Gotcha:** `uv run` re-syncs the task venv from its `uv.lock` on every launch,
+which reverts that editable install straight back to the pinned tag (symptoms:
+your local core edits silently don't take effect). Set `UV_NO_SYNC=1` in the task
+repo (export it in your shell, or use `uv run --no-sync`) so the editable overlay
+sticks; run a manual `uv sync` only when you change other deps, then re-run the
+editable install. See heat-task's README ("Co-developing `psyexp-core` locally")
+for the full workflow.
+
+## Releasing
+
+Tagging and publishing are deliberately separate, so tags stay cheap to iterate on:
+
+1. **Bump + lock + changelog**, then tag `vX.Y.Z`. The tag runs the checks and
+   creates a **draft** GitHub Release — it does **not** publish anything.
+2. **Review the draft** Release and publish it. That triggers
+   [`publish.yml`](.github/workflows/publish.yml), which uploads to
+   [PyPI](https://pypi.org/project/psyexp-core/) via **Trusted Publishing** (OIDC;
+   no API token stored).
+
+PyPI versions are immutable, so retagging never republishes; bump the version to
+ship new code. See **[docs/releasing.md](docs/releasing.md)** for the full process,
+SemVer policy, pre-releases, retag semantics, and the one-time PyPI setup.

psyexp_core-0.5.1/README.md

@@ -0,0 +1,74 @@
+# psyexp-core
+
+Task-agnostic harness for PsychoPy experiments, shared across the lab's task
+repos (`heat-task`, `mid-task`, `mid-task-deterministic`). It owns the *plumbing*
+that every task duplicates; each task repo keeps only its own stimuli, trial
+logic, and record schemas.
+
+## What's in here
+
+| Module | Responsibility |
+| --- | --- |
+| `screen` | `setup_screen()` — open a fullscreen PsychoPy window, enable VSYNC, run a frame-timing calibration, and return a `ScreenDiagnostics`. |
+| `diagnostics` | The `ScreenDiagnostics` dataclass (import-light; no PsychoPy). |
+| `rundir` | `make_run_dir(data_dir, label, session_time)` — timestamped output directory. |
+| `manifest` | `write_manifest(...)` + `system_info()` — JSON run manifest with system/display/process diagnostics and the resolved `psyexp_core_version`. App-specific fields are injected via `header` / `study_params`. |
+| `recording` | `CsvWriter` base class (maps a dataclass record onto a fixed column schema). |
+| `wizard` | questionary / prompt_toolkit setup-wizard primitives: shared styles, `ask_text` / `ask_select` / `ask_confirm`, `PosFloatValidator`, `prompt_unique_name`, `quit_app`. |
+| `instructions` | `page_through(...)` — a self-paced, keypress-driven instruction pager. |
+| `keyboard` | PTB / PsychoPy-event keyboard abstraction: `build_keyboard` / `get_keys` / `wait_for_keys` / `clear_events`, plus the timed-press API for response windows — `get_presses` (name + rt), `reset_clock_on_flip` / `reset_clock` / `clock_time`. |
+
+## Use from a task repo
+
+Add it as a dependency. For day-to-day development, point at a local checkout so
+edits are live without reinstalling:
+
+```toml
+# your-task/pyproject.toml
+dependencies = ["psyexp-core"]
+
+[tool.uv.sources]
+psyexp-core = { path = "../psyexp-core", editable = true }
+```
+
+For a reproducible release build, pin a tagged ref instead:
+
+```toml
+[tool.uv.sources]
+psyexp-core = { git = "ssh://git@github.com/<you>/psyexp-core.git", tag = "v0.1.0" }
+```
+
+`write_manifest` records the resolved `psyexp_core_version` so each run is
+traceable back to a core version.
+
+### Co-developing core while a task repo keeps the git pin
+
+Lab task repos (e.g. `heat-task`) commit the **git-tag** source above so clones
+reproduce exactly, then overlay a local editable install for development:
+
+```bash
+uv pip install -e ../psyexp-core
+```
+
+**Gotcha:** `uv run` re-syncs the task venv from its `uv.lock` on every launch,
+which reverts that editable install straight back to the pinned tag (symptoms:
+your local core edits silently don't take effect). Set `UV_NO_SYNC=1` in the task
+repo (export it in your shell, or use `uv run --no-sync`) so the editable overlay
+sticks; run a manual `uv sync` only when you change other deps, then re-run the
+editable install. See heat-task's README ("Co-developing `psyexp-core` locally")
+for the full workflow.
+
+## Releasing
+
+Tagging and publishing are deliberately separate, so tags stay cheap to iterate on:
+
+1. **Bump + lock + changelog**, then tag `vX.Y.Z`. The tag runs the checks and
+   creates a **draft** GitHub Release — it does **not** publish anything.
+2. **Review the draft** Release and publish it. That triggers
+   [`publish.yml`](.github/workflows/publish.yml), which uploads to
+   [PyPI](https://pypi.org/project/psyexp-core/) via **Trusted Publishing** (OIDC;
+   no API token stored).
+
+PyPI versions are immutable, so retagging never republishes; bump the version to
+ship new code. See **[docs/releasing.md](docs/releasing.md)** for the full process,
+SemVer policy, pre-releases, retag semantics, and the one-time PyPI setup.

psyexp_core-0.5.1/docs/ci-setup.md

@@ -0,0 +1,100 @@
+# Setting up PyPI CI (one-time)
+
+This is the **one-time** setup that lets [`publish.yml`](../.github/workflows/publish.yml)
+upload `psyexp-core` to PyPI. For the day-to-day release process (bump, tag,
+publish the draft), see [releasing.md](releasing.md).
+
+## How auth works: Trusted Publishing (OIDC), no stored token
+
+We do **not** store a PyPI API token anywhere — not as a repo secret, not as an
+environment secret. Instead the publish job uses **Trusted Publishing**: at run
+time GitHub mints a short-lived OIDC token, and PyPI accepts the upload because it
+matches a *trusted publisher* you registered (owner + repo + workflow + environment).
+
+Why this is the safest option:
+
+- There's no long-lived credential to leak — the token exists only for minutes,
+  inside the one publish job.
+- The token is scoped to the `pypi` **environment**, so only a run in that
+  environment can mint it — not test/PR/push workflows.
+- The `pypi` environment adds a **manual approval gate** before the job runs.
+
+The publish job already declares this (no edits needed):
+
+```yaml
+# .github/workflows/publish.yml
+permissions:
+  id-token: write          # mint the OIDC token
+environment:
+  name: pypi               # gate + scope
+```
+
+## Step 1 — Create the `pypi` GitHub Environment + approval gate
+
+GitHub auto-creates an environment on first use *without* protections, so this step
+is only needed to add the reviewer gate (recommended).
+
+**UI:** Repo → **Settings → Environments → New environment** → name it `pypi`.
+Then under **Deployment protection rules**:
+
+- Enable **Required reviewers** and add yourself (and/or a `@HAPNlab` team). The
+  publish job will now pause and wait for an approval click before it runs.
+- *(Optional)* **Deployment branches and tags** → *Selected* → add a tag rule like
+  `v*` so only version tags can deploy to `pypi`.
+
+**CLI alternative** (needs repo admin; reviewer IDs are numeric user/team IDs):
+
+```sh
+# create/configure the environment with a required reviewer
+gh api -X PUT repos/HAPNlab/psyexp-core/environments/pypi \
+  -F "reviewers[][type]=User" -F "reviewers[][id]=<YOUR_USER_ID>"
+# look up your numeric id:
+gh api users/<your-login> --jq .id
+```
+
+## Step 2 — Register the trusted publisher on PyPI
+
+This tells PyPI to trust uploads from this repo's publish workflow.
+
+### If the project does **not** exist on PyPI yet (first release)
+
+Use a **pending publisher** — it creates the project on first successful upload:
+
+1. Log in to PyPI → **Account settings → Publishing** (or
+   <https://pypi.org/manage/account/publishing/>).
+2. Under **Add a new pending publisher**, fill in:
+   - **PyPI Project Name:** `psyexp-core`
+   - **Owner:** `HAPNlab`
+   - **Repository name:** `psyexp-core`
+   - **Workflow name:** `publish.yml`
+   - **Environment name:** `pypi`
+3. Save.
+
+### If the project already exists
+
+Project page → **Manage → Publishing → Add a new publisher**, with the same
+owner / repo / workflow / environment values above.
+
+> The **Environment name must be exactly `pypi`** — it has to match the
+> `environment: name:` in `publish.yml`, or PyPI will reject the OIDC token.
+
+## Step 3 — Do a release
+
+Follow [releasing.md](releasing.md): bump the version + `CHANGELOG.md`, `uv lock`,
+tag `vX.Y.Z`. The tag drafts a GitHub Release; **publish the draft**. That triggers
+`publish.yml`, which will:
+
+1. run the test matrix and build the sdist/wheel, then
+2. pause on the `pypi` environment for your **approval**, then
+3. upload to PyPI via OIDC.
+
+Approve it from the **Actions** run page (or the repo's **Environments** view).
+
+## Troubleshooting
+
+| Symptom | Cause / fix |
+|---|---|
+| `invalid-publisher` / OIDC rejected | The PyPI trusted publisher's owner/repo/workflow/**environment** don't all match. Re-check Step 2 — `pypi` and `publish.yml` are the usual culprits. |
+| Job runs but never uploads / waits forever | It's parked on the environment approval gate. Approve it on the run page. |
+| `File already exists` | That version is already on PyPI (versions are immutable). `skip-existing: true` turns this into a skip; bump the version to ship new code. See [releasing.md](releasing.md#retag--re-release-semantics). |
+| `id-token` permission error | The job needs `permissions: id-token: write` (already set in `publish.yml`). |