specmod 0.2.3__tar.gz → 0.3.0__tar.gz

{specmod-0.2.3 → specmod-0.3.0}/.github/workflows/build.yml

@@ -10,10 +10,14 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
         with:
           fetch-depth: 0   # hatch-vcs derives the version from tags
-      - uses: astral-sh/setup-uv@v5
+      # Pinned to a full version, unlike the other three. `astral-sh/setup-uv`
+      # publishes no bare major tag — `@v10` does not resolve, and using it
+      # fails every job at "Getting action download info", before a step runs.
+      # Bump this deliberately; do not "tidy" it to `@v10`.
+      - uses: astral-sh/setup-uv@v10.0.1
       - run: uv python install 3.11
 
       - name: Build sdist and wheel
@@ -34,7 +38,7 @@ jobs:
           print('specmod', specmod.__version__, '- wheel imports cleanly')
           "
 
-      - uses: actions/upload-artifact@v4
+      - uses: actions/upload-artifact@v7
         with:
           name: dist
           path: dist/

{specmod-0.2.3 → specmod-0.3.0}/.github/workflows/docs.yml

@@ -24,10 +24,14 @@ jobs:
   docs:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
         with:
           fetch-depth: 0   # hatch-vcs derives the version from tags
-      - uses: astral-sh/setup-uv@v5
+      # Pinned to a full version, unlike the other three. `astral-sh/setup-uv`
+      # publishes no bare major tag — `@v10` does not resolve, and using it
+      # fails every job at "Getting action download info", before a step runs.
+      # Bump this deliberately; do not "tidy" it to `@v10`.
+      - uses: astral-sh/setup-uv@v10.0.1
       - run: uv python install 3.11
       - run: uv venv # create a venv to install into
 
@@ -50,7 +54,7 @@ jobs:
 
       # 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
+      - uses: actions/upload-artifact@v7
         with:
           name: docs-html
           path: docs/_build/html

{specmod-0.2.3 → specmod-0.3.0}/.github/workflows/release.yml

@@ -77,7 +77,7 @@ jobs:
       id-token: write   # mandatory for Trusted Publishing
       contents: read
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
         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
@@ -85,7 +85,11 @@ jobs:
           ref: ${{ needs.release-please.outputs.tag_name }}
           fetch-depth: 0   # hatch-vcs derives the version by describing tags
 
-      - uses: astral-sh/setup-uv@v5
+      # Pinned to a full version, unlike the other three. `astral-sh/setup-uv`
+      # publishes no bare major tag — `@v10` does not resolve, and using it
+      # fails every job at "Getting action download info", before a step runs.
+      # Bump this deliberately; do not "tidy" it to `@v10`.
+      - uses: astral-sh/setup-uv@v10.0.1
       - run: uv python install 3.11
       - run: uv build
 

{specmod-0.2.3 → specmod-0.3.0}/.github/workflows/test.yml

@@ -14,8 +14,12 @@ jobs:
   lint:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: astral-sh/setup-uv@v5
+      - uses: actions/checkout@v7
+      # Pinned to a full version, unlike the other three. `astral-sh/setup-uv`
+      # publishes no bare major tag — `@v10` does not resolve, and using it
+      # fails every job at "Getting action download info", before a step runs.
+      # Bump this deliberately; do not "tidy" it to `@v10`.
+      - uses: astral-sh/setup-uv@v10.0.1
         with:
           enable-cache: true
       - run: uv python install 3.11
@@ -28,10 +32,14 @@ jobs:
   typecheck:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
         with:
           fetch-depth: 0   # hatch-vcs needs history to derive the version
-      - uses: astral-sh/setup-uv@v5
+      # Pinned to a full version, unlike the other three. `astral-sh/setup-uv`
+      # publishes no bare major tag — `@v10` does not resolve, and using it
+      # fails every job at "Getting action download info", before a step runs.
+      # Bump this deliberately; do not "tidy" it to `@v10`.
+      - uses: astral-sh/setup-uv@v10.0.1
         with:
           enable-cache: true
       - run: uv python install 3.11
@@ -48,10 +56,14 @@ jobs:
         os: [ubuntu-latest, macos-latest]
         python-version: ["3.11", "3.12", "3.13"]
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
         with:
           fetch-depth: 0
