assertpy 1.1__tar.gz → 2.36.0__tar.gz

assertpy-2.36.0/.github/workflows/ci.yml

@@ -0,0 +1,465 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+# every suite runs on four workers by file: split by test, a pair in test_snapshots.py races on the cwd __snapshots
+jobs:
+  test:
+    timeout-minutes: 15
+    runs-on: ${{ matrix.os }}
+    # mapped at job level so the upload step can ask whether it has a token before it runs: the secrets
+    # context is not readable from a step `if`, and step-level env is not in scope for its own condition
+    env:
+      CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14", "3.15"]
+        include:
+          # the Codecov cell also installs every optional integration (pandas/polars/numpy extras plus
+          # pydantic/attrs/requests), so the tests the other minimal-env cells skip run here for real
+          - os: ubuntu-latest
+            python-version: "3.14"
+            full-deps: true
+          - os: windows-latest
+            python-version: "3.14"
+          - os: macos-latest
+            python-version: "3.14"
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
+        with:
+          python-version: ${{ matrix.python-version }}
+          allow-prereleases: true
+
+      - name: Install dependencies
+        if: '!matrix.full-deps'
+        run: uv sync --locked --extra json
+
+      - name: Install dependencies (all integrations)
+        if: matrix.full-deps
+        run: uv sync --locked --extra json --extra data --extra inline --group integrations --group docs-examples --group oracle
+
+      - name: Test
+        # no coverage: only the full-deps cell reports it, and on 3.12 its tracer made this the slowest cell of the run
+        if: '!matrix.full-deps'
+        run: uv run pytest -v -n 4 --dist loadfile --ignore=tests/test_docs_examples.py tests
+
+      - name: The oracle is installed
+        # its module skips where a package is absent, so an absence here would pass for a green run
+        if: matrix.full-deps
+        run: uv run python -c "import openapi_schema_validator, fqdn, isoduration, rfc3986_validator"
+
+      - name: Test with coverage (enforce 100%)
+        # Only the full-deps cell has every integration installed and 0 skips, so it is
+        # the only cell that can reach 100%. This is the hard local gate; Codecov's status
+        # is reporting on top, not the sole guard (it uploads async and can fail open).
+        # The doc-example guard is excluded here so its runs never pad the coverage number.
+        if: matrix.full-deps
+        run: uv run pytest -v -n 4 --dist loadfile --cov=assertpy --cov-report=term-missing --cov-report=xml --cov-fail-under=100 --ignore=tests/test_docs_examples.py tests
+
+      - name: Guard doc examples
+        # Runs once (docs are platform-independent) and without coverage, so executing the
+        # README/guide snippets can't mask a real coverage gap in the test suite.
+        if: matrix.full-deps
+        run: uv run pytest tests/test_docs_examples.py
+
+      - name: Upload coverage to Codecov
+        # Only the full-deps cell. The bare 3.14/ubuntu cell skips every integration test and used
+        # to upload too: Codecov merges reports so the number stayed right, but one of the two was
+        # always a partial report sent at a 100% target.
+        # A run without repository secrets gets an empty token, and Codecov rejects an untokened upload
+        # to a protected branch, so the job went red on the upload while every test passed.  The gate is
+        # the token rather than who opened the pull request: dependabot pushes its branches into this
+        # repository, so a fork test reads false for it and it still runs without secrets.
+        if: matrix.full-deps && env.CODECOV_TOKEN != ''
+        uses: codecov/codecov-action@303a32d7a59b442fa8d48b6a1cc6825c09c847a5 # v7.1.1
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: coverage.xml
+          # A failed upload is a broken report, not a passing build. The 100% gate above is the hard
+          # guard either way, so this cannot turn a real coverage drop into a green run.
+          fail_ci_if_error: true
+
+  declared-floors:
+    # Every lower bound on a published extra is a promise, and the lockfile only ever resolves the newest
+    # of each, so the bottom of every range was a claim nobody checked. This job checks them, and each
+    # widening of it found a real defect: first the data libraries, where the refusal gate keyed on
+    # numpy's wording for an unusable operand and that wording is different below numpy 2, then
+    # `asttokens>=2.0` and `behave>=1.2.6`, which were simply wrong, then `starlette>=0.40`, whose test
+    # client reaches a function deprecated in 3.14.
+    #
+    # Scope, said exactly: every extra in `[project.optional-dependencies]`, plus the `dev` and
+    # `integrations` groups, which is what running the suite needs. The `docs`, `typecheck`, `mutation`,
+    # `docs-examples` and `benchmark` groups are not here: each drives a tool with its own command rather
+    # than this suite, and none of them is a promise to anyone installing the package.
+    #
+    # Its own job rather than a cell in the matrix above. An `include` entry naming an `os` and a
+    # `python-version` that already exist is merged into that combination instead of adding one, so a
+    # cell written that way would have replaced the ordinary runs rather than joining them.
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - python-version: "3.10"
+            extras: "allure,behave,data,inline,json,numpy,pandas,polars"
+            groups: "--group dev --group integrations"
+            imports: "typing_extensions, numpy, pandas, polars, asttokens, executing, idna, jsonschema, jsonpath_ng, referencing, allure_commons, behave, attr, attrs, django, flask, httpx, httpx2, pydantic, requests, starlette"
+          - python-version: "3.11"
+            extras: "allure,behave,data,inline,json,numpy,pandas,polars"
+            groups: "--group dev --group integrations"
+            imports: "numpy, pandas, polars, asttokens, executing, idna, jsonschema, jsonpath_ng, referencing, allure_commons, behave, attr, attrs, django, flask, httpx, httpx2, pydantic, requests, starlette"
+          - python-version: "3.12"
+            extras: "allure,behave,data,inline,json,numpy,pandas,polars"
+            groups: "--group dev --group integrations"
+            imports: "numpy, pandas, polars, asttokens, executing, idna, jsonschema, jsonpath_ng, referencing, allure_commons, behave, attr, attrs, django, flask, httpx, httpx2, pydantic, requests, starlette"
+          - python-version: "3.13"
+            extras: "allure,behave,data,inline,json,numpy,pandas,polars"
+            groups: "--group dev --group integrations"
+            imports: "numpy, pandas, polars, asttokens, executing, idna, jsonschema, jsonpath_ng, referencing, allure_commons, behave, attr, attrs, django, flask, httpx, httpx2, pydantic, requests, starlette"
+          - python-version: "3.14"
+            extras: "allure,behave,data,inline,json,numpy,pandas,polars"
+            groups: "--group dev --group integrations"
+            imports: "numpy, pandas, polars, asttokens, executing, idna, jsonschema, jsonpath_ng, referencing, allure_commons, behave, attr, attrs, django, flask, httpx, httpx2, pydantic, requests, starlette"
+          # The one dependency every user gets, at its own floor, and it needs a cell to itself: pydantic
+          # 2.0 requires typing-extensions>=4.6.1, so every cell installing `integrations` resolves it
+          # above the declared bound. Measured 4.0.0 here against 4.6.1 in each of those.
+          - python-version: "3.10"
+            extras: "allure,behave,data,inline,json,numpy,pandas,polars"
+            groups: "--group dev"
+            imports: "typing_extensions, numpy, pandas, polars, asttokens, executing, idna, jsonschema, jsonpath_ng, referencing, allure_commons, behave"
+            reduced: "no integrations, so pydantic cannot lift typing-extensions off its declared floor"
+          # 3.15 carries what is installable and green there. No combination of the data libraries
+          # publishes a wheel for it yet. The `integrations` group installs since pydantic 2.14, and stays
+          # out for one test: this cell resolves anyio 4.15.1 on 3.15 where the cells below resolve
+          # 4.14.2, and starlette at its floor 0.46.0 imports a name that anyio deprecates, which the
+          # suite's `-W error` refuses. Move this cell up to the others when both are settled.
+          - python-version: "3.15"
+            extras: "allure,behave,inline,json"
+            groups: "--group dev"
+            imports: "asttokens, executing, idna, jsonschema, jsonpath_ng, referencing, allure_commons, behave"
+            reduced: "no data-library wheel for 3.15 yet, and starlette at its floor warns under the anyio resolved here"
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
+        with:
+          python-version: ${{ matrix.python-version }}
+          allow-prereleases: true
+
+      - name: Install every declared dependency at its lower bound
+        # `lowest-direct` resolves every direct dependency to the oldest its specifier allows, which is
+        # what the metadata promises. Hand-pinning `numpy==1.26.0` did the same for three of them and
+        # covered none of the rest.
+        #
+        # `--only-binary` because the oldest allowed release is not installable everywhere: pandas 2.0.0
+        # publishes no wheel above 3.11 and building it fails on a missing `pkg_resources`. With it the
+        # resolver lands on the oldest release that has a wheel for this interpreter, which is the oldest
+        # a user of it can actually get. Measured: pandas 2.0.0 on 3.10 and 3.11, 2.1.1 on 3.12, 2.2.3 on
+        # 3.13, 2.3.3 on 3.14.
+        #
+        # `uv pip install` and not `uv sync`, which was measured rewriting `uv.lock` wholesale: the tests
+        # that shell out then read a lockfile that is not the committed one, and six of them failed on
+        # exactly that.
+        #
+        # Every extra by name, `data` and the three it aggregates alike, because
+        # `tests/test_declared_floors.py` reads these lines and asks for each of them.
+        run: |
+          uv venv --python ${{ matrix.python-version }}
+          uv pip install --only-binary=:all: --resolution lowest-direct -e ".[${{ matrix.extras }}]" ${{ matrix.groups }}
+
+      - name: Every installed floor must import
+        # A release old enough to install and too old to import would otherwise leave the cell green:
+        # its tests answer `pytest.importorskip` with a skip, and a skip carrying its own reason is
+        # invisible to the missing-module guard in `tests/conftest.py`.
+        #
+        # The `integrations` group is in the list too, not only the published extras: it is installed by
+        # the same command and its tests skip the same way. The `dev` group is not, because nothing in it
+        # skips: the suite imports pytest and hypothesis to run at all, and the gates that shell out to
+        # ruff and ty refuse rather than skip when the tool does not answer.
+        run: uv run --no-sync python -c "import ${{ matrix.imports }}"
+
+      - name: What this cell resolved
+        # Just what is installed and at which version. Which of those are declared floors, and whether
+        # each was reached, is decided once in `floors-reached` below, where `tomllib` is available and
+        # a requirement carrying an environment marker parses rather than being mangled by a regex.
+        run: |
+          uv run --no-sync python - <<'PROBE'
+          import importlib.metadata as md
+          import pathlib
+
+          with pathlib.Path("resolved.txt").open("w", encoding="utf-8") as verdict:
+              for distribution in sorted(md.distributions(), key=lambda item: item.metadata["Name"] or ""):
+                  name = distribution.metadata["Name"]
+                  if name:
+                      print(f"{name} {distribution.version}", file=verdict)
+          print(pathlib.Path("resolved.txt").read_text(encoding="utf-8"))
+          PROBE
+
+      - name: Keep this cell's resolution for the aggregate
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: floors-resolved-${{ matrix.python-version }}-${{ strategy.job-index }}
+          path: resolved.txt
+          retention-days: 1
+
+      - name: Suite at the floor
+        # `--no-sync` is load bearing here and nowhere else: a bare `uv run` restores the environment
+        # from the lockfile, which would put the newest of everything back and leave this job testing
+        # what the matrix above already tests
+        run: uv run --no-sync pytest -q -n 4 --dist loadfile --ignore=tests/test_docs_examples.py tests
+
+  floors-reached:
+    # The cross-cell half of the floor job, and it has to be cross-cell: `typing-extensions` reaches its
+    # floor only where pydantic is absent, and `attrs` only where it is installed by name rather than
+    # arriving through jsonschema. No cell reaches everything, and between them they do.
+    #
+    # Every declaration is read here rather than in the cells, with `tomllib` rather than a regex: a
+    # requirement carrying an environment marker holds quotes of its own, and reading it by pattern
+    # silently truncated `typing-extensions>=4.0; python_version < '3.11'` to nothing.
+    timeout-minutes: 5
+    needs: declared-floors
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
+
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          pattern: floors-resolved-*
+          path: resolutions
+
+      - name: Every declared floor is reached somewhere
+        run: |
+          uv run --no-project --with packaging python - <<'AGGREGATE'
+          import pathlib
+          import tomllib
+          from packaging.requirements import Requirement
+          from packaging.version import Version
+
+          # keyed by name and floor, because two extras may declare two different bounds on one
+          # distribution and reaching either says nothing about the other
+          UNREACHED: dict[tuple[str, str], str] = {}
+
+          declared = {}
+          project = tomllib.loads(pathlib.Path("pyproject.toml").read_text(encoding="utf-8"))
+          sources = [project["project"]["dependencies"]]
+          sources += list(project["project"]["optional-dependencies"].values())
+          sources += [project["dependency-groups"][name] for name in ("dev", "integrations")]
+          for group in sources:
+              for line in group:
+                  requirement = Requirement(line)
+                  floors = [spec.version for spec in requirement.specifier if spec.operator == ">="]
+                  if floors and requirement.name != "assertpy":
+                      declared.setdefault(requirement.name, set()).add(floors[0])
+
+          installed = {}
+          files = sorted(pathlib.Path("resolutions").rglob("resolved.txt"))
+          if not files:
+              raise SystemExit("no cell reported a resolution, so this job proves nothing")
+          for path in files:
+              for row in path.read_text(encoding="utf-8").splitlines():
+                  name, version = row.rsplit(" ", 1)
+                  installed.setdefault(name.lower().replace("_", "-"), set()).add(version)
+
+          never, stale = [], []
+          for name, floors in sorted(declared.items()):
+              key = name.lower().replace("_", "-")
+              for floor in sorted(floors, key=Version):
+                  reached = any(Version(seen) == Version(floor) for seen in installed.get(key, ()))
+                  excused = (key, floor) in UNREACHED
+                  print(f"{name:18} floor {floor:10} {'reached' if reached else 'NEVER REACHED'}")
+                  if not reached and not excused:
+                      never.append(f"{name}>={floor}")
+                  if reached and excused:
+                      stale.append(f"{name}>={floor}")
+          if never:
+              raise SystemExit(f"declared floors no cell installs: {', '.join(never)}")
+          if stale:
+              raise SystemExit(f"recorded as unreachable and reached anyway, so the note is stale: {', '.join(stale)}")
+          AGGREGATE
+
+  optional-integrations:
+    # allure and behave get their own job because installing them is incompatible with the coverage
+    # gate: with allure present the `except ImportError` fallback in pytest_plugin.py never runs, and
+    # without it the import itself never runs. The gating cell keeps the second state, this one holds
+    # the first. Everywhere else the two are tested against mocks, which accept any call and would
+    # wave through the renamed parameter or moved attribute a Dependabot bump can bring.
+    timeout-minutes: 10
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
+
+      - name: Set up Python
+        uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
+        with:
+          python-version: "3.14"
+
+      - name: Install dependencies
+        run: uv sync --locked --extra json --extra allure --extra behave
+
+      - name: Contract tests against the real libraries
+        run: uv run pytest -v tests/test_optional_integration_contracts.py
+
+      - name: The rest of the suite must also pass with both installed
+        # Installing allure flips `_HAS_ALLURE`, so every failing assertion in the suite takes the
+        # real attach path. That must not change any other test's outcome.
+        run: uv run pytest -q -n 4 --dist loadfile --ignore=tests/test_docs_examples.py tests
+
+  lint:
+    timeout-minutes: 10
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
+
+      - name: Set up Python
+        uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
+        with:
+          python-version: "3.14"
+
+      - name: Install dependencies
+        # the whole `data` stack, because the overloads narrow on *structure* and the structures are
+        # pandas', polars' and numpy's to change. A stub release that stops declaring the member a
+        # shape keys on moves those values back to the generic builder, silently: it type-checks, and
+        # the narrowed methods just stop being offered. The integration matrix below is what notices
+        run: uv sync --locked --extra json --extra data --extra inline --group typecheck --group integrations
+
+      - name: Ruff check
+        run: uv run ruff check .
+
+      - name: Ruff format check
+        run: uv run ruff format --check .
+
+      - name: Type check (ty)
+        run: uv run ty check assertpy/ tests/test_typing.py
+
+      - name: Type check (mypy --strict, public typing surface)
+        run: uv run mypy --strict --follow-imports=silent tests/test_typing.py
+
+      # the engine, not the launcher: `pyright` on PyPI and the npm engine it launches are released apart
+      # and have drifted before, and every recorded number here was recorded against one build. The
+      # gates that call pyright from Python pin the same one, in `tests/typing_harness.py`
+      - name: Type check (pyright, public typing surface)
+        env:
+          PYRIGHT_PYTHON_FORCE_VERSION: "1.1.414"
+        run: uv run pyright --pythonversion 3.14 tests/test_typing.py
+
+      # a fourth overload-resolution engine on the same file, which is what the badge names. Its
+      # settings are in `pyrefly.toml`, and the preset there is deliberate: the fallback one answers
+      # green while looking at much less
+      - name: Type check (pyrefly, public typing surface)
+        run: uv run pyrefly check tests/test_typing.py
+
+      # the fourth checker over the promises too: the harness reads three, and both defects the file
+      # was written for were accepted by all four
+      - name: Type check (pyrefly, the object matches the promise)
+        run: uv run pyrefly check tests/typing_promises.py
+
+      # the gates that need the checkers this job installs: each file's docstring says what it holds
+      - name: Type check (pytest gates, all four checkers)
+        run: >
+          uv run pytest -q -n 4 --dist loadfile
+          tests/test_pyright_baseline.py
+          tests/test_typing_completeness.py
+          tests/test_typing_promises.py
+          tests/test_typing_negative.py
+          tests/test_typing_chain_corpus.py
+          tests/test_typing_integrations.py
+          tests/test_typing_http.py
+          tests/test_typing_from_a_wheel.py
+          tests/test_check_protocols.py
+          tests/test_operation_contract.py
+          tests/test_typing_conformance.py
+
+  sdist:
+    # the suite as a distribution runs it, from the sdist: `scripts/check_sdist.py` says how and why
+    timeout-minutes: 20
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - mode: packager
+            options: '--export="--extra json"'
+          # the lint job's set, for the type-checker gates
+          - mode: developer
+            options: '--developer --export="--extra json --extra data --extra inline --group typecheck --group integrations"'
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
+
+      - name: Set up Python
+        uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
+        with:
+          python-version: "3.14"
+
+      - name: The suite from the sdist and from the checkout (${{ matrix.mode }})
+        run: >
+          python scripts/check_sdist.py ${{ matrix.options }} --work "$RUNNER_TEMP/check_sdist"
+          -- -q -n 4 --dist loadfile --ignore=tests/test_docs_examples.py tests
+
+  ci-ok:
+    timeout-minutes: 5
+    needs: [test, declared-floors, floors-reached, optional-integrations, lint, sdist]
+    if: always()
+    runs-on: ubuntu-latest
+    steps:
+      - name: Verify required jobs succeeded
+        env:
+          TEST_RESULT: ${{ needs.test.result }}
+          FLOOR_RESULT: ${{ needs.declared-floors.result }}
+          REACHED_RESULT: ${{ needs.floors-reached.result }}
+          INTEGRATIONS_RESULT: ${{ needs.optional-integrations.result }}
+          LINT_RESULT: ${{ needs.lint.result }}
+          SDIST_RESULT: ${{ needs.sdist.result }}
+        run: |
+          [ "$TEST_RESULT" = "success" ] &&
+          [ "$FLOOR_RESULT" = "success" ] &&
+          [ "$REACHED_RESULT" = "success" ] &&
+          [ "$INTEGRATIONS_RESULT" = "success" ] &&
+          [ "$LINT_RESULT" = "success" ] &&
+          [ "$SDIST_RESULT" = "success" ]

