assertpy 2.35.0__py3-none-any.whl

assertpy/_engine/_typing.py

@@ -0,0 +1,1226 @@
+"""The typed surface itself: one protocol per kind of value, and the only one of the six written by hand.
+
+`assert_that()` picks between them with an overload ladder in `assertpy/assertpy.py`, and a checker sees
+the protocol rather than the builder.  That is what makes `assert_that({}).is_positive()` an error before
+it is a `TypeError`.
+
+Four of the other five typed modules are generated from this one, so a declaration added here reaches
+the polling chain, both verdict proxies and the negation twins only after the generators run.  The
+fifth, the capability facade, reads the runtime mixins instead: it stands in for the builder rather
+than for a view.
+
+Declare a method on the protocols it applies to and on no others.  One on `_CoreAssertion` is offered to
+every value, which is the distinction this layer exists to make.
+
+Everything is under `TYPE_CHECKING`, so nothing here costs an import and nothing here enforces itself.
+`tests/test_protocol_parity.py` and `tests/test_typing_conformance.py` hold a declaration to the runtime.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    import datetime
+    import re
+    from collections.abc import Awaitable, Callable, Hashable, Iterable, Mapping, Sized
+    from pathlib import Path
+    from typing import Any, ClassVar, Protocol, SupportsFloat, SupportsIndex, TypeVar, overload
+
+    from typing_extensions import TypeIs
+
+    from .._engine._introspection import MappingLike
+    from .._matcher_impls import ClassInfo, ExceptionInfo, RetriedInfo, WarningInfo
+    from ..assertpy import AssertionBuilder
+    from ..matchers import Matcher
+    from ._check_typing import (
+        _CheckArrayAssertion,
+        _CheckBoolAssertion,
+        _CheckBytesAssertion,
+        _CheckCallableAssertion,
+        _CheckCompletedAssertion,
+        _CheckComplexAssertion,
+        _CheckCoreAssertion,
+        _CheckDateAssertion,
+        _CheckDateTimeAssertion,
+        _CheckDictAssertion,
+        _CheckExpectedCompletionAssertion,
+        _CheckExpectedRaiseAssertion,
+        _CheckExpectedWarningAssertion,
+        _CheckFrameAssertion,
+        _CheckInvokedAssertion,
+        _CheckIterableAssertion,
+        _CheckListAssertion,
+        _CheckNumericAssertion,
+        _CheckObjectAssertion,
+        _CheckPathAssertion,
+        _CheckStringAssertion,
+        _CheckWarnedAssertion,
+    )
+    from ._compat import Self
+    from ._negated_typing import (
+        _NegatedArrayAssertion,
+        _NegatedBoolAssertion,
+        _NegatedBytesAssertion,
+        _NegatedCallableAssertion,
+        _NegatedCompletedAssertion,
+        _NegatedComplexAssertion,
+        _NegatedCoreAssertion,
+        _NegatedDateAssertion,
+        _NegatedDateTimeAssertion,
+        _NegatedDictAssertion,
+        _NegatedExpectedCompletionAssertion,
+        _NegatedExpectedRaiseAssertion,
+        _NegatedExpectedWarningAssertion,
+        _NegatedFrameAssertion,
+        _NegatedInvokedAssertion,
+        _NegatedIterableAssertion,
+        _NegatedListAssertion,
+        _NegatedNumericAssertion,
+        _NegatedObjectAssertion,
+        _NegatedPathAssertion,
+        _NegatedStringAssertion,
+        _NegatedTextAssertion,
+        _NegatedWarnedAssertion,
+    )
+    from ._poll_typing import _AsyncPoll, _SyncPoll
+
+    # ``ignore``/``include`` accept a single key, a nested-path tuple, or a list/set/frozenset of them.
+    _KeySpecs = Hashable | list[Hashable] | set[Hashable] | frozenset[Hashable]
+
+    _E = TypeVar("_E")  # tracked element type of a collection assertion
+    _R = TypeVar("_R")  # result element type after a mapping pivot
+    _N = TypeVar("_N", int, float)  # tracked numeric type, so value keeps int or float
+    _K = TypeVar("_K")  # tracked dict key type
+    _V = TypeVar("_V")  # tracked dict value type
+    _B_co = TypeVar("_B_co", bytes, bytearray, covariant=True)  # tracked bytes type (output-only -> covariant)
+    _U = TypeVar("_U")
+    _U2 = TypeVar("_U2")
+    _U3 = TypeVar("_U3")  # the type a TypeIs predicate refines the tracked value to
+    _Other = TypeVar("_Other")  # an element of the sequence a pairwise quantifier walks alongside
+    _T_co = TypeVar("_T_co", covariant=True)  # the subject of a value no overload recognises
+    _P_co = TypeVar("_P_co", covariant=True)  # what a polled probe hands back, covariant so a subclass reaches its rung
+    _Exc = TypeVar("_Exc", bound=BaseException)  # the exception a caught call holds, invariant as the builder is
+    _Landed = TypeVar("_Landed", bound=BaseException)  # the exception `raises()` names, or a pivot lands on
+
+    # a capability, not a list: the list said `float | Decimal | Fraction` and refused `numpy.int64`
+    _Number = SupportsFloat
+
+    # a predicate's verdict is `object`, not `bool`, which refused a `numpy.bool_`
+
+    class _MembershipAssertion(Protocol):
+        """ "Is every one of my elements in there", asked the same way by three types.
+
+        `*supersets` is `object`, and that is measured rather than lazy.  The runtime compares by `==`,
+        so a superset of a wider element type works: `list[Dog]` against `list[Animal]`, `[1]` against
+        `1.0`, a `list[object]` holding the right values.  Both narrowings tried, `Iterable[_E]` and
+        `Iterable[_E] | _E`, refused those, and the first also refused the documented
+        `is_subset_of(1, 2, 3)` that our own suite calls.
+
+        The mapping view declares its own, because there the runtime refuses a shape by name rather
+        than by comparison.  `contains` stays out for the older reason: a string means `str | Matcher`
+        by it, and lifting the untyped form once widened the string by accident.
+        """
+
+        def is_subset_of(self, *supersets: object, allow_empty: bool = ...) -> Self: ...
+
+    class _SizedAssertion(Protocol):
+        """What every value with a length can be asked, declared once instead of in four protocols.
+
+        Not on `_CoreAssertion`, because a number has no length and offering `is_empty()` on one would be
+        the false promise this whole file exists to avoid.  Not generated either: a protocol that other
+        protocols inherit is the language's own way of saying "these share a capability", and a checker
+        understands it without anything being generated, recorded or kept in step.
+        """
+
+        def has_same_size_as(self, other: Sized) -> Self: ...
+        def has_size_greater_than(self, size: SupportsIndex) -> Self: ...
+        def has_size_less_than(self, size: SupportsIndex) -> Self: ...
+        def has_size_between(self, low: SupportsIndex, high: SupportsIndex) -> Self: ...
+        def is_empty(self) -> Self: ...
+        def is_not_empty(self) -> Self: ...
+
+    class _FilesystemAssertion(Protocol):
+        """What a value naming a place on disk can be asked.
+
+        Carried by both the string and the path protocols, because a path is written as a `str` at least
+        as often as it is written as a `Path`, and refusing one of the two spellings would be a rule
+        that exists only in the type checker.
+        """
+
+        def exists(self) -> Self: ...
+        def does_not_exist(self) -> Self: ...
+        def is_file(self) -> Self: ...
+        def is_directory(self) -> Self: ...
+        def is_named(self, filename: str) -> Self: ...
+        def is_child_of(self, parent: object) -> Self: ...
+        def is_readable(self) -> Self: ...
+        def is_writable(self) -> Self: ...
+        def is_executable(self) -> Self: ...
+
+    class _RealNumberAssertion(Protocol):
+        """What a real number can be asked, whether it is spelled `int`, `float` or `bool`.
+
+        `bool` is here because it is an `int` in Python, and an assertion that works on one works on the
+        other; leaving it out would be a distinction the runtime does not make.  Closeness is the
+        exception, declared on the numeric view alone: a distance measured from a flag is a mistake the
+        runtime refuses, as `tolerance=` does.
+        """
+
+        def is_positive(self) -> Self: ...
+        def is_negative(self) -> Self: ...
+        def is_nan(self) -> Self: ...
+        def is_not_nan(self) -> Self: ...
+        def is_inf(self) -> Self: ...
+        def is_not_inf(self) -> Self: ...
+        def is_not_between(self, low: _Number, high: _Number) -> Self: ...
+        def is_between(self, low: _Number, high: _Number) -> Self: ...
+        def is_greater_than(self, other: _Number) -> Self: ...
+        def is_greater_than_or_equal_to(self, other: _Number) -> Self: ...
+        def is_less_than(self, other: _Number) -> Self: ...
+        def is_less_than_or_equal_to(self, other: _Number) -> Self: ...
+
+    class _WalkAssertion(Protocol):
+        """The quantifiers and the extraction pivot, which anything walkable answers.
+
+        Apart from the JSON family below because the two domains are not the same: a frame walks
+        and is not a document, and offering it `at_json_path` promises a refusal.  `_StructureAssertion`
+        keeps both together for the mapping and sequence views, which are inside both.
+        """
+
+        def extracting(
+            self,
+            # a selector stays `object`: every narrowing tried refused working code, `Hashable | slice` included
+            name: object,
+            /,
+            *names: object,
+            # named rather than `**kwargs`, so `filtr=` is caught; `Mapping` because `dict` is invariant
+            filter: str | Mapping[str, object] | Callable[[Any], object] = ...,  # noqa: A002  # public keyword
+            # `sort` is narrower by the runtime: one index is refused, the same index inside a list is honoured
+            sort: str | Iterable[object] | Callable[[Any], object] = ...,
+        ) -> _ListAssertion[Any]: ...
+        def each(self, matcher: Matcher[Any] | Callable[[Any], object], *, allow_empty: bool = ...) -> Self: ...
+        def all_satisfy(self, matcher: Matcher[Any] | Callable[[Any], object], *, allow_empty: bool = ...) -> Self: ...
+
+    class _JsonAssertion(Protocol):
+        """The document family, for a value the JSON assertions accept: a `dict` or a `list`."""
+
+        def at_json_path(self, path: str) -> _CoreAssertion:
+            """Navigate into the document and continue on whatever is there.
+
+            A path lands on an object, an array, a string, a number, a boolean or a null, and which one
+            it is lives in the document rather than in any type.  So what comes back offers the
+            assertions every value can answer, and nothing beyond them: naming a shape here is what
+            offered `contains_key` on an `int` and made a type check pass on a call that raises.
+
+            Reaching further is a narrowing the caller states: a matcher, or a `TypeIs` predicate that
+            carries the type into the rest of the chain.  What runs is the predicate, and what is read
+            is its boolean answer, so the declared narrowing is taken on trust from whoever wrote it.
+            """
+            ...
+
+        def has_json_path(self, path: str) -> Self: ...
+        def does_not_have_json_path(self, path: str) -> Self: ...
+        def matches_json_schema(self, schema: dict[str, Any]) -> Self: ...
+        def matches_json_schema_from_file(self, path: str | Path) -> Self: ...
+        def conforms_to_openapi(
+            self,
+            spec: dict[str, Any],
+            path: str,
+            method: str,
+            *,
+            status: str | int | None = ...,
+            content_type: str = ...,
+            strict_nullable: bool = ...,
+        ) -> Self: ...
+
+    class _StructureAssertion(_WalkAssertion, _JsonAssertion, Protocol):
+        """Quantifiers, the JSON family and the two pivots, which a mapping and a sequence share.
+
+        That sharing is what a JSON document is made of, and the reason these never belonged to
+        either one alone.  Kept as one name so the views that are inside both domains compose it
+        rather than listing halves.
+        """
+
+    class _RepeatableAssertion(Protocol[_E]):
+        """What a value with repeatable elements can be asked about its repeats and their order.
+
+        Generic over the element, and that is not decoration: `contains_in_order` names the element type,
+        so a protocol without the parameter leaves `_E` free and lets a list of integers be asked about
+        strings.  Each carrier binds it to what its own elements are.
+        """
+
+        def contains_duplicates(self) -> Self: ...
+        def does_not_contain_duplicates(self) -> Self: ...
+        def contains_only_once(self, *items: object) -> Self: ...
+        def contains_in_order(self, *items: _E | Matcher[_E]) -> Self: ...
+
+    class _ZeroAssertion(Protocol):
+        """Zero and its negation, which every numeric spelling shares, complex included."""
+
+        def is_zero(self) -> Self: ...
+        def is_not_zero(self) -> Self: ...
+
+    class _CoreAssertion(Protocol):
+        """Base protocol with assertions available for all types."""
+
+        @property
+        def not_(self) -> _NegatedCoreAssertion: ...
+
+        def described_as(self, description: str) -> Self: ...
+        def is_equal_to(
+            self,
+            other: object,
+            *,
+            ignore: _KeySpecs | None = ...,
+            include: _KeySpecs | None = ...,
+            tolerance: float | None = ...,
+            rel: float | None = ...,
+            comparators: dict[Any, Callable[[Any, Any], Any]] | None = ...,
+            ignore_null: bool = ...,
+            strict_types: bool = ...,
+        ) -> Self: ...
+        def is_not_equal_to(self, other: object) -> Self: ...
+        def is_same_as(self, other: object) -> Self: ...
+        def is_not_same_as(self, other: object) -> Self: ...
+        def is_true(self) -> Self: ...
+        def is_false(self) -> Self: ...
+        def is_none(self) -> Self: ...
+        def is_not_none(self) -> Self: ...
+        def is_type_of(self, some_type: type) -> Self: ...
+        def is_instance_of(self, some_class: ClassInfo) -> Self: ...
+        def is_instance_of_any(self, *some_classes: ClassInfo) -> Self: ...
+        def is_subclass_of(self, some_class: ClassInfo) -> Self: ...
+        def is_length(self, length: SupportsIndex | Matcher[int]) -> Self: ...
+        def is_length_between(self, low: SupportsIndex, high: SupportsIndex) -> Self: ...
+        def is_callable(self) -> Self: ...
+        def is_not_callable(self) -> Self: ...
+        def is_iterable(self) -> Self: ...
+        def is_not_iterable(self) -> Self: ...
+        # a protocol narrowing `satisfies` restates the ladder; the predicate stays `Any` in this widest one
+        @overload
+        def satisfies(self, matcher: Callable[[Any], TypeIs[str]]) -> _StringAssertion: ...
+        @overload
+        def satisfies(self, matcher: Callable[[Any], TypeIs[bool]]) -> _BoolAssertion: ...
+        @overload
+        def satisfies(self, matcher: Callable[[Any], TypeIs[int]]) -> _NumericAssertion[int]: ...
+        @overload
+        def satisfies(self, matcher: Callable[[Any], TypeIs[float]]) -> _NumericAssertion[float]: ...
+        @overload
+        def satisfies(self, matcher: Callable[[Any], TypeIs[complex]]) -> _ComplexAssertion: ...
+        @overload
+        def satisfies(self, matcher: Callable[[Any], TypeIs[dict[_K, _V]]]) -> _DictAssertion[_K, _V]: ...
+        @overload
+        def satisfies(self, matcher: Callable[[Any], TypeIs[list[_E] | tuple[_E, ...]]]) -> _IterableAssertion[_E]: ...
+        @overload
+        def satisfies(self, matcher: Callable[[Any], TypeIs[set[_E] | frozenset[_E]]]) -> _IterableAssertion[_E]: ...
+        @overload
+        def satisfies(self, matcher: Callable[[Any], TypeIs[datetime.datetime]]) -> _DateTimeAssertion: ...
+        @overload
+        def satisfies(self, matcher: Callable[[Any], TypeIs[datetime.date]]) -> _DateAssertion: ...
+        @overload
+        def satisfies(self, matcher: Callable[[Any], TypeIs[Path]]) -> _PathAssertion: ...
+        @overload
+        def satisfies(self, matcher: Callable[[Any], TypeIs[bytes]]) -> _BytesAssertion[bytes]: ...
+        @overload
+        def satisfies(self, matcher: Callable[[Any], TypeIs[bytearray]]) -> _BytesAssertion[bytearray]: ...
+        @overload
+        def satisfies(self, matcher: Callable[[Any], TypeIs[Callable[..., object]]]) -> _CallableAssertion[Any]: ...
+        @overload
+        def satisfies(self, matcher: Callable[[Any], TypeIs[_CapableT]]) -> AssertionBuilder[_CapableT]: ...
+        @overload
+        def satisfies(self, matcher: Callable[[Any], TypeIs[_U]]) -> _ObjectAssertion[_U]: ...
+        @overload
+        def satisfies(self, matcher: Matcher[Any] | Callable[[Any], object]) -> Self: ...
+        def all_fields_satisfy(
+            self, matcher: Matcher[Any] | Callable[[Any], object], *, allow_empty: bool = ...
+        ) -> Self: ...
+        def has_no_none_fields(self, *, allow_empty: bool = ...) -> Self: ...
+        def is_in(self, *items: object) -> Self: ...
+        def is_not_in(self, *items: object) -> Self: ...
+        def snapshot(
+            self,
+            id: str | None = ...,  # noqa: A002  # mirrors public snapshot() parameter
+            path: str = ...,
+            *,
+            ignore: _KeySpecs | None = ...,
+            include: _KeySpecs | None = ...,
+            tolerance: float | None = ...,
+            rel: float | None = ...,
+            comparators: dict[Any, Callable[[Any, Any], Any]] | None = ...,
+            placeholders: Mapping[Any, Matcher[Any] | Callable[[Any], object]] | None = ...,
+        ) -> Self: ...
+        def matches_contract_snapshot(self, id: str | None = ..., path: str = ...) -> Self: ...  # noqa: A002  # mirrors public parameter
+        def matches_inline(
+            self,
+            expected: object = ...,
+            *,
+            ignore: _KeySpecs | None = ...,
+            include: _KeySpecs | None = ...,
+            tolerance: float | None = ...,
+            rel: float | None = ...,
+            comparators: dict[Any, Callable[[Any, Any], Any]] | None = ...,
+            placeholders: Mapping[Any, Matcher[Any] | Callable[[Any], object]] | None = ...,
+        ) -> Self: ...
+        # a builder twin was tried and dropped: text and numeric ordering collide in one class.  A pivot
+        # hands back `AssertionBuilder[_E]`, as does what the capability umbrella claims, so both stay untyped
+        def check(self) -> _CheckCoreAssertion: ...
+        @property
+        def value(self) -> object: ...
+
+    class _Holding(Protocol[_T_co]):
+        """A view as the value it holds and nothing more, which is what the rungs of `is_not_none` are keyed on.
+
+        Keyed on `_ObjectAssertion` itself, ty answered `Unknown` for nine of the sixteen kinds a rung names: a
+        `bool`, an `int`, a `float`, the four sequences and sets, a `datetime` and a callable.  Keyed on this it
+        resolves each, and the other three checkers answer as they did.  A rung reads `value` alone, so a
+        protocol of one's own that inherits the view and narrows `value` lands where that value does.
+        """
+
+        @property
+        def value(self) -> _T_co: ...
+
+    class _ObjectAssertion(_CoreAssertion, Protocol[_T_co]):
+        """What a value no overload recognises can be asked, which is the core surface and ordering.
+
+        The fallback used to hand back the builder itself, carrying all 152 assertion names, so
+        `assert_that(Person()).is_positive()` type-checked and then raised.  This is the other end: a
+        value with no capability any overload can see gets what applies to every value.
+
+        Ordering is here and not in `_CoreAssertion`, and the difference matters.  Every other view
+        spells its own operand (`str` against `str`, a date against a date), which is what makes the
+        comparison worth checking, and a frame is refused outright.  Only an unrecognised value has no
+        operand to name, so it takes `object` and judges anything.  That is a recorded boundary rather
+        than an oversight: `tests/typing_negative_baseline.py` holds why every narrower spelling trades
+        a correct call for an incorrect one, and a `Decimal` compared against an `int` is the case it
+        would break.
+
+        The three refinements are declared here rather than inherited because they have to return this
+        view: they are the reason `.value` can be read without a `cast()`, and a refinement that came
+        back as the builder would put all 152 names back at the first `is_not_none()`.
+        """
+
+        @property
+        def not_(self) -> _NegatedObjectAssertion[_T_co]: ...
+
+        @property
+        def value(self) -> _T_co: ...
+        def matches_structure(self, spec: dict[Any, Any]) -> Self: ...
+        def is_greater_than(self, other: Any) -> Self: ...
+        def is_greater_than_or_equal_to(self, other: Any) -> Self: ...
+        def is_less_than(self, other: Any) -> Self: ...
+        def is_less_than_or_equal_to(self, other: Any) -> Self: ...
+        def is_between(self, low: Any, high: Any) -> Self: ...
+        def is_not_between(self, low: Any, high: Any) -> Self: ...
+
+        def check(self) -> _CheckObjectAssertion[_T_co]: ...
+
+        # attrs reaches mypy only, so the object view carries `matches_structure` rather than a shape
+
+        # the four numeric assertions an unrecognised value can answer whatever it registered as, which
+        # is how `Decimal` and `Fraction` arrive here: neither is an `int` or a `float`, so no overload
+        # names them.  Keyed on the conversion `math.isnan` reads, which does not imply the registration
+        # the runtime gate reads and cannot: a value that converts and never registered type-checks here
+        # and raises, the same boundary the relational six above already stand on.
+        #
+        # The other four, `is_nan` and friends, are NOT here and the split is measured: they sit behind
+        # `numbers.Real` rather than `numbers.Number`, so `Fraction` answers them and `Decimal` raises.
+        # No structural key separates the two, so declaring them would trade a false refusal on one
+        # stdlib type for a false acceptance on the other, and the false acceptance is what the fallback
+        # exists to remove.  The operands drop the datetime half the numeric view carries: a `datetime`
+        # has an overload above this one, so a subject here is never one and the pairing cannot arise.  The
+        # operands take the same union as the receiver: an `__index__`-only registered number is a bound
+        # the runtime accepts, measured
+        def is_zero(self: _ObjectAssertion[SupportsFloat | SupportsIndex]) -> _ObjectAssertion[_T_co]: ...
+        def is_not_zero(self: _ObjectAssertion[SupportsFloat | SupportsIndex]) -> _ObjectAssertion[_T_co]: ...
+        def is_close_to(
+            self: _ObjectAssertion[SupportsFloat | SupportsIndex],
+            other: SupportsFloat | SupportsIndex,
+            tolerance: SupportsFloat | SupportsIndex | None = ...,
+            *,
+            rel: SupportsFloat | SupportsIndex | None = ...,
+        ) -> _ObjectAssertion[_T_co]: ...
+        def is_not_close_to(
+            self: _ObjectAssertion[SupportsFloat | SupportsIndex],
+            other: SupportsFloat | SupportsIndex,
+            tolerance: SupportsFloat | SupportsIndex | None = ...,
+            *,
+            rel: SupportsFloat | SupportsIndex | None = ...,
+        ) -> _ObjectAssertion[_T_co]: ...
+
+        # no rung for a shape: both spellings tried put one checker in the wrong
+        @overload
+        def is_not_none(self: _Holding[str | None]) -> _StringAssertion: ...
+        @overload
+        def is_not_none(self: _Holding[bool | None]) -> _BoolAssertion: ...
+        @overload
+        def is_not_none(self: _Holding[int | None]) -> _NumericAssertion[int]: ...
+        @overload
+        def is_not_none(self: _Holding[float | None]) -> _NumericAssertion[float]: ...
+        @overload
+        def is_not_none(self: _Holding[complex | None]) -> _ComplexAssertion: ...
+        @overload
+        def is_not_none(self: _Holding[dict[_K, _V] | None]) -> _DictAssertion[_K, _V]: ...
+        @overload
+        def is_not_none(self: _Holding[list[_E] | tuple[_E, ...] | None]) -> _IterableAssertion[_E]: ...
+        @overload
+        def is_not_none(self: _Holding[set[_E] | frozenset[_E] | None]) -> _IterableAssertion[_E]: ...
+        @overload
+        def is_not_none(self: _Holding[datetime.datetime | None]) -> _DateTimeAssertion: ...
+        @overload
+        def is_not_none(self: _Holding[datetime.date | None]) -> _DateAssertion: ...
+        @overload
+        def is_not_none(self: _Holding[Path | None]) -> _PathAssertion: ...
+        @overload
+        def is_not_none(self: _Holding[bytes | None]) -> _BytesAssertion[bytes]: ...
+        @overload
+        def is_not_none(self: _Holding[bytearray | None]) -> _BytesAssertion[bytearray]: ...
+        @overload
+        def is_not_none(self: _Holding[Callable[..., object] | None]) -> _CallableAssertion[Any]: ...
+        @overload
+        def is_not_none(self: _Holding[_U | None]) -> _ObjectAssertion[_U]: ...
+        @overload
+        def is_not_none(self) -> Self: ...
+        @overload
+        def is_instance_of(self, some_class: type[str]) -> _StringAssertion: ...
+        @overload
+        def is_instance_of(self, some_class: type[bool]) -> _BoolAssertion: ...
+        @overload
+        def is_instance_of(self, some_class: type[int]) -> _NumericAssertion[int]: ...
+        @overload
+        def is_instance_of(self, some_class: type[float]) -> _NumericAssertion[float]: ...
+        @overload
+        def is_instance_of(self, some_class: type[complex]) -> _ComplexAssertion: ...
+        @overload
+        def is_instance_of(self, some_class: type[dict[_K, _V]]) -> _DictAssertion[_K, _V]: ...
+        @overload
+        def is_instance_of(self, some_class: type[list[_E] | tuple[_E, ...]]) -> _IterableAssertion[_E]: ...
+        @overload
+        def is_instance_of(self, some_class: type[set[_E] | frozenset[_E]]) -> _IterableAssertion[_E]: ...
+        @overload
+        def is_instance_of(self, some_class: type[datetime.datetime]) -> _DateTimeAssertion: ...
+        @overload
+        def is_instance_of(self, some_class: type[datetime.date]) -> _DateAssertion: ...
+        @overload
+        def is_instance_of(self, some_class: type[Path]) -> _PathAssertion: ...
+        @overload
+        def is_instance_of(self, some_class: type[bytes]) -> _BytesAssertion[bytes]: ...
+        @overload
+        def is_instance_of(self, some_class: type[bytearray]) -> _BytesAssertion[bytearray]: ...
+        @overload
+        def is_instance_of(self, some_class: tuple[type[_U], type[_U2]]) -> _ObjectAssertion[_U | _U2]: ...
+        @overload
+        def is_instance_of(
+            self, some_class: tuple[type[_U], type[_U2], type[_U3]]
+        ) -> _ObjectAssertion[_U | _U2 | _U3]: ...
+        @overload
+        def is_instance_of(self, some_class: type[_U]) -> _ObjectAssertion[_U]: ...
+        @overload
+        def is_instance_of(self, some_class: ClassInfo) -> Self: ...
+
+        @overload
+        def is_instance_of_any(self, first: type[_U], second: type[_U2], /) -> _ObjectAssertion[_U | _U2]: ...
+        @overload
+        def is_instance_of_any(
+            self, first: type[_U], second: type[_U2], third: type[_U3], /
+        ) -> _ObjectAssertion[_U | _U2 | _U3]: ...
+        @overload
+        def is_instance_of_any(self, *some_classes: ClassInfo) -> Self: ...
+
+    class _TextAssertion(_MembershipAssertion, _RepeatableAssertion[str], _SizedAssertion, _CoreAssertion, Protocol):
+        """What a piece of text can be asked, whether a caller passed it in or the library caught it.
+
+        Split out from the string view so the invoked view can share it without sharing the rest.  The
+        message a raised exception hands back is a `str`, so every assertion here applies to it, and
+        the assertions that read a path do not: that inheritance offered `exists()` on the text of an
+        exception, which the runtime then looks for on disk.
+        """
+
+        @property
+        def not_(self) -> _NegatedTextAssertion: ...
+
+        @overload
+        def satisfies(self, matcher: Callable[[str], TypeIs[str]]) -> _StringAssertion: ...
+        @overload
+        def satisfies(self, matcher: Callable[[str], TypeIs[bool]]) -> _BoolAssertion: ...
+        @overload
+        def satisfies(self, matcher: Callable[[str], TypeIs[int]]) -> _NumericAssertion[int]: ...
+        @overload
+        def satisfies(self, matcher: Callable[[str], TypeIs[float]]) -> _NumericAssertion[float]: ...
+        @overload
+        def satisfies(self, matcher: Callable[[str], TypeIs[complex]]) -> _ComplexAssertion: ...
+        @overload
+        def satisfies(self, matcher: Callable[[str], TypeIs[dict[_K, _V]]]) -> _DictAssertion[_K, _V]: ...
+        @overload
+        def satisfies(self, matcher: Callable[[str], TypeIs[list[_E] | tuple[_E, ...]]]) -> _IterableAssertion[_E]: ...
+        @overload
+        def satisfies(self, matcher: Callable[[str], TypeIs[set[_E] | frozenset[_E]]]) -> _IterableAssertion[_E]: ...
+        @overload
+        def satisfies(self, matcher: Callable[[str], TypeIs[datetime.datetime]]) -> _DateTimeAssertion: ...
+        @overload
+        def satisfies(self, matcher: Callable[[str], TypeIs[datetime.date]]) -> _DateAssertion: ...
+        @overload
+        def satisfies(self, matcher: Callable[[str], TypeIs[Path]]) -> _PathAssertion: ...
+        @overload
+        def satisfies(self, matcher: Callable[[str], TypeIs[bytes]]) -> _BytesAssertion[bytes]: ...
+        @overload
+        def satisfies(self, matcher: Callable[[str], TypeIs[bytearray]]) -> _BytesAssertion[bytearray]: ...
+        @overload
+        def satisfies(self, matcher: Callable[[str], TypeIs[Callable[..., object]]]) -> _CallableAssertion[Any]: ...
+        @overload
+        def satisfies(self, matcher: Callable[[str], TypeIs[_CapableT]]) -> AssertionBuilder[_CapableT]: ...
+        @overload
+        def satisfies(self, matcher: Callable[[str], TypeIs[_U]]) -> _ObjectAssertion[_U]: ...
+        @overload
+        def satisfies(self, matcher: Matcher[str] | Callable[[str], object]) -> Self: ...
+
+        """Assertions available for ``str`` values."""
+
+        def contains(self, *items: str | Matcher[str]) -> Self: ...
+
+        @property
+        def value(self) -> str: ...
+        def is_equal_to_ignoring_case(self, other: str) -> Self: ...
+        def is_equal_to_ignoring_whitespace(self, other: str) -> Self: ...
+        def contains_ignoring_case(self, *items: str) -> Self: ...
+        def starts_with(self, prefix: str) -> Self: ...
+        def starts_with_ignoring_case(self, prefix: str) -> Self: ...
+        def ends_with(self, suffix: str) -> Self: ...
+        def ends_with_ignoring_case(self, suffix: str) -> Self: ...
+        def matches(self, pattern: str | re.Pattern[str]) -> Self: ...
+        def does_not_match(self, pattern: str | re.Pattern[str]) -> Self: ...
+        def is_alpha(self) -> Self: ...
+        def is_digit(self) -> Self: ...
+        def is_lower(self) -> Self: ...
+        def is_upper(self) -> Self: ...
+        def is_alphanumeric(self) -> Self: ...
+        def is_whitespace(self) -> Self: ...
+        def contains_any_of(self, *items: str) -> Self: ...
+        def contains_none_of(self, *items: str) -> Self: ...
+        def is_unicode(self) -> Self: ...
+        def is_greater_than(self, other: str) -> Self: ...
+        def is_greater_than_or_equal_to(self, other: str) -> Self: ...
+        def is_less_than(self, other: str) -> Self: ...
+        def is_less_than_or_equal_to(self, other: str) -> Self: ...
+        def does_not_contain(self, *items: str | Matcher[str]) -> Self: ...
+        def contains_only(self, *items: str | Matcher[str]) -> Self: ...
+        def contains_sequence(self, *items: str | Matcher[str]) -> Self: ...
+        def contains_exactly(self, *items: str | Matcher[str]) -> Self: ...
+        def contains_exactly_in_any_order(self, *items: str | Matcher[str]) -> Self: ...
+        def is_sorted(
+            self, key: Callable[[str], object] = ..., reverse: bool = ..., *, allow_empty: bool = ...
+        ) -> Self: ...
+        # the runtime answers every quantifier for a `str`, so `assert_that("ab").each(...)` was a type error that ran
+        def each(self, matcher: Matcher[str] | Callable[[str], object], *, allow_empty: bool = ...) -> Self: ...
+        def all_satisfy(self, matcher: Matcher[str] | Callable[[str], object], *, allow_empty: bool = ...) -> Self: ...
+        def any_satisfy(self, matcher: Matcher[str] | Callable[[str], object]) -> Self: ...
+        def none_satisfy(self, matcher: Matcher[str] | Callable[[str], object]) -> Self: ...
+        def satisfies_exactly(self, *matchers: Matcher[str] | Callable[[str], object]) -> Self: ...
+        def satisfies_exactly_in_any_order(self, *matchers: Matcher[str] | Callable[[str], object]) -> Self: ...
+        # both named: `Any` let a caller write a character operation on whatever the other side holds
+        def zip_satisfies(
+            self, other: Iterable[_Other], predicate: Callable[[str, _Other], object], *, allow_empty: bool = ...
+        ) -> Self: ...
+        def filtered_on(self, predicate: Matcher[str] | Callable[[str], object]) -> _ListAssertion[str]: ...
+        def mapped(self, func: Callable[[str], _R]) -> _ListAssertion[_R]: ...
+        def flat_mapped(self, func: Callable[[str], Iterable[_R]]) -> _ListAssertion[_R]: ...
+        # the string view here handed the filesystem assertions to a caught message through `first()`
+        def first(self) -> _TextAssertion: ...
+        def last(self) -> _TextAssertion: ...
+        def element(self, index: SupportsIndex) -> _TextAssertion: ...
+        def single(self) -> _TextAssertion: ...
+        def extracting_group(self, pattern: str | re.Pattern[str], group: int | str = ...) -> Self: ...
+        # which of the two a pattern yields cannot be known statically
+        def matches_with_groups(self, pattern: str | re.Pattern[str]) -> AssertionBuilder[Any]: ...
+
+    class _StringAssertion(_TextAssertion, _FilesystemAssertion, Protocol):
+        """Assertions available for ``str`` values.
+
+        The text assertions plus the ones that read the value as a path, because a path is written as a
+        `str` at least as often as it is written as a `Path`.
+        """
+
+        @property
+        def not_(self) -> _NegatedStringAssertion: ...
+
+        def check(self) -> _CheckStringAssertion: ...
+
+        # redeclared so a pivot keeps its result a `str` rather than the text capability
+        def first(self) -> _StringAssertion: ...
+        def last(self) -> _StringAssertion: ...
+        def element(self, index: SupportsIndex) -> _StringAssertion: ...
+        def single(self) -> _StringAssertion: ...
+
+    class _NumericAssertion(_RealNumberAssertion, _ZeroAssertion, _CoreAssertion, Protocol[_N]):
+        """Assertions available for ``int`` and ``float`` values.
+
+        Generic over the number type ``_N`` so ``value`` keeps the exact numeric type instead of the
+        ``int | float`` union.
+
+        `complex` and `bool` have protocols of their own, each carrying what the runtime actually
+        accepts for that type rather than the whole numeric set.
+        """
+
+        # either tolerance holding is enough; with neither given the runtime refuses the call
+        def is_close_to(
+            self, other: _Number, tolerance: _Number | None = ..., *, rel: _Number | None = ...
+        ) -> Self: ...
+        def is_not_close_to(
+            self, other: _Number, tolerance: _Number | None = ..., *, rel: _Number | None = ...
+        ) -> Self: ...
+        @property
+        def not_(self) -> _NegatedNumericAssertion[_N]: ...
+
+        def check(self) -> _CheckNumericAssertion[_N]: ...
+
+        @property
+        def value(self) -> _N: ...
+        @overload
+        def satisfies(self, matcher: Callable[[_N], TypeIs[str]]) -> _StringAssertion: ...
+        @overload
+        def satisfies(self, matcher: Callable[[_N], TypeIs[bool]]) -> _BoolAssertion: ...
+        @overload
+        def satisfies(self, matcher: Callable[[_N], TypeIs[int]]) -> _NumericAssertion[int]: ...
+        @overload
+        def satisfies(self, matcher: Callable[[_N], TypeIs[float]]) -> _NumericAssertion[float]: ...
+        @overload
+        def satisfies(self, matcher: Callable[[_N], TypeIs[complex]]) -> _ComplexAssertion: ...
+        @overload
+        def satisfies(self, matcher: Callable[[_N], TypeIs[dict[_K, _V]]]) -> _DictAssertion[_K, _V]: ...
+        @overload
+        def satisfies(self, matcher: Callable[[_N], TypeIs[list[_E] | tuple[_E, ...]]]) -> _IterableAssertion[_E]: ...
+        @overload
+        def satisfies(self, matcher: Callable[[_N], TypeIs[set[_E] | frozenset[_E]]]) -> _IterableAssertion[_E]: ...
+        @overload
+        def satisfies(self, matcher: Callable[[_N], TypeIs[datetime.datetime]]) -> _DateTimeAssertion: ...
+        @overload
+        def satisfies(self, matcher: Callable[[_N], TypeIs[datetime.date]]) -> _DateAssertion: ...
+        @overload
+        def satisfies(self, matcher: Callable[[_N], TypeIs[Path]]) -> _PathAssertion: ...
+        @overload
+        def satisfies(self, matcher: Callable[[_N], TypeIs[bytes]]) -> _BytesAssertion[bytes]: ...
+        @overload
+        def satisfies(self, matcher: Callable[[_N], TypeIs[bytearray]]) -> _BytesAssertion[bytearray]: ...
+        @overload
+        def satisfies(self, matcher: Callable[[_N], TypeIs[Callable[..., object]]]) -> _CallableAssertion[Any]: ...
+        @overload
+        def satisfies(self, matcher: Callable[[_N], TypeIs[_CapableT]]) -> AssertionBuilder[_CapableT]: ...
+        @overload
+        def satisfies(self, matcher: Callable[[_N], TypeIs[_U]]) -> _ObjectAssertion[_U]: ...
+        @overload
+        def satisfies(self, matcher: Matcher[_N] | Callable[[_N], object]) -> Self: ...
+        # `_Number` rather than `_N`: comparing an `int` against a `float` has to keep working
+        def is_even(self) -> Self: ...
+        def is_odd(self) -> Self: ...
+        def is_divisible_by(self, divisor: SupportsIndex) -> Self: ...
+
+    class _ComplexAssertion(_ZeroAssertion, _CoreAssertion, Protocol):
+        """Assertions available for ``complex`` values, which is far fewer than for a real number.
+
+        Ordering is not defined for a complex number, and neither is parity, divisibility, NaN or
+        infinity: the runtime refuses all thirteen of those with `TypeError: ordering is not defined for
+        type <complex>` and its relatives.  It used to advertise them anyway, because `complex` shared
+        the numeric protocol, so a checker suggested a method whose only outcome was a crash.
+        """
+
+        @property
+        def not_(self) -> _NegatedComplexAssertion: ...
+
+        def check(self) -> _CheckComplexAssertion: ...
+
+        @property
+        def value(self) -> complex: ...
+
+    class _BoolAssertion(_RealNumberAssertion, _ZeroAssertion, _CoreAssertion, Protocol):
+        """Assertions available for ``bool``: every numeric one but the integer-only three and closeness.
+
+        `bool` is a subclass of `int`, so it used to resolve to the numeric protocol and be offered
+        `is_even`, `is_odd` and `is_divisible_by`.  The runtime refuses exactly those three with
+        `TypeError: val is not an integer, got bool`, and closeness too, and accepts the rest: `True > 0`
+        is a real comparison.  The type now says the same thing.
+        """
+
+        @property
+        def not_(self) -> _NegatedBoolAssertion: ...
+
+        def check(self) -> _CheckBoolAssertion: ...
+
+        @property
+        def value(self) -> bool: ...
+
+    class _IterableAssertion(
+        _MembershipAssertion,
+        _StructureAssertion,
+        _RepeatableAssertion[_E],
+        _SizedAssertion,
+        _CoreAssertion,
+        Protocol[_E],
+    ):
+        """Assertions available for ``list``, ``tuple``, ``set``, and ``frozenset`` values.
+
+        Generic over the element type ``_E`` so element-access pivots (``first``/``last``/``element``/
+        ``single``) narrow the chain to the element, and ``value`` keeps the element type.
+        """
+
+        @property
+        def not_(self) -> _NegatedIterableAssertion[_E]: ...
+
+        def check(self) -> _CheckIterableAssertion[_E]: ...
+
+        @property
+        def value(self) -> list[_E] | tuple[_E, ...] | set[_E] | frozenset[_E]: ...
+        def contains(self, *items: _E | Matcher[_E]) -> Self: ...
+        def does_not_contain(self, *items: _E | Matcher[_E]) -> Self: ...
+        def contains_only(self, *items: _E | Matcher[_E]) -> Self: ...
+        def contains_sequence(self, *items: _E | Matcher[_E]) -> Self: ...
+        def contains_exactly(self, *items: _E | Matcher[_E]) -> Self: ...
+        def contains_exactly_in_any_order(self, *items: _E | Matcher[_E]) -> Self: ...
+        def is_sorted(
+            self, key: Callable[[_E], object] = ..., reverse: bool = ..., *, allow_empty: bool = ...
+        ) -> Self: ...
+        def starts_with(self, prefix: _E) -> Self: ...
+        def ends_with(self, suffix: _E) -> Self: ...
+        def each(self, matcher: Matcher[_E] | Callable[[_E], object], *, allow_empty: bool = ...) -> Self: ...
+        def all_satisfy(self, matcher: Matcher[_E] | Callable[[_E], object], *, allow_empty: bool = ...) -> Self: ...
+        def any_satisfy(self, matcher: Matcher[_E] | Callable[[_E], object]) -> Self: ...
+        def none_satisfy(self, matcher: Matcher[_E] | Callable[[_E], object]) -> Self: ...
+        def satisfies_exactly(self, *matchers: Matcher[_E] | Callable[[_E], object]) -> Self: ...
+        def satisfies_exactly_in_any_order(self, *matchers: Matcher[_E] | Callable[[_E], object]) -> Self: ...
+        def zip_satisfies(
+            self, other: Iterable[_Other], predicate: Callable[[_E, _Other], object], *, allow_empty: bool = ...
+        ) -> Self: ...
+        def filtered_on(self, predicate: Matcher[_E] | Callable[[_E], object]) -> _ListAssertion[_E]: ...
+        def mapped(self, func: Callable[[_E], _R]) -> _ListAssertion[_R]: ...
+        def flat_mapped(self, func: Callable[[_E], Iterable[_R]]) -> _ListAssertion[_R]: ...
+        def first(self) -> AssertionBuilder[_E]: ...
+        def last(self) -> AssertionBuilder[_E]: ...
+        def element(self, index: SupportsIndex) -> AssertionBuilder[_E]: ...
+        def single(self) -> AssertionBuilder[_E]: ...
+
+    class _ListAssertion(_IterableAssertion[_E], Protocol[_E]):
+        """The iterable view of a collection this library built, rather than one a caller passed in.
+
+        Every pipeline step returns one of these, and the difference from `_IterableAssertion` is a single
+        line: `value` is a `list`, not one of four containers.  That is not a guess.  `filtered_on`,
+        `mapped`, `flat_mapped` and `extracting` build a list whatever they were given, on a `tuple`, a
+        `set` and a `frozenset` alike, so declaring the union afterwards described an input that has
+        already been left behind, and made callers narrow a type the library had already settled.
+        """
+
+        @property
+        def not_(self) -> _NegatedListAssertion[_E]: ...
+
+        def check(self) -> _CheckListAssertion[_E]: ...
+
+        @property
+        def value(self) -> list[_E]: ...
+
+    class _DictAssertion(_StructureAssertion, _SizedAssertion, _CoreAssertion, Protocol[_K, _V]):
+        """Assertions available for ``dict`` values, generic over the key and value types."""
+
+        @property
+        def not_(self) -> _NegatedDictAssertion[_K, _V]: ...
+
+        def check(self) -> _CheckDictAssertion[(_K, _V)]: ...
+
+        # both spellings, as neither covers the other
+        def is_subset_of(self, *supersets: Mapping[Any, Any] | MappingLike, allow_empty: bool = ...) -> Self: ...
+
+        def contains(self, *items: object) -> Self: ...
+
+        @property
+        def value(self) -> dict[_K, _V]: ...
+        def each(self, matcher: Matcher[_K] | Callable[[_K], object], *, allow_empty: bool = ...) -> Self: ...
+        def all_satisfy(self, matcher: Matcher[_K] | Callable[[_K], object], *, allow_empty: bool = ...) -> Self: ...
+        def contains_key(self, *keys: _K | Matcher[_K]) -> Self: ...
+        def does_not_contain_key(self, *keys: _K | Matcher[_K]) -> Self: ...
+        def contains_value(self, *values: _V | Matcher[_V]) -> Self: ...
+        def does_not_contain_value(self, *values: _V | Matcher[_V]) -> Self: ...
+        def contains_entry(self, *args: object, **kwargs: object) -> Self: ...
+        def does_not_contain_entry(self, *args: object, **kwargs: object) -> Self: ...
+        def does_not_contain(self, *items: object) -> Self: ...
+        def contains_only(self, *keys: object) -> Self: ...
+        def is_sorted(
+            self, key: Callable[[_K], object] = ..., reverse: bool = ..., *, allow_empty: bool = ...
+        ) -> Self: ...
+        # an element pivot hands back the builder: `_K` into the factory's view is dispatch this API cannot write
+        def filtered_on(self, predicate: Matcher[_K] | Callable[[_K], object]) -> _ListAssertion[_K]: ...
+        def mapped(self, func: Callable[[_K], _R]) -> _ListAssertion[_R]: ...
+        def flat_mapped(self, func: Callable[[_K], Iterable[_R]]) -> _ListAssertion[_R]: ...
+        def first(self) -> AssertionBuilder[_K]: ...
+        def last(self) -> AssertionBuilder[_K]: ...
+        def element(self, index: SupportsIndex) -> AssertionBuilder[_K]: ...
+        def single(self) -> AssertionBuilder[_K]: ...
+        def matches_structure(self, spec: dict[Any, Any]) -> Self: ...
+
+    # the shapes a checker recognises without importing the library that defines them.  Every member is one
+    # `pandas-stubs` declares: `pivot` and not `__dataframe__`, which the stubs answer through their catch-all
+    # and mypy then reads as an array.  No series shape, since nothing separates a series from a `pandas.Index`
+
+    # the umbrella: any capability keeps the whole surface.  `__dict__` is out, it lives on `object`
+
+    class _CollectionShape(Protocol):
+        # `__iter__` alone: a generator has no `__len__` and `contains()` works on one
+        def __iter__(self) -> Any: ...
+
+    class _HeadersShape(Protocol):
+        def keys(self) -> Any: ...
+        # positional-only, the way typeshed spells it
+        def __getitem__(self, key: Any, /) -> Any: ...
+
+    class _HttpResponseShape(Protocol):
+        # read-only, so a client spelling either as a property still matches
+        @property
+        def status_code(self) -> int: ...
+        @property
+        def headers(self) -> _HeadersShape: ...
+
+    class _ModelShape(Protocol):
+        def model_dump(self, *args: Any, **kwargs: Any) -> Any: ...
+
+    class _DataclassShape(Protocol):
+        # `ClassVar`, because that is what `__dataclass_fields__` is: as an instance variable it matched nothing
+        __dataclass_fields__: ClassVar[Any]
+
+    class _MappingLikeShape(Protocol):
+        def keys(self) -> Any: ...
+        # positional-only, the way typeshed spells it
+        def __getitem__(self, key: Any, /) -> Any: ...
+
+    _Capable = _CollectionShape | _HttpResponseShape | _ModelShape | _DataclassShape | _MappingLikeShape
+    _CapableT = TypeVar("_CapableT", bound=_Capable)
+
+    class _FrameShape(Protocol):
+        def pivot(self, *args: Any, **kwargs: Any) -> Any: ...
+        @property
+        def shape(self) -> Any: ...
+
+    class _ArrayShape(Protocol):
+        def __array__(self) -> Any: ...
+        @property
+        def strides(self) -> Any: ...
+        # a numpy scalar carries the other two and no length, and falls through to the numeric fallback
+        def __len__(self) -> int: ...
+
+    # covariant: the view only ever hands the subject back, through `.value`
+    _FrameT_co = TypeVar("_FrameT_co", bound=_FrameShape, covariant=True)
+    _ArrayT_co = TypeVar("_ArrayT_co", bound=_ArrayShape, covariant=True)
+
+    class _CollectionShapedAssertion(_SizedAssertion, _MembershipAssertion, _WalkAssertion, Protocol):
+        """What a frame, a series and an array all answer, measured rather than assumed.
+
+        Every family here is one their runtime gates accept: they are sized, they are walked, and they
+        answer membership.  What is deliberately absent is as measured: the JSON family refuses them,
+        `matches_structure` refuses a polars frame, and the ordering assertions refuse them through
+        `is_between` while `is_greater_than` leaks the library's own ambiguity error instead.
+
+        One boundary the shapes cannot express: a zero-dimensional array carries `__array__` and
+        `strides` like any other, and `numpy.ndarray[Any, Any]` covers it, yet it has no length and
+        cannot be iterated.  So `is_not_empty`, `is_length`, `contains_only` and `each` are offered on
+        `numpy.array(1)` and raise there.  Separating it statically would need a shape keyed on the
+        dimension, which the stubs do not carry, and `tests/test_dataframe.py` holds what it does
+        instead.
+        """
+
+        def contains(self, *items: object) -> Self: ...
+        def does_not_contain(self, *items: object) -> Self: ...
+        def contains_only(self, *items: object) -> Self: ...
+
+    class _ArrayLikeAssertion(_CollectionShapedAssertion, _CoreAssertion, Protocol):
+        """The two numpy assertions, which every array-like the runtime accepts can answer."""
+
+        def is_array_equal(self, expected: object, **options: Any) -> Self: ...
+        def is_array_close_to(
+            self,
+            expected: object,
+            *,
+            rtol: float = ...,
+            atol: float = ...,
+            equal_nan: bool = ...,
+            **options: Any,
+        ) -> Self: ...
+
+    class _FrameAssertion(_ArrayLikeAssertion, Protocol[_FrameT_co]):
+        """Assertions available for a pandas or polars frame, which is array-like as well."""
+
+        @property
+        def not_(self) -> _NegatedFrameAssertion[_FrameT_co]: ...
+
+        def check(self) -> _CheckFrameAssertion[_FrameT_co]: ...
+
+        @property
+        def value(self) -> _FrameT_co: ...
+        def is_frame_equal(self, expected: object, **options: Any) -> Self: ...
+
+    class _ArrayAssertion(_ArrayLikeAssertion, Protocol[_ArrayT_co]):
+        """Assertions available for a numpy array, which is everything a frame has but `is_frame_equal`."""
+
+        @property
+        def not_(self) -> _NegatedArrayAssertion[_ArrayT_co]: ...
+
+        def check(self) -> _CheckArrayAssertion[_ArrayT_co]: ...
+
+        @property
+        def value(self) -> _ArrayT_co: ...
+
+    class _DateAssertion(_CoreAssertion, Protocol):
+        """Assertions available for a ``datetime.date`` value.
+
+        The chronological nine are not here.  They refuse a plain date at run time, on the value and not
+        only on the operand, so `assert_that(day).is_before(stamp)` type-checked and raised for as long
+        as one view served both types.  They live on the datetime view below.
+        """
+
+        @property
+        def not_(self) -> _NegatedDateAssertion: ...
+
+        def check(self) -> _CheckDateAssertion: ...
+
+        @property
+        def value(self) -> datetime.date: ...
+        # at run time the operands must match the value's exact type
+        def is_greater_than(self, other: datetime.date) -> Self: ...
+        def is_greater_than_or_equal_to(self, other: datetime.date) -> Self: ...
+        def is_less_than(self, other: datetime.date) -> Self: ...
+        def is_less_than_or_equal_to(self, other: datetime.date) -> Self: ...
+        def is_between(self, low: datetime.date, high: datetime.date) -> Self: ...
+        def is_not_between(self, low: datetime.date, high: datetime.date) -> Self: ...
+
+    class _DateTimeAssertion(_CoreAssertion, Protocol):
+        """Assertions available for a ``datetime.datetime`` value.
+
+        A sibling of the date view rather than a child of it, and the ordering below is why: at run time
+        an operand has to match the value's own type, so a datetime orders against a datetime.  Inheriting
+        the date view brought its `is_less_than(other: datetime.date)` along, and
+        `assert_that(stamp).is_less_than(day)` type-checked and raised.
+        """
+
+        @property
+        def not_(self) -> _NegatedDateTimeAssertion: ...
+
+        def check(self) -> _CheckDateTimeAssertion: ...
+
+        @property
+        def value(self) -> datetime.datetime: ...
+        def is_greater_than(self, other: datetime.datetime) -> Self: ...
+        def is_greater_than_or_equal_to(self, other: datetime.datetime) -> Self: ...
+        def is_less_than(self, other: datetime.datetime) -> Self: ...
+        def is_less_than_or_equal_to(self, other: datetime.datetime) -> Self: ...
+        def is_between(self, low: datetime.datetime, high: datetime.datetime) -> Self: ...
+        def is_not_between(self, low: datetime.datetime, high: datetime.datetime) -> Self: ...
+        def is_before(self, other: datetime.datetime) -> Self: ...
+        def is_after(self, other: datetime.datetime) -> Self: ...
+        def is_before_or_equal_to(self, other: datetime.datetime) -> Self: ...
+        def is_after_or_equal_to(self, other: datetime.datetime) -> Self: ...
+        def is_equal_to_ignoring_milliseconds(self, other: datetime.datetime) -> Self: ...
+        def is_equal_to_ignoring_seconds(self, other: datetime.datetime) -> Self: ...
+        def is_equal_to_ignoring_time(self, other: datetime.datetime) -> Self: ...
+        # closeness on a datetime is a timedelta, the one place the numeric family takes something else.  Optional
+        # because the one runtime method serves numbers too, where `rel` may stand alone; a datetime has no size
+        # for `rel` to be a fraction of, so it is declared as nothing but `None`
+        def is_close_to(
+            self, other: datetime.datetime, tolerance: datetime.timedelta | None = ..., *, rel: None = ...
+        ) -> Self: ...
+        def is_not_close_to(
+            self, other: datetime.datetime, tolerance: datetime.timedelta | None = ..., *, rel: None = ...
+        ) -> Self: ...
+
+    class _PathAssertion(_FilesystemAssertion, _CoreAssertion, Protocol):
+        """Assertions available for ``pathlib.Path`` values."""
+
+        @property
+        def not_(self) -> _NegatedPathAssertion: ...
+
+        def check(self) -> _CheckPathAssertion: ...
+
+        @property
+        def value(self) -> Path: ...
+
+    class _BytesAssertion(_MembershipAssertion, _SizedAssertion, _CoreAssertion, Protocol[_B_co]):
+        """Assertions available for ``bytes`` and ``bytearray`` values, generic over which one."""
+
+        @property
+        def not_(self) -> _NegatedBytesAssertion[_B_co]: ...
+
+        def check(self) -> _CheckBytesAssertion[_B_co]: ...
+
+        def contains(self, *items: object) -> Self: ...
+        def does_not_contain(self, *items: object) -> Self: ...
+
+        @property
+        def value(self) -> _B_co: ...
+        def is_sorted(
+            self, key: Callable[[int], object] = ..., reverse: bool = ..., *, allow_empty: bool = ...
+        ) -> Self: ...
+        def filtered_on(self, predicate: Matcher[int] | Callable[[int], object]) -> _ListAssertion[int]: ...
+        def mapped(self, func: Callable[[int], _R]) -> _ListAssertion[_R]: ...
+        def flat_mapped(self, func: Callable[[int], Iterable[_R]]) -> _ListAssertion[_R]: ...
+        def first(self) -> _NumericAssertion[int]: ...
+        def last(self) -> _NumericAssertion[int]: ...
+        def element(self, index: SupportsIndex) -> _NumericAssertion[int]: ...
+        def single(self) -> _NumericAssertion[int]: ...
+        # the prefix and suffix pair handles bytes natively, so it is reachable under both names
+        def starts_with(self, prefix: bytes | bytearray) -> Self: ...
+        def ends_with(self, suffix: bytes | bytearray) -> Self: ...
+        def is_valid_utf8(self) -> Self: ...
+        def is_valid_encoding(self, encoding: str) -> Self: ...
+        def starts_with_bytes(self, prefix: bytes | bytearray) -> Self: ...
+        def contains_bytes(self, sub: bytes | bytearray) -> Self: ...
+        def has_byte_at(self, index: SupportsIndex, expected: SupportsIndex) -> Self: ...
+        def is_hex_equal_to(self, expected_hex: str) -> Self: ...
+        def decoded_as(self, encoding: str = ...) -> _StringAssertion: ...
+        def is_greater_than(self, other: bytes | bytearray) -> Self: ...
+        def is_greater_than_or_equal_to(self, other: bytes | bytearray) -> Self: ...
+        def is_less_than(self, other: bytes | bytearray) -> Self: ...
+        def is_less_than_or_equal_to(self, other: bytes | bytearray) -> Self: ...
+
+    class _InvokedAssertion(_TextAssertion, Protocol[_Exc]):
+        """Assertions available after ``when_called_with()`` captured an exception message.
+
+        The captured message is a ``str`` (hence the text assertions, though not the ones reading a
+        path: a message is not a filename).
+
+        `returned()` is absent and that is measured: after `raises()` the call never completed, so it
+        raises `no return value captured`.  A call that did complete lands on `_WarnedAssertion` or
+        `_CompletedAssertion`, which carry it instead.
+        """
+
+        @property
+        def not_(self) -> _NegatedInvokedAssertion[_Exc]: ...
+
+        def check(self) -> _CheckInvokedAssertion[_Exc]: ...
+
+        def raised(self) -> AssertionBuilder[_Exc]: ...
+        # these three pivot to the exception they found; a bare `type` names none, and ty refused it against the bound
+        @overload
+        def caused_by(self, ex: type[_Landed]) -> _InvokedAssertion[_Landed]: ...
+        # the cause is read with `isinstance`, so a union or a tuple of classes is taken, landing on no one class
+        @overload
+        def caused_by(self, ex: ClassInfo) -> _InvokedAssertion[BaseException]: ...
+        def errors(self) -> _ListAssertion[BaseException]: ...
+        @overload
+        def error_of(self, ex: type[_Landed]) -> _InvokedAssertion[_Landed]: ...
+        @overload
+        def error_of(self, ex: type) -> _InvokedAssertion[BaseException]: ...
+        def does_not_contain_error(self, *ex_types: type | ExceptionInfo) -> Self: ...
+        @overload
+        def has_root_cause(self, ex: type[_Landed]) -> _InvokedAssertion[_Landed]: ...
+        @overload
+        def has_root_cause(self, ex: ClassInfo) -> _InvokedAssertion[BaseException]: ...
+        def contains_error(self, *ex_types: type | ExceptionInfo) -> Self: ...
+        # a `list` is a subgroup, so the entry type is recursive; spelled with `Any` inside because a
+        # recursive alias declared here is what ty reads as `Any` anyway, measured in `_typing.py`'s own
+        # history, and naming it would suggest a precision the checkers do not carry
+        def matches_error_tree(self, *expected: type | list[Any]) -> Self: ...
+
+    class _WarnedAssertion(_TextAssertion, Protocol[_P_co]):
+        """Assertions available after ``when_called_with()`` captured a warning message.
+
+        The message is text like the invoked view's, and the call completed, so
+        [`returned()`][assertpy.exception.ExceptionMixin.returned] reads the value it produced.  The
+        exception family is absent: nothing was caught, and every one of those eight raises
+        `no exception captured`, measured.
+        """
+
+        @property
+        def not_(self) -> _NegatedWarnedAssertion[_P_co]: ...
+
+        def check(self) -> _CheckWarnedAssertion[_P_co]: ...
+
+        # named outright: bound through `self`, ty found no member here that uses the parameter and read `Unknown`
+        def returned(self) -> AssertionBuilder[_P_co]: ...
+
+    class _CallableAssertion(_CoreAssertion, Protocol[_P_co]):
+        """Assertions available for callable values.
+
+        `when_called_with()` is not here.  It refuses a chain with no expectation set, so the four
+        methods that set one hand back the view carrying it.
+        """
+
+        @property
+        def not_(self) -> _NegatedCallableAssertion[_P_co]: ...
+
+        def check(self) -> _CheckCallableAssertion[_P_co]: ...
+
+        @property
+        def value(self) -> Callable[..., _P_co]: ...
+        @overload
+        def raises(self, ex: type[_Landed]) -> _ExpectedRaiseAssertion[_P_co, _Landed]: ...
+        # several classes, any one of which may be raised, land on no one class, as a bare `type` does
+        @overload
+        def raises(self, ex: type | ExceptionInfo) -> _ExpectedRaiseAssertion[_P_co, BaseException]: ...
+        def does_not_raise(self, ex: type | ExceptionInfo) -> _ExpectedCompletionAssertion[_P_co]: ...
+        def warns(self, warning: type[Warning] | WarningInfo = ...) -> _ExpectedWarningAssertion[_P_co]: ...
+        def does_not_warn(self, warning: type[Warning] | WarningInfo = ...) -> _ExpectedCompletionAssertion[_P_co]: ...
+        # an `async def` probe is awaited on every poll, so the chain is over what the coroutine returns
+        @overload
+        def eventually(
+            self: _Holding[Callable[..., Awaitable[_R]]],
+            *,
+            timeout: float = ...,
+            interval: float = ...,
+            ignoring: type[Exception] | RetriedInfo = ...,
+            trace: bool = ...,
+        ) -> _AsyncPoll[_R]: ...
+        @overload
+        def eventually(
+            self,
+            *,
+            timeout: float = ...,
+            interval: float = ...,
+            ignoring: type[Exception] | RetriedInfo = ...,
+            trace: bool = ...,
+        ) -> _AsyncPoll[_P_co]: ...
+        def eventually_sync(
+            self,
+            *,
+            timeout: float = ...,
+            interval: float = ...,
+            ignoring: type[Exception] | RetriedInfo = ...,
+            trace: bool = ...,
+        ) -> _SyncPoll[_P_co]: ...
+
+    class _CompletedAssertion(_CallableAssertion[_P_co], Protocol[_P_co]):
+        """Assertions available after a `does_not_raise()` or `does_not_warn()` call completed.
+
+        The value under test is still the callable, not a message, so the text assertions are absent:
+        every one of them raises `val must be a string or an iterable`, measured.  What the call
+        produced is reachable through `returned()`.
+        """
+
+        @property
+        def not_(self) -> _NegatedCompletedAssertion[_P_co]: ...
+
+        def check(self) -> _CheckCompletedAssertion[_P_co]: ...
+
+        def returned(self: _CompletedAssertion[_R]) -> AssertionBuilder[_R]: ...
+
+    class _ExpectedRaiseAssertion(_CallableAssertion[_P_co], Protocol[_P_co, _Exc]):
+        """A callable with a `raises()` expectation set, waiting for the call that tests it."""
+
+        @property
+        def not_(self) -> _NegatedExpectedRaiseAssertion[_P_co, _Exc]: ...
+
+        def check(self) -> _CheckExpectedRaiseAssertion[_P_co, _Exc]: ...
+
+        def when_called_with(self, *some_args: object, **some_kwargs: object) -> _InvokedAssertion[_Exc]: ...
+
+    class _ExpectedWarningAssertion(_CallableAssertion[_P_co], Protocol[_P_co]):
+        """A callable with a `warns()` expectation set, waiting for the call that tests it."""
+
+        @property
+        def not_(self) -> _NegatedExpectedWarningAssertion[_P_co]: ...
+
+        def check(self) -> _CheckExpectedWarningAssertion[_P_co]: ...
+
+        def when_called_with(self, *some_args: object, **some_kwargs: object) -> _WarnedAssertion[_P_co]: ...
+
+    class _ExpectedCompletionAssertion(_CallableAssertion[_P_co], Protocol[_P_co]):
+        """A callable expected to complete, which is what `does_not_raise()` and `does_not_warn()` set."""
+
+        @property
+        def not_(self) -> _NegatedExpectedCompletionAssertion[_P_co]: ...
+
+        def check(self) -> _CheckExpectedCompletionAssertion[_P_co]: ...
+
+        def when_called_with(self, *some_args: object, **some_kwargs: object) -> _CompletedAssertion[_P_co]: ...