-      - uses: astral-sh/setup-uv@v5
+      # Pinned to a full version, unlike the other three. `astral-sh/setup-uv`
+      # publishes no bare major tag — `@v10` does not resolve, and using it
+      # fails every job at "Getting action download info", before a step runs.
+      # Bump this deliberately; do not "tidy" it to `@v10`.
+      - uses: astral-sh/setup-uv@v10.0.1
         with:
           enable-cache: true
       - run: uv python install ${{ matrix.python-version }}
@@ -64,7 +76,7 @@ jobs:
         # 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
+      - uses: codecov/codecov-action@v7
         if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.11'
         with:
           files: coverage.xml
@@ -73,10 +85,14 @@ jobs:
   floors:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
         with:
           fetch-depth: 0
-      - uses: astral-sh/setup-uv@v5
+      # Pinned to a full version, unlike the other three. `astral-sh/setup-uv`
+      # publishes no bare major tag — `@v10` does not resolve, and using it
+      # fails every job at "Getting action download info", before a step runs.
+      # Bump this deliberately; do not "tidy" it to `@v10`.
+      - uses: astral-sh/setup-uv@v10.0.1
       - run: uv python install 3.11
       - run: uv venv
       # Exercise the declared minimums. CI otherwise installs the newest of
@@ -92,10 +108,14 @@ jobs:
     # third kind, so it runs per-PR rather than at release.
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
         with:
           fetch-depth: 0
-      - uses: astral-sh/setup-uv@v5
+      # Pinned to a full version, unlike the other three. `astral-sh/setup-uv`
+      # publishes no bare major tag — `@v10` does not resolve, and using it
+      # fails every job at "Getting action download info", before a step runs.
+      # Bump this deliberately; do not "tidy" it to `@v10`.
+      - uses: astral-sh/setup-uv@v10.0.1
         with:
           enable-cache: true
       - run: uv python install 3.11

{specmod-0.2.3 → specmod-0.3.0}/.pre-commit-config.yaml

@@ -36,12 +36,18 @@ repos:
       # 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.
+      #
+      # The two vendored directories under `docs/_static/` are excluded for
+      # both reasons at once. Their `.woff2` files are binary, and the licences
+      # beside them have to stay byte identical to what upstream publishes —
+      # `trailing-whitespace` edited Merriweather's OFL the first time it was
+      # staged, which is a licence rewritten to satisfy a linter.
       - id: end-of-file-fixer
-        exclude: '\.spec$'
+        exclude: &verbatim '(\.spec$|^docs/_static/(fonts|katex)/)'
       - id: trailing-whitespace
-        exclude: '\.spec$'
+        exclude: *verbatim
       - id: mixed-line-ending
-        exclude: '\.spec$'
+        exclude: *verbatim
 
   - repo: https://github.com/kynan/nbstripout
     rev: 0.8.1

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

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

{specmod-0.2.3 → specmod-0.3.0}/CHANGELOG.md

@@ -9,6 +9,42 @@ release could have this problem — every later one has a real predecessor tag
 so leave subsequent headings as generated. release-please only prepends to this
 file, so this edit survives. -->
 