assertpy-2.36.0/.gitignore

@@ -0,0 +1,34 @@
+# .gitignore
+*.py[cod]
+.cache
+.pytest_cache
+__pycache__
+
+# testing output
+*.xml
+*.log
+cover
+.coverage
+htmlcov
+.hypothesis
+__snapshots
+mycustompath
+
+# packaging
+MANIFEST
+dist
+
+# mac
+.DS_Store
+
+# venv
+.venv
+
+# IDE
+/.idea
+.vscode
+
+# docs output
+docs/build
+docs/out
+/site/

assertpy-2.36.0/ARCHITECTURE.md

@@ -0,0 +1,167 @@
+# The typed surface
+
+`assert_that()` hands back a different set of methods depending on what you gave it, and four checkers have to
+agree on which set. Read this before changing a public signature. None of it is discoverable from the files.
+
+## Two halves
+
+The runtime is a stack of mixins. `AssertionBuilder` inherits `StringMixin`, `NumericMixin`, `DictMixin` and a
+dozen more, so every assertion exists on every value and refuses what it cannot handle.
+
+The typed surface is Protocols in `assertpy/_engine/_typing.py`, one per kind of value, picked by an overload
+ladder on `assert_that` in `assertpy/assertpy.py`. A checker sees only the protocol, so
+`assert_that({}).is_positive()` is a type error and `assert_that(1).is_positive()` is not.
+
+Neither half knows about the other. Everything below keeps them from drifting apart.
+
+Most of it is not yours to edit:
+
+| file | protocols | declarations |
+|---|---|---|
+| `_engine/_typing.py` | 43 | 415 |
+| `_engine/_check_typing.py` | 34 | 326 |
+| `_engine/_builder_check_typing.py` | 1 | 320 |
+| `_engine/_capable_typing.py` | 10 | 325 |
+| `_engine/_poll_typing.py` | 22 | 1505 |
+| `_engine/_negated_typing.py` | 23 | 1053 |
+
+One is written by hand. `tests/test_architecture_doc.py` recomputes this table. No line counts, which
+move on every edit to a generated file.
+
+## What is generated
+
+| file | written by | built from |
+|---|---|---|
+| `_engine/_typing.py` | hand | the protocols themselves |
+| `assertpy.py` overload ladder | hand | which protocol each subject resolves to |
+| `_engine/_poll_typing.py` | `scripts/generate_poll_protocols.py` | `_typing.py`, `assertpy.py`, `_engine/_operations.py` |
+| `_engine/_builder_check_typing.py` | `scripts/generate_poll_protocols.py` | the same three |
+| `_engine/_capable_typing.py` | `scripts/generate_poll_protocols.py` | the **runtime mixins** under `assertpy/*.py`, `_engine/_operations.py` |
+| `_engine/_negated_typing.py` | `scripts/generate_poll_protocols.py` | `_typing.py` and `_engine/_operations.py` |
+| `_engine/_check_typing.py` | `scripts/generate_check_protocols.py` | `_typing.py`, `_engine/_operations.py` |
+
+One script writes four of them. That is the part people miss.
+
+- **polling twins** answer `eventually()` and `eventually_sync()`, so every assertion hands back the chain.
+- **verdict twins** answer `check()`, returning an `AssertionOutcome` instead of `Self`.
+- **the capability façade** stands in for the builder itself, so it reads the mixins rather than the views:
+  reading the views would narrow it to what one value type answers. It skips its own hand-written list, and
+  takes which mixin methods pivot from `_engine/_operations.py`, since the mixins write those `-> Self` too.
+- **negation twins** answer `.not_`, where one assertion hands back the view the chain had before it.
+
+`_engine/_operations.py` decides what the first two leave out: `NOT_AN_OPERATION`, `WITHOUT_A_VERDICT`.
+
+## Changing a signature
+
+```bash
+uv run python scripts/regenerate.py
+```
+
+That runs both generators, re-records `tests/api_snapshot.json`, which pins the public surface, and
+re-records the table of sizes above. Read the diff it leaves.
+
+**The generators carry hard-coded import lines.** A signature naming something the generated file did not
+already import produces a file that will not compile, and ruff reports `F821 Undefined name` against a file you
+never edited. Add the name to the import template in the generator.
+
+## Adding a type of value
+
+The runtime comes first, because the rest is generated or recorded from it.
+
+1. Write the mixin, compose it into `AssertionBuilder`'s bases.
+2. Add it to `_COVERAGE` in `tests/test_protocol_parity.py`, which has its own gate.
+3. Declare the protocol in `_engine/_typing.py`.
+4. Add the arm to the `assert_that` ladder in `assertpy.py`.
+5. Pin it with `assert_type` in `tests/test_typing.py`, the file the README badge is about.
+6. Regenerate.
+7. Re-record the snapshot, last.
+
+Regenerating before step 1 produces a stale façade. Recording the snapshot before the mixin is composed makes
+its gate red again.
+
+## Adding an assertion to a type that exists
+
+The skipped step is the third.
+
+1. Write the method on its mixin.
+2. Declare it on the protocols it applies to in `_engine/_typing.py`, and on those only. A declaration
+   on `_CoreAssertion` offers it to every value, which is the thing the typed surface exists to avoid.
+3. Register it in `_engine/_operations.py` unless it is a plain assertion. No verdict goes in
+   `WITHOUT_A_VERDICT` under what it does instead, since `check()` and `not_` mean nothing on it and
+   both used to accept them. A pivot that also asserts goes in `ALSO_ASSERTS`, since reaching
+   `self.error()` does not separate a verdict from a precondition.
+4. If the polling twin is meant to leave it out, add the name to `_AFTER_A_CALL` in
+   `tests/test_poll_protocols.py`. The whole caught-exception family is absent from that twin, and the
+   list is what says so on purpose rather than by accident.
+5. Regenerate. The generators emit what they find, so a missing declaration surfaces not here but in
+   `test_protocol_parity.py::test_mixin_methods_are_declared_on_its_protocols`.
+
+A signature naming a type the generated files do not import produces a file that does not compile. The
+import lines are templates inside the generators.
+
+## The gates
+
+| gate | the question it answers |
+|---|---|
+| `test_typing.py` | does each subject resolve to the protocol it should, under all four checkers |
+| `test_pin_coverage.py` | does every declaration that changes the type have a pin above |
+| `test_protocol_parity.py` | does every declared method exist on the runtime builder |
+| `test_typing_conformance.py` | do the declaration and the runtime agree parameter by parameter |
+| `test_poll_protocols.py` | are the polling twins what the generator produces today |
+| `test_check_protocols.py` | are the verdict twins |
+| `test_capable_protocol.py` | is the façade |
+| `test_api_compatibility.py` | has the public surface moved without the snapshot being re-recorded |
+| `test_typing_completeness.py` | can a checker name a type for every exported symbol |
+| `test_pyright_baseline.py` | has a new pyright diagnostic appeared in the package |
+| `test_typing_promises.py` | is the object at the end of a chain the type the checker was promised |
+| `test_negated_protocols.py` | does every reachable view have a negation twin that hands the view back, and is the file what the generator produces |
+| `test_architecture_doc.py` | does this document still describe the tree, counts included |
+| `test_typing_negative.py` | do the checkers still refuse what they should |
+| `test_typing_chain_corpus.py` | do the chains the chain model takes, to two pivots, still type the way they were recorded |
+| `test_typing_from_a_wheel.py` | does the typed surface survive packaging |
+| `test_typing_integrations.py`, `test_typing_http.py` | do real pandas, polars, numpy and HTTP values still resolve |
+| `test_typing_harness.py` | is pyright's report read off its output alone, and refused where that is not one report |
+| `test_overload_order.py` | is the frame overload still above every other shape-keyed one |
+| `test_operation_contract.py` | is the register of operations that reach no verdict still the true one |
+| `test_typing_claims.py` | are the four checkers still run with zero suppressions, as the badge says |
+| `test_docs_typing.py` | do the snippets in the README and the guides type-check |
+| `test_public_surface.py` | does `import assertpy` still give what it gave |
+
+Which one goes red tells you what you did:
+
+- a declaration the runtime does not have: `test_protocol_parity.py`
+- a declaration whose parameters the runtime does not match: `test_typing_conformance.py`
+- a generated file edited by hand: that file's own gate, one of the four
+- a protocol changed without regenerating: the polling, verdict and negation gates, never the facade one,
+  which reads the mixins instead
+- a subject resolving to the wrong protocol: `test_typing.py`, and only under whichever checker sees it
+- a public name added or moved: `test_api_compatibility.py`, which is a snapshot rather than a rule
+
+The four checkers are ty, mypy `--strict`, Pyright and Pyrefly. Where they disagree it is recorded, in
+`tests/typing_negative_baseline.py`, `tests/typing_integrations_baseline.py` and
+`tests/typing_chain_corpus_baseline.json`.
+
+Pyright's engine is pinned in `tests/typing_harness.py`. The PyPI distribution is a launcher for a node package
+and the two move at different speeds.
+
+## True, though it looks wrong
+
+- **`assert_that`'s implementation returns `Any`.** The real return made Pyright allocate four gigabytes against
+  a protocol carrying the whole surface and die. The overloads are what callers see.
+- **Some overlapping overloads are deliberate**, recorded per method in `tests/pyright_baseline.py`.
+- **Some variance suggestions are refused**, recorded there too, per TypeVar.
+- **`ty` is scoped to `assertpy/` and `tests/test_typing.py`.** Over the whole tree it reports hundreds of
+  diagnostics from `tests/`, which is full of calls that must not type-check.
+
+## Where the two halves may differ
+
+**Which methods are offered.** At run time every assertion exists on every value; a typed view offers only the
+ones that apply. That gap is the point of the typed surface.
+
+**What an offered method accepts.** Here they must agree exactly, and both directions have shipped as defects:
+
+- the type **refuses** what the runtime accepts, so working code is rejected
+- the type **accepts** what the runtime refuses, so a checker approves a call that raises
+
+The runtime is the fact and the declaration follows it. `ClassInfo` in `_matcher_impls.py` is the worked
+example: recursive because `isinstance` accepts tuples nested to any depth.