assertpy2 2.20.0__tar.gz → 2.20.1__tar.gz

{assertpy2-2.20.0 → assertpy2-2.20.1}/.github/workflows/ci.yml

@@ -17,6 +17,10 @@ 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]
@@ -75,7 +79,11 @@ jobs:
         # 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.
-        if: matrix.full-deps
+        # 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@fb8b3582c8e4def4969c97caa2f19720cb33a72f # v7.0.0
         with:
           token: ${{ secrets.CODECOV_TOKEN }}

{assertpy2-2.20.0 → assertpy2-2.20.1}/.github/workflows/codeql.yml

@@ -21,7 +21,7 @@ jobs:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
-      - uses: github/codeql-action/init@e4fba868fa4b1b91e1fdab776edc8cfbe6e9fb81 # v4.37.3
+      - uses: github/codeql-action/init@d1ba80a13dd99fba24a470575428917156a28b43 # v4.37.5
         with:
           languages: python
-      - uses: github/codeql-action/analyze@e4fba868fa4b1b91e1fdab776edc8cfbe6e9fb81 # v4.37.3
+      - uses: github/codeql-action/analyze@d1ba80a13dd99fba24a470575428917156a28b43 # v4.37.5

{assertpy2-2.20.0 → assertpy2-2.20.1}/.github/workflows/codspeed.yml

@@ -35,7 +35,7 @@ jobs:
         uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
 
       - name: Run benchmarks under CodSpeed
-        uses: CodSpeedHQ/action@f22792bfac16f3e14eb9fbea76f4a48e9cc22b93 # v4.19.1
+        uses: CodSpeedHQ/action@0ca9cbbf4623b599a6c3ed4fc8a922942705d9f1 # v5.0.2
         with:
           mode: simulation
           run: uv run --locked --group benchmark pytest benchmarks/ --codspeed --no-cov

{assertpy2-2.20.0 → assertpy2-2.20.1}/.github/workflows/publish.yml

@@ -66,7 +66,7 @@ jobs:
         run: syft scan dir:dist -o "cyclonedx-json=provenance/assertpy2.sbom.cdx.json"
 
       - name: Publish to PyPI