+## [0.3.0](https://github.com/sgjholt/SpecMod/compare/v0.2.3...v0.3.0) (2026-09-06)
+
+
+### ⚠ BREAKING CHANGES
+
+* the tutorial page moves from `/tutorial/SpecModTutorial.html` to `/tutorial/specmod-tutorial.html`.
+* the ten mutating functions in `specmod.preprocess` are renamed and now return a new stream or trace. `get_signal` is removed, and the two undated deprecation shims are gone.
+
+### Features
+
+* let the fitted band be capped, fixed or corrected by hand ([ba241a9](https://github.com/sgjholt/SpecMod/commit/ba241a95d94a298418b3c6f414a0026b9f310926))
+* preprocess returns new streams instead of mutating ([78aabeb](https://github.com/sgjholt/SpecMod/commit/78aabeb4856eda4208787fcd53b0df77bc50bd1c))
+
+
+### Bug Fixes
+
+* give the noise and bandwidth registries a documented home ([daeb2cc](https://github.com/sgjholt/SpecMod/commit/daeb2cc43eff2869e9617e4111f281f9bd4d33bb))
+* **transforms:** re-export every public name from base ([67c24c3](https://github.com/sgjholt/SpecMod/commit/67c24c3dda80f7fbc1bd51861861bde48d943eac))
+
+
+### Code Refactoring
+
+* **docs:** build the tutorial from a script too ([de846c6](https://github.com/sgjholt/SpecMod/commit/de846c6128fc7922df8e1e3c2c1c01f2b8bf95bb))
+* **docs:** one notebook builder per notebook, named after it ([0175f89](https://github.com/sgjholt/SpecMod/commit/0175f890f5f92668341a17bece7149f7d8f8c6b7))
+* split io and plotting into packages ([027b77f](https://github.com/sgjholt/SpecMod/commit/027b77f7d050716b7d98fc873a8a4e93098d1d68))
+
+
+### Documentation
+
+* adopt the academic theme from the branding manual ([76f0aa0](https://github.com/sgjholt/SpecMod/commit/76f0aa0a40a134eeb91b8ada04c8f5fa66243c54))
+* kebab-case the tutorial notebook, snake_case its builder ([5a65b73](https://github.com/sgjholt/SpecMod/commit/5a65b7336980bf5d7163c4cad28e7c273715c0a3))
+* measure the MathJax figure instead of asserting it ([cba7e01](https://github.com/sgjholt/SpecMod/commit/cba7e0116a09ba8d4565308ee8c0227d138b20cd))
+* render maths with KaTeX, served from this site ([902d3fe](https://github.com/sgjholt/SpecMod/commit/902d3fec4230e6af17ea1b7a9d32d9e9c153fd8e))
+* self-host the branding fonts ([c1e6f9f](https://github.com/sgjholt/SpecMod/commit/c1e6f9fe16f4ec48c5e788e6b29181c5ffc01bbf))
+* the decomposition is finished ([bbb2b71](https://github.com/sgjholt/SpecMod/commit/bbb2b7189b9f98c3baa48fe907bc2c414455f5d9))
+
 ## [0.2.3](https://github.com/sgjholt/SpecMod/compare/v0.2.2...v0.2.3) (2026-09-05)
 
 

{specmod-0.2.3 → specmod-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: specmod
-Version: 0.2.3
+Version: 0.3.0
 Summary: A Python toolbox for processing and modelling seismic spectra
 Project-URL: Homepage, https://github.com/sgjholt/SpecMod
 Project-URL: Repository, https://github.com/sgjholt/SpecMod
@@ -35,11 +35,12 @@ Requires-Dist: pytest-cov>=5.0; extra == 'dev'
 Requires-Dist: pytest>=8.0; extra == 'dev'
 Requires-Dist: ruff>=0.6; extra == 'dev'
 Provides-Extra: docs
+Requires-Dist: furo>=2024.1; extra == 'docs'
 Requires-Dist: myst-nb>=1.1; extra == 'docs'
 Requires-Dist: myst-parser>=3.0; extra == 'docs'
-Requires-Dist: pydata-sphinx-theme>=0.15; extra == 'docs'
 Requires-Dist: sphinx-togglebutton>=0.3; extra == 'docs'
 Requires-Dist: sphinx>=7.3; extra == 'docs'
+Requires-Dist: sphinxcontrib-katex>=0.9; extra == 'docs'
 Provides-Extra: io
 Requires-Dist: h5py>=3.11; extra == 'io'
 Requires-Dist: pyarrow>=16.0; extra == 'io'
@@ -179,13 +180,13 @@ changes nothing else.
 
 ## Reading picks
 
-Arrivals are attached to traces by `set_picks`, which detects the format from
-the file rather than from its name:
+`with_picks` returns a stream with arrivals attached, detecting the format
+from the file rather than from its name:
 
 ```python
 import specmod.preprocess as pre
 
-pre.set_picks(stream, "event.xml")
+stream = pre.with_picks(stream, "event.xml")
 ```
 
 Everything `obspy.read_events` parses is read through one delegate — QuakeML,

{specmod-0.2.3 → specmod-0.3.0}/README.md

@@ -122,13 +122,13 @@ changes nothing else.
 
 ## Reading picks
 
-Arrivals are attached to traces by `set_picks`, which detects the format from
-the file rather than from its name:
+`with_picks` returns a stream with arrivals attached, detecting the format
+from the file rather than from its name:
 
 ```python
 import specmod.preprocess as pre
 
-pre.set_picks(stream, "event.xml")
+stream = pre.with_picks(stream, "event.xml")
 ```
 
 Everything `obspy.read_events` parses is read through one delegate — QuakeML,

{specmod-0.2.3 → specmod-0.3.0}/docs/REFACTOR_PLAN.md

@@ -3571,7 +3571,7 @@ Each phase ends green on CI and is independently mergeable.
 | **2b. Release plumbing** ✅ | ~~Sphinx skeleton + `pydata-sphinx-theme` + autodoc/napoleon/intersphinx~~ ✅; ~~`docs.yml` → a published site~~ ✅ — Read the Docs rather than GH Pages, for versions (§6.3); ~~release-please + PyPI Trusted Publishing~~ ✅ — one `release.yml`, not two workflows (§6.5); ~~Zenodo webhook~~ ✅ documented. Five repository settings have to be turned on by hand: `docs/releasing.md` lists them. The `ci/` mirror that staged workflow files for hand-copying is gone — it existed because an agent token could not push `.github/workflows/`, and that permission is now granted. Parallel with 2 | 1 | 1–2 days |
 | **3. Transform layer** | `SpectralEstimator` protocol; `FFTEstimator`, `WelchEstimator`, `MultitaperEstimator`; `smoothing/` incl. Konno–Ohmachi and `LogBinner`; mtspec demoted to optional legacy backend; Tier 1 + Tier 2 tests; theory docs page | 2 | 5–7 days |
 | **4. CWT** | `CWTEstimator` + `Scalogram`; COI handling; the Parseval/units calibration and its test; `time_average()`; `ScalogramQC` + the four QC checks; COI floor into `BandwidthSelector`; scalogram plotting; HDF5 scalogram storage | 3 | 6–8 days |
-| **5. Decompose** | Split `Spectral.py` (655 lines) into `core/` + `snr/` ✅; ~~`Fitting.py` → `fitting/`~~ ✅ — `base`/`guess`/`spectrum`/`event`, 745 lines to four modules of 30–300, public names unchanged; models as objects ✅; `io/`; `viz/`; non-mutating operations; mypy override list → empty ✅; `picks/` per §4.9 ✅ | 3 | 4–6 days |
+| **5. Decompose** ✅ | Split `Spectral.py` (655 lines) into `core/` + `snr/` ✅; ~~`Fitting.py` → `fitting/`~~ ✅ — `base`/`guess`/`spectrum`/`event`, 745 lines to four modules of 30–300, public names unchanged; models as objects ✅; ~~`io/`~~ ✅ — `layout`/`hdf5`/`backend`; ~~`viz/`~~ ✅ — shipped as `plotting/`, `pair`/`grid`/`style`; ~~non-mutating operations~~ ✅ — `preprocess` was the last holdout, and the ten functions were renamed rather than only re-signatured so the break is loud; mypy override list → empty ✅; `picks/` per §4.9 ✅ | 3 | 4–6 days |
 | **6. Ship** | Full docs content, tutorial rewritten as an executed `myst-nb` page with no `os.chdir`, 0.1→1.0 "what changed" page, **1.0 release** | 4, 5 | 2–3 days |
 
 **Executing the tutorial was pulled forward out of Phase 6.** The `myst-nb`

specmod-0.3.0/docs/_builders/_notebook.py

@@ -0,0 +1,162 @@
+"""Shared machinery for the notebook builders in this directory.
+
+Every notebook in this repository is written by a script here, named after the
+notebook it writes. One copy of ``md``, ``code`` and the notebook envelope,
+rather than one per builder: the first builder carried all three inline, which
+was fine while there was one, and a second would have started by copying them.
+The two copies would then have drifted on cell metadata, ``nbformat_minor``, or
+the trailing newline — none of it visible in a rendered notebook, all of it
+noise in the diff of a regenerated one.
+
+The two notebooks do not live in the same place, and should not:
+
+``docs/notebooks/choosing-a-transform.ipynb``
+    Not published. ``choosing-a-transform.md`` is the page that carries this
+    material, and ``conf.py`` excludes ``notebooks/**``.
+
+``tutorial/specmod-tutorial.ipynb``
+    Published, and executed on every docs build. It stays outside ``docs/``
+    because it reads ``tutorial/data/events/`` through paths relative to
+    itself, and because eight other files name that directory.
+
+So a builder says where its notebook goes, and only the name is derived. This
+directory is the one place to look for all of them.
+
+Builders are **not** part of the published site — ``conf.py`` excludes
+``_builders/**`` — and are deliberately outside the ruff and mypy scopes,
+which ``.pre-commit-config.yaml`` pins to ``src/``, ``tests/`` and ``tools/``.
+They carry long prose lines and mathematical unicode that the source rules
+reject, so keep new builders here rather than under ``tools/``.
+"""
+
+from __future__ import annotations
+
+import json
+import pathlib
+from typing import Any
+
+#: The repository root: this file is ``<root>/docs/_builders/_notebook.py``.
+ROOT = pathlib.Path(__file__).resolve().parent.parent.parent
+
+#: Where a builder writes unless it says otherwise.
+NOTEBOOKS = ROOT / "docs" / "notebooks"
+
+#: The envelope a notebook gets when its builder does not supply one.
+DEFAULT_METADATA: dict[str, Any] = {
+    "kernelspec": {
+        "display_name": "Python 3",
+        "language": "python",
+        "name": "python3",
+    },
+    "language_info": {"name": "python", "version": "3.11"},
+}
+
+
+class NotebookBuilder:
+    """Cells in, one ``.ipynb`` out.
+
+    Prefer :func:`builder_for`, which takes the output name from the calling
+    script's own filename so the two cannot drift apart.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        *,
+        into: pathlib.Path = NOTEBOOKS,
+        metadata: dict[str, Any] | None = None,
+    ) -> None:
+        self.name = name
+        self.into = into
+        self.metadata = DEFAULT_METADATA if metadata is None else metadata
+        self.cells: list[dict[str, Any]] = []
+
+    def md(self, text: str) -> None:
+        """A markdown cell."""
+        self.cells.append(
+            {
+                "cell_type": "markdown",
+                "id": None,
+                "metadata": {},
+                "source": text.strip().splitlines(True),
+            }
+        )
+
+    def code(self, text: str) -> None:
+        """A code cell, with no outputs — the docs build executes it."""
+        self.cells.append(
+            {
+                "cell_type": "code",
+                "execution_count": None,
+                "id": None,
+                "metadata": {},
+                "outputs": [],
+                "source": text.strip().splitlines(True),
+            }
+        )
+
+    def write(self) -> pathlib.Path:
+        """Write the notebook and report where it went.
+
+        The output is what is committed, byte for byte —
+        ``tests/test_docs_are_current.py`` asserts it. That is why the cell
+        sources in a builder are written already formatted rather than being
+        passed through ``ruff format`` here: ruff is not importable from this
+        environment, and the pre-commit hook, CI and a local checkout pin
+        three different versions, so a formatting step at build time would
+        make "rebuilding changes nothing" depend on which ruff you had.
+        """
+        for position, cell in enumerate(self.cells):
+            # Sequential rather than the random hex `nbformat` assigns, so a
+            # regenerated notebook diffs against the committed one only where
+            # its content changed. Random ids would rewrite every cell.
+            #
+            # Filled in here, but the key is created in `md`/`code` so it lands
+            # in the position `nbformat` writes it. Key order is not meaningful
+            # to a notebook and is entirely meaningful to `git diff`.
+            cell["id"] = str(position)
+        notebook = {
+            "cells": self.cells,
+            "metadata": self.metadata,
+            "nbformat": 4,
+            "nbformat_minor": 5,
+        }
+        # Relative to this file, not to whoever happened to run it: the path
+        # was once hardcoded to one machine's checkout, so the script only
+        # worked there.
+        out = self.into / f"{self.name}.ipynb"
+        out.parent.mkdir(parents=True, exist_ok=True)
+        # `ensure_ascii=False`: the prose is full of em dashes and mathematical
+        # symbols, and `\\u2014` in a source file is unreadable and unsearchable.
+        out.write_text(json.dumps(notebook, indent=1, ensure_ascii=False) + "\n")
+        code_cells = sum(c["cell_type"] == "code" for c in self.cells)
+        print(f"wrote {out} — {len(self.cells)} cells ({code_cells} code)")
+        return out
+
+
+def builder_for(
+    script: str,
+    *,
+    into: pathlib.Path = NOTEBOOKS,
+    metadata: dict[str, Any] | None = None,
+) -> NotebookBuilder:
+    """The builder writing the notebook this script is named after.
+
+    Pass ``__file__``. ``choosing_a_transform.py`` writes
+    ``choosing-a-transform.ipynb``: underscores become hyphens, so each side
+    keeps the convention of its own language — ``snake_case`` for a Python
+    module, ``kebab-case`` for a file that becomes a URL on the published
+    site.
+
+    Deriving the name rather than repeating it is what makes the convention
+    hold. A builder and its notebook cannot be given different names without
+    renaming the file, so there is no way to end up with
+    ``_build_notebook.py`` again — a name that said nothing about which of
+    several notebooks it built.
+
+    ``into`` is the directory the notebook goes in, for the one that cannot
+    live beside the others.
+    """
+    return NotebookBuilder(
+        pathlib.Path(script).stem.replace("_", "-"), into=into, metadata=metadata
+    )