assertpy2 2.22.0__tar.gz → 2.24.0__tar.gz

{assertpy2-2.22.0 → assertpy2-2.24.0}/CONTRIBUTING.md

@@ -23,17 +23,26 @@ Read more about how pulls work on GitHub's [About pull requests](https://help.gi
 - Python 3.10+
 - [uv](https://docs.astral.sh/uv/) as the package manager
 
+## Before you change a public signature
+
+Read [ARCHITECTURE.md](ARCHITECTURE.md). Four files under `assertpy2/_engine/` are generated, the public
+surface is pinned by a recorded snapshot, and neither is discoverable from the files themselves.
+
 ## Verification pipeline
 
 Run all checks before submitting a PR. Every step must pass.
 
-Install exactly this set. A bare `uv sync` leaves out the optional libraries several tests import, and
-those tests fail rather than skip:
+### Install
+
+A bare `uv sync` leaves out the optional libraries several tests import, and those tests then fail
+rather than skip. Install exactly this set:
 
 ```bash
 uv sync --extra json --extra data --extra inline --group integrations --group docs-examples
 ```
 
+### The main gate
+
 ```bash
 uv run ruff check .
 uv run ruff format --check .
@@ -43,17 +52,58 @@ uv run pytest tests/test_docs_examples.py tests/test_typing_claims.py
 uv run --group docs mkdocs build --strict
 ```
 
-The public typing surface is checked by three checkers. Run them after the block above, not before:
-`uv run --group typecheck` adds the checkers to the same `.venv` and leaves them there, and a coverage
-run with them installed collects a different set:
+CI requires 100% code coverage.
+
+### Then once on the supported floor
+
+Run the suite on Python 3.10 as well. This is not optional, and the block above does not cover it.
+
+A union carries `__name__` from 3.14 onwards and not before. `logging.LoggerAdapter` became
+subscriptable in 3.11. Neither difference is visible to a type checker told to target 3.10, and both
+shipped as defects that every other gate passed.
+
+Use a throwaway environment. `uv run --python 3.10` inside the project rebuilds `.venv` for that
+version, and on Windows it can fail partway and leave you without pytest:
+
+```bash
+uv venv /tmp/py310 --python 3.10
+
+export VIRTUAL_ENV=/tmp/py310
+uv pip install -e ".[json,data,inline]"
+uv pip install pytest pytest-cov hypothesis ruff
+uv pip install attrs pydantic requests httpx flask
+
+/tmp/py310/bin/python -m pytest tests --ignore=tests/test_docs_examples.py -q
+```
+
+`ruff` belongs in that list: the tests that compare a generated file against its generator shell out
+to it, and without it they fail for a reason that has nothing to do with your change.
+
+### The four type checkers
+
+Run these after the main gate, not before. `uv run --group typecheck` adds the checkers to the same
+`.venv` and leaves them there, and a coverage run with them installed collects a different set:
 
 ```bash
 uv run --group typecheck mypy --strict --follow-imports=silent tests/test_typing.py
-uv run --group typecheck pyright tests/test_typing.py
+PYRIGHT_PYTHON_FORCE_VERSION=1.1.413 uv run --group typecheck pyright --pythonversion 3.14 tests/test_typing.py
+uv run --group typecheck pyrefly check tests/test_typing.py
 uv run --group typecheck pytest tests/test_pyright_baseline.py
 ```
 
-Three details that cost time if you meet them the hard way:
+`PYRIGHT_PYTHON_FORCE_VERSION` picks the engine rather than the launcher. The `pyright` distribution on
+PyPI stopped at 1.1.411 on 25 June while npm has shipped 1.1.412 and 1.1.413 since, so the launcher and
+the engine move apart. The baseline is recorded against one engine, and `tests/typing_harness.py` pins
+the same build, so only this direct invocation needs the variable.
+
+`--pythonversion 3.14` is not decoration. Pyright reports against the interpreter it finds unless
+told otherwise, and the count moves with it: 174 diagnostics for this package on 3.10 against 169 on
+3.14.
+
+Without it a contributor on the supported floor meets a red baseline that says nothing about their
+change. The baseline test passes the same target itself, so it gives one answer everywhere.
+
+### Three details that cost time if you meet them the hard way
 
 - `ty check` is scoped on purpose. Run over the whole tree it reports hundreds of diagnostics from
   `tests/`, which is full of deliberate negative typing cases: calls that must not type-check.
@@ -63,8 +113,6 @@ Three details that cost time if you meet them the hard way:
 - `tests/test_docs_examples.py` is run separately because it executes the snippets in `docs/`, which
   needs the `docs-examples` group and a different collection.
 
-CI requires 100% code coverage.
-
 ## Commit style
 
 Use [Conventional Commits](https://www.conventionalcommits.org/): `feat:`, `fix:`, `refactor:`, `test:`, `docs:`, `chore:`, etc.

{assertpy2-2.22.0 → assertpy2-2.24.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: assertpy2
-Version: 2.22.0
+Version: 2.24.0
 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
@@ -57,7 +57,7 @@ Description-Content-Type: text/markdown
     <img src="docs/logo.svg" alt="assertpy2" width="280">
   </picture>
   <br>
-  <b>A fully typed fluent assertion library for Python</b><br>
+  <b>Fully typed fluent assertion library for Python</b><br>
   A modern, batteries-included fork of <a href="https://github.com/assertpy/assertpy">assertpy</a>
 </p>
 
@@ -68,7 +68,7 @@ Description-Content-Type: text/markdown
   <a href="https://pypi.org/project/assertpy2/"><img src="https://img.shields.io/pypi/pyversions/assertpy2" alt="Python"></a>
   <a href="https://pepy.tech/projects/assertpy2"><img src="https://static.pepy.tech/badge/assertpy2/month" alt="Downloads"></a>
   <br>
-  <a href="https://solganis.github.io/assertpy2/concepts/type-safety/"><img src="https://img.shields.io/badge/type--checked-ty%20%7C%20mypy%20%7C%20pyright-2ea043" alt="public overloads type-checked by ty, mypy --strict, and pyright with zero suppressions"></a>
+  <a href="https://solganis.github.io/assertpy2/concepts/type-safety/"><img src="https://img.shields.io/badge/overloads-ty%20%7C%20mypy%20%7C%20pyright%20%7C%20pyrefly-2ea043" alt="every public overload checked by ty, mypy --strict, pyright and pyrefly with zero suppressions"></a>
   <a href="https://solganis.github.io/assertpy2/"><img src="https://img.shields.io/badge/docs-online-black" alt="Documentation"></a>
   <a href="https://scorecard.dev/viewer/?uri=github.com/Solganis/assertpy2"><img src="https://img.shields.io/ossf-scorecard/github.com/Solganis/assertpy2?label=OpenSSF%20Scorecard" alt="OpenSSF Scorecard"></a>
 </p>
@@ -201,7 +201,7 @@ There are [45 matchers](https://solganis.github.io/assertpy2/guides/matchers/),
 <h2 align="center"><a href="https://solganis.github.io/assertpy2/concepts/type-safety/">Type-aware autocomplete</a></h2>
 
 `assert_that()` uses `@overload` to return type-specific Protocols.<br>
-Your IDE shows only methods relevant to the value you're testing, not all 100+:
+Your IDE shows only methods relevant to the value you're testing, not the whole surface:
 
 - `assert_that("hello").` &rarr; string methods: `starts_with`, `matches`, `is_alpha`, ...
 - `assert_that(42).` &rarr; numeric methods: `is_positive`, `is_between`, `is_close_to`, ...
@@ -209,7 +209,7 @@ Your IDE shows only methods relevant to the value you're testing, not all 100+:
 - `assert_that(my_dict).` &rarr; dict methods: `contains_key`, `contains_entry`, `has_json_path`, ...
 - `assert_that(b"\x89PNG").` &rarr; bytes methods: `starts_with_bytes`, `is_valid_utf8`, `decoded_as`, ...
 
-11 type-specific Protocols instead of one `Any`.<br>
+15 type-specific Protocols instead of one `Any`.<br>
 Works in PyCharm, VS Code, and any LSP-compatible editor.
 
 <h2 align="center"><a href="https://solganis.github.io/assertpy2/concepts/type-safety/#typed-narrowing-with-value">Typed narrowing</a></h2>
@@ -221,7 +221,7 @@ An assertion hands the value back, statically narrowed.
 <!-- docs-guard: skip -->
 ```python
 order = assert_that(repo.find(42)).is_not_none().is_instance_of(PaidOrder).value
-order.refund()  # statically PaidOrder - verified by ty, mypy, and pyright
+order.refund()  # statically PaidOrder - verified by ty, mypy, pyright and pyrefly
 ```
 
 For API tests,
@@ -263,6 +263,7 @@ is open to anything else you build.
 - [**Structural matching**](https://solganis.github.io/assertpy2/guides/matchers/#structural-matching): `matches_structure()` for declarative dict/API-response validation.
 - [**Recursive field assertions**](https://solganis.github.io/assertpy2/guides/assertions/#recursive-field-assertions): `all_fields_satisfy()` / `has_no_none_fields()` apply a predicate to every leaf of an object graph.
 - [**Vacuous-assertion guard**](https://solganis.github.io/assertpy2/guides/assertions/#assertions-that-checked-nothing): `--assertpy2-vacuous` warns when a universal assertion passes over an empty collection, having checked nothing.
+- [**Dangling-assertion detector**](https://solganis.github.io/assertpy2/guides/assertions/#assertions-that-never-ran): `--assertpy2-dangling` warns when a chain builds an assertion and never runs it. `assert assert_that(x).is_positive` passes on any value, and neither ruff nor coverage sees it.
 - [**Universal negation**](https://solganis.github.io/assertpy2/guides/fluent/#universal-negation): `.not_` inverts any assertion, no dedicated `is_not_*` methods.
 - [**Collection pipeline**](https://solganis.github.io/assertpy2/guides/fluent/#collection-pipeline): `filtered_on()`, `mapped()`, `flat_mapped()`, `first()`, `last()`, `element()`, `single()`.
 - [**Positional & pairwise checks**](https://solganis.github.io/assertpy2/guides/assertions/#lists): `satisfies_exactly()`, `zip_satisfies()`, `contains_only_once()`, `has_same_size_as()`, plus `*_in_any_order` variants.

{assertpy2-2.22.0 → assertpy2-2.24.0}/README.md

@@ -5,7 +5,7 @@
     <img src="docs/logo.svg" alt="assertpy2" width="280">
   </picture>
   <br>
-  <b>A fully typed fluent assertion library for Python</b><br>
+  <b>Fully typed fluent assertion library for Python</b><br>
   A modern, batteries-included fork of <a href="https://github.com/assertpy/assertpy">assertpy</a>
 </p>
 
@@ -16,7 +16,7 @@
   <a href="https://pypi.org/project/assertpy2/"><img src="https://img.shields.io/pypi/pyversions/assertpy2" alt="Python"></a>
   <a href="https://pepy.tech/projects/assertpy2"><img src="https://static.pepy.tech/badge/assertpy2/month" alt="Downloads"></a>
   <br>
-  <a href="https://solganis.github.io/assertpy2/concepts/type-safety/"><img src="https://img.shields.io/badge/type--checked-ty%20%7C%20mypy%20%7C%20pyright-2ea043" alt="public overloads type-checked by ty, mypy --strict, and pyright with zero suppressions"></a>
+  <a href="https://solganis.github.io/assertpy2/concepts/type-safety/"><img src="https://img.shields.io/badge/overloads-ty%20%7C%20mypy%20%7C%20pyright%20%7C%20pyrefly-2ea043" alt="every public overload checked by ty, mypy --strict, pyright and pyrefly with zero suppressions"></a>
   <a href="https://solganis.github.io/assertpy2/"><img src="https://img.shields.io/badge/docs-online-black" alt="Documentation"></a>
   <a href="https://scorecard.dev/viewer/?uri=github.com/Solganis/assertpy2"><img src="https://img.shields.io/ossf-scorecard/github.com/Solganis/assertpy2?label=OpenSSF%20Scorecard" alt="OpenSSF Scorecard"></a>
 </p>
@@ -149,7 +149,7 @@ There are [45 matchers](https://solganis.github.io/assertpy2/guides/matchers/),
 <h2 align="center"><a href="https://solganis.github.io/assertpy2/concepts/type-safety/">Type-aware autocomplete</a></h2>
 
 `assert_that()` uses `@overload` to return type-specific Protocols.<br>
-Your IDE shows only methods relevant to the value you're testing, not all 100+:
+Your IDE shows only methods relevant to the value you're testing, not the whole surface:
 
 - `assert_that("hello").` &rarr; string methods: `starts_with`, `matches`, `is_alpha`, ...
 - `assert_that(42).` &rarr; numeric methods: `is_positive`, `is_between`, `is_close_to`, ...
@@ -157,7 +157,7 @@ Your IDE shows only methods relevant to the value you're testing, not all 100+:
 - `assert_that(my_dict).` &rarr; dict methods: `contains_key`, `contains_entry`, `has_json_path`, ...
 - `assert_that(b"\x89PNG").` &rarr; bytes methods: `starts_with_bytes`, `is_valid_utf8`, `decoded_as`, ...
 
-11 type-specific Protocols instead of one `Any`.<br>
+15 type-specific Protocols instead of one `Any`.<br>
 Works in PyCharm, VS Code, and any LSP-compatible editor.
 
 <h2 align="center"><a href="https://solganis.github.io/assertpy2/concepts/type-safety/#typed-narrowing-with-value">Typed narrowing</a></h2>
@@ -169,7 +169,7 @@ An assertion hands the value back, statically narrowed.
 <!-- docs-guard: skip -->
 ```python
 order = assert_that(repo.find(42)).is_not_none().is_instance_of(PaidOrder).value
-order.refund()  # statically PaidOrder - verified by ty, mypy, and pyright
+order.refund()  # statically PaidOrder - verified by ty, mypy, pyright and pyrefly
 ```
 
 For API tests,
@@ -211,6 +211,7 @@ is open to anything else you build.
 - [**Structural matching**](https://solganis.github.io/assertpy2/guides/matchers/#structural-matching): `matches_structure()` for declarative dict/API-response validation.
 - [**Recursive field assertions**](https://solganis.github.io/assertpy2/guides/assertions/#recursive-field-assertions): `all_fields_satisfy()` / `has_no_none_fields()` apply a predicate to every leaf of an object graph.
 - [**Vacuous-assertion guard**](https://solganis.github.io/assertpy2/guides/assertions/#assertions-that-checked-nothing): `--assertpy2-vacuous` warns when a universal assertion passes over an empty collection, having checked nothing.
+- [**Dangling-assertion detector**](https://solganis.github.io/assertpy2/guides/assertions/#assertions-that-never-ran): `--assertpy2-dangling` warns when a chain builds an assertion and never runs it. `assert assert_that(x).is_positive` passes on any value, and neither ruff nor coverage sees it.
 - [**Universal negation**](https://solganis.github.io/assertpy2/guides/fluent/#universal-negation): `.not_` inverts any assertion, no dedicated `is_not_*` methods.
 - [**Collection pipeline**](https://solganis.github.io/assertpy2/guides/fluent/#collection-pipeline): `filtered_on()`, `mapped()`, `flat_mapped()`, `first()`, `last()`, `element()`, `single()`.
 - [**Positional & pairwise checks**](https://solganis.github.io/assertpy2/guides/assertions/#lists): `satisfies_exactly()`, `zip_satisfies()`, `contains_only_once()`, `has_same_size_as()`, plus `*_in_any_order` variants.

{assertpy2-2.22.0 → assertpy2-2.24.0}/assertpy2/_clustering.py

@@ -59,9 +59,7 @@ __tracebackhide__ = True
 # steps that name a *place* in a value, as opposed to `item`, which names a member of a set
 _COORDINATE: Final = frozenset({"key", "index", "attr", "line"})
 
-# a position collapses to one placeholder: `users[0].role` and `users[7].role` are the same difference
-# reported against two rows, and a reader chasing a common cause wants them in one line. a line number
-# is incidental in the same way
+# a position collapses to one placeholder: `users[0].role` and `users[7].role` are one difference on two rows
 _POSITIONAL: Final = frozenset({"index", "line"})
 _ANY_POSITION: Final = "[*]"
 
@@ -190,8 +188,7 @@ def stable_repr(value: object, _seen: frozenset[int] = frozenset()) -> str:
     try:
         if isinstance(value, (set, frozenset)):
             members = sorted(stable_repr(member, inner) for member in value)
-            # an empty one falls back to `repr`, since `{}` is a dict; the price is that `set()`
-            # and the `frozenset()` it equals read apart, where two non-empty equal ones read alike
+            # an empty one falls back to `repr`: `{}` is a dict, so `set()` and the `frozenset()` it equals read apart
             return "{" + ", ".join(members) + "}" if value else _safe_repr(value)
         if isinstance(value, dict):
             pairs = (f"{stable_repr(key, inner)}: {stable_repr(item, inner)}" for key, item in value.items())
@@ -289,9 +286,7 @@ def is_well_formed(key: Signature) -> bool:
         )
     if key.steps:
         return False
-    # exactly one of the two, which is what `signature()` sets: the diagnostic replaces the values,
-    # never joins them.  A pair of values only for the kinds whose fields hold the compared values, or
-    # a `contains` payload would print the `None` that stands for a missing item as somebody's value
+    # a pair of values only for the kinds whose fields hold them, or a `contains` payload prints a `None`
     if key.label:
         return not key.values
     return len(key.values) == 2 and key.where in _VALUES_ARE_VALUES
@@ -330,17 +325,14 @@ def clusters(
     """
     if total_failures <= 0:
         return []
-    # keyed on the node id, not appended: one test can be reported failing more than once, which is
-    # what `pytest-rerunfailures` does on every retry, and counting its attempts as separate failures
-    # printed a cluster of six over two tests
+    # keyed on the node id: `pytest-rerunfailures` retries printed a cluster of six over two tests
     grouped: dict[Signature, dict[str, None]] = {}
     actuals: dict[Signature, dict[str, None]] = {}
     expecteds: dict[Signature, dict[str, None]] = {}
     for nodeid, found in recorded:
         for one in found:
             grouped.setdefault(one.signature, {})[nodeid] = None
-            # one past the limit, so a full side is distinguishable from a capped one by its length
-            # alone. The smallest value is always kept, whichever order the failures came in
+            # one past the limit, so a full side is distinguishable from a capped one by its length alone
             for store, value in ((actuals, one.actual), (expecteds, one.expected)):
                 seen = store.setdefault(one.signature, {})
                 if len(seen) <= _EXAMPLE_LIMIT:
@@ -353,8 +345,7 @@ def clusters(
         for key, nodeids in grouped.items()
         if len(nodeids) >= minimum
     ]
-    # size first, then the signature itself: two clusters of equal size must not swap places between
-    # runs, and the signature is the only thing about them that cannot vary
+    # size first, then the signature: two clusters of equal size must not swap places between runs
     large.sort(key=lambda cluster: (-cluster.size, cluster.signature))
     return large
 
@@ -479,21 +470,18 @@ def render(
         lines.append(f"{collect_errors} collection error{'' if one else 's'}, not counted below")
     for cluster, where in zip(shown, _headings(shown), strict=True):
         lines.append(_headline(cluster, where, total_failures))
-        # a cluster keyed on its diagnostic already says the difference in words, and the values under
-        # it are the ones that vary between its failures rather than the thing they share
+        # a cluster keyed on its diagnostic says the difference in words; the values are what varies inside it
         if cluster.signature.label:
             lines.append(f"    {cluster.signature.label}")
         else:
             lines.append(f"    actual:   {_side(cluster.actuals)}")
             lines.append(f"    expected: {_side(cluster.expecteds)}")
     if omitted:
-        # said rather than dropped: five of eleven causes shown silently reads as "these are the
-        # causes".  "more" rather than "smaller", since equal-sized clusters are ordered by signature
+        # said rather than dropped: "five of eleven" silently reads as "these are the causes".  "more" rather
+        # than "smaller", since equal-sized clusters are ordered by signature
         lines.append(f"{len(omitted)} more cluster{'' if len(omitted) == 1 else 's'} not shown")
     covered = len({nodeid for cluster in found for nodeid in cluster.nodeids})
     if covered < total_failures:
-        # what the number measures, rather than "not clustered": two tests that share a difference under
-        # a floor of three are related, and the summary declined to print them, which is not the same as
-        # having found nothing about them
+        # what the number measures, not "not clustered": the summary declined to print a pair under the floor
         lines.append(f"{total_failures - covered} of {total_failures} outside any cluster of {minimum}")
     return lines