name: Python CI on: push: branches: [ "master", "main" ] # No base-branch filter, deliberately. A pull request that targets another # branch is the bottom half of a stack, and it is the half that still has to # be reviewed and merged: with `branches` set to main it arrived with four # checks instead of the thirty this workflow runs, and the gates only spoke # once it was already at the front of the queue. # # This does not double any run. The `push` trigger above is limited to the # two trunk branches, so a commit on a working branch fires `pull_request` # alone and a commit on main fires `push` alone. The two jobs that care which # one it was, `sonar` and `pr-comment`, key on `github.event_name` rather # than on the base, so they behave for a stacked pull request exactly as they # do for any other. pull_request: workflow_dispatch: permissions: contents: read jobs: quality: runs-on: ubuntu-latest permissions: contents: read steps: - uses: actions/checkout@v7 with: persist-credentials: false # A conflict resolved carelessly during a rebase can leave markers behind in # a file no other gate reads. CHANGELOG.md is the usual victim: it collides # on every parallel branch and nothing lints it, so the markers ride a fully # green pull request all the way to main. Only the opening and closing # markers are matched, never a bare row of "=", because that is legitimate # Markdown (a setext heading underline). - name: Check for merge-conflict markers run: | if git grep -nE '^(<{7} |>{7} )' -- . ; then echo "::error::Unresolved merge-conflict markers found in the files listed above." exit 1 fi - name: Set up Python 3.13 uses: actions/setup-python@v7 with: python-version: "3.13" cache: 'pip' - name: Install dependencies run: | python -m pip install --upgrade pip pip install -r requirements.txt pip install -r requirements-dev.txt pip install -r requirements-notebook.txt pip install -e . # The clips are the one committed asset CI never regenerates: an FDTD run # plus four video encodes each is far too slow for a pull request, and the # encoders are not bit-reproducible anyway. So nothing could tell that the # code drawing a clip had moved since the clip was written, and twelve of # them shipped an ASCII hyphen in their Spanish tick labels for months # after that was repaired, with every gate green. Each render stamps a # fingerprint of the code that drew it; this recomputes the fingerprints # from the sources and names any clip whose one has moved. It parses the # figure package rather than importing it, so it needs no rendering stack # and runs in seconds. The clips themselves live in # jmrplens/phonometry-assets, so "is every file there" is answered from # the tree of the commit assets.lock records: a blobless fetch of that one # commit is a few hundred kilobytes, where the clips are a third of a # gigabyte, and the check only ever needed the names. - name: Fetch the names of the published clips, without the clips run: | git init -q assets-tree git -C assets-tree remote add origin https://github.com/jmrplens/phonometry-assets.git git -C assets-tree fetch -q --depth 1 --filter=blob:none origin "$(cat assets.lock)" git -C assets-tree ls-tree -r --name-only FETCH_HEAD images/ > assets-manifest.txt echo "$(wc -l < assets-manifest.txt) clip files published at $(cut -c1-12 assets.lock)" - name: Check every published clip matches the code that draws it run: python scripts/check_animation_freshness.py --manifest assets-manifest.txt - name: Lint with Ruff run: ruff check . # Ruff is also the formatter. Before this step the tree had no formatter at # all and 673 of its 812 Python files disagreed with any single style; the # gate is what keeps that from happening again. Markdown is excluded in # `[tool.ruff]`, so this never touches the documentation snippets. - name: Check formatting with Ruff run: ruff format --check . # `stub/src` is in this list because it was in no path list at all. The # PyOctaveBand transition shim lives outside the package this repository # installs, so nothing here ever imported or type checked it, and two # defects reached its published page that way. Ruff walks the tree from # `.` and has always reached the shim; mypy takes the paths it is given, # and this one was never among them. `tests/static_typing` holds what # only a type checker can see, such as a published catalogue joined with # a caller's being accepted by a lookup's `catalogue=`: the suite runs # those files, but a wrong annotation passes at run time. - name: Type check with Mypy run: mypy src scripts stub/src tests/static_typing - name: Security check with Bandit run: bandit -r src # The workflows hold the repository's tokens and the release's identity, and # nothing reviewed them: the release step expanded `${{ }}` straight into a # shell, eight checkouts left their token in .git for any later step to # read, and the mirror ran on a workflow_run trigger that had never fired. # zizmor reads every file under .github/ and fails on any finding; its # settings, including the rule that actions are pinned to a tag, are in # .github/zizmor.yml. The token lets it ask GitHub whether a pinned action # has a published advisory. - name: Audit the workflows with zizmor env: GH_TOKEN: ${{ github.token }} run: zizmor --config .github/zizmor.yml --format github .github/ # The PyOctaveBand transition stub under stub/ is built from the tree by a # workflow_dispatch publish job, so until now the first time anything looked # at it was the moment it went to PyPI: a README that named the wrong # warning class and a dependency line with no ceiling were both discovered # after they had shipped. Building it on every pull request costs seconds # and moves `twine check` (which is what renders the long description and # would reject a malformed one) to where a mistake is still cheap. transition-stub: name: Transition stub builds and its metadata is sound runs-on: ubuntu-latest permissions: contents: read steps: - uses: actions/checkout@v7 with: persist-credentials: false - name: Set up Python 3.13 uses: actions/setup-python@v7 with: python-version: "3.13" - name: Build the stub and check its long description run: | python -m pip install --upgrade pip build twine python -m build stub/ twine check stub/dist/* # The resolver reads the built metadata, not stub/pyproject.toml, so the # cap that keeps `pip install -U PyOctaveBand` on the line whose API the # shim re-exports is asserted where it will actually be enforced. - name: Fail if the built metadata does not cap phonometry below the next major run: python scripts/check_stub_metadata.py # Fast gate (runtime deps only, no pytest): the committed # docs/conformance.json, the docs/CONFORMANCE.md rendered from it, and every # count quoted from either must equal a fresh `make conformance` run. conformance: name: Conformance report up to date runs-on: ubuntu-latest permissions: contents: read steps: - uses: actions/checkout@v7 with: persist-credentials: false - name: Set up Python 3.13 uses: actions/setup-python@v7 with: python-version: "3.13" cache: 'pip' - name: Install runtime dependencies run: | python -m pip install --upgrade pip pip install -r requirements.txt pip install -e . - name: Regenerate the conformance artefact, the report and the quoted counts run: make conformance # `make conformance` now writes as well as reads: it regenerates the report # and rewrites the counts quoted in .zenodo.json, the docs/ mirror and the # site frontmatter. So the staleness gate has to cover the whole tree, not # just the report. Diffing only docs/CONFORMANCE.md would let the rewrite # fix the prose in the runner's checkout and pass, while the branch keeps # the stale numbers. - name: Fail if the committed report or any quoted count is stale run: | # --porcelain rather than `git diff`, because a diff is blind to an # untracked file and the artefact is one of the things this regenerates. # docs/conformance.json arrived untracked once and the job went green # while a fresh checkout could not build the site at all. if [ -n "$(git status --porcelain)" ]; then git status --porcelain git diff echo "::error::The conformance artefact, the report or a count quoted from either is out of date, or a generated file is untracked - run 'make conformance' and commit the result." exit 1 fi # Belt and braces, and the command to run locally: the read-only check on # the committed state. The report can be current while the prose quoting it # is not; the counts were typed out in three places and two of them fell a # release behind. - name: Fail if any page quotes a stale conformance count run: python scripts/check_conformance_claims.py # The artefact is committed, so it can be wrong in ways a regeneration # diff cannot see: a count that no longer matches its rows, a numpy scalar # where a float belongs, a citation whose split no longer rebuilds it, a # dead line in the override ratchet. This reads what is committed and says # which one. - name: Fail if the committed artefact is not internally consistent run: python scripts/check_conformance_artifact.py # The artefact's closed vocabularies are restated by the site: once in the # Zod schema that validates it into the content collection, once in the # label maps that word a verdict and a relation in each language. Nothing # compared them until this, and a relation added to the reader and missing # from the schema stopped the site build with a content error naming ten # checks and no cause. Cheap and stdlib-only, so it runs here rather than # waiting for the docs workflow to build the site. - name: Fail if the site does not accept and word every vocabulary run: python scripts/check_conformance_vocabulary.py # Drift gate for the generated Starlight API reference: the committed pages # under site/src/content/docs/reference/api and the sidebar fragment must # equal a fresh `make api-docs` run (deterministic, stdlib-only generator). api-docs: name: Generated API reference up to date runs-on: ubuntu-latest permissions: contents: read steps: - uses: actions/checkout@v7 with: persist-credentials: false - name: Set up Python 3.13 uses: actions/setup-python@v7 with: python-version: "3.13" cache: 'pip' - name: Install runtime dependencies run: | python -m pip install --upgrade pip pip install -r requirements.txt pip install -e . - name: Regenerate the API reference run: make api-docs - name: Fail if the committed API reference is stale run: | if ! git diff --exit-code -- site/src/content/docs/reference/api site/src/generated; then echo "::error::The generated API reference is out of date - run 'make api-docs' and commit the result." exit 1 fi untracked=$(git ls-files --others --exclude-standard -- site/src/content/docs/reference/api site/src/generated) if [ -n "$untracked" ]; then echo "::error::Generated API pages are not committed:" echo "$untracked" exit 1 fi # Drift gate for the llms artifacts: the committed llms.txt, llms-full.txt, # the shards under site/public/llms and the generated overview mirrors under # docs/ must equal a fresh `make llms` run. Every other generated artifact # had this gate; these were regenerated by the docs workflow and never # compared, so a stale commit could not be told from a fresh one. llms: name: llms artifacts up to date runs-on: ubuntu-latest permissions: contents: read steps: - uses: actions/checkout@v7 with: persist-credentials: false - name: Set up Python 3.13 uses: actions/setup-python@v7 with: python-version: "3.13" - name: Regenerate the llms artifacts run: make llms - name: Fail if the committed artifacts are stale run: | if ! git diff --exit-code -- llms.txt llms-full.txt site/public/llms docs; then echo "::error::The llms artifacts are out of date - run 'make llms' and commit the result." exit 1 fi untracked=$(git ls-files --others --exclude-standard -- site/public/llms docs) if [ -n "$untracked" ]; then echo "::error::Generated llms files are not committed:" echo "$untracked" exit 1 fi # Drift gate for the evidence pages the site renders from docs/: the entries # of docs/ERRATA.md and docs/ERRATA.es.md are transplanted into one # reference/errata page per document family and an index (EN + ES), so the # site can never show a hand-copied or stale version of them. The # conformance pages are no longer transplanted - they render from # docs/conformance.json through src/components/Conformance.astro, which the # `conformance` job gates instead. site-reports: name: Generated evidence pages up to date runs-on: ubuntu-latest permissions: contents: read steps: - uses: actions/checkout@v7 with: persist-credentials: false - name: Set up Python 3.13 uses: actions/setup-python@v7 with: python-version: "3.13" # Stdlib-only generator: no project install needed, it only reshapes text. - name: Check the transplanted errata pages run: python scripts/generate_site_reports.py --check # Evidence gate for docs/ERRATA.md. Each entry there is a permanent public # statement that a named body or author printed something wrong, so it must # cite the page it quotes rather than an extraction: PDF text layers delete # radicals and minus signs silently, and one entry was drafted on an # extraction that had eaten a square root, and caught in review. The script # flags any multiplicative claim whose ratio sits on sqrt(2), sqrt(3), pi, # 2 pi, 1/sqrt(2), ln 2 or a small integer, which is the signature of a lost # glyph. See scripts/check_errata_evidence.py and CONTRIBUTING.md. errata-evidence: name: Errata entries cite their page runs-on: ubuntu-latest permissions: contents: read steps: - uses: actions/checkout@v7 with: persist-credentials: false - name: Set up Python 3.13 uses: actions/setup-python@v7 with: python-version: "3.13" # Stdlib-only checker: it reads docs/ERRATA.md and nothing else. - name: Check the errata evidence run: python scripts/check_errata_evidence.py # The Python fences of a page form one sequential example: a later fence may # use names an earlier fence defined, never the reverse. One shipped page # used names its own figure block defined further down, while a same-named # variable from a different room sat in scope, so reading top to bottom gave # numbers that were not the annotated ones. Reader-owned placeholders (the # reader's measurement, never invented by the page) are registered in the # script. See scripts/check_fence_names.py and # docs/contributing/docs-and-figures.md#f17. fence-names: name: Documentation fences read in order runs-on: ubuntu-latest permissions: contents: read steps: - uses: actions/checkout@v7 with: persist-credentials: false - name: Set up Python 3.13 uses: actions/setup-python@v7 with: python-version: "3.13" # Stdlib-only checker: it parses the fences and imports nothing else. - name: Check the fence reading order run: python scripts/check_fence_names.py # Coverage gate for the curated quick table in docs/reference/api/index.md: every # phonometry.__all__ name must have a table row (extra rows such as methods # or namespace entries are fine). See scripts/check_api_reference.py. api-reference-table: name: Curated API quick table covers __all__ runs-on: ubuntu-latest permissions: contents: read steps: - uses: actions/checkout@v7 with: persist-credentials: false - name: Set up Python 3.13 uses: actions/setup-python@v7 with: python-version: "3.13" cache: 'pip' - name: Install runtime dependencies run: | python -m pip install --upgrade pip pip install -r requirements.txt pip install -e . - name: Check docs/reference/api/index.md coverage run: python scripts/check_api_reference.py # A pressure of 101 325 and a pressure of 101.325 are both legitimate values # here: the ISO 3740 family prints kilopascals, IEC 61094-2 and ISO 15186-3 # print pascals, and the result of the mix-up is still a float. No guard by # magnitude can separate them, because either reading is a real duty # somewhere else in the tree, so the unit lives in the parameter name and # this holds it there. It walks the imported package rather than the source # tree, because ReportMetadata is published from the root and defined in a # private module, and a scan by file path does not see it. parameter-units: name: Every public quantity names its unit runs-on: ubuntu-latest permissions: contents: read steps: - uses: actions/checkout@v7 with: persist-credentials: false - name: Set up Python 3.13 uses: actions/setup-python@v7 with: python-version: "3.13" cache: 'pip' - name: Install runtime dependencies run: | python -m pip install --upgrade pip pip install -r requirements.txt pip install -e . - name: Check that no public name or constant hides its unit or misspells it run: python scripts/check_parameter_units.py # The same walk holds every public identifier, and every value a caller # types, to the American spelling the library is written in, and in situ # to in_situ: a caller who wrote center_frequency on one function should # not meet centre_frequency on the next. - name: Check that every public identifier is spelled in American English run: python scripts/check_identifier_spelling.py # The same walk holds every public choice of a fixed set of strings to a # Literal of its options, so a type checker refuses a misspelt option # before the call runs; a string open by its nature says why. - name: Check that every fixed public choice is typed Literal run: python scripts/check_choice_literals.py # A published table is shared by every caller in the process, so a dict # behind a `Mapping` annotation, or a writeable array, lets one caller change # a printed number for everyone after it without anything raising. This holds # every value reachable from a public name to immutable containers all the # way down. It walks the imported package, like parameter-units, because a # table built by a function call only shows its type once it exists. frozen-constants: name: Every published table refuses writes runs-on: ubuntu-latest permissions: contents: read steps: - uses: actions/checkout@v7 with: persist-credentials: false - name: Set up Python 3.13 uses: actions/setup-python@v7 with: python-version: "3.13" cache: 'pip' - name: Install runtime dependencies run: | python -m pip install --upgrade pip pip install -r requirements.txt pip install -e . - name: Check that no published constant can be changed in place run: python scripts/check_frozen_constants.py # A value transcribed from a book is only checkable if the next reader can # open the same page. The convention lived in review until a table came to # cite a folio its page does not print and another attributed to a table two # columns it does not carry. This holds every published record that carries a # `source` to the grammar the errata registry uses, and every table # transcribed from a book or a paper to a banner naming both its PDF page and # its printed folio; a standard stays outside, because it numbers its own # clauses and tables and is cited by that number. It walks the imported # package, like the units guard, and re-runs its own census over the banners # so a table from a new book fails until it is registered. published-sources: name: Every published value names its page runs-on: ubuntu-latest permissions: contents: read steps: - uses: actions/checkout@v7 with: persist-credentials: false - name: Set up Python 3.13 uses: actions/setup-python@v7 with: python-version: "3.13" cache: 'pip' - name: Install runtime dependencies run: | python -m pip install --upgrade pip pip install -r requirements.txt pip install -e . - name: Check that every published value cites its page and folio run: python scripts/check_published_sources.py - name: Check that every published catalogue reaches the catalogues page run: python scripts/check_published_catalogues_reach_the_page.py # The site renders the catalogues from a module this dumps, so a row added # to a data file without regenerating it would leave the page showing the # catalogue as it was. Same arrangement as the API reference: the artefact # is committed and CI checks it against a fresh run. - name: Check the catalogue data the site renders run: python scripts/generate_catalogue_data.py --check # The JSON Schema of a catalogue file is written from the row classes, so # a field added to one would be missing from every editor that completes # a catalogue file until the published schema is written again. - name: Check the catalogue schema the site publishes run: python scripts/generate_catalogue_schema.py --check # The solids catalogue's point is that a published value is worth more beside # another published value than alone, and four books print the same material. # Two densities that disagree are a digit somebody typed wrong, because every # density the script does not already accept agrees across these tables to # within 2,6 per cent, so it fails above 8 per cent and lets anything under # that pass without a word. Moduli and speeds disagree by thirty per cent # between books without anybody being wrong, so those it reports and never # fails; the ones it reports by default are the few an order of magnitude # apart, which is how tin's twelvefold modulus surfaced. It walks the # imported package, like the units and sources guards. solid-agreement: name: The books agree about the solids they share runs-on: ubuntu-latest permissions: contents: read steps: - uses: actions/checkout@v7 with: persist-credentials: false - name: Set up Python 3.13 uses: actions/setup-python@v7 with: python-version: "3.13" cache: 'pip' - name: Install runtime dependencies run: | python -m pip install --upgrade pip pip install -r requirements.txt pip install -e . - name: Check that the books agree about the solids they share run: python scripts/check_solid_agreement.py # The same idea over every catalogue: two books that credit one study for # one material are two readings of one measurement, and a pair that does # not overlap is a misread page rather than a disagreement. - name: Check the rows two books took from the same place run: python scripts/check_shared_sources.py # The committed documentation figures (.github/images) must match a fresh # `make graphs` run. The rendering + compute stack is pinned in # requirements-figures.txt so SVG *structure* (elements, text, colours) and # WebP dimensions/encoding are stable -- matplotlib/fonttools/pillow fix the # layout, numpy/scipy fix the computed data. The pin is also load-bearing # for the diagram plates' baked glyph outlines (scripts/diagrams/outline.py # shapes them through the wheel's FT2Font/libraqm and DejaVu faces): a wheel # bump rewrites every glyph in all 592 plate files and is reviewed as its # own regeneration. The comparison itself (scripts/check_figures.py) is # tolerance-aware rather than a byte diff: GitHub's heterogeneous runner # CPUs shift a few path coordinates ~1 ULP, which is visually irrelevant but # breaks a byte compare. Bump the pinned stack together with a fresh # `make graphs` regeneration. figures: name: Documentation figures up to date runs-on: ubuntu-latest permissions: contents: read steps: - uses: actions/checkout@v7 with: persist-credentials: false - name: Set up Python 3.13 uses: actions/setup-python@v7 with: python-version: "3.13" cache: 'pip' - name: Install the locked figure-rendering stack run: | python -m pip install --upgrade pip pip install -e . # Pin the render+compute stack last so it wins over looser deps. pip install -r requirements-figures.txt - name: Fail if any label's mathematics does not parse # Before the regeneration, not after: an unparseable label aborts the # generation, and this names the file and line instead of leaving a # traceback in the middle of a four-hundred-figure run. Reads the # sources, so it costs seconds and covers labels no figure exercises. run: python scripts/check_mathtext.py - name: Fail if a Spanish label would keep an English decimal point # The one defect the language gate structurally cannot see: it compares # untranslated WORDS, and a number is not a word. Static, so it needs no # generation run. run: python scripts/check_decimal_comma.py - name: Regenerate figures and diagrams run: make graphs - name: Regenerate the plates again and demand identical bytes # The diagram plates bake their labels to glyph outlines and must be # bit-deterministic: two runs in the same job have to agree byte for # byte, which is stronger than the tolerance gate below and catches an # accidentally unordered collection in the glyph store the moment it # appears. run: | mkdir /tmp/plates-first-run cp .github/images/diagram_*.svg .github/images/sound_power_methods*.svg /tmp/plates-first-run/ python scripts/generate_diagrams.py for f in /tmp/plates-first-run/*.svg; do cmp "$f" ".github/images/$(basename "$f")" done - name: Fail if any committed figure is stale # Tolerance-aware compare instead of a byte diff: GitHub's runner fleet is # hardware-heterogeneous, so the pinned stack computes a few path # coordinates ~1 ULP apart depending on the CPU the run lands on. That # sub-pixel drift is irrelevant but breaks a byte diff; the script checks # SVG structure + numeric tolerance and raster RMS instead, so real figure # changes still fail while cross-CPU noise passes. See scripts/check_figures.py. run: python scripts/check_figures.py - name: Fail if any shaded region is illegible # Staleness says the figures match the code; it says nothing about # whether a shaded region can be seen. This measures every filled area # against the page it is drawn on and fails below the CIEDE2000 # threshold, which is what catches a fill tuned on one theme and left # invisible on the other. It parses the committed SVGs (a few seconds # for the whole set) and needs no rendering stack of its own. run: python scripts/check_figure_contrast.py - name: Check every line can be seen on the dark page # The step above measures filled areas. A stroke is not a fill, and the # ISO 3745 microphone array shipped with its hemisphere drawn in a # half-opacity grey hairline that composited to 1.3:1 on the dark theme: # present in the SVG, invisible to a reader, and green on every gate. # This blends each stroke with its own opacity over the dark page and # holds hairlines to 3:1 and thicker lines to 2:1, with the grid and axis # furniture exempt because they are drawn to recede. run: python scripts/check_stroke_contrast.py - name: Check the Spanish figures are in Spanish # The Spanish variant of a figure is the English one with its strings # looked up in a table at save time, so a string nobody added to the # table ships in English inside `X_es.svg` while every other gate stays # green: the page is Spanish, the i18n parity gate sees a translated # page, this job sees a figure that matches its generator, and the # figure is in English. That is how roughly two hundred of them reached # the tree. The lookup itself writes down what it could not translate, # during the `make graphs` above (no second render, and it cannot change # a rendered byte), and this fails on any untranslated string the # committed baseline does not already record -- and on a baseline line # that has been paid off and not deleted. run: python scripts/check_figure_language.py - name: Fail if an annotation on a figure cannot be read # Two ways a label fails the reader, and nothing else can see either. A # label across a curve and given no backing is hard to read: the strokes # of the letters and of the curve are the same weight, and on the dark # page close to the same lightness. A label something is drawn over is # not there at all. The figure matches its generator, the contrast steps # above measure fills and strokes rather than what overlaps what, and # `svg.fonttype = "path"` means the committed file has no text node to # find the label in -- so the measurement has to happen while the # matplotlib artists are alive, which is what the `make graphs` above # did, for both language editions. This reads it and fails on any label # over the calibrated number of pixels either way, printing the band # below that for a person to judge. run: python scripts/check_figure_annotations.py - name: Fail if two tick labels of one axis run into each other # A band axis set by hand on a logarithmic scale keeps matplotlib's own # minor labels between the bands unless the minor formatter is cleared: # the octave axis of enclosed_space_absorption shipped reading # "2 × 10²50 4 × 10²500" under both panels. The figure matches its # generator, the annotation step above measures the labels a generator # places and not the ones an axis draws, and the committed file has no # text node to find a tick in, so the `make graphs` above measures every # axis of both language editions as it saves them. This fails on minor # labels left to the scale beside major ticks set by hand, and on any # two labels of one axis that touch. run: python scripts/check_figure_ticks.py - name: Fail if a Spanish figure numbers a tick with an English point # The decimal-comma check above reads the label a generator writes; this # reads the label a formatter wrote, in the figure as committed. They are # different halves: three machines localise a Spanish figure (the # library's localize_axes, format_frequency_axis where a caller hands it # the language, and the save-time pass), and a panel none of them reached # keeps its English point while the legend beside it carries the comma. # A zoom inset, a contour colorbar, the z of a 3-D array and a log axis # of distances each shipped that way. Reads the committed SVGs, so it # needs no rendering stack. run: python scripts/check_figure_decimal_point.py - name: Fail if a legend closes over a plotted point # A legend is an opaque plate the author places by hand, and its width is # set by its longest label, which is a defect waiting to happen in a # bilingual corpus: the Spanish label is routinely half again as long as # the English one, so a box that clears the data in one language reaches # back over it in the other. Every other gate stays green, because the # figure matches its generator, the colours pass and the annotation audit # measures labels rather than legends. This reads the committed SVGs for # a plotted point under a legend frame, and carries the drawings where # the mark under the box is a rail rather than a reading with the reason # each one is a decision. run: python scripts/check_figure_legends.py - name: Fail if a legend, a curve or a marker covers a tick label # A legend can land on a tick label as well as on a point, and a curve # can run through one: the radial labels of a polar plot sit inside it, # strung along one ray, and an inset writes its labels over the data of # the panel it sits in. The tick step above measures the labels of one # axis against each other and the annotation step the labels a # generator places, so neither sees it. This reads the committed SVGs # for anything drawn over a tick label, through the clip it is drawn # with, so it needs no rendering stack. run: python scripts/check_figure_tick_clearance.py - name: Fail if a label is drawn over a tick label, another label or a line # The step above measures the marks drawn over a tick label, not a # text, and the annotation step leaves the plates out. A note placed by # hand landed on the numbers of the axis beside it, the heading of a # plate lane was crossed by the impulse it names, and a note that ran # out of its axes was struck through by the spine. This reads the # committed SVGs, figures and plates, glyph by glyph, so a label turned # on a 3-D plate is read along its own baseline; the leader of an # annotation, the grid and a line behind a chip pass. run: python scripts/check_figure_text_clearance.py - name: Fail if a figure signs a number with a hyphen # The corpus signs its negative numbers with U+2212, and a polar angle # formatter that ignores axes.unicode_minus, a reading built with an # f-string and a plate that sets the characters it is handed each wrote # the hyphen-minus instead, a shorter, lower glyph beside the proper one. # This reads the string every committed SVG records beside its outlines, # all four variants, figures and plates alike. run: python scripts/check_figure_minus_sign.py # The Python snippets printed in the guides must run. They are the first # thing a reader copies, and nothing executed them until this job existed: # the metrology split shipped seven blocks where `from phonometry import # signals` sat next to `from scipy import signal` and silently rebound the # name, which Python does not warn about and no other gate can see. The # script also holds the English and Spanish pages to the same API and skips, # with a written reason, the pages whose blocks are excerpts of a workflow # rather than a script. doc-snippets: name: Documentation snippets run runs-on: ubuntu-latest permissions: contents: read steps: - uses: actions/checkout@v7 with: persist-credentials: false - name: Set up Python 3.13 uses: actions/setup-python@v7 with: python-version: "3.13" cache: 'pip' # The video guide's examples encode, so the snippets run where ffmpeg is. - name: Install ffmpeg run: | sudo apt-get update -q sudo apt-get install -y -q --no-install-recommends ffmpeg - name: Install dependencies # The guides plot and print fiches, so the snippets need the figure and # report stacks as well as the package itself. run: | python -m pip install --upgrade pip # The audio extra rides along because the io guide's snippets read and # write the formats it serves; a guide that documents the extra has to # run under it, the same reason the figure and report requirements are # here for the pages that draw and render. pip install -e ".[audio]" pip install -r requirements-figures.txt -r requirements-reports.txt # The contributor guide's examples of tests wait on errors with # pytest.raises, so its pinned pytest is installed too. grep -E '^pytest==' requirements-dev.txt | cut -d' ' -f1 > snippet-tools.txt pip install -r snippet-tools.txt - name: Run every snippet the guides print run: python scripts/check_doc_snippets.py # The guides are hard-wrapped, so a sentence can wrap onto a "-" or a ">" and # stop being a sentence: CommonMark ends the paragraph at the marker. One # variant takes the site build down (unclosed inline maths, which MDX then # evaluates as JavaScript); the other is silent and ships a quoted block in # the middle of a paragraph. Needs no dependencies, so it runs on its own # rather than waiting behind an install. markdown-hazards: name: Markdown renders the way it reads runs-on: ubuntu-latest permissions: contents: read steps: - uses: actions/checkout@v7 with: persist-credentials: false - name: Set up Python 3.13 uses: actions/setup-python@v7 with: python-version: "3.13" - name: Check the hand-written markdown run: python scripts/check_markdown_hazards.py - name: Every script reads a fence the one way # Where a fence closes is decided in scripts/markdown_fences.py, as # CommonMark decides it, for the markdown check above and every other # script that reads a page, and in site/src/lib/markdown-fences.mjs, the # same reading in JavaScript, for the site's own code. Four scripts and # four pieces of the site used to work it out by themselves, each right # on the pages it was written against and each reading a fence shown # inside another fence inside out. Static, stdlib only, so it runs here # with the checks that use the shared reader. run: python scripts/check_fence_readers.py - name: No em dash in the published prose # The house style writes its prose without the em dash, in the pages, # the mirrors, the CHANGELOG, the docstrings and the figure labels # alike; a standard's title reproduced as printed keeps its own. Static, # stdlib only, so it runs here with the markdown checks. run: python scripts/check_em_dashes.py - name: Every install command quotes its extras # zsh reads the brackets of an extras requirement as a glob and stops # before pip runs, so every install command a reader copies (the pages, # the docstrings, the library's messages, the README, the llms files, # the CHANGELOG) quotes the requirement that carries extras. Static, # stdlib only, so it runs here with the markdown checks. run: python scripts/check_quoted_extras.py - name: Every Spanish label keeps its accents, eñes and glossary terms # A translation typed without the Spanish keyboard layout reads fine to # every other gate, and twenty-nine figure labels shipped as # "Correccion", "medicion" and "aqui". This reads the translation tables # of the figures, the diagrams and the library's renderers, the labels # of every committed Spanish figure, and the example fiches built in # Spanish, and fails on a form that is never correct Spanish without # its mark. It reads the Spanish pages too for the translation # glossary, which a word it has replaced passes every other gate: # «seno» for the waveform and «incertidumbre extendida» shipped in # about fifty places, and «media cuadrática» or «cuadrado medio» for # the mean square in two diagrams, two figures, two renderers, seven # pages and an erratum, and «presupuesto», which is money, for a # budget of decibels, absorption or error (a «balance») in sixteen # pages and a diagram. «Cuadrado medio» passes only in a sentence of # an analysis of variance, one that names the analysis, the mean # square by its row, or the header of its table. Static, stdlib only, # so it runs here with the other checks on published text. run: python scripts/check_spanish_accents.py # A form feed is one invisible byte, and inside a raw docstring it is the # backslash and the f of the command that follows it: `\frac` was published # as `rac`, with the fraction gone and no error anywhere. Guard the class # rather than the byte. Needs no dependencies, so it runs on its own. control-characters: name: No stray control character runs-on: ubuntu-latest permissions: contents: read steps: - uses: actions/checkout@v7 with: persist-credentials: false - name: Set up Python 3.13 uses: actions/setup-python@v7 with: python-version: "3.13" - name: Check the tracked text files run: python scripts/check_control_characters.py # ISO 80000-2 sets a subscript by what it is, and a glyph pair can honestly # take both slopes: the z of the ISO 9613-2 barrier screening is a # path-length difference, the z of the ISO 2631-5 dose is a direction, and # both documents print D_z. So the slope is decided per file, which opens # with the standard it implements, and two slopes for one symbol inside one # file is a page contradicting itself. Static and dependency-free, so it runs # on its own rather than waiting behind an install. subscript-slope: name: One meaning per subscript per file runs-on: ubuntu-latest permissions: contents: read steps: - uses: actions/checkout@v7 with: persist-credentials: false - name: Set up Python 3.13 uses: actions/setup-python@v7 with: python-version: "3.13" - name: Check that no file sets one subscript both ways run: python scripts/check_subscript_slope.py # ISO 80000-2 prints the mathematical constants upright, and an italic e is a # variable. KaTeX and mathtext set a bare letter italic, so the exponential is # upright only where the source asks for it, and the corpus had both. Static # and dependency-free, like the subscript gate beside it. euler-number: name: Euler's number is upright runs-on: ubuntu-latest permissions: contents: read steps: - uses: actions/checkout@v7 with: persist-credentials: false - name: Set up Python 3.13 uses: actions/setup-python@v7 with: python-version: "3.13" - name: Check that no formula sets the exponential's e in italic run: python scripts/check_euler_number.py # generate_api_docs copies the mathematics of a docstring to the site # verbatim, and KaTeX reads what the docstring actually holds. A doubled # backslash is a line break with a command after it, which KaTeX refuses, # and the page still ships with everything after the bad block swallowed. # The same four characters are correct in one kind of docstring and wrong in # the other, so this reads the value Python builds rather than the file. It # also refuses a bare command KaTeX will not take as a sub- or superscript # (|dL_n|_\max where |dL_n|_{\max} is meant), in the docstrings and in the # hand-written pages. The site job catches both too, after a full build; this # costs a second and runs without one. docstring-math: name: Docstring mathematics reaches the page intact runs-on: ubuntu-latest permissions: contents: read steps: - uses: actions/checkout@v7 with: persist-credentials: false - name: Set up Python 3.13 uses: actions/setup-python@v7 with: python-version: "3.13" - name: Check the docstrings and the pages for mathematics KaTeX refuses run: python scripts/check_docstring_math.py # Every helper that takes a language defaults to English, so a call that does # not pass the caller's on raises nothing and ships an English string or an # English decimal point in the Spanish figure. On a log frequency axis nothing # in the library repairs it: localize_axes skips that axis, whose labels are # fixed strings by the time it runs. Finding the calls needs the helper resolved # through the imports, a result's .plot() through its receiver and a **kwargs # through what it can carry, so the check is an AST walk rather than a grep. # Static and dependency-free, so it runs on its own. language-forwarding: name: Every call passes the language on runs-on: ubuntu-latest permissions: contents: read steps: - uses: actions/checkout@v7 with: persist-credentials: false - name: Set up Python 3.13 uses: actions/setup-python@v7 with: python-version: "3.13" - name: Check that no call leaves the caller's language behind run: python scripts/check_language_forwarding.py - name: Check that no style default collides with its own alias run: python scripts/check_plot_style_defaults.py - name: Check that no grouped number can break across a line run: python scripts/check_digit_grouping.py # A private module-level constant is a number lifted out of a standard so the # code that uses it can say where it came from, and one nothing reads is # either a leftover or the trace of a check the docstring above it still # promises. The sweep this came from found both: a recommended specimen # velocity carried and never checked, and a docstring promising a default the # code did not take. Static and dependency-free, so it runs on its own. dead-constants: name: No private constant goes unread runs-on: ubuntu-latest permissions: contents: read steps: - uses: actions/checkout@v7 with: persist-credentials: false - name: Set up Python 3.13 uses: actions/setup-python@v7 with: python-version: "3.13" - name: Check that every private constant is read somewhere run: python scripts/check_dead_constants.py # A pytest.raises, pytest.warns or pytest.deprecated_call block passes on # whatever call inside it raises or warns. Seven writer tests built their # catalogue inside the block of the write they checked, and six warning # tests built their case inside the block of the model, so a refusal from # the builder would have passed for the one under test. Ruff holds the block # to one statement; this holds the statement to one call that could raise # or warn, with SonarCloud's own definition (S5778, S9088), so the mistake # is caught before a pull request rather than after. # Static and dependency-free, so it runs on its own. raises-blocks: name: Every exception test waits on one call runs-on: ubuntu-latest permissions: contents: read steps: - uses: actions/checkout@v7 with: persist-credentials: false - name: Set up Python 3.13 uses: actions/setup-python@v7 with: python-version: "3.13" - name: Check that no raises, warns or deprecated_call block holds a second call run: python scripts/check_raises_blocks.py # A level is a ratio to a reference value, and ISO 1683 fixes one per # quantity. The package publishes them once, as # phonometry.metrology.REFERENCE_VALUES; before that the same 20 µPa # was typed out seventeen times and one name meant a pressure in four modules # and a power in two. This fails on a reference value in src that repeats a # value of the table instead of reading it, and on one that differs from it # without naming the document it comes from. Deciding what a reference is # needs the name, the value and the comment beside it, so it is an AST walk # rather than a grep. Static and dependency-free, so it runs on its own. reference-values: name: Every reference value points at ISO 1683 or names its source runs-on: ubuntu-latest permissions: contents: read steps: - uses: actions/checkout@v7 with: persist-credentials: false - name: Set up Python 3.13 uses: actions/setup-python@v7 with: python-version: "3.13" - name: Check that no reference value is a copy or has no document run: python scripts/check_reference_values.py # A standard prints its limits in decimal, and a margin of two readings that # is 6 dB in decimal comes out 5,999 999 999 999 996 or 6,000 000 000 000 004 # in binary, so a verdict read straight off the comparison turns on the last # bit. The sweep that settled this class fixed more than a hundred sites; # this keeps the next one out. It fails on a computed decimal compared with a # printed limit, or with zero, that is neither settled through # phonometry._internal.boundary nor compared with a named slack, unless # scripts/boundary_comparison_exemptions.tsv lists it with its reason, and on # an exemption that no longer matches anything. Telling a computed value from # a caller's means following it through assignments, calls and dataclass # fields, so it is an AST data-flow walk rather than a grep. Static and # dependency-free, so it runs on its own. boundary-comparisons: name: No verdict hangs on the last bits of a computed decimal runs-on: ubuntu-latest permissions: contents: read steps: - uses: actions/checkout@v7 with: persist-credentials: false - name: Set up Python 3.13 uses: actions/setup-python@v7 with: python-version: "3.13" - name: Check that every boundary comparison is settled or exempted with a reason run: python scripts/check_boundary_comparisons.py # np.asarray hands back the caller's own array when it is already of the # asked type, and so does every validation helper built on it, so a result # that keeps what it was given shares memory with the caller: changing the # caller's array afterwards changes a result already computed, judged and # perhaps printed, and nothing raises. Clearing the writeable flag on such an # array is worse, because it freezes the caller's own. A public record that # can hold an array inherits OwnsArrays, which copies every array it is # built with (an array a factory allocates and passes through handed_over # is sealed instead of copied), so this fails on such a record that does # not, and on a copy written around an array handed to one, which would be # made twice. Then it follows every parameter through assignments, views, # containers and the package's own helpers to the other places an array is # kept, and fails on one that is not a read-only copy of its own, and on any # handed_over call it cannot prove is the only holder of a new array. An AST # data-flow walk, static and dependency-free, so it runs on its own. array-aliasing: name: Every result keeps its own copy of the arrays it was given runs-on: ubuntu-latest permissions: contents: read steps: - uses: actions/checkout@v7 with: persist-credentials: false - name: Set up Python 3.13 uses: actions/setup-python@v7 with: python-version: "3.13" - name: Check that no result keeps an array it was handed run: python scripts/check_array_aliasing.py # Jupyter, VS Code, Colab and the IPython terminal display the last # expression of a cell whole, and a dataclass record with nothing else to # show is its repr: every field, and every array as numpy prints it, in # full up to a thousand values, pages of numbers for a record of a few such # arrays. A public record inherits RichDisplay (through OwnsArrays when it # can hold an array), which shows a table of its fields instead, so this # fails on a public record that does not, or that sets the table aside with # a display method of its own. It # shares the AST reading of the array-aliasing gate: static and # dependency-free, so it runs on its own. record-display: name: Every public record shows itself as a table in a notebook runs-on: ubuntu-latest permissions: contents: read steps: - uses: actions/checkout@v7 with: persist-credentials: false - name: Set up Python 3.13 uses: actions/setup-python@v7 with: python-version: "3.13" - name: Check that every public record displays itself run: python scripts/check_record_display.py # A conformance row states what a standard prints and what this library # computes. A row that computes the expected value itself, from the same # constants, compares a formula with a second copy of it and reports Pass # whatever the library does; three did, and a wrong sign in the function they # certified would have gone out green. Counting them needs the delegation # resolved -- through helpers, across modules, and under whatever name the # imports gave the library -- so the check is an AST walk rather than a grep. # Static and dependency-free, so it runs on its own. conformance-rows: name: Every conformance row runs the library runs-on: ubuntu-latest permissions: contents: read steps: - uses: actions/checkout@v7 with: persist-credentials: false - name: Set up Python 3.13 uses: actions/setup-python@v7 with: python-version: "3.13" - name: Check that no row certifies the library without running it run: python scripts/check_conformance_rows.py # The committed example .report() fiches (.github/reports) must match a fresh # `make reports` run. Same drift gate as the figures, one layer further down # the pipeline: the fiches are what the documentation links to as worked # examples of what the library prints, so a stale one publishes a wrong # answer. Nothing checked them until this job existed, and two of them sat a # plot-styling release behind the code for weeks. The rendering stack is # pinned across both requirements files (matplotlib/numpy in -figures, # svglib/reportlab/pypdfium2 in -reports) because every link in the chain # fixes the rendered page the check compares. reports: name: Example report fiches up to date runs-on: ubuntu-latest permissions: contents: read steps: - uses: actions/checkout@v7 with: persist-credentials: false - name: Set up Python 3.13 uses: actions/setup-python@v7 with: python-version: "3.13" cache: 'pip' - name: Install the locked fiche-rendering stack run: | python -m pip install --upgrade pip pip install -e . # Pin the render+compute stack last so it wins over looser deps. pip install -r requirements-figures.txt -r requirements-reports.txt - name: Regenerate the example fiches run: make reports - name: Fail if any committed fiche is stale # Tolerance-aware compare instead of a byte diff: GitHub's heterogeneous # runner CPUs shift a few of the embedded plot's path coordinates ~1 ULP, # which rewrites the PDF page stream for no visible reason. The script # compares the extracted text exactly and the rendered page within a # calibrated pixel tolerance, so a real fiche change fails while # cross-CPU coordinate noise passes. See scripts/check_reports.py. run: python scripts/check_reports.py tests: runs-on: ${{ matrix.os }} # Its longest cell in the last 72 passing runs took 45 min, on Windows. # The Run tests step has a limit of its own; this one leaves the steps # around it, the setup before and the uploads after, a quarter of an hour. timeout-minutes: 95 permissions: contents: read # Required for the OIDC-based Codecov upload (no token secret needed). id-token: write strategy: fail-fast: false matrix: os: [ubuntu-latest, macos-latest, windows-latest] # From the oldest Python requires-python admits to the newest the # classifiers name, every one in between included; # tests/test_minimum_requirements.py holds the list to pyproject.toml. python-version: ["3.12", "3.13", "3.14"] steps: - uses: actions/checkout@v7 with: persist-credentials: false - name: Set up Python ${{ matrix.python-version }} uses: actions/setup-python@v7 with: python-version: ${{ matrix.python-version }} cache: 'pip' - name: Install dependencies run: | python -m pip install --upgrade pip pip install -r requirements.txt pip install -r requirements-dev.txt pip install -e . # Heavy third-party oracle sets (the EBU loudness test set, the stipa.info # certified STIPA bench, the NORAH2 public release) are never fetched here. # The suites that use them fall back to the committed derived series and # extracts under tests/data/ - see tests/data/README.md - which is the path # CI takes, and whose assertions never skip. A handful of cases that exist # only to exercise a full set do skip here and report as such (the EBU # programme-audio cases and the full-bench inventory guard); pytest prints # the resolution in its run header. - name: Run tests # -n auto fans the suite out across the runner's cores via pytest-xdist; # pytest-cov combines the per-worker coverage into a single coverage.xml. # Pin the numerical thread pools to one thread each so the per-core xdist # workers do not oversubscribe the CPU with nested BLAS/OpenMP pools. # The step took at most 43 min in those runs. A test that hangs is # ended fifteen minutes after it started (faulthandler_timeout in # pyproject.toml), and fifteen minutes after its failure when its # teardown hangs; the other workers then run what was already sent to # them, so a hang late in the run still ends inside 80 min, with the # test named and the JUnit and coverage files written. Past that the # runner stops pytest, which may then write neither for the uploads # below. timeout-minutes: 80 env: OMP_NUM_THREADS: "1" MKL_NUM_THREADS: "1" OPENBLAS_NUM_THREADS: "1" NUMEXPR_NUM_THREADS: "1" VECLIB_MAXIMUM_THREADS: "1" run: | pytest -n auto --junitxml=test-results-${{ matrix.os }}-${{ matrix.python-version }}.xml --cov=src --cov-report=xml # The run above holds NumPy in float32 to the bound the guide publishes, # but a pass leaves no number behind. This prints what each runner # measured, and where, so the ARM and Windows runners keep a record of # their own; -k leaves the torch cases out, which need the array-api job. - name: Record the NumPy float32 measurement run: pytest -q -rfEP tests/simulation/test_backend_tolerance.py -k "cpu and float32 and not torch" - name: Upload Test Results uses: actions/upload-artifact@v7 with: name: test-results-${{ matrix.os }}-${{ matrix.python-version }} path: | test-results-${{ matrix.os }}-${{ matrix.python-version }}.xml coverage.xml if: always() - name: Upload coverage to Codecov if: matrix.os == 'ubuntu-latest' uses: codecov/codecov-action@v7 with: files: coverage.xml use_oidc: true fail_ci_if_error: false # The main matrix runs against the latest numpy with the pure-Python # impulse kernel; this job exercises the numba-jitted path on the newest # numba (numba pins numpy, so it lives in its own environment), and # minimum-versions below builds the same kernels at the numba floor. tests-perf: name: tests (numba-jitted kernel) runs-on: ubuntu-latest # At most 23 min in its last 72 passing runs, and a hung test ends the # run fifteen minutes after it started (pyproject.toml). timeout-minutes: 50 permissions: contents: read # Declared once for the whole job so the guard below runs under exactly the # environment it vouches for. Split across the two steps, the guard could # stay green on its own NUMBA_DISABLE_JIT while the suite lost its copy and # ran interpreted from end to end. env: # conftest.py disables JIT by default (coverage); override it here, this # is the only job exercising the numba-compiled kernel. NUMBA_DISABLE_JIT: "0" # Pin the numerical thread pools to one thread each so the per-core xdist # workers do not oversubscribe the CPU with nested BLAS/OpenMP pools, # exactly as the main test job does. OMP_NUM_THREADS: "1" MKL_NUM_THREADS: "1" OPENBLAS_NUM_THREADS: "1" NUMEXPR_NUM_THREADS: "1" VECLIB_MAXIMUM_THREADS: "1" steps: - uses: actions/checkout@v7 with: persist-credentials: false # The newest Python the package supports. This job used to sit on 3.13 # because numba trails a new interpreter by a release or two, and while it # did, the jitted kernel was never built against the newest Python we ship # for. numba publishes cp314 wheels from 0.63.0 on, and the floor in # pyproject.toml (numba>=0.60.0) predates them, so on 3.14 pip resolves a # release that has them; the floor itself is built on 3.12 by the # minimum-versions job. # Tracking the newest version is the strictest single choice for this job: # a compiled extension meeting a new interpreter is the thing most likely # to break, and the pure-Python kernel is covered on both versions by the # main matrix regardless. - name: Set up Python 3.14 uses: actions/setup-python@v7 with: python-version: "3.14" cache: 'pip' - name: Install dependencies (with numba) run: | python -m pip install --upgrade pip pip install -r requirements-dev.txt pip install -e ".[perf,plot]" # Fails the job if the kernel falls back to the interpreted path, which # would leave this job green while exercising nothing it exists for. # Compiling here also fills numba's on-disk cache next to the module, so # the test workers below load the kernel instead of each compiling a copy. - name: Check the jitted kernel compiles run: python scripts/check_jit_kernel.py - name: Run tests (jitted kernel) # Same fan-out as the main matrix. The compiled kernel is not a reason # to stay serial: the step above compiles it once and the workers that # reach it read the cache in a fraction of a second, against a suite # that takes about twenty minutes to run one test at a time. run: pytest -q -n auto # The FDTD engines step on any Array API backend. array-api-strict refuses # every call outside the standard and every mix of host and device arrays, # so a NumPy-only call in the engines fails here before it fails on a GPU; # torch on CPU is the backend a user without a GPU can install, held to # the tolerance the guide publishes. array-api: name: FDTD engines on array-api-strict and torch (CPU) runs-on: ubuntu-latest # Under 5 min in its last 18 passing runs, and a hung test ends the run # fifteen minutes after it started (pyproject.toml). timeout-minutes: 25 permissions: contents: read # One thread per pool, as in the main test job: torch and the BLAS pools # would otherwise each start one thread per core in every xdist worker. env: OMP_NUM_THREADS: "1" MKL_NUM_THREADS: "1" OPENBLAS_NUM_THREADS: "1" NUMEXPR_NUM_THREADS: "1" VECLIB_MAXIMUM_THREADS: "1" steps: - uses: actions/checkout@v7 with: persist-credentials: false # A cache key of its own. setup-python keys the pip cache on # requirements.txt alone by default, which every Python 3.13 job on Linux # shares; the first of them to finish saves the cache without torch, and # the wheel would be fetched again on every run. - name: Set up Python 3.13 uses: actions/setup-python@v7 with: python-version: "3.13" cache: 'pip' cache-dependency-path: | requirements.txt requirements-dev.txt requirements-torch.txt # torch alone from its CPU index, at the pin requirements-torch.txt # holds: with PyPI beside that index pip takes the newest torch on either, # and PyPI's brings the CUDA wheels. The second line finds the pin met. - name: Install dependencies (torch from its CPU index) run: | python -m pip install --upgrade pip pip install -r requirements.txt -r requirements-dev.txt pip install --index-url https://download.pytorch.org/whl/cpu torch -c requirements-torch.txt pip install -r requirements-torch.txt pip install -e . # -rfEP keeps the failure summary and prints what each passing # tolerance test measured, and where, so every run leaves its number # in the log. - name: Run the backend tests run: pytest -q -rfEP -n auto tests/simulation # The video writer pipes frames into ffmpeg, a system program rather than a # wheel, so the main matrix runs its logic against a fake ffmpeg and skips # the real encodes. This job installs Ubuntu's ffmpeg and runs them: WebM, # MP4 and GIF are written, then decoded and counted with ffprobe. Whether # that ffmpeg has SVT-AV1 decides whether the AV1-first CPU path is # tested, and the summary says which, before the tests run, rather than # failing the build over a distribution's choice of encoders. video: name: Videos encode with a real ffmpeg runs-on: ubuntu-latest # Its tests take under a minute in its first five passing runs, and # installing ffmpeg took under a minute in three of them and 15 and 17 # min in the other two, waiting on Ubuntu's mirror; a hung test ends the # run fifteen minutes after it started (pyproject.toml). timeout-minutes: 45 permissions: contents: read steps: - uses: actions/checkout@v7 with: persist-credentials: false - name: Set up Python 3.13 uses: actions/setup-python@v7 with: python-version: "3.13" cache: 'pip' - name: Install ffmpeg run: | sudo apt-get update -q sudo apt-get install -y -q --no-install-recommends ffmpeg - name: Say which CPU encoders this ffmpeg has run: | ffmpeg -hide_banner -version | head -1 if ffmpeg -hide_banner -encoders | grep -q ' libsvtav1 '; then echo "This ffmpeg has SVT-AV1, so the AV1-first CPU path is tested below" >> "$GITHUB_STEP_SUMMARY" else echo "This ffmpeg has no SVT-AV1, so the AV1-first CPU path is not tested below (VP9 is)" >> "$GITHUB_STEP_SUMMARY" fi - name: Install dependencies run: | python -m pip install --upgrade pip pip install -r requirements.txt -r requirements-dev.txt pip install -e . # -rs prints why a test skipped, so a missing encoder reads in the log. - name: Write and decode the videos run: >- pytest -q -rs -n auto tests/io/test_video_encoders.py tests/io/test_write_video.py tests/io/test_write_video_ffmpeg.py tests/simulation/test_write_fdtd_animation.py tests/simulation/test_write_elastic_fdtd_animation.py tests/simulation/test_video_job.py # The FDTD engines' NumPy numbers, held to the golden digests in # engine-digests.json. Their bits depend on the C library's libm and on # NumPy's SIMD dispatch, so they are checked in the one environment the # file records, which is this job's: Ubuntu 24.04 and its C library, glibc # 2.39 (GitHub refreshes the image behind the label, not its release), # Python 3.13, the pinned stack, and NumPy's AVX-512 kernels switched off, # so whichever x86 runner this lands on computes the same bits. The # measured file is kept as an artifact: a moved digest can be read there # and, when the move is meant, committed with # `make engine-digests RUN=`. A NumPy bump fails here on the # environment line alone until that is done. engine-digests: name: FDTD engines hold their golden digests runs-on: ubuntu-24.04 # Under a minute in its first five runs, and a hung test ends the run # fifteen minutes after it started (pyproject.toml). timeout-minutes: 25 permissions: contents: read steps: - uses: actions/checkout@v7 with: persist-credentials: false - name: Set up Python 3.13 uses: actions/setup-python@v7 with: python-version: "3.13" cache: 'pip' - name: Install dependencies run: | python -m pip install --upgrade pip pip install -r requirements.txt -r requirements-dev.txt pip install -e . # Assigned before it is written: echo would return its own status and # hide the helper's, so a helper that fails would not fail the step. - name: Name NumPy's AVX-512 kernels to switch off id: avx512 run: | features="$(python scripts/engine_digests.py --avx512-features)" echo "features=$features" >> "$GITHUB_OUTPUT" - name: Measure the engines' digests env: PHONOMETRY_ENGINE_DIGESTS: require NPY_DISABLE_CPU_FEATURES: ${{ steps.avx512.outputs.features }} run: python scripts/engine_digests.py --output engine-digests.measured.json # A step of its own, which runs when the measurement fails: a moved digest # fails the measurement, and this test names the scenario and the key. # Not when the helper above failed, which would leave the kernels on. - name: Hold the engines to their golden digests if: (success() || failure()) && steps.avx512.outcome == 'success' env: PHONOMETRY_ENGINE_DIGESTS: require NPY_DISABLE_CPU_FEATURES: ${{ steps.avx512.outputs.features }} run: pytest -q -n0 tests/simulation/test_engine_golden_digests.py - name: Keep the measured digests if: always() uses: actions/upload-artifact@v7 with: name: engine-digests-measured path: engine-digests.measured.json # Apple's MPS device, on the macOS runners that expose a working one # (macOS 14 reports MPS available but cannot allocate on it). It holds the # float32 tolerance the guide publishes for torch:mps, and runs the long # float32 contour check on MPS, whose sums are float32 with Neumaier's # compensation: a compiler that reassociates the compensated sum fails it. mps: name: FDTD engines on torch MPS runs-on: macos-15 # Under 2 min in its last 18 passing runs, and a hung test ends the run # fifteen minutes after it started (pyproject.toml). timeout-minutes: 25 permissions: contents: read steps: - uses: actions/checkout@v7 with: persist-credentials: false # A cache key of its own too, apart from the macOS 3.13 cell of the matrix. - name: Set up Python 3.13 uses: actions/setup-python@v7 with: python-version: "3.13" cache: 'pip' cache-dependency-path: | requirements.txt requirements-dev.txt requirements-torch.txt - name: Install dependencies run: | python -m pip install --upgrade pip pip install -r requirements.txt -r requirements-dev.txt -r requirements-torch.txt pip install -e . - name: Check MPS is usable, then run the tolerance and contour tests on it run: | python -c "import torch, sys; ok = torch.backends.mps.is_available() and torch.ones(4, device='mps').sum().item() == 4.0; sys.exit(0 if ok else 'no usable MPS device on this runner')" pytest -q -rfEP tests/simulation/test_backend_tolerance.py tests/simulation/test_fdtd_backends.py -k "torch:mps" # A run on a node must give the numbers the run here gives. This job builds # the cpu stage of the node image (docker/node/Dockerfile) with the pins it # installs itself, serves it through sshd on localhost, names it in a hosts # file, and runs the simulation functions both ways, compared with # array_equal: the same pins on the same CPU agree bit for bit. It writes # a video there too, compares its run with the run here and counts its # frames here with ffprobe. It lints the image's Dockerfile and its # provisioning script first. A pull request that moves the digest of the # cpu stage's base image runs it too, so a new digest is checked before it # is merged. remote-node: name: Remote simulation on a localhost node # The release the node image's cpu stage starts from (docker/node/ # Dockerfile, ubuntu:24.04): where NumPy falls back to libm, the run here # and the run in the container agree bit for bit only on the same glibc. # Move both together. runs-on: ubuntu-24.04 permissions: contents: read # A build of the image with nothing cached takes minutes and the runs take # seconds; installing ffmpeg, for ffprobe, took 15 and 17 min in two runs # of the video job, waiting on Ubuntu's mirror: a job still going after # this has hung. timeout-minutes: 45 steps: - uses: actions/checkout@v7 with: persist-credentials: false # hadolint by its release tag; shellcheck is the runner image's own. - name: Lint the node image's Dockerfile and its provisioning script run: | docker run --rm -i hadolint/hadolint:v2.15.1 hadolint --failure-threshold warning - < docker/node/Dockerfile shellcheck docker/node/provision.sh # The caches. A pip cache and the image's layer cache would both be safe # here: Actions scopes a cache to the ref of the run that wrote it, so a # pull_request run writes only under its merge ref and reads its own, its # base branch's and main's, and only runs on main (its pushes and # dispatches) write under main. The pip cache is left off all the same: # zizmor's cache-poisoning rule takes a job that builds an image with # docker/build-push-action for one that publishes, and refuses a # setup-python cache in it. The layer cache, which that rule does not # cover, stays: it spares the build its downloads, and what the image # computes is checked against the run here regardless. The job publishes # nothing: the image goes no further than this runner's Docker, and the # build uploads no record of itself as an artifact. - name: Set up Python 3.13 uses: actions/setup-python@v7 with: python-version: "3.13" - name: Install dependencies run: | python -m pip install --upgrade pip pip install -r requirements.txt -r requirements-dev.txt pip install -e . - name: Set up Docker Buildx uses: docker/setup-buildx-action@v4 # The cpu stage fetches a PPA key, the pinned ffmpeg build (checked # against its SHA-256) and the figure stack: kept in the Actions cache by # build step, rebuilt only when its inputs change, the ffmpeg pin included. - name: Build the node image for a CPU uses: docker/build-push-action@v7 env: DOCKER_BUILD_RECORD_UPLOAD: "false" with: context: . file: docker/node/Dockerfile target: cpu tags: phonometry-node:cpu load: true cache-from: type=gha,scope=node-cpu cache-to: type=gha,mode=max,scope=node-cpu # sshd runs as root on a port of its own, on 127.0.0.1 alone, and lets # this runner's user in with a key made here, never with a password. The # runner image carries OpenSSH's server (its ssh package); ssh-keygen -A # makes any host key it lacks. Without PAM, sshd refuses even a key to an # account whose password is locked, as a runner's may be: '*' is no # password, and not a locked one. sshd logs to a file of the job, which # the last step shows when the job fails or is cancelled. The hosts file # bounds each run at five minutes, under the fifteen pytest gives a test # (faulthandler_timeout in pyproject.toml), so a node that stops # answering fails its test with the client's own error instead of # holding the job or ending pytest; the step takes seconds. - name: Serve the node through sshd on localhost run: | user="$(id -un)" sudo usermod -p '*' "$user" sudo ssh-keygen -A sudo mkdir -p /run/sshd sudo /usr/sbin/sshd -p 2222 -o ListenAddress=127.0.0.1 -o PasswordAuthentication=no -o KbdInteractiveAuthentication=no \ -E "$RUNNER_TEMP/sshd.log" install -d -m 700 ~/.ssh ssh-keygen -q -t ed25519 -N "" -f ~/.ssh/node_key cat ~/.ssh/node_key.pub >> ~/.ssh/authorized_keys chmod 600 ~/.ssh/authorized_keys chmod go-w ~ printf '%s\n' "Host phonometry-ci-node" " HostName 127.0.0.1" " Port 2222" " User $user" \ " IdentityFile ~/.ssh/node_key" " IdentitiesOnly yes" \ " StrictHostKeyChecking accept-new" " UserKnownHostsFile ~/.ssh/known_hosts_node" >> ~/.ssh/config chmod 600 ~/.ssh/config ssh -o BatchMode=yes phonometry-ci-node "docker image inspect --format '{{.Id}}' phonometry-node:cpu" printf '%s\n' "[hosts.ci]" 'ssh = "phonometry-ci-node"' 'runner = "docker"' \ 'image = "phonometry-node:cpu"' 'label = "the localhost node of CI"' 'timeout_s = 300' \ > "$RUNNER_TEMP/hosts.toml" # ffprobe counts the frames of the video the node sends back. - name: Install ffmpeg run: | sudo apt-get update -q sudo apt-get install -y -q --no-install-recommends ffmpeg # A test that skips compares nothing, and pytest exits 0 all the same: # the job fails on any skip, whatever its reason. pytest writes no # colour, so that a summary line starts with SKIPPED and not with an # escape sequence that a forced colour (FORCE_COLOR, PY_COLORS) would # put first and the check would read past. Actions runs a step with # bash -e alone, so pipefail is set for pytest's status to pass through # tee. - name: Run the simulations on the node and here, and compare them env: PHONOMETRY_TEST_NODE: ci PHONOMETRY_HOSTS_FILE: ${{ runner.temp }}/hosts.toml run: | set -o pipefail pytest -q --color=no -rfEPs tests/simulation/test_localhost_node.py tests/simulation/test_video_remote_node.py \ | tee "$RUNNER_TEMP/node-tests.txt" if grep -q '^SKIPPED' "$RUNNER_TEMP/node-tests.txt"; then echo "::error::The localhost-node tests skipped instead of running on the node." exit 1 fi # Why a login was refused, or why sshd did not start or could not take # its port, is in sshd's log and in no step's output: with -E, sshd # writes there what it would otherwise send to the system log. A job # past its timeout is cancelled, not failed, and a run that hangs is the # one whose log is wanted most. - name: Show sshd's log if: failure() || cancelled() run: | if [ -f "$RUNNER_TEMP/sshd.log" ]; then sudo cat "$RUNNER_TEMP/sshd.log" fi # The floors in pyproject.toml are measured: each is the oldest release the # library's suite passes with on the oldest Python the package supports. # Every other job installs the pinned, newest stack, so without this one a # floor would be a promise nobody checks, and the day the code started to # need something newer it would go on claiming the old release. Here the # floors are installed exactly, read from pyproject.toml by # scripts/minimum_requirements.py so that raising one is an edit in one # place, and --check fails the job if pip settled on anything else. # # It runs the library's tests, not the figure and documentation tooling: # the generators and their checkers compare against artefacts drawn on the # pinned figure stack, so they are tied to it, and their test modules carry # the `pinned_stack` mark. --without-pinned-stack (tests/conftest.py) leaves # those modules out before importing them, since some import names the floor # matplotlib does not have. The jitted kernels are on, so the numba floor is # compiled and exercised too. minimum-versions: name: Library tests at the dependency floors runs-on: ubuntu-latest # Under 25 min in its last 72 passing runs, and a hung test ends the # run fifteen minutes after it started (pyproject.toml). timeout-minutes: 50 permissions: contents: read env: NUMBA_DISABLE_JIT: "0" OMP_NUM_THREADS: "1" MKL_NUM_THREADS: "1" OPENBLAS_NUM_THREADS: "1" NUMEXPR_NUM_THREADS: "1" VECLIB_MAXIMUM_THREADS: "1" steps: - uses: actions/checkout@v7 with: persist-credentials: false - name: Set up Python 3.12 uses: actions/setup-python@v7 with: python-version: "3.12" - name: Install the floors pyproject.toml declares, exactly run: | python -m pip install --upgrade pip python scripts/minimum_requirements.py > minimum-requirements.txt cat minimum-requirements.txt # The test tools at the versions the main matrix pins. grep -E '^(pytest|pytest-xdist|pypdf|pypdfium2|pystoi|pyyaml|jsonschema)==' requirements-dev.txt | cut -d' ' -f1 > test-tools.txt # torch's floor alone from its CPU index: the CUDA wheels are # gigabytes, and with PyPI beside that index pip could take them. pip install --index-url https://download.pytorch.org/whl/cpu torch -c minimum-requirements.txt pip install -r minimum-requirements.txt -r test-tools.txt pip install --no-deps -e . python scripts/minimum_requirements.py --check - name: Check the jitted kernels compile at the numba floor run: python scripts/check_jit_kernel.py - name: Run the library tests at the floors run: pytest -q -n auto --without-pinned-stack # The suite calls _repr_html_ and _repr_pretty_ itself; a notebook goes # through IPython, which picks the method, runs matplotlib on its inline # backend and sends a warning to the cell's stderr. This executes # tests/notebooks/smoke.ipynb with nbclient on a real ipykernel, with the # package installed as a user installs it, and reads what each cell put # out: a filter bank result as its table, .plot() as an inline PNG, a # verdict as FAIL, a .report() PDF in a temporary directory and a # FilterBankWarning, the topic class under PhonometryWarning that the # low sampling rate provokes. notebook: name: phonometry runs in a notebook kernel runs-on: ubuntu-latest permissions: contents: read steps: - uses: actions/checkout@v7 with: persist-credentials: false - name: Set up Python 3.13 uses: actions/setup-python@v7 with: python-version: "3.13" cache: 'pip' - name: Install the package, its plot and report extras, and a kernel run: | python -m pip install --upgrade pip pip install -r requirements.txt -r requirements-reports.txt -r requirements-notebook.txt pip install ".[plot,report]" - name: Execute the smoke notebook and read its outputs run: python scripts/check_notebook.py tests/notebooks/smoke.ipynb # JupyterLite runs Python in the browser on Pyodide, where micropip # installs a package against the numpy, scipy and matplotlib Pyodide builds # for WebAssembly, whatever PyPI holds. This builds the wheel and loads the # Pyodide that tests/pyodide pins under Node. The first step installs the # wheel as a JupyterLite user would, requirements included, then the # requirements of the plot and report extras (keep_going, so every one # Pyodide cannot meet is named at once), and fails saying which floor in # pyproject.toml the builds Pyodide ships fall short of. The second # runs whatever the first said: it installs the wheel without its # requirements, on Pyodide's own numpy and scipy, and runs an import and an # octave filter bank, so the job also says whether the code itself runs # there. pyodide: name: phonometry installs and runs in Pyodide (JupyterLite) runs-on: ubuntu-latest permissions: contents: read steps: - uses: actions/checkout@v7 with: persist-credentials: false - name: Set up Python 3.13 uses: actions/setup-python@v7 with: python-version: "3.13" - name: Build the wheel run: python -m pip wheel --no-deps --wheel-dir dist . - uses: actions/setup-node@v7 with: node-version: 24 - name: Install the Pyodide tests/pyodide pins, with the pnpm it pins run: | corepack enable pnpm install --frozen-lockfile working-directory: tests/pyodide - name: Install the wheel and its plot and report extras with micropip run: node tests/pyodide/smoke.mjs install dist/phonometry-*.whl - name: Run an octave filter bank on the numpy and scipy Pyodide ships if: ${{ !cancelled() }} run: node tests/pyodide/smoke.mjs run dist/phonometry-*.whl sonar: needs: tests runs-on: ubuntu-latest # Dependabot runs with a restricted token and no access to repository secrets, so # SONAR_TOKEN is empty there and the scan can only ever fail. Skip it for those runs. if: >- github.actor != 'dependabot[bot]' && (github.event_name == 'pull_request' || github.ref == 'refs/heads/master' || github.ref == 'refs/heads/main') steps: - uses: actions/checkout@v7 with: persist-credentials: false fetch-depth: 0 - name: Download coverage report uses: actions/download-artifact@v8 with: name: test-results-ubuntu-latest-3.13 - name: SonarCloud Scan uses: SonarSource/sonarqube-scan-action@v8 env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }} pr-comment: needs: [quality, tests] runs-on: ubuntu-latest if: always() && github.event_name == 'pull_request' permissions: contents: read pull-requests: write issues: write steps: # Full history: the comment is a diff of the committed conformance artefact # against the same file on the base branch, and a checkout at the default # depth has only the merge commit to show for it. A missing baseline is not # an error - the comment falls back to totals and says so - but it makes # every pull request look like it changed nothing. - uses: actions/checkout@v7 with: persist-credentials: false fetch-depth: 0 - name: Set up Python 3.13 uses: actions/setup-python@v7 with: python-version: "3.13" # Stdlib only. The comment reads two committed JSON files and joins them; # it does not run the checks. It used to install the whole scientific stack # and spend 45 s regenerating a report the `conformance` job has already # proven current, which meant a stale artefact was reported twice and # fixed by neither. - name: Download Test Results uses: actions/download-artifact@v8 with: pattern: test-results-* path: test-results continue-on-error: true - name: Generate Comment Body run: python .github/scripts/comment_pr.py env: GITHUB_REPOSITORY: ${{ github.repository }} GITHUB_RUN_ID: ${{ github.run_id }} # The branch the artefact is diffed against, and the commit the two # "full report" links are permalinks to. `github.sha` on a pull request # is the merge commit, which is not a commit anyone can browse. GITHUB_BASE_REF: ${{ github.base_ref }} GITHUB_HEAD_SHA: ${{ github.event.pull_request.head.sha }} - name: Post PR Comment uses: actions/github-script@v9 with: script: | const fs = require('fs'); const body = fs.readFileSync('pr_comment_body.md', 'utf8'); const marker = ''; // Update the single sticky conformance comment instead of posting a // new one every run: find the existing marked comment and edit it. const { data: comments } = await github.rest.issues.listComments({ issue_number: context.issue.number, owner: context.repo.owner, repo: context.repo.repo, per_page: 100, }); const existing = comments.find( (c) => c.body && c.body.includes(marker) ); if (existing) { await github.rest.issues.updateComment({ owner: context.repo.owner, repo: context.repo.repo, comment_id: existing.id, body: body, }); } else { await github.rest.issues.createComment({ issue_number: context.issue.number, owner: context.repo.owner, repo: context.repo.repo, body: body, }); }