-        uses: pypa/gh-action-pypi-publish@ba38be9e461d3875417946c167d0b5f3d385a247 # v1.14.1
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
 
       - name: Upload to GitHub Release
         run: gh release upload "$TAG_NAME" dist/* provenance/*

{assertpy2-2.20.0 → assertpy2-2.20.1}/.github/workflows/scorecard.yml

@@ -30,6 +30,6 @@ jobs:
           name: SARIF file
           path: results.sarif
           retention-days: 5
-      - uses: github/codeql-action/upload-sarif@e4fba868fa4b1b91e1fdab776edc8cfbe6e9fb81 # v4.37.3
+      - uses: github/codeql-action/upload-sarif@d1ba80a13dd99fba24a470575428917156a28b43 # v4.37.5
         with:
           sarif_file: results.sarif

{assertpy2-2.20.0 → assertpy2-2.20.1}/.github/workflows/zizmor.yml

@@ -23,4 +23,4 @@ jobs:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
-      - uses: zizmorcore/zizmor-action@6fc4b006235f201fdab3722e17240ab420d580e5 # v0.6.1
+      - uses: zizmorcore/zizmor-action@3dc1ecc9bcb9e94e9b2c709687979e1298497054 # v0.6.2

{assertpy2-2.20.0 → assertpy2-2.20.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: assertpy2
-Version: 2.20.0
+Version: 2.20.1
 Summary: Fluent assertion library for Python with composable matchers, structural matching, and full type safety
 Project-URL: Homepage, https://github.com/Solganis/assertpy2
 Project-URL: Repository, https://github.com/Solganis/assertpy2

{assertpy2-2.20.0 → assertpy2-2.20.1}/assertpy2/_engine/_diff.py

@@ -29,12 +29,18 @@ from __future__ import annotations
 
 import dataclasses
 import difflib
+from typing import TYPE_CHECKING, TypeVar
 
 from ..errors import DiffEntry, DiffResult, _safe_repr
 from ._compare import _node_decision
 from ._introspection import is_attrs_instance, is_mapping_like, is_model_dump_object, is_namedtuple
 from ._path import _ROOT, _Path
 
+if TYPE_CHECKING:
+    from collections.abc import Hashable, Iterable
+
+_K = TypeVar("_K", bound="Hashable")  # a mapping key or a field name, kept as itself through the walk
+
 __tracebackhide__ = True
 
 
@@ -254,20 +260,34 @@ def _element_entries(actual_item, expected_item, path: _Path, seen, config) -> l
     return _child_entries(actual_item, expected_item, path, descended_for=decision, _seen=seen, config=config)
 
 
+def _ordered_keys(actual: Iterable[_K], expected: Iterable[_K]) -> list[_K]:
+    """Every key of both sides, in the order a reader wrote them.
+
+    A union of two sets loses insertion order, which is why this used to be sorted: without an order
+    imposed, the report varied with the hash seed.  Sorting bought determinism at the price of the one
+    ordering that carries meaning - a JSON response reads in the order its fields arrived, and `k0, k1,
+    k10, k100` reads as no order at all.  Walking the actual side and then the keys only the expected
+    side has is just as deterministic, and it is the order pytest shows.
+    """
+    seen = set(actual)
+    return [*actual, *(key for key in expected if key not in seen)]
+
+
 def _dataclass_diff_entries(actual, expected, prefix: _Path, seen, config=None) -> list[DiffEntry]:
-    """Diff two dataclasses over the sorted union of field names, both directions, recursing.
+    """Diff two dataclasses over both sides' field names in declaration order, recursing.
 
     Reports fields present on only one side, and recurses into nested containers.  ``seen`` must
     already include the ids of ``actual``/``expected``.  Shared by the top-level and nested paths
     so both report dataclass fields identically.
     """
     entries: list[DiffEntry] = []
-    actual_names = {field.name for field in dataclasses.fields(actual)}
-    expected_names = {field.name for field in dataclasses.fields(expected)}
-    for field in sorted(actual_names | expected_names):
-        if field not in expected_names:
+    actual_names = [field.name for field in dataclasses.fields(actual)]
+    expected_names = [field.name for field in dataclasses.fields(expected)]
+    in_actual, in_expected = set(actual_names), set(expected_names)
+    for field in _ordered_keys(actual_names, expected_names):
+        if field not in in_expected:
             entries.append(prefix.attr(field).entry(actual=getattr(actual, field), expected=None, absent="expected"))
-        elif field not in actual_names:
+        elif field not in in_actual:
             entries.append(prefix.attr(field).entry(actual=None, absent="actual", expected=getattr(expected, field)))
         else:
             actual_value = getattr(actual, field)
@@ -356,7 +376,7 @@ def _build_equality_diff(
         actual_dict = _field_dict(actual, both_model)
         expected_dict = _field_dict(expected, both_model)
         entries = []
-        for key in sorted(set(actual_dict) | set(expected_dict)):
+        for key in _ordered_keys(actual_dict, expected_dict):
             if key not in expected_dict:
                 entries.append(_prefix.attr(key).entry(actual=actual_dict[key], expected=None, absent="expected"))
             elif key not in actual_dict:
@@ -439,7 +459,7 @@ def _sub_diff_entries(
         entries: list[DiffEntry] = []
         actual_keys = set(actual)
         expected_keys = set(expected)
-        for key in sorted(actual_keys | expected_keys, key=_safe_repr):
+        for key in _ordered_keys(actual, expected):
             if key not in expected_keys:
                 entries.append(prefix.key(key).entry(actual=actual[key], expected=None, absent="expected"))
             elif key not in actual_keys:
@@ -504,7 +524,7 @@ def _sub_diff_entries(
         actual_dict = _field_dict(actual, both_model)
         expected_dict = _field_dict(expected, both_model)
         entries = []
-        for key in sorted(set(actual_dict) | set(expected_dict)):
+        for key in _ordered_keys(actual_dict, expected_dict):
             if key not in expected_dict:
                 entries.append(prefix.attr(key).entry(actual=actual_dict[key], expected=None, absent="expected"))
             elif key not in actual_dict:

{assertpy2-2.20.0 → assertpy2-2.20.1}/assertpy2/assertpy.py

@@ -2,9 +2,7 @@
 
 from __future__ import annotations
 
-import contextlib
 import contextvars
-import inspect
 import logging
 import os
 import sys
@@ -16,7 +14,7 @@ from typing import TYPE_CHECKING, Any, Final, Generic, Literal, TypeVar, overloa
 if TYPE_CHECKING:
     import datetime
     import pathlib
-    from collections.abc import Callable, Iterator
+    from collections.abc import Callable
 
     from typing_extensions import TypeIs
 
@@ -60,7 +58,7 @@ from .snapshot import SnapshotMixin
 from .string import StringMixin
 from .warning import WarningMixin
 
-__version__ = "2.20.0"
+__version__ = "2.20.1"
 
 # the tracked value type of the generic AssertionBuilder fallback (_U appears only in narrowing stubs)
 _T = TypeVar("_T")
@@ -73,33 +71,44 @@ if TYPE_CHECKING:
     _V = TypeVar("_V")  # dict value type
 
 __tracebackhide__ = True  # clean tracebacks via py.test integration
-contextlib.__tracebackhide__ = True  # ty: ignore[unresolved-attribute]  # pytest monkey-patch
 
 # assertpy2 source files, used to strip internal frames when locating the caller for warn-mode messages.
 # Derived from the package directory so new modules are covered automatically (no hand-maintained list).
-ASSERTPY_FILES: Final = [
-    os.path.join("assertpy2", name) for name in os.listdir(os.path.dirname(__file__)) if name.endswith(".py")
-]
+# Absolute paths in a set, not suffixes in a list: membership is one hash lookup per frame where the
+# suffix scan ran `endswith` once per module, thirty string comparisons a frame on a path taken for
+# every collected soft failure.  Exact paths also stop a user file of the same name from shadowing ours.
+ASSERTPY_FILES: Final = frozenset(
+    os.path.join(os.path.dirname(__file__), name)
+    for name in os.listdir(os.path.dirname(__file__))
+    if name.endswith(".py")
+)
 
 
 def _caller_location() -> tuple[str, int] | None:
     """The ``(filename, lineno)`` of the user frame that called into assertpy2, skipping internal frames.
 
-    Used to locate a warn-mode warning and each collected soft-assertion failure.  A user file living
-    under a directory named ``assertpy2`` could shadow every frame, so ``None`` is returned rather than
-    crashing.
+    Used to locate a warn-mode warning and each collected soft-assertion failure.
+
+    The answer is the frame just outside the *outermost* assertpy2 frame, which is why the walk cannot
+    stop at the first user frame it meets going inwards: a predicate passed to `satisfies()` or `each()`
+    runs inside our own call, and the line worth reporting is the assertion in the test rather than the
+    lambda we invoked.  Walking outwards and keeping the last handover does the same in one pass,
+    without building a list of the whole stack.
+
+    ``None`` where no such handover exists, so a caller that cannot be located logs without the prefix
+    instead of crashing on unpacking.
     """
-    frames = []
-    frame = inspect.currentframe()
+    frame: types.FrameType | None = sys._getframe(1)  # CPython accessor; the inspect equivalent is 10x slower here
+    location: tuple[str, int] | None = None
+    inner_is_internal = False
     while frame:
-        frames.append((frame.f_code.co_filename, frame.f_lineno))
+        filename = frame.f_code.co_filename
+        is_internal = filename in ASSERTPY_FILES
+        if inner_is_internal and not is_internal:
+            location = (filename, frame.f_lineno)
+        inner_is_internal = is_internal
         frame = frame.f_back
-    previous: tuple[str, int] | None = None
-    for filename, lineno in reversed(frames):
-        if any(filename.endswith(internal) for internal in ASSERTPY_FILES):
-            return previous
-        previous = (filename, lineno)
-    return None  # pragma: no cover - error() is always reached through an assertpy frame
+    return location
 
 
 # soft assertions (contextvars for thread/async safety)
@@ -110,12 +119,33 @@ _soft_err: contextvars.ContextVar[list[AssertionOutcome]] = contextvars.ContextV
 _soft_group: contextvars.ContextVar[str | None] = contextvars.ContextVar("assertpy2_soft_group", default=None)
 
 
+class _Group:
+    """The context `group()` hands back.
+
+    A class rather than a `@contextlib.contextmanager` generator, and the same goes for the soft block
+    itself.  A generator-based manager puts `contextlib.__exit__` on the stack, so a failure raised on
+    the way out is reported against `contextlib.py` instead of the `with` line in the test.  The old
+    cure was setting `__tracebackhide__` on the `contextlib` module, which fixed our two managers by
+    changing how every third-party context manager in the process is reported.
+    """
+
+    __slots__ = ("_label", "_token")
+
+    def __init__(self, label: str) -> None:
+        self._label = label
+
+    def __enter__(self) -> None:
+        self._token = _soft_group.set(self._label)
+
+    def __exit__(self, *_exc: object) -> None:
+        _soft_group.reset(self._token)
+
+
 class SoftAssertionCollector:
     """Collector returned by [`soft_assertions()`][assertpy2.assertpy.soft_assertions] for grouping
     errors hierarchically."""
 
-    @contextlib.contextmanager
-    def group(self, label: str) -> Iterator[None]:
+    def group(self, label: str) -> _Group:
         """Group subsequent assertion failures under *label*.
 
         Examples:
@@ -127,11 +157,7 @@ class SoftAssertionCollector:
                     with sa.group("Body"):
                         assert_that(body["status"]).is_equal_to("ok")
         """
-        token = _soft_group.set(label)
-        try:
-            yield
-        finally:
-            _soft_group.reset(token)
+        return _Group(label)
 
 
 def _located(location: tuple[str, int] | None, msg: str) -> str:
@@ -184,8 +210,32 @@ def _format_soft_errors(errs: list[AssertionOutcome]) -> str:
     return "\n".join(lines)
 
 
-@contextlib.contextmanager
-def soft_assertions() -> Iterator[SoftAssertionCollector]:
+class _SoftAssertions:
+    """The context `soft_assertions()` hands back.  See `_Group` for why this is a class."""
+
+    __slots__ = ()
+
+    def __enter__(self) -> SoftAssertionCollector:
+        ctx = _soft_ctx.get()
+        if ctx == 0:
+            _soft_err.set([])
+        _soft_ctx.set(ctx + 1)
+        return SoftAssertionCollector()
+
+    def __exit__(self, exc_type: type[BaseException] | None, *_exc: object) -> None:
+        _soft_ctx.set(_soft_ctx.get() - 1)
+        if exc_type is not None:
+            return  # an error out of the block wins: it says more than the failures collected before it
+        errs = _soft_err.get([])
+        if errs and _soft_ctx.get() == 0:
+            out = _format_soft_errors(errs)
+            _soft_err.set([])
+            # the same class as a single failure, so one `except AssertionFailure` covers a soft block
+            # too, and it hands back what it aggregated rather than only the text it rendered
+            raise AssertionFailure(out, failures=tuple(errs))
+
+
+def soft_assertions() -> _SoftAssertions:
     """Create a soft assertion context.
 
     Normally, any assertion failure will halt test execution immediately by raising an error.
@@ -232,23 +282,7 @@ def soft_assertions() -> Iterator[SoftAssertionCollector]:
         If you need more forgiving behavior, use [`soft_fail()`][assertpy2.assertpy.soft_fail] to add
         a failure message without halting test execution.
     """
-    ctx = _soft_ctx.get()
-    if ctx == 0:
-        _soft_err.set([])
-    _soft_ctx.set(ctx + 1)
-
-    try:
-        yield SoftAssertionCollector()
-    finally:
-        _soft_ctx.set(_soft_ctx.get() - 1)
-
-    errs = _soft_err.get([])
-    if errs and _soft_ctx.get() == 0:
-        out = _format_soft_errors(errs)
-        _soft_err.set([])
-        # the same class as a single failure, so one `except AssertionFailure` covers a soft block too,
-        # and it hands back what it aggregated rather than only the text it rendered
-        raise AssertionFailure(out, failures=tuple(errs))
+    return _SoftAssertions()
 
 
 def assert_all(*callables: Callable[[], object]) -> None:

{assertpy2-2.20.0 → assertpy2-2.20.1}/assertpy2/dynamic.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import collections.abc
 import inspect
+from typing import Any
 
 from ._engine._introspection import is_namedtuple
 from ._engine._mixin_base import _MixinBase
@@ -43,9 +44,22 @@ class DynamicMixin(_MixinBase):
         assert_that(fred).has_shoe_size(12)
     """
 
-    def __getattr__(self, attr):
+    def __getattr__(self, attr: str) -> Any:
         """Asserts that val has attribute attr and that its value is equal to other via a dynamic
-        assertion of the form ``has_<attr>()``."""
+        assertion of the form ``has_<attr>()``.
+
+        The return stays ``Any`` on purpose, and the reason is written down because the annotation looks
+        like an oversight worth fixing.  Two unrelated things resolve through this hook: a ``has_``
+        wrapper, which takes one argument and hands back the builder, and any name registered with
+        `add_extension`, which takes and returns whatever it declares.  No single signature is true of
+        both.  Pinning the argument list reported a correct zero-argument extension call as too few
+        arguments, and pinning the return type reported a correct extension result as the wrong type
+        where it was used.  Both were measured against mypy, pyright and ty.
+
+        The narrower annotation also bought less than it looked like.  It could not catch an assertion
+        chained onto a dynamic step, because that access resolves back through this same hook; the only
+        thing it added was a verdict in assignment position, which is where it was wrong for extensions.
+        """
         if not attr.startswith("has_"):
             raise AttributeError(f"assertpy has no assertion <{attr}()>")
 

{assertpy2-2.20.0 → assertpy2-2.20.1}/assertpy2/errors.py

@@ -198,6 +198,17 @@ def _diff_side(value: object, limit: int = 400) -> str:
     return _truncated(_safe_repr(value), limit)
 
 
+def _diff_sides(actual: object, expected: object, limit: int = 400) -> tuple[str, str]:
+    """Both sides of one comparison, capped onto the difference rather than from the start.
+
+    `_diff_side` caps each side on its own, which is right for a row that stands alone.  A pair read
+    together needs the pair's window: two 10 000-character strings differing in the middle were both
+    cut at character 400, so the section printed two identical-looking values under a heading saying
+    they were not equal, while the diff below it pointed straight at the change.
+    """
+    return _windowed(_safe_repr(actual), _safe_repr(expected), limit)
+
+
 def _windowed(actual: str, expected: str, width: int = 160) -> tuple[str, str]:
     """Both lines cut to a window around their first difference.
 

{assertpy2-2.20.0 → assertpy2-2.20.1}/assertpy2/helpers.py

@@ -6,11 +6,6 @@ import math
 import numbers
 import re
 
-try:
-    import attrs
-except ImportError:  # pragma: no cover - optional dependency; the attrs branch runs only when present
-    attrs = None  # ty: ignore[invalid-assignment]  # sentinel for the absent optional module
-
 from assertpy2.errors import DiffResult, _safe_repr, _truncated, _windowed
 
 from ._engine._compare import _CompareConfig, _config_note, _guarded_not_equal, _node_decision, _spec_matches
@@ -437,9 +432,10 @@ class HelpersMixin(_MixinBase):
             _seen = _seen | {id(mapping)}
             parts = []
             ellip = False
-            # build items by iterating keys + [] (the dict-likeness gate guarantees those, not items())
-            mapping_items = ((key, mapping[key]) for key in mapping)
-            for key, value in sorted(mapping_items, key=lambda item: _safe_repr(item[0])):
+            # build items by iterating keys + [] (the dict-likeness gate guarantees those, not items()).
+            # left in the order the mapping holds them, which is what the diff under this line prints:
+            # sorting only here made the two halves of one message disagree about where a key sits
+            for key, value in ((key, mapping[key]) for key in mapping):
                 if key not in counterpart:
                     parts.append(f"{_safe_repr(key)}: {_safe_repr(value)}")
                 else:
@@ -550,7 +546,15 @@ class HelpersMixin(_MixinBase):
         if is_model_dump_object(obj):
             return obj.model_dump()
         if is_attrs_instance(obj):
-            # attrs is importable whenever an attrs instance exists, so the guarded import bound it;
+            # deferred, and the only import in the package that is: at module level it cost 8.5 ms and
+            # 22 modules of a 39.8 ms import, a fifth of it, paid by every pytest run in an environment
+            # where attrs happens to be installed.  The auto-loaded plugin means that is every run, and
+            # it was paid whether or not any attrs instance ever reached a comparison.  Here it is paid
+            # by the one branch that needs it, and the guard above already proved the library is present
+            # (nothing carries `__attrs_attrs__` unless attrs built it).  Every other optional
+            # dependency in the package is imported inside its own branch for the same reason.
+            import attrs
+
             # asdict recurses like dataclasses.asdict, flattening nested attrs for ignore/include
             return attrs.asdict(obj)
         if hasattr(obj, "__dict__") and not isinstance(obj, type):

{assertpy2-2.20.0 → assertpy2-2.20.1}/assertpy2/pytest_plugin.py

@@ -12,7 +12,7 @@ from . import _inline, _satisfies, async_assertions, errors
 from . import snapshot as _snapshot
 from ._engine._diff import _sub_diff_entries
 from ._engine._path import _ROOT
-from .errors import _diff_side, _json_safe, _render_diff
+from .errors import _diff_side, _diff_sides, _json_safe, _render_diff
 
 try:
     import allure  # ty: ignore[unresolved-import]  # optional dependency
@@ -368,9 +368,15 @@ def pytest_runtest_makereport(item, call):
         # capped like the diff rows: this section is read on a terminal, and the untouched values stay
         # on the exception for anything that wants them
         lines = []
-        if named_actual:
+        if named_actual and named_expected:
+            # windowed as a pair: capping each side on its own hides the difference when it sits past
+            # the cap, and prints two values that look identical under a heading saying they are not
+            left, right = _diff_sides(actual, expected)
+            lines.append(f"  actual:   {left}")
+            lines.append(f"  expected: {right}")
+        elif named_actual:
             lines.append(f"  actual:   {_diff_side(actual)}")
-        if named_expected:
+        else:
             lines.append(f"  expected: {_diff_side(expected)}")
         report.sections.append(("AssertionFailure", "\n".join(lines)))
 

assertpy2-2.20.1/docs/concepts/stability.md

@@ -0,0 +1,63 @@
+# Stability
+
+What you can build on, and what enforces it. Every row below is held by a test that fails CI, not by
+an intention.
+
+## The contract
+
+| You can depend on | Enforced by |
+|---|---|
+| The 36 names `assertpy2` exports, and the fields of every record it hands you | [`test_public_surface.py`](https://github.com/Solganis/assertpy2/blob/main/tests/test_public_surface.py) pins both against a hand-written list |
+| Every assertion the type checker offers you existing at runtime | [`test_protocol_parity.py`](https://github.com/Solganis/assertpy2/blob/main/tests/test_protocol_parity.py) walks all ten protocols |
+| The type your chain has after each step | [`test_typing.py`](https://github.com/Solganis/assertpy2/blob/main/tests/test_typing.py), 123 `assert_type` checks under ty, mypy `--strict` and Pyright, zero suppressions |
+| One relation keeping one name across the API | [`test_api_vocabulary.py`](https://github.com/Solganis/assertpy2/blob/main/tests/test_api_vocabulary.py) |
+| The three-method `Matcher` protocol your custom matchers implement | [`test_matcher_parity.py`](https://github.com/Solganis/assertpy2/blob/main/tests/test_matcher_parity.py) |
+| The Allure attachment schema | versioned in its own `format` field, so a consumer branches on a number rather than guessing |
+| Your assertions keeping their verdict | 4100 tests at 100 % branch coverage, plus mutation testing |
+
+The records in the first row are `AssertionOutcome`, `MatchResult`, `DiffEntry`, `DiffResult`, `Step`,
+`PollSample` and `PollTrace`. Fields are added, never renamed or removed, inside a major version.
+
+Documentation is held to the same bar: every example in these guides is executed and type-checked in
+CI, so a snippet you copy is one that ran.
+
+## Reading a failure from code
+
+Failures carry [structured data](../guides/errors.md#structured-errors) for exactly this. Reach for it
+rather than for the rendered text:
+
+| You want | Use |
+|---|---|
+| the values that were compared | `failure.actual`, `failure.expected` |
+| where they differ | `failure.diff.entries`, each with a `path` |
+| a location you can walk in code | [`entry.steps`](../guides/errors.md#paths-a-program-can-follow) |
+| every failure a soft block collected | `failure.failures` |
+| a verdict without an exception | [`check()`](../guides/errors.md#asking-instead-of-asserting) |
+
+Those are covered by the table above. **Message wording is not**: it improves in minor releases, so a
+`pytest.raises(match=...)` written against our phrasing, or a snapshot of a failing run, is the one
+thing that predictably needs updating. Match on the exception type and read the fields.
+
+## Upgrading
+
+Semantic versioning, read strictly: a new assertion is a minor, a patch carries fixes only.
+
+Two kinds of change ship in a minor, and the release notes list each one under **Behaviour changes**:
+
+- **an input that was silently wrong starts raising**, such as an empty prefix that no value could fail
+- **a wrong verdict is corrected**, so an assertion that passed and should not have begins to fail
+
+Both are the reason to read that section before upgrading. Nothing else in a minor is designed to
+change what your suite reports.
+
+## Not part of the API
+
+Anything whose name starts with `_`, and the module an assertion happens to live in. The reference
+lists `matches_structure()` because you can call it from `assert_that()`, and its anchor reads
+`assertpy2._satisfies.SatisfiesMixin.matches_structure` because that is where the code sits.
+Importing from there is not supported.
+
+Python 3.10 and up. Dropping a version that upstream still supports would be a major.
+
+Code written against [assertpy](../getting-started/migration.md) keeps working, and that holds for
+refactors: an internal change that would break a documented assertpy call is not internal.

{assertpy2-2.20.0 → assertpy2-2.20.1}/docs/concepts/type-safety.md

@@ -94,6 +94,20 @@ This is the deliberate cost of keeping the original assertpy API working unchang
 mutually satisfiable: for a checker to accept `has_first_name` on a dict, `_DictAssertion` would need a
 `__getattr__`, and that same declaration would stop it reporting `contins_key` as a typo.
 
+[Custom assertions](../extending/custom-assertions.md) registered with `add_extension()` sit on the same
+line, for the same reason. The name is attached at runtime, so it reaches a checker through that one
+`__getattr__` and nowhere else:
+
+<!-- docs-guard: untyped -->
+```python
+assert_that(order).is_paid()  # clean: a user class falls to the generic builder
+assert_that(5).is_5()         # type error: _NumericAssertion has no attribute is_5
+```
+
+Both lines run. If your extension targets a value with an overload of its own, the call needs
+`# type: ignore[attr-defined]` at each site, and the return type a checker infers for it is `Any`
+rather than whatever the extension actually returns.
+
 ## Typed narrowing with .value
 
 Assertions don't just check a value - they can hand it back, typed. The `value` property ends a chain
@@ -274,9 +288,27 @@ A few refinements keep it precise:
 
 ## Set up your type checker
 
-The narrowing works in any checker mode, but strict mode surfaces the most - a wrong method called on a
-narrowed value, a missing return annotation, a `.value` read where the type was never narrowed. Turn it
-on for your checker:
+Under mypy, one setting decides whether any of this reaches your tests. mypy does not look inside a
+function with no annotations at all, and a test written as `def test_orders():` is exactly that, so the
+narrowing is silently skipped for the file where you wanted it most. The same three mistakes below are
+reported six times by Pyright and `ty` out of the box, three times by mypy at its defaults, and six by
+mypy once it is told to read those bodies:
+
+<!-- docs-guard: skip -->
+
+```python
+def test_unannotated():        # mypy default: not checked at all
+    assert_that("abc").is_greater_than(3)
+
+def test_annotated() -> None:  # mypy default: checked
+    assert_that("abc").is_greater_than(3)
+```
+
+Either annotate every test with `-> None`, or set `check_untyped_defs = true`, which `strict = true`
+already includes. Pyright and `ty` need neither.
+
+Strict mode then surfaces the most - a wrong method called on a narrowed value, a missing return
+annotation, a `.value` read where the type was never narrowed. Turn it on for your checker:
 
 ```toml
 # pyproject.toml - mypy

{assertpy2-2.20.0 → assertpy2-2.20.1}/docs/extending/custom-assertions.md

@@ -4,6 +4,8 @@ Add your own assertions to `assertpy2` with `add_extension()`.
 
 ## A custom assertion
 
+<!-- docs-guard: untyped -->
+
 ```python
 from assertpy2 import add_extension, assert_that
 
@@ -18,6 +20,11 @@ assert_that(5).is_5()
 assert_that(6).is_5()  # fails!
 ```
 
+Both lines run, but a type checker rejects the first one: `5` resolves to the numeric protocol, which
+declares no `is_5`. An extension is only visible to a checker on values that fall to the generic
+builder, which means your own classes rather than `str`, `int`, `dict` and the rest. The reason and the
+ways round it are in [Where the typed surface ends](../concepts/type-safety.md#where-the-typed-surface-ends).
+
 `remove_extension()` takes the same function and unregisters it, so a temporary assertion does not
 leak into other tests:
 
@@ -48,6 +55,8 @@ def my_extensions():
 
 Then request the fixture in any test that needs the extensions:
 
+<!-- docs-guard: untyped -->
+
 ```python
 from assertpy2 import assert_that
 

{assertpy2-2.20.0 → assertpy2-2.20.1}/docs/getting-started/migration.md

@@ -106,4 +106,5 @@ New capabilities the original never had, ready whenever you want them:
 - [Async and blocking polling](../guides/testing.md#async-assertions) for eventual consistency.
 - [JSON Path / Schema](../guides/data.md), [regex group extraction](../guides/data.md#regex-group-extraction), and [bytes assertions](../guides/assertions.md#bytes--bytearray).
 
-See the [comparison](comparison.md) for the full feature delta.
+See the [comparison](comparison.md) for the full feature delta, and [stability](../concepts/stability.md)
+for what is covered by a compatibility promise and what is not.