specmod 0.2.0__tar.gz

specmod-0.2.0/.git-blame-ignore-revs

@@ -0,0 +1,6 @@
+# Revisions to skip in `git blame` — formatting-only, no behaviour change.
+# Enable locally with:
+#   git config blame.ignoreRevsFile .git-blame-ignore-revs
+
+# style: apply ruff format and autofixes across the tree
+b74ae4d632dffaafad9a440a624fd50f5c73274c

specmod-0.2.0/.github/workflows/build.yml

@@ -0,0 +1,40 @@
+name: build
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0   # hatch-vcs derives the version from tags
+      - uses: astral-sh/setup-uv@v5
+      - run: uv python install 3.11
+
+      - name: Build sdist and wheel
+        run: uv build
+
+      - name: Check metadata
+        run: uvx twine check dist/*
+
+      - name: Install from the wheel in a clean env
+        # Catches missing package data and bad entry points, which an editable
+        # install will happily hide.
+        run: |
+          uv venv /tmp/smoke
+          uv pip install --python /tmp/smoke/bin/python dist/*.whl
+          /tmp/smoke/bin/python -c "
+          import specmod
+          from specmod import core, fitting, pipeline, preprocess, transforms, utils
+          print('specmod', specmod.__version__, '- wheel imports cleanly')
+          "
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/

specmod-0.2.0/.github/workflows/docs.yml

@@ -0,0 +1,51 @@
+name: docs
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+# Read the Docs publishes the site; this job only checks that it builds. It is
+# kept alongside Read the Docs' own pull request build because it is the fast,
+# in-repository check that does not depend on a third-party service being up —
+# and because it is an import check, which is worth having in CI regardless.
+# See docs/documentation.md.
+
+concurrency:
+  group: docs-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  # The job name is what branch protection matches, not the workflow name.
+  # This was `build`, which collided with build.yml's job of the same name and
+  # left two unrelated checks sharing one name — and no check called `docs` for
+  # a required-checks list to name.
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0   # hatch-vcs derives the version from tags
+      - uses: astral-sh/setup-uv@v5
+      - run: uv python install 3.11
+      - run: uv venv # create a venv to install into
+
+      # The package itself, not just the docs extra: autodoc imports every
+      # module it documents, so a docs build is also an import check.
+      - run: uv pip install -e ".[docs,io]"
+
+      - name: Build
+        # No -W. Intersphinx resolves seven inventories over the network and
+        # warns when one is briefly unreachable, which would turn a third
+        # party's downtime into a red build. A genuinely broken build exits
+        # non-zero on its own. `.readthedocs.yaml` sets fail_on_warning: false
+        # for the same reason — keep the two in step.
+        run: uv run sphinx-build -b html docs docs/_build/html
+
+      # Not a Pages artefact: this is a plain zip anyone can download from the
+      # run and open locally, and it stays useful if Read the Docs is down.
+      - uses: actions/upload-artifact@v4
+        with:
+          name: docs-html
+          path: docs/_build/html

specmod-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,76 @@
+name: release
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+# release-please pushes the release branch, opens the PR, and on merge creates
+# the tag and the GitHub Release. The publish job below needs neither: PyPI
+# Trusted Publishing authenticates with an OIDC token, so nothing long-lived
+# lives in secrets.
+permissions:
+  contents: write
+  pull-requests: write
+
+# Two pushes to main should not race to update the same release PR.
+concurrency:
+  group: release
+  cancel-in-progress: false
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    outputs:
+      release_created: ${{ steps.release.outputs.release_created }}
+      tag_name: ${{ steps.release.outputs.tag_name }}
+    steps:
+      - uses: googleapis/release-please-action@v4
+        id: release
+        with:
+          config-file: release-please-config.json
+          manifest-file: .release-please-manifest.json
+
+  # Deliberately in this workflow rather than a separate publish.yml keyed on
+  # `release: published`, which is what §6.5 of the plan used to describe.
+  # release-please creates the release with the default GITHUB_TOKEN, and
+  # per GitHub's docs "events triggered by the GITHUB_TOKEN will not create a
+  # new workflow run" — so that publish workflow would never fire. The
+  # alternative is a personal access token in secrets, which is the one thing
+  # Trusted Publishing exists to avoid. Gating on the action's own output
+  # keeps the token count at zero.
+  #
+  # Zenodo is unaffected: it listens to the release *webhook*, which is not
+  # subject to that restriction, so the DOI is still minted from the release.
+  publish:
+    needs: release-please
+    if: needs.release-please.outputs.release_created == 'true'
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/specmod
+    permissions:
+      id-token: write   # mandatory for Trusted Publishing
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # The tag, not the branch. main has already moved on by one commit
+          # (the release PR merge), and hatch-vcs would derive a .postN.devN
+          # version from it.
+          ref: ${{ needs.release-please.outputs.tag_name }}
+          fetch-depth: 0   # hatch-vcs derives the version by describing tags
+
+      - uses: astral-sh/setup-uv@v5
+      - run: uv python install 3.11
+      - run: uv build
+
+      # The tag is the version, and pyproject's tag_regex decides whether
+      # hatch-vcs can read it. If those two ever disagree the wheel is built
+      # as 0.1.1.postN.devN and would be uploaded under that name — PyPI does
+      # not let it be taken back. tests/test_release_config.py checks the
+      # formats agree; this checks the artefact that is about to be published.
+      - name: The built version is the tag
+        run: python tools/check_built_version.py "${{ needs.release-please.outputs.tag_name }}" dist
+
+      - uses: pypa/gh-action-pypi-publish@release/v1

specmod-0.2.0/.github/workflows/test.yml

@@ -0,0 +1,130 @@
+name: test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: test-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - run: uv python install 3.11
+      - run: uv venv
+      - name: ruff check
+        run: uvx ruff@0.16.1 check --output-format=github src/ tests/ tools/
+      - name: ruff format
+        run: uvx ruff@0.16.1 format --check src/ tests/ tools/
+
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0   # hatch-vcs needs history to derive the version
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - run: uv python install 3.11
+      - run: uv venv
+      - run: uv pip install -e ".[dev]"
+      - run: uv pip install mypy
+      - run: uv run mypy
+
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - run: uv python install ${{ matrix.python-version }}
+      - run: uv venv
+      - run: uv pip install -e ".[dev]"
+      - run: uv pip install pytest pytest-cov
+      - name: pytest
+        # Dataset-marked tests need a network fetch; they are excluded here so
+        # the suite stays hermetic. See docs/REFACTOR_PLAN.md §5.2. Notebook
+        # execution is excluded because it costs ~40s and a Jupyter kernel, and
+        # is worth paying once rather than six times — see the notebook job.
+        run: uv run pytest -m "not dataset and not notebook" --cov=specmod --cov-report=xml --cov-report=term
+      - uses: codecov/codecov-action@v4
+        if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.11'
+        with:
+          files: coverage.xml
+          fail_ci_if_error: false
+
+  floors:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v5
+      - run: uv python install 3.11
+      - run: uv venv
+      # Exercise the declared minimums. CI otherwise installs the newest of
+      # everything, so the floors are only ever tested by a user.
+      - run: uv pip install --resolution lowest-direct -e ".[dev]"
+      - run: uv run --no-sync python tools/check_floors.py
+      - run: uv run --no-sync pytest -m "not dataset and not notebook" -q
+
+  notebook:
+    # The tutorial is the documented entry point and has broken three times:
+    # twice on renamed modules, once on a renamed data directory that left
+    # every import resolving. Executing it is the only check that catches the
+    # third kind, so it runs per-PR rather than at release.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - run: uv python install 3.11
+      - run: uv venv
+      - run: uv pip install -e ".[dev,tutorial]"
+      - run: uv run pytest -m notebook -q
+
+  # One check to require in branch protection, instead of ten — and stable when
+  # the matrix changes, which the six `test (os, version)` names are not.
+  #
+  # `if: always()` is load-bearing. Without it a failing dependency *skips* this
+  # job rather than failing it, and GitHub treats a skipped required check as
+  # satisfied — so branch protection would go green on a red build. Running
+  # always, and failing explicitly on any non-success, is what closes that.
+  #
+  # `skipped` counts as a failure here on purpose: nothing above is
+  # conditionally skipped, so a skip means something upstream went wrong.
+  ci:
+    if: always()
+    needs: [lint, typecheck, test, floors, notebook]
+    runs-on: ubuntu-latest
+    steps:
+      - name: Report what every job did
+        run: echo '${{ toJSON(needs) }}'
+      - name: Fail unless all of them succeeded
+        if: >-
+          contains(needs.*.result, 'failure')
+          || contains(needs.*.result, 'cancelled')
+          || contains(needs.*.result, 'skipped')
+        run: |
+          echo "::error::a required job did not succeed; see the report above"
+          exit 1

specmod-0.2.0/.gitignore

@@ -0,0 +1,48 @@
+# Local, uncommitted configuration overrides (see docs/REFACTOR_PLAN.md §4.7).
+# Promote one deliberately with `specmod config freeze > studies/<name>.toml`.
+specmod.local.toml
+*.local.toml
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.eggs/
+
+# Environments
+.venv/
+venv/
+env/
+
+# Tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+coverage.xml
+htmlcov/
+
+# Docs
+docs/_build/
+
+# Editors / OS
+.ftpconfig
+.DS_Store
+.idea/
+.vscode/
+*.swp
+
+# Notebook checkpoints
+.ipynb_checkpoints/
+
+# Tutorial output. Regenerated by running the notebook; committing it means a
+# diff every time anyone executes it, and a stale copy the moment the pipeline
+# changes. The inputs (Tutorial/Data, Tutorial/MetaData) *are* committed.
+Tutorial/Spectra/*.h5
+Tutorial/Spectra/FlatFiles/
+
+# Created by `uv run` without --no-sync; this project resolves fresh on
+# purpose so the floors job can test the declared minimums.
+uv.lock

specmod-0.2.0/.pre-commit-config.yaml

@@ -0,0 +1,62 @@
+# `pre-commit install` wires only the pre-commit stage by default, which left
+# the commit-msg hook below inert in every clone that ran the documented setup
+# — including the one that then committed three session links. Naming the
+# stages here means one `pre-commit install` installs both.
+default_install_hook_types: [pre-commit, commit-msg]
+
+repos:
+  # CI runs `uvx ruff` unpinned, so it always gets the newest release. Keep
+  # this rev at that newest release or CI will fail on rules this does not have.
+  # It has bitten twice: 0.9.6 against latest, then 0.15.8 against 0.16.1, where
+  # PLR0917 graduated out of preview and started firing only in CI.
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.16.1
+    hooks:
+      # Scoped to match CI, which runs `ruff ... src/ tests/ tools/`. Without
+      # this the hook lints everything staged and CI lints three directories,
+      # so a commit touching `docs/notebooks/` or `stubs/` is blocked by rules
+      # nothing else enforces — and the notebook builder legitimately contains
+      # long markdown lines and mathematical unicode that `RUF001` reads as
+      # ambiguous. Widen both together or neither.
+      - id: ruff-check
+        args: [--fix]
+        files: ^(src|tests|tools)/
+      - id: ruff-format
+        files: ^(src|tests|tools)/
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: check-added-large-files
+        # The repo carried 25 MB of data before this refactor; keep it out.
+        args: [--maxkb=1024]
+      - id: check-toml
+      - id: check-yaml
+      # These three rewrite files as text. `.spec` artifacts are pickles, and
+      # running the hooks over one silently stripped six bytes from the middle
+      # of it — a corrupted pickle that still looks like a plausible diff.
+      # Anything binary has to be excluded by hand; the hooks do not detect it.
+      - id: end-of-file-fixer
+        exclude: '\.spec$'
+      - id: trailing-whitespace
+        exclude: '\.spec$'
+      - id: mixed-line-ending
+        exclude: '\.spec$'
+
+  - repo: https://github.com/kynan/nbstripout
+    rev: 0.8.1
+    hooks:
+      - id: nbstripout
+        # The tutorial notebook was 4.4 MB of embedded PNGs. Under myst-nb the
+        # outputs are regenerated at docs build time.
+
+  - repo: local
+    hooks:
+      - id: no-session-links
+        name: reject Claude session URLs in commit messages
+        # This repository is public; session links are private state.
+        entry: >-
+          bash -c 'if grep -qiE "^Claude-Session:|claude\.ai/code/session_" "$1";
+          then echo "commit-msg: message contains a Claude session link"; exit 1; fi'
+        language: system
+        stages: [commit-msg]

specmod-0.2.0/.readthedocs.yaml

@@ -0,0 +1,47 @@
+# Read the Docs build configuration.
+#
+# Read the Docs publishes the documentation; GitHub Actions only checks that it
+# builds. The reason for the split is versions: this package is alpha and users
+# are told to pin an exact version, so the documentation for a release has to
+# stay readable after the trunk has moved on. Read the Docs keeps one build per
+# tag, a `stable` pointing at the newest, and a `latest` from `main`, with a
+# version switcher between them — and it builds pull requests to their own
+# throwaway URL.
+#
+# Schema: https://docs.readthedocs.com/platform/stable/config-file/v2.html
+
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.11" # the version CI's lint, typecheck and docs jobs use
+  jobs:
+    post_checkout:
+      # Read the Docs clones shallow and without tags, to save time. hatch-vcs
+      # derives the version from `git describe`, and `docs/conf.py` reads it
+      # back through importlib.metadata — so without these the sidebar reads
+      # the fallback 0.0.0 on every build, including tagged ones.
+      # `|| true` because a repository that is already complete makes
+      # --unshallow exit non-zero, which would fail the build.
+      - git fetch --unshallow || true
+      - git fetch --tags || true
+
+sphinx:
+  configuration: docs/conf.py
+  # Deliberately off, for the same reason the CI job has no `-W`: intersphinx
+  # resolves seven inventories over the network and warns whenever one of them
+  # is briefly unreachable. That would make a third party's downtime a failed
+  # documentation build. A genuinely broken build still exits non-zero.
+  fail_on_warning: false
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        # `io` alongside `docs` because autodoc imports every module it
+        # documents, and `specmod.io` imports h5py and pyarrow. Without it the
+        # API reference loses those pages to import errors.
+        - docs
+        - io

specmod-0.2.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.2.0"
+}

specmod-0.2.0/AGENTS.md

@@ -0,0 +1,92 @@
+# Working on SpecMod with a coding agent
+
+Rules for Claude Code, Codex, and any other agent committing to this
+repository. `CLAUDE.md` points here so there is one copy.
+
+The long version of everything below is
+[`docs/development.md`](docs/development.md). This file is the part an agent
+must not get wrong, and every entry is here because it has actually gone wrong.
+
+## Before the first commit
+
+```sh
+uv venv && uv pip install -e ".[dev]"
+pre-commit install          # installs BOTH the pre-commit and commit-msg hooks
+```
+
+`pre-commit install` is not optional. In a fresh container it is easy to skip,
+and the `commit-msg` hook is the only thing enforcing the rule below.
+
+## Never publish session links
+
+**No `Claude-Session:` trailers, session URLs, or agent-console links** in
+commit messages, PR titles, PR bodies, code comments, or anything else that
+lands in the repository. It is public; those links are private state.
+
+`Co-Authored-By:` is fine. If your harness appends a session trailer by
+default, strip it — the repository's rule wins over the harness default. The
+`commit-msg` hook rejects it, which is why installing the hooks comes first.
+
+## Commit messages are load-bearing
+
+[Conventional Commits](https://www.conventionalcommits.org). They are not a
+style preference: `release-please` reads them to compute the version bump and
+to generate `CHANGELOG.md`. See
+[`docs/releasing.md`](docs/releasing.md).
+
+- `feat:` minor, `fix:` patch, `refactor:` / `docs:` / `build:` appear in the
+  changelog, `test:` / `ci:` / `chore:` are hidden.
+- `!` or a `BREAKING CHANGE:` footer bumps the minor while the project is
+  `0.x`, not the major.
+- Say *why*, with the measurement if there was one. The history is the record
+  of what was checked; a message that only restates the diff wastes it.
+
+## Workflow files need a permission you may not have
+
+`.github/workflows/` is editable directly, but only when the session's GitHub
+App token carries the `workflows` permission. Without it the push is rejected
+outright:
+
+```
+refusing to allow a GitHub App to create or update workflow
+`.github/workflows/test.yml` without `workflows` permission
+```
+
+That is a loud failure, not a silent one. If you meet it, say so and ask for
+the permission — do not reintroduce a parallel copy of the workflows to work
+around it. There used to be one, in `ci/`, and keeping two versions of every
+workflow in step cost more than the problem it solved.
+
+## Verify before reporting
+
+Run these, and report what they actually printed:
+
+```sh
+pytest -m "not dataset and not notebook"     # the suite CI runs
+pytest --without-optional-extras             # what a default install sees
+ruff check src/ tests/ tools/ && ruff format --check src/ tests/ tools/
+mypy
+sphinx-build -b html docs docs/_build/html   # if docs/ changed
+```
+
+`--without-optional-extras` matters: a development environment with
+`specmod[multitaper]` installed passes tests that CI fails.
+
+## Things that look like noise and are not
+
+- **Golden references.** `tests/golden/*.json` is a record of numbers this code
+  used to produce. Do not regenerate it to make a test pass. If a change moves
+  a number, that is the finding — say which number, by how much, and why, and
+  regenerate deliberately with `python tools/make_golden.py`.
+- **Measured tables in the docs.** Numbers in `docs/*.md` are generated between
+  markers by `python tools/measure_docs.py`. Edit the tool, not the table.
+- **Tolerances.** Several carry a comment explaining what was measured to
+  choose them. Widening one to get to green, without measuring, is the specific
+  failure `docs/REFACTOR_PLAN.md` §6.6 exists to catch.
+
+## Say what you did not check
+
+The plan's §6.6 is an audit of claims in this repository that turned out to
+describe mechanisms nobody had built. Do not add to it. If something is
+untested, unreproducible, or assumed, write that down next to the claim — a
+bound with a number behind it beats a confident sentence.