assertpy2 2.22.0__tar.gz → 2.23.0__tar.gz

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

@@ -49,10 +49,15 @@ 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
+uv run --group typecheck pyright --pythonversion 3.14 tests/test_typing.py
 uv run --group typecheck pytest tests/test_pyright_baseline.py
 ```
 
+`--pythonversion 3.14` is not decoration. Pyright reports against the interpreter it finds unless told
+otherwise, and the count moves with it: 108 diagnostics for this package on 3.10 against 102 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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: assertpy2
-Version: 2.22.0
+Version: 2.23.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>
 
@@ -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>
@@ -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.23.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>
 
@@ -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>
@@ -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.23.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,8 @@ 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`, since `{}` 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 +287,8 @@ 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
+    # exactly one of the two: a pair of values only for the kinds whose fields hold them, or a `contains` payload
+    # would print the `None` standing for a missing item
     if key.label:
         return not key.values
     return len(key.values) == 2 and key.where in _VALUES_ARE_VALUES
@@ -330,17 +327,15 @@ 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` reports one test failing per retry, and counting attempts 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 +348,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
 

{assertpy2-2.22.0 → assertpy2-2.23.0}/assertpy2/_dangling.py

@@ -18,11 +18,21 @@ runtime and cannot shift a frame.
 What it deliberately does not flag:
 
 * a builder bound to a name (`b = assert_that(x)`), because whether `b` is used later is not a
-  question about this statement;
-* a chain that ends on a pivot (`.described_as(...)`, `.extracting(...)`), because the set of
-  assertions is a runtime property of the builder and hard-coding it here would rot;
+  question about this statement, and ruff's F841 answers it when the answer is never;
 * `assert_conforms()`, `fail()`, `soft_fail()`, which assert on their own rather than returning a
   builder, so a bare call to them is correct usage.
+
+A chain ending on a pivot or a configurer is the same defect wearing a longer tail:
+``assert_that(load).raises(ValueError)`` never calls anything, and ``assert_that(rows).extracting("id")``
+throws the extracted value away.  Both were left out while the set of operations that reach no verdict
+was only a runtime property; `assertpy2/_engine/_operations.py` states it now, and a gate keeps it in
+step with the source, so reading it here cannot rot.
+
+An ``assert`` in front reads the chain instead of discarding it, and a builder and a bound method are
+both truthy, so ``assert assert_that(items).is_empty`` is green on every value.  Neither B018 nor
+coverage sees that one: the value is consumed rather than dropped, and the line does run.  What the
+``assert`` reads is the whole question, since ``assert assert_that(x).val`` tests that value instead,
+and the register names the members that hand it back.
 """
 
 from __future__ import annotations
@@ -32,13 +42,22 @@ import io
 import tokenize
 from typing import TYPE_CHECKING, Final, NamedTuple
 
+from ._engine._operations import (
+    ALSO_ASSERTS,
+    CONFIGURES,
+    DESCRIBES,
+    HANDS_THE_SUBJECT_BACK,
+    POLLS,
+    TRANSFORMS,
+    WITHOUT_A_VERDICT,
+)
+
 if TYPE_CHECKING:
     from collections.abc import Iterator
 
 __tracebackhide__ = True
 
-# the builder factories, and only those: everything else in the package's public surface either
-# asserts by itself or is not an entry point at all
+# the builder factories and only those: everything else either asserts by itself or is not an entry point
 _ENTRY: Final = frozenset({"assert_that", "assert_warn"})
 _PACKAGE: Final = "assertpy2"
 
@@ -58,7 +77,27 @@ A project that registered its own wrapper reads `check(1)` on the offending line
 `assert_that()` there costs a moment of "that is not what my code says" on every finding.
 """
 _NOT_CALLED: Final = "assertion is looked up and never called (missing parentheses)"
+_ENDS_ON: Final = {
+    CONFIGURES: "{name}() only sets an expectation here, and nothing calls it",
+    TRANSFORMS: "{name}() hands back another value here, and nothing asserts on it",
+    DESCRIBES: "{name}() only sets the failure description here, and asserts nothing",
+    POLLS: "{name}() starts a polling chain here, and no assertion follows it",
+}
+"""What to say about a chain ending on an operation that reaches no verdict, one sentence per kind."""
+
+_NO_VERDICT: Final = {name: kind for name, kind in WITHOUT_A_VERDICT.items() if name not in ALSO_ASSERTS}
 _NOT_AWAITED: Final = "eventually() chain is never awaited, so nothing is polled (missing await)"
+_UNDER_ASSERT: Final = "nothing here asserts: assert reads the builder, whose truth says nothing about the value"
+"""What to say about a dangling chain an `assert` reads.
+
+The wrapper turns every shape below into the same defect and a worse one: a builder, a proxy and a
+bound method are all truthy, so the line is green whatever the value is, and it reads as if it
+asserted.  Neither ruff nor coverage sees it, since the value is consumed and the line does run.
+
+The sentence stops at "says nothing" rather than promising the line passes, because a few of the
+builder's own fields are falsy by default and turn the line red instead.  Green or red, neither
+outcome was decided by the value under test.
+"""
 
 
 class Finding(NamedTuple):
@@ -106,9 +145,8 @@ def _rebound(tree: ast.Module) -> frozenset[str]:
             names.add(node.id)
         elif isinstance(node, ast.arg):
             names.add(node.arg)
-        # kept apart from the branch below, whose body is identical: merging them into one `or` is what
-        # ruff asks for and what a type checker then rejects, since `ExceptHandler.name` is `str | None`
-        # and only the separate branch narrows it
+        # merging the identical branches is what ruff asks for and a type checker then rejects, since only the
+        # separate branch narrows `ExceptHandler.name`
         elif isinstance(node, ast.ExceptHandler) and node.name:  # noqa: SIM114
             names.add(node.name)
         elif isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
@@ -181,12 +219,12 @@ def _reaches_entry(node: ast.expr, bindings: _Bindings) -> bool:
             return False
 
 
-def _polls(node: ast.expr) -> bool:
-    """True when an attribute chain calls ``eventually()``, the async one, anywhere along it."""
+def _runs(node: ast.expr, name: str) -> bool:
+    """True when an attribute chain calls *name* anywhere along it."""
     current: ast.expr = node
     while True:
         if isinstance(current, ast.Call):
-            if isinstance(current.func, ast.Attribute) and current.func.attr == "eventually":
+            if isinstance(current.func, ast.Attribute) and current.func.attr == name:
                 return True
             current = current.func
         elif isinstance(current, ast.Attribute):
@@ -195,6 +233,49 @@ def _polls(node: ast.expr) -> bool:
             return False
 
 
+def _tail(node: ast.expr) -> str | None:
+    """The name a statement ends on when that name reaches no verdict, else ``None``."""
+    if isinstance(node, ast.Call) and isinstance(node.func, ast.Attribute) and node.func.attr in _NO_VERDICT:
+        return node.func.attr
+    return None
+
+
+def _reads_a_verdict_field(node: ast.Attribute) -> bool:
+    """Whether the attribute reads a field off a verdict rather than leaving an assertion uncalled.
+
+    Both sit behind `check()` and only the step before them tells them apart: `check().is_empty().passed`
+    reads a field of what the assertion decided, while `check().is_empty` is that assertion with its
+    parentheses missing, which is the shape this whole check exists for.
+    """
+    if not _runs(node, "check") or not isinstance(node.value, ast.Call):
+        return False
+    called = node.value.func
+    return not (isinstance(called, ast.Attribute) and called.attr == "check")
+
+
+def _reads_a_truthy_chain(node: ast.expr, bindings: _Bindings) -> bool:
+    """Whether `assert <node>` reads a chain that decided nothing.
+
+    An attribute handing the subject back is excluded, since `assert assert_that(x).val` tests that
+    value rather than leaving an assertion uncalled, and so is a verdict's own field.  Nothing else is:
+    reading the builder's state asserts as little as reading a method does, and `logger` is truthy on
+    every subject there is.
+
+    A chain ending on a bare `check()` is left alone deliberately.  It is truthy and asserts nothing,
+    but calling it a defect means deciding the name is ours, and a project may register an extension
+    called `check` that asserts by itself.  A read attribute needs no such guess, since nothing was
+    called at all.  Measured before deciding: no bare `check()` under an `assert` in 524 files across
+    this suite, the fixture projects and a consuming framework.
+    """
+    if not _reaches_entry(node, bindings):
+        return False
+    if _entry_call(node, bindings) or _tail(node) or (_runs(node, "eventually") and not _closed(node)):
+        return True
+    if not isinstance(node, ast.Attribute):
+        return False
+    return node.attr not in HANDS_THE_SUBJECT_BACK and not _reads_a_verdict_field(node)
+
+
 def _closed(node: ast.expr) -> bool:
     """True when the statement ends in a bare ``close()``, the discard the chain itself stays quiet about."""
     return (
@@ -206,11 +287,12 @@ def _closed(node: ast.expr) -> bool:
     )
 
 
-def _statements(tree: ast.Module) -> Iterator[tuple[ast.Expr, tuple[str, ...]]]:
-    """Every expression statement with the scope it sits in, as the chain of names around it.
+def _statements(tree: ast.Module) -> Iterator[tuple[ast.Expr | ast.Assert, tuple[str, ...]]]:
+    """Every statement that consumes a builder on the spot, with the scope it sits in.
 
-    An expression statement is the only place a discarded builder can appear: anywhere else the value
-    is bound, passed or returned, and whether *that* asserts is not a question about this statement.
+    Two do.  An expression statement discards the value, and anywhere else it is bound, passed or
+    returned, where whether *that* asserts is not a question about this statement.  An `assert` reads
+    it for its truth, which a builder and a bound method answer the same way whatever the value is.
 
     The scope is a chain rather than one name because a bare name does not identify a test: two classes
     in one file may each define `test_same`, and matching on the name alone handed both findings to
@@ -224,7 +306,7 @@ def _statements(tree: ast.Module) -> Iterator[tuple[ast.Expr, tuple[str, ...]]]:
             if isinstance(child, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
                 stack.append((child, (*scope, child.name)))
             else:
-                if isinstance(child, ast.Expr):
+                if isinstance(child, ast.Expr | ast.Assert):
                     yield child, scope
                 stack.append((child, scope))
 
@@ -247,7 +329,7 @@ def _marked_lines(source: str) -> frozenset[int]:
         return frozenset()
 
 
-def _silenced(statement: ast.Expr, marked: frozenset[int]) -> bool:
+def _silenced(statement: ast.stmt, marked: frozenset[int]) -> bool:
     """Whether the statement carries the marker on any of its own lines.
 
     Every line the statement spans counts, so the marker can sit at the end of a call broken over
@@ -279,6 +361,10 @@ def findings(source: str, path: str, extra_entries: frozenset[str] = frozenset()
     for statement, scope in _statements(tree):
         if _silenced(statement, marked):
             continue
+        if isinstance(statement, ast.Assert):
+            if _reads_a_truthy_chain(statement.test, bindings):
+                found.append(Finding(path, statement.lineno, _UNDER_ASSERT, scope))
+            continue
         value = statement.value
         awaited = isinstance(value, ast.Await)
         while isinstance(value, ast.Await):  # `await assert_that(x).eventually()...` unwraps to the chain
@@ -287,6 +373,8 @@ def findings(source: str, path: str, extra_entries: frozenset[str] = frozenset()
             found.append(Finding(path, statement.lineno, _NO_ASSERTION.format(name=name), scope))
         elif isinstance(value, ast.Attribute) and _reaches_entry(value, bindings):
             found.append(Finding(path, statement.lineno, _NOT_CALLED, scope))
-        elif not awaited and _polls(value) and not _closed(value) and _reaches_entry(value, bindings):
+        elif not awaited and _runs(value, "eventually") and not _closed(value) and _reaches_entry(value, bindings):
             found.append(Finding(path, statement.lineno, _NOT_AWAITED, scope))
+        elif (tail := _tail(value)) and _reaches_entry(value, bindings):
+            found.append(Finding(path, statement.lineno, _ENDS_ON[_NO_VERDICT[tail]].format(name=tail), scope))
     return sorted(found, key=lambda finding: finding.lineno)