ipakit 0.2.0__tar.gz → 0.4.0__tar.gz

ipakit-0.4.0/.github/workflows/ci.yml

@@ -0,0 +1,297 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  schedule:
+    # Nightly full suite: runs the slow-marked sweep tests that per-PR CI skips.
+    - cron: "0 7 * * *"
+  workflow_dispatch:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  # Decide whether this push/PR touches anything but documentation. A doc-only
+  # change cannot move the metric, the derived artifacts or the Python surface,
+  # so the three build jobs below skip it and only `docs` runs. Every gate that
+  # reads the documents must therefore live in `docs` and not only in the
+  # pytest job, or a doc-only change skips its own check. The default is
+  # to run everything: anything we cannot cleanly diff sets code=true, so the
+  # optimization can only ever skip work it is sure is safe to skip.
+  changes:
+    name: detect doc-only changes
+    runs-on: ubuntu-latest
+    outputs:
+      code: ${{ steps.filter.outputs.code }}
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - id: filter
+        env:
+          BASE: ${{ github.event_name == 'pull_request' && github.event.pull_request.base.sha || github.event.before }}
+          HEAD: ${{ github.sha }}
+        run: |
+          set -eu
+          # Fail safe: no usable base (first push, force-push, missing SHA) runs
+          # the full build rather than guessing what changed.
+          if [ -z "${BASE:-}" ] || ! git cat-file -e "${BASE}^{commit}" 2>/dev/null; then
+            echo "no usable base ('${BASE:-}'); running full CI"
+            echo "code=true" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          changed="$(git diff --name-only "$BASE" "$HEAD")"
+          echo "changed files:"
+          printf '  %s\n' $changed
+          code=false
+          while IFS= read -r f; do
+            [ -z "$f" ] && continue
+            case "$f" in
+              # The doc set: docs/, any markdown, the generated tutorial
+              # notebook, and the license. Everything else is code.
+              docs/*|*.md|ipakit/notebooks/*|LICENSE*) ;;
+              *) code=true ;;
+            esac
+          done <<INNER
+          $changed
+          INNER
+          echo "run build jobs? code=$code"
+          echo "code=$code" >> "$GITHUB_OUTPUT"
+
+  lint:
+    name: lint (ruff / black / mypy)
+    needs: changes
+    if: ${{ needs.changes.outputs.code == 'true' }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+      - run: python -m pip install --upgrade pip
+      - run: pip install -e ".[lint]"
+      # `.`, matching the Makefile, because naming three directories left the
+      # tracked root `conftest.py` linted by neither -- and it configures the
+      # whole suite. An unused import added there passes this job and fails
+      # `make lint`, which is the wrong way round: the gate anyone reads was
+      # the looser one. ruff and black both honor .gitignore, so `.` is the
+      # same file set the release gate walks, not a wider one.
+      - run: ruff check .
+      - run: black --check .
+      - run: mypy --config-file=pyproject.toml
+
+  test:
+    name: test (py${{ matrix.python-version }})
+    needs: changes
+    if: ${{ needs.changes.outputs.code == 'true' }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+          cache-dependency-path: pyproject.toml
+      - run: python -m pip install --upgrade pip
+      # The test extra carries lxml, which is what validates the shipped XML
+      # against the grammars beside it; without a validator test_schema.py
+      # errors rather than skipping, so this job is where that is guaranteed
+      # to run. The ICU-backed X-SAMPA cross-check self-skips (importorskip);
+      # the confusion-matrix guard is stdlib and runs.
+      - run: pip install -e ".[test]"
+      # What is under test, asserted before anything tests it. The suite is
+      # only evidence about this branch if `import ipakit` resolves inside the
+      # checkout, and nothing here checked that: an install resolving to a
+      # published ipakit instead would run the whole suite green against code
+      # the branch does not contain. `make check` has run this since it
+      # existed; CI, which is the run anyone actually reads, did not.
+      # It also puts the tiergraph path and version in the log, which is the
+      # provenance a red run gets diagnosed against.
+      - name: The subject under test is this checkout
+        run: python -m scripts.gate_subject
+      # Across the runner's cores, as the Makefile does. A matrix job is three
+      # runs of the same suite, so the saving is paid three times per push.
+      # The default -m 'not slow' (pyproject addopts) keeps the O(n^2) sweep
+      # tests out of the per-PR run; the full-suite job below runs them.
+      - run: pytest -n auto
+
+  full-suite:
+    name: full suite (incl. slow)
+    needs: changes
+    # The per-PR test job skips slow-marked sweep tests to keep feedback fast.
+    # This job runs every test, slow included, where the wait is acceptable:
+    # merges to main, the nightly schedule, and manual dispatch — never on a
+    # pull_request.
+    if: ${{ github.event_name != 'pull_request' && needs.changes.outputs.code == 'true' }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+      - run: python -m pip install --upgrade pip
+      - run: pip install -e ".[test]"
+      # Override the addopts default (-m 'not slow') so every test runs.
+      - run: pytest -m "slow or not slow" -n auto
+
+  guards:
+    name: derived-artifact guards (ICU)
+    needs: changes
+    if: ${{ needs.changes.outputs.code == 'true' }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+      - run: python -m pip install --upgrade pip
+      # dev pulls icukit-pyicu (bundled ICU + PyICU) so the X-SAMPA table can be derived.
+      - run: pip install -e ".[dev]"
+      - name: X-SAMPA table matches ICU + overrides
+        run: python scripts/xsampa_table.py validate
+      - name: Confusion matrix matches the metric
+        run: python scripts/confusion.py validate
+      - name: Geometry figures in docs/distance.md match the metric (numpy; skipped in the matrix job)
+        env:
+          PYTHONHASHSEED: "0"
+        run: pytest tests/test_geometry_doc.py
+      - name: Committed tiergraph baselines match their manifest
+        run: PYTHONHASHSEED=0 python scripts/tiergraph_capture.py verify-baselines
+      # The full invariant sweep, including "derived artifacts current", which
+      # is what caught the stale figure record this commit repairs. `make
+      # check` has always run it and CI never did, so the only thing standing
+      # between a regenerated artifact and a stale record of it was whether
+      # somebody happened to run the release gate by hand. About 40 seconds.
+      - name: Invariants hold and derived artifacts are current
+        run: PYTHONHASHSEED=0 python scripts/invariants.py
+      # The last two release-gate steps CI did not reach. Both re-derive a
+      # committed golden and compare; the manifest above only proves those
+      # goldens have not been hand-edited, which is a different question from
+      # whether the code still produces them. Nothing else reads either file:
+      # containment-navigation.json is read only by containment_oracle.py, and
+      # consolidation_parity.sha256 only by consolidation_parity.py -- the
+      # parity test asserts a round-trip over the corpus, never that the
+      # committed digest still matches it. About four seconds together.
+      - name: Containment navigation matches its golden
+        run: PYTHONHASHSEED=0 python scripts/containment_oracle.py
+      - name: Consolidation parity digest matches the derived corpus
+        run: PYTHONHASHSEED=0 python scripts/consolidation_parity.py check
+      - name: ICU cross-check tests (skipped in the matrix job)
+        run: pytest tests/test_xsampa.py
+      - name: Panphon characterization tests (skipped in the matrix job)
+        run: pytest tests/test_panphon_facts.py tests/test_panphon_live_geometry.py tests/tiergraph/test_j_panphon.py
+      - name: Read accepted CLTS source identity
+        id: clts-source
+        run: |
+          python -c 'from ipakit.clts import source_policy; s = source_policy()["source"]; print("repository=" + s["upstream-url"].removeprefix("https://github.com/")); print("revision=" + s["version"])' >> "$GITHUB_OUTPUT"
+      - uses: actions/checkout@v7
+        with:
+          repository: ${{ steps.clts-source.outputs.repository }}
+          ref: ${{ steps.clts-source.outputs.revision }}
+          path: .clts-source
+          persist-credentials: false
+      - name: CLTS snapshot regeneration and exhaustive scorer parity
+        env:
+          IPAKIT_CLTS_DIR: ${{ github.workspace }}/.clts-source
+        run: pytest tests/test_clts_snapshot.py tests/test_clts_mapping.py tests/tiergraph/test_clts_profile.py
+      - name: Comparison extras tests (partition check skips in the matrix job)
+        run: pytest tests/test_comparison_example.py
+
+  render:
+    name: render (figure tests need real renderers)
+    needs: changes
+    if: ${{ needs.changes.outputs.code == 'true' }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+      - run: python -m pip install --upgrade pip
+      # The figure tests measure a rendered raster or layout, so they need a
+      # real renderer -- rsvg-convert (librsvg2-bin) for the SVG figures, dot
+      # (graphviz) for the tiergraph layout. No other job installs one, so
+      # everywhere else those figure tests skip. This job installs both and is
+      # the one place they run.
+      - run: sudo apt-get update && sudo apt-get install -y graphviz librsvg2-bin
+      - run: pip install -e ".[test]"
+      # REQUIRE_RENDERERS turns a missing renderer from a silent skip into a
+      # hard failure here (see tests/_renderers.py), so this job cannot go green
+      # having rendered nothing. `-m 'slow or not slow'` overrides the addopts
+      # default (`-m 'not slow'`) so the slow-marked figure tests run too.
+      - name: Figure tests run against installed renderers
+        env:
+          REQUIRE_RENDERERS: "1"
+        run: pytest tests/test_tract_figures.py tests/test_animation_rest.py tests/test_frontal.py tests/tiergraph/test_dot.py -m "slow or not slow" -q
+
+  docs:
+    name: docs (README + tutorial values current)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+      - run: python -m pip install --upgrade pip
+      # The doc examples run against the installed package and its dependencies;
+      # scripts/docexamples.py, scripts/docquotes.py and scripts/tutorial.py
+      # are stdlib-only. scripts/inventory_cards.py is not: it validates every
+      # declared SPDX identifier through packaging, which is declared in the
+      # test extra because only a gate reads it. Installing the extra keeps that
+      # version constraint in pyproject.toml rather than spelling it here too.
+      - run: pip install -e ".[test]"
+      - name: README and docs Python examples produce their stated values
+        run: PYTHONHASHSEED=0 python scripts/docexamples.py
+      # Runs here, not only in the pytest job, because a doc-only change skips
+      # that job and a doc-only change is exactly what breaks a quotation.
+      - name: Quotations are in the documents they cite
+        run: python scripts/docquotes.py .
+      - name: Tutorial page and notebook are current
+        run: PYTHONHASHSEED=0 python scripts/tutorial.py check all
+      # Three more generated documents with a `check` mode each. `make check`
+      # has run all three for as long as they have existed; CI never has, so
+      # the regenerate-never-hand-edit rule held only for whoever ran the
+      # release gate by hand, and a drifting exhibit reached main green.
+      # They belong in this job rather than a code-triggered one because two
+      # of the three derive from code while the artifact lives under docs/:
+      # an exhibit goes stale when the metric moves, and it also goes stale
+      # when someone edits the document, and this is the only job that runs
+      # for both. Together they add about a second.
+      - name: House-style exhibits match ipa.xml
+        run: python scripts/house_style.py check
+      - name: Perceptual-validation exhibits match the data and the metric
+        run: PYTHONHASHSEED=0 python scripts/perceptual_validation.py check
+      - name: State of the work matches docs/design
+        run: python scripts/state_of_work.py check
+      # The declarations under ipakit/data and the summary page under docs/ are
+      # one generated artifact, so the check has to run for a change to either.
+      # `guards` skips a doc-only change, which would let a hand edit to the
+      # summary skip the gate that guards it; this job runs for every change.
+      # The clone is a sparse, blobless fetch of the dictionary metadata alone,
+      # about a megabyte.
+      - name: eSpeak declarations match the pinned eSpeak NG revision
+        run: python scripts/espeak_vocabularies.py check --fetch --source "${{ runner.temp }}/espeak-ng"
+      - name: MFA declarations match the pinned mfa-models revision
+        run: python scripts/mfa_vocabularies.py check --fetch --source "${{ runner.temp }}/mfa-models"
+      - name: Inventory cards match declarations and computed counts
+        run: python scripts/inventory_cards.py check --mfa-models "${{ runner.temp }}/mfa-models"

ipakit-0.4.0/.github/workflows/publish.yml

@@ -0,0 +1,68 @@
+name: Publish
+
+# Build once, then publish via PyPI Trusted Publishing (OIDC) -- no API tokens.
+# Cut a GitHub Release (tag vX.Y.Z) to publish to PyPI.
+#
+# One-time setup (see docs/releasing.md):
+#   - PyPI:   add a Trusted Publisher (project ipakit, this repo, workflow
+#             publish.yml, environment "pypi").
+#   - GitHub: create environment "pypi" (Settings > Environments).
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: build sdist + wheel
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+      - run: python -m pip install --upgrade pip build twine
+      - run: python -m build
+      - name: Check distribution metadata
+        run: python -m twine check dist/*
+      - name: Verify version matches release tag
+        # Read the version from the built wheel's metadata, which is what
+        # uploads, rather than importing ipakit: this job installs only the
+        # build tools, and importing the package needs its dependencies.
+        env:
+          TAG: ${{ github.event.release.tag_name }}
+        run: |
+          VERSION=$(python - <<'EOF'
+          import glob, zipfile
+          from email.parser import BytesParser
+          (wheel,) = glob.glob("dist/*.whl")
+          with zipfile.ZipFile(wheel) as archive:
+              (name,) = [n for n in archive.namelist() if n.endswith(".dist-info/METADATA")]
+              print(BytesParser().parsebytes(archive.read(name))["Version"])
+          EOF
+          )
+          echo "wheel metadata version=$VERSION release tag=$TAG"
+          test "$VERSION" = "${TAG#v}"
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+  publish-pypi:
+    name: publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/ipakit
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

ipakit-0.4.0/.pre-commit-config.yaml

@@ -0,0 +1,64 @@
+# Pre-commit hooks for ipakit.
+# Mirrors the HSG repo's hook set, adapted for ipakit's flat layout (package at
+# ./ipakit, tests at ./tests). Tool settings live in pyproject.toml.
+# Install once with:  pip install -e ".[dev]" && pre-commit install
+minimum_pre_commit_version: "3.0.0"
+
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: trailing-whitespace
+        files: ^(ipakit|tests)/
+        # Praat's long TextGrid format writes a trailing space after every value.
+        exclude: ^tests/fixtures/textgrid/
+      - id: end-of-file-fixer
+        files: ^(ipakit|tests)/
+        # Verbatim upstream notice hashes are part of the PHOIBLE source pin.
+        exclude: ^ipakit/data/phoible/(MIT-upstream|GPL-3\.0)\.txt$
+      - id: check-yaml
+      - id: check-toml
+      - id: check-added-large-files
+        # The shipped Panphon XML is a 1.5 MB declaration of another
+        # project's feature table, generated by scripts/panphon_geometry.py
+        # and checked against the installed library. It is deliberately
+        # committed and distributed with attribution and its MIT notice.
+        # The guard stays at its default for everything else.
+        # PHOIBLE's full original catalog compresses to 877 KB; its exact
+        # source/transport hashes and wheel/sdist contents are tested.
+        exclude: ^(ipakit/data/feature-models/panphon\.xml|ipakit/data/phoible/data/phoible\.csv\.gz)$
+      - id: check-merge-conflict
+
+  - repo: https://github.com/psf/black-pre-commit-mirror
+    rev: 26.5.1
+    hooks:
+      - id: black
+        # Match the lint job's scope exactly. CI runs `black --check ipakit
+        # tests scripts`; leaving scripts out here made every local commit
+        # touching one report "Passed" for a file the hook never opened, and
+        # the divergence only surfaced in CI.
+        files: ^(ipakit|tests|scripts)/
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.16.5
+    hooks:
+      - id: ruff-check
+        args: ["--fix"]
+        # As above: CI runs `ruff check ipakit tests scripts`.
+        files: ^(ipakit|tests|scripts)/
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v2.3.1
+    hooks:
+      - id: mypy
+        # Native GraphProfile subclasses need the same runtime types CI installs.
+        # tests/test_ci_contract.py keeps this requirement equal to pyproject.
+        additional_dependencies: ["tiergraph>=0.4.0"]
+        # NOT widened to match the others. `pyproject.toml` sets
+        # `files = ["ipakit"]` deliberately, because the lint job installs
+        # `.[lint]`, which has no pytest -- a scope reaching a test file
+        # fails there while passing locally under `.[dev]`. This hook agrees
+        # with that scope; widening it would disagree with CI rather than
+        # match it.
+        files: ^ipakit/
+        args: ["--config-file=pyproject.toml"]