assertpy2 2.20.1__tar.gz → 2.22.0__tar.gz

assertpy2-2.22.0/CONTRIBUTING.md

@@ -0,0 +1,83 @@
+# Contributing
+
+Contributions of docs, tests, or code are welcome.
+
+## Workflow
+
+1. For a new assertion or matcher, open an issue first. The API grows from demand, and a working
+   implementation on its own is not enough to land one
+2. Fork the repo
+3. Clone your fork (`git clone <your_fork_url>`)
+4. Create a branch (`git checkout -b my_branch`)
+5. Install dependencies with the [one sync command](#verification-pipeline) below, not a bare `uv sync`
+6. Make your changes
+7. Run the [verification pipeline](#verification-pipeline) and fix any issues
+8. Commit using [Conventional Commits](#commit-style)
+9. Push your branch (`git push origin my_branch`)
+10. Open a [Pull Request](http://github.com/Solganis/assertpy2/pulls)
+
+Read more about how pulls work on GitHub's [About pull requests](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests) page.
+
+## Requirements
+
+- Python 3.10+
+- [uv](https://docs.astral.sh/uv/) as the package manager
+
+## 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:
+
+```bash
+uv sync --extra json --extra data --extra inline --group integrations --group docs-examples
+```
+
+```bash
+uv run ruff check .
+uv run ruff format --check .
+uv run ty check assertpy2/ tests/test_typing.py
+uv run pytest --cov=assertpy2 --cov-fail-under=100 --ignore=tests/test_docs_examples.py tests
+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:
+
+```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 pytest tests/test_pyright_baseline.py
+```
+
+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.
+- `--all-extras` is not a shortcut for the sync line. Installing `allure` or `behave` makes 100%
+  coverage unreachable by construction, because the `except ImportError` branch guarding them stops
+  being executed. CI never installs them for the coverage job either.
+- `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.
+
+## Tests
+
+Write tests for every new feature or bug fix. Use `assertpy2` assertions in tests.
+
+## Documentation examples
+
+Guide code blocks are executed and type-checked in CI, so an example you add has to run. A block that
+cannot (pseudo-context, a deliberate failure, a rejected counter-example) is marked with an HTML comment
+above the fence: `tests/test_docs_examples.py` lists the markers and what each one exempts.
+
+Setup a page assumes (a domain class, a repository, an HTTP response) goes in
+`tests/docs_fixtures.py`, not into an extra block on the page.

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

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: assertpy2
-Version: 2.20.1
+Version: 2.22.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>The fully-typed fluent assertion library for Python</b><br>
+  <b>A 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>
 
@@ -95,23 +95,44 @@ def test_user():
 
 The [full documentation](https://solganis.github.io/assertpy2/) covers every assertion, matcher, and integration.
 
-<h2 align="center"><a href="https://solganis.github.io/assertpy2/getting-started/comparison/">Why fluent assertions?</a></h2>
-
-A fluent chain reads as one intent and replaces several bare asserts -<br>
-and your IDE offers only the [methods that fit the value's type](https://solganis.github.io/assertpy2/concepts/type-safety/):
+<table>
+<tr>
+<td valign="top" width="50%">
+<a href="#why-fluent-assertions"><b>Failures that point at the difference</b></a><br>
+A recursive diff names the exact path that differs, in color, instead of dumping both structures.
+</td>
+<td valign="top" width="50%">
+<a href="#type-aware-autocomplete"><b>Type-aware autocomplete</b></a><br>
+<code>assert_that()</code> returns a protocol per value type, so your IDE offers the methods that fit.
+</td>
+</tr>
+<tr>
+<td valign="top">
+<a href="#typed-narrowing"><b>Typed narrowing</b></a><br>
+An assertion hands the value back statically narrowed, with no <code>cast</code> and no bare <code>assert</code>.
+</td>
+<td valign="top">
+<a href="#features"><b>Composable matchers</b></a><br>
+45 matchers that combine with <code>&amp;</code>, <code>|</code>, <code>~</code> and nest inside the expected structure itself.
+</td>
+</tr>
+<tr>
+<td valign="top">
+<a href="#features"><b>Built for test suites</b></a><br>
+Soft assertions, polling for eventual consistency, snapshots, and expected-exception chains.
+</td>
+<td valign="top">
+<a href="#integrations"><b>Integrations</b></a><br>
+Allure, Behave, JSON Path and Schema, pandas, polars, numpy, and OpenAPI response contracts.
+</td>
+</tr>
+</table>
 
-<!-- docs-guard: skip -->
-```python
-# bare - three statements, no autocomplete help
-assert isinstance(items, list)
-assert len(items) == 3
-assert "admin" in items
+<h2 align="center"><a href="https://solganis.github.io/assertpy2/getting-started/comparison/">Why fluent assertions?</a></h2>
 
-# assertpy2 - one chain, type-aware autocomplete
-assert_that(items).is_instance_of(list).is_length(3).contains("admin")
-```
+`assert` states a condition well, and pytest reports it well.
 
-The real difference shows up on failure. Plain `assert` dumps both structures and leaves you to find the two wrong fields:
+What it cannot say is *where* two structures differ. It prints both and leaves the reading to you:
 
 ```text
 assert response == expected
@@ -122,7 +143,7 @@ E     {'user': {'name': 'Alice', 'role': 'superadmin'}} != {'user': {'name': 'Al
 E     {'status': 'active'} != {'status': 'disabled'}
 ```
 
-assertpy2 reports the [exact path to every difference](https://solganis.github.io/assertpy2/guides/errors/#rich-pytest-diffs), in color:
+assertpy2 names the [exact path](https://solganis.github.io/assertpy2/guides/errors/#rich-pytest-diffs), in color:
 
 <!-- docs-guard: skip -->
 ```python
@@ -133,24 +154,45 @@ assert_that(response).is_equal_to(expected)
   <img src="https://raw.githubusercontent.com/Solganis/assertpy2/main/docs/assets/diff-equal.png" width="300" alt="Structured diff in the terminal: user.role shown with its path, removal in red and addition in green">
 </p>
 
-The diff recurses through nested containers, and matcher predicates get the same path-level treatment. For dynamic fields like IDs or timestamps, assert a subset with [`matches_structure()`](https://solganis.github.io/assertpy2/guides/matchers/#structural-matching).
+It recurses through nested containers, and matcher predicates get the same treatment.
 
-Matchers are ordinary values, so they also compose inside the expected structure itself, at any depth,
-with or without the fluent chain:
+For dynamic fields like IDs, assert a subset with
+[`matches_structure()`](https://solganis.github.io/assertpy2/guides/matchers/#structural-matching).
+
+The chain is the other half: one statement carries the whole intent, and your IDE offers only the
+[methods that fit the value](https://solganis.github.io/assertpy2/concepts/type-safety/).
+
+<!-- docs-guard: skip -->
+```python
+assert_that(items).is_instance_of(list).is_length(3).contains("admin")
+```
+
+Matchers are ordinary values that answer `==`, the way `unittest.mock.ANY` does.
+
+Nothing is patched, so a matcher can sit inside the expected structure itself, at any depth:
 
 ```python
 response = {"id": 7, "user": {"name": "Alice", "age": 30}, "tags": ["a", "b"]}
 
 assert_that(response).is_equal_to(
-    {"id": match.greater_than(0), "user": {"name": "Alice", "age": match.between(18, 120)}, "tags": ["a", "b"]}
+    {
+        "id": match.greater_than(0),
+        "user": {"name": "Alice", "age": match.between(18, 120)},
+        "tags": ["a", "b"],
+    }
 )
 
 # or keep the bare `assert`, and pytest's own rewriting reports it
-assert response == {"id": match.greater_than(0), "user": match.ignore(), "tags": ["a", "b"]}
+assert response == {
+    "id": match.greater_than(0),
+    "user": match.ignore(),
+    "tags": ["a", "b"],
+}
 ```
 
-The fluent form keeps the path-level diff, the bare form keeps pytest's. There are
-[39 matchers](https://solganis.github.io/assertpy2/guides/matchers/), and they combine with `&`, `|` and `~`.
+The fluent form keeps the path-level diff, the bare form keeps pytest's.
+
+There are [45 matchers](https://solganis.github.io/assertpy2/guides/matchers/), combining with `&`, `|` and `~`.
 
 <p align="center">
   <img src="https://raw.githubusercontent.com/Solganis/assertpy2/main/docs/assets/diff-gallery.png" width="640" alt="Structured diffs in the terminal: dict path, list element, set extra/missing, and structural-matcher predicate diffs, side by side">
@@ -167,13 +209,14 @@ 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`, ...
 
-9 type-specific Protocols instead of one `Any`.<br>
+11 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>
 
-An assertion hands the value back, statically narrowed. `is_not_none()` strips `None`,
-`is_instance_of()` narrows to the class, and `.value` returns it with no `cast` and no bare `assert`:
+An assertion hands the value back, statically narrowed.
+
+`is_not_none()` strips `None`, `is_instance_of()` narrows to the class, and `.value` returns it:
 
 <!-- docs-guard: skip -->
 ```python
@@ -181,31 +224,52 @@ order = assert_that(repo.find(42)).is_not_none().is_instance_of(PaidOrder).value
 order.refund()  # statically PaidOrder - verified by ty, mypy, and pyright
 ```
 
-For API tests, [`assert_conforms()`](https://solganis.github.io/assertpy2/concepts/type-safety/#contract-narrowing-with-assert_conforms) validates a raw payload against a Pydantic model and narrows the chain to it,<br>
-with `exact=True` catching silent contract drift:
+For API tests,
+[`assert_conforms()`](https://solganis.github.io/assertpy2/concepts/type-safety/#contract-narrowing-with-assert_conforms)
+validates a payload against a Pydantic model and narrows to it. `exact=True` catches contract drift:
 
 <!-- docs-guard: skip -->
 ```python
 data = assert_conforms(response.json(), OrderModel).value  # data: OrderModel
 ```
 
+<h2 align="center"><a href="https://solganis.github.io/assertpy2/guides/errors/#asking-instead-of-asserting">A failure you can read from code</a></h2>
+
+An exception is the right default, and a dead end for anything that wants to read the result.
+
+`check()` runs the next assertion for its verdict instead:
+
+```python
+response = {"user": {"name": "Alice", "role": "superadmin"}, "status": "active"}
+expected = {"user": {"name": "Alice", "role": "admin"}, "status": "active"}
+
+outcome = assert_that(response).check().is_equal_to(expected)
+
+if not outcome and outcome.diff:
+    print(outcome.diff.entries[0].path)  # user.role
+```
+
+It is truthy when the assertion held. When it did not, it carries `.message`, `.actual`, `.expected`
+and a walkable `.diff`, and so does `AssertionFailure`.
+
+So a reporter reads structure instead of parsing a string. That is how the
+[Allure integration](https://solganis.github.io/assertpy2/extending/integrations/#allure) works, and it
+is open to anything else you build.
+
 <h2 align="center">Features</h2>
 
 **Fluent API**
 
-- [**Composable matchers**](https://solganis.github.io/assertpy2/guides/matchers/): `match.greater_than(5)`, `match.is_uuid()`, combine with `&`, `|`, `~`, usable in plain `assert ==`.
 - [**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.
 - [**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.
-- [**Fluent chaining**](https://solganis.github.io/assertpy2/guides/fluent/#chaining): chain assertions into readable one-liners.
 
 **Type safety**
 
-- [**Type-aware autocomplete**](https://solganis.github.io/assertpy2/concepts/type-safety/): 9 Protocols, IDE shows only relevant methods per type.
-- [**Typed narrowing**](https://solganis.github.io/assertpy2/concepts/type-safety/#typed-narrowing-with-value): `.value` hands the checked value back, statically narrowed by `is_not_none()`, `is_instance_of()`, and a [`satisfies()` `TypeIs` predicate](https://solganis.github.io/assertpy2/concepts/type-safety/#refinement-narrowing-with-a-typeis-predicate-advanced).
+- [**Refinement predicates**](https://solganis.github.io/assertpy2/concepts/type-safety/#refinement-narrowing-with-a-typeis-predicate-advanced): `satisfies()` takes a `TypeIs` predicate, so a domain check narrows the chain too.
 - [**Contract testing**](https://solganis.github.io/assertpy2/concepts/type-safety/#contract-narrowing-with-assert_conforms): `assert_conforms()` validates a raw payload against a Pydantic model and narrows to it. [`exact=True`](https://solganis.github.io/assertpy2/concepts/type-safety/#contract-drift-with-exacttrue) catches contract drift, `each=True` validates list endpoints.
 
 **Built-in types**
@@ -221,18 +285,19 @@ data = assert_conforms(response.json(), OrderModel).value  # data: OrderModel
 
 - [**Soft assertions**](https://solganis.github.io/assertpy2/guides/testing/#soft-assertions): thread-safe and async-safe via `contextvars`, each failure reported with its `file:line`. Group with `sa.group()` or `assert_all()`.
 - [**Polling assertions**](https://solganis.github.io/assertpy2/guides/testing/#async-assertions): `eventually()` (async) / `eventually_sync()` (blocking) retry for eventual consistency, with a convergence trace on timeout.
-- [**Expected exceptions**](https://solganis.github.io/assertpy2/guides/errors/#expected-exceptions): `raises().when_called_with()`, walk the cause chain (`caused_by()`, `has_root_cause()`), match `ExceptionGroup` (`contains_error()`), or pivot to the object (`raised()`).
-- [**Structured errors**](https://solganis.github.io/assertpy2/guides/errors/#structured-errors): `AssertionFailure` carries `.actual`, `.expected`, `.diff`, and the diff renders into the message itself, so it shows off pytest too.
-- [**Assertions as values**](https://solganis.github.io/assertpy2/guides/errors/#asking-instead-of-asserting): `check()` runs the next assertion for its verdict instead of raising, returning an `AssertionOutcome` that is truthy when it held and carries the message, values and diff when it did not.
-- [**Rich pytest diffs**](https://solganis.github.io/assertpy2/guides/errors/#rich-pytest-diffs): recursive structural diffs across containers, dataclasses, attrs, and Pydantic models, with intra-line carets for strings and circular-reference protection.
-- [**Snapshot testing**](https://solganis.github.io/assertpy2/guides/testing/#snapshot-testing): three modes under one typed API, all updated with `--assertpy2-snapshot-update`: `snapshot()` (external JSON file), [`matches_inline()`](https://solganis.github.io/assertpy2/guides/testing/#inline-snapshots) (recorded into the test source), and [`matches_contract_snapshot()`](https://solganis.github.io/assertpy2/guides/testing/#contract-snapshots) (value-tolerant structural regressions).
-- [**OpenAPI response contracts**](https://solganis.github.io/assertpy2/reference/json/#assertpy2.json_mixin.JsonMixin.conforms_to_openapi): `conforms_to_openapi(spec, path, method)` validates a JSON response body against an operation's response schema (OpenAPI 3.0/3.1 and Swagger 2.0), reporting every violation with its JSON path.
+- [**Expected exceptions**](https://solganis.github.io/assertpy2/guides/errors/#expected-exceptions): `raises().when_called_with()`, walk the cause chain (`caused_by()`, `has_root_cause()`), search an `ExceptionGroup` (`contains_error()`, `errors()`, `error_of()`), or pivot to the object (`raised()`).
+- [**HTTP responses**](https://solganis.github.io/assertpy2/recipes/#test-an-http-api-response): assert on the response itself and every failure names the request it came from, with `decoded_as_json()` to step into the body. No client library is a dependency.
+- [**Structured errors**](https://solganis.github.io/assertpy2/guides/errors/#structured-errors): `AssertionFailure` carries `.actual`, `.expected` and `.diff`, and the diff renders into the message, so it shows off pytest too.
+- [**Assertions as values**](https://solganis.github.io/assertpy2/guides/errors/#asking-instead-of-asserting): `check()` runs the next assertion for its verdict instead of raising, handing back an `AssertionOutcome`.
+- [**Rich pytest diffs**](https://solganis.github.io/assertpy2/guides/errors/#rich-pytest-diffs): recursive diffs across containers, dataclasses, attrs and Pydantic models, with intra-line carets for strings.
+- [**Snapshot testing**](https://solganis.github.io/assertpy2/guides/testing/#snapshot-testing): an external JSON file, an [inline](https://solganis.github.io/assertpy2/guides/testing/#inline-snapshots) value recorded into the test source, or a [value-tolerant contract](https://solganis.github.io/assertpy2/guides/testing/#contract-snapshots), all updated with `--assertpy2-snapshot-update`.
+- [**OpenAPI response contracts**](https://solganis.github.io/assertpy2/reference/json/#assertpy2.json_mixin.JsonMixin.conforms_to_openapi): `conforms_to_openapi()` checks a JSON body against an operation's response schema, reporting every violation with its JSON path.
 
 **Extensibility**
 
-- [**Custom matchers**](https://solganis.github.io/assertpy2/guides/matchers/#custom-matchers): `register_matcher()` to compose existing ones, or subclass `BaseMatcher` for a rule that needs its own predicate. Both compose with `&`, `|`, `~`.
+- [**Custom matchers**](https://solganis.github.io/assertpy2/guides/matchers/#custom-matchers): `register_matcher()` composes existing ones, `BaseMatcher` carries its own predicate. Both compose with `&`, `|`, `~`.
+- [**Custom assertions**](https://solganis.github.io/assertpy2/extending/custom-assertions/): `add_extension()` adds a method to the builder.
 - [**Regex group extraction**](https://solganis.github.io/assertpy2/guides/data/#regex-group-extraction): `extracting_group()` and `matches_with_groups()` for regex captures.
-- [**Extensions**](https://solganis.github.io/assertpy2/extending/custom-assertions/): `add_extension()` for custom assertion methods.
 
 <h2 align="center"><a href="https://solganis.github.io/assertpy2/extending/integrations/">Integrations</a></h2>
 

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

@@ -5,7 +5,7 @@
     <img src="docs/logo.svg" alt="assertpy2" width="280">
   </picture>
   <br>
-  <b>The fully-typed fluent assertion library for Python</b><br>
+  <b>A 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>
 
@@ -43,23 +43,44 @@ def test_user():
 
 The [full documentation](https://solganis.github.io/assertpy2/) covers every assertion, matcher, and integration.
 
-<h2 align="center"><a href="https://solganis.github.io/assertpy2/getting-started/comparison/">Why fluent assertions?</a></h2>
-
-A fluent chain reads as one intent and replaces several bare asserts -<br>
-and your IDE offers only the [methods that fit the value's type](https://solganis.github.io/assertpy2/concepts/type-safety/):
+<table>
+<tr>
+<td valign="top" width="50%">
+<a href="#why-fluent-assertions"><b>Failures that point at the difference</b></a><br>
+A recursive diff names the exact path that differs, in color, instead of dumping both structures.
+</td>
+<td valign="top" width="50%">
+<a href="#type-aware-autocomplete"><b>Type-aware autocomplete</b></a><br>
+<code>assert_that()</code> returns a protocol per value type, so your IDE offers the methods that fit.
+</td>
+</tr>
+<tr>
+<td valign="top">
+<a href="#typed-narrowing"><b>Typed narrowing</b></a><br>
+An assertion hands the value back statically narrowed, with no <code>cast</code> and no bare <code>assert</code>.
+</td>
+<td valign="top">
+<a href="#features"><b>Composable matchers</b></a><br>
+45 matchers that combine with <code>&amp;</code>, <code>|</code>, <code>~</code> and nest inside the expected structure itself.
+</td>
+</tr>
+<tr>
+<td valign="top">
+<a href="#features"><b>Built for test suites</b></a><br>
+Soft assertions, polling for eventual consistency, snapshots, and expected-exception chains.
+</td>
+<td valign="top">
+<a href="#integrations"><b>Integrations</b></a><br>
+Allure, Behave, JSON Path and Schema, pandas, polars, numpy, and OpenAPI response contracts.
+</td>
+</tr>
+</table>
 
-<!-- docs-guard: skip -->
-```python
-# bare - three statements, no autocomplete help
-assert isinstance(items, list)
-assert len(items) == 3
-assert "admin" in items
+<h2 align="center"><a href="https://solganis.github.io/assertpy2/getting-started/comparison/">Why fluent assertions?</a></h2>
 
-# assertpy2 - one chain, type-aware autocomplete
-assert_that(items).is_instance_of(list).is_length(3).contains("admin")
-```
+`assert` states a condition well, and pytest reports it well.
 
-The real difference shows up on failure. Plain `assert` dumps both structures and leaves you to find the two wrong fields:
+What it cannot say is *where* two structures differ. It prints both and leaves the reading to you:
 
 ```text
 assert response == expected
@@ -70,7 +91,7 @@ E     {'user': {'name': 'Alice', 'role': 'superadmin'}} != {'user': {'name': 'Al
 E     {'status': 'active'} != {'status': 'disabled'}
 ```
 
-assertpy2 reports the [exact path to every difference](https://solganis.github.io/assertpy2/guides/errors/#rich-pytest-diffs), in color:
+assertpy2 names the [exact path](https://solganis.github.io/assertpy2/guides/errors/#rich-pytest-diffs), in color:
 
 <!-- docs-guard: skip -->
 ```python
@@ -81,24 +102,45 @@ assert_that(response).is_equal_to(expected)
   <img src="https://raw.githubusercontent.com/Solganis/assertpy2/main/docs/assets/diff-equal.png" width="300" alt="Structured diff in the terminal: user.role shown with its path, removal in red and addition in green">
 </p>
 
-The diff recurses through nested containers, and matcher predicates get the same path-level treatment. For dynamic fields like IDs or timestamps, assert a subset with [`matches_structure()`](https://solganis.github.io/assertpy2/guides/matchers/#structural-matching).
+It recurses through nested containers, and matcher predicates get the same treatment.
 
-Matchers are ordinary values, so they also compose inside the expected structure itself, at any depth,
-with or without the fluent chain:
+For dynamic fields like IDs, assert a subset with
+[`matches_structure()`](https://solganis.github.io/assertpy2/guides/matchers/#structural-matching).
+
+The chain is the other half: one statement carries the whole intent, and your IDE offers only the
+[methods that fit the value](https://solganis.github.io/assertpy2/concepts/type-safety/).
+
+<!-- docs-guard: skip -->
+```python
+assert_that(items).is_instance_of(list).is_length(3).contains("admin")
+```
+
+Matchers are ordinary values that answer `==`, the way `unittest.mock.ANY` does.
+
+Nothing is patched, so a matcher can sit inside the expected structure itself, at any depth:
 
 ```python
 response = {"id": 7, "user": {"name": "Alice", "age": 30}, "tags": ["a", "b"]}
 
 assert_that(response).is_equal_to(
-    {"id": match.greater_than(0), "user": {"name": "Alice", "age": match.between(18, 120)}, "tags": ["a", "b"]}
+    {
+        "id": match.greater_than(0),
+        "user": {"name": "Alice", "age": match.between(18, 120)},
+        "tags": ["a", "b"],
+    }
 )
 
 # or keep the bare `assert`, and pytest's own rewriting reports it
-assert response == {"id": match.greater_than(0), "user": match.ignore(), "tags": ["a", "b"]}
+assert response == {
+    "id": match.greater_than(0),
+    "user": match.ignore(),
+    "tags": ["a", "b"],
+}
 ```
 
-The fluent form keeps the path-level diff, the bare form keeps pytest's. There are
-[39 matchers](https://solganis.github.io/assertpy2/guides/matchers/), and they combine with `&`, `|` and `~`.
+The fluent form keeps the path-level diff, the bare form keeps pytest's.
+
+There are [45 matchers](https://solganis.github.io/assertpy2/guides/matchers/), combining with `&`, `|` and `~`.
 
 <p align="center">
   <img src="https://raw.githubusercontent.com/Solganis/assertpy2/main/docs/assets/diff-gallery.png" width="640" alt="Structured diffs in the terminal: dict path, list element, set extra/missing, and structural-matcher predicate diffs, side by side">
@@ -115,13 +157,14 @@ 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`, ...
 
-9 type-specific Protocols instead of one `Any`.<br>
+11 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>
 
-An assertion hands the value back, statically narrowed. `is_not_none()` strips `None`,
-`is_instance_of()` narrows to the class, and `.value` returns it with no `cast` and no bare `assert`:
+An assertion hands the value back, statically narrowed.
+
+`is_not_none()` strips `None`, `is_instance_of()` narrows to the class, and `.value` returns it:
 
 <!-- docs-guard: skip -->
 ```python
@@ -129,31 +172,52 @@ order = assert_that(repo.find(42)).is_not_none().is_instance_of(PaidOrder).value
 order.refund()  # statically PaidOrder - verified by ty, mypy, and pyright
 ```
 
-For API tests, [`assert_conforms()`](https://solganis.github.io/assertpy2/concepts/type-safety/#contract-narrowing-with-assert_conforms) validates a raw payload against a Pydantic model and narrows the chain to it,<br>
-with `exact=True` catching silent contract drift:
+For API tests,
+[`assert_conforms()`](https://solganis.github.io/assertpy2/concepts/type-safety/#contract-narrowing-with-assert_conforms)
+validates a payload against a Pydantic model and narrows to it. `exact=True` catches contract drift:
 
 <!-- docs-guard: skip -->
 ```python
 data = assert_conforms(response.json(), OrderModel).value  # data: OrderModel
 ```
 
+<h2 align="center"><a href="https://solganis.github.io/assertpy2/guides/errors/#asking-instead-of-asserting">A failure you can read from code</a></h2>
+
+An exception is the right default, and a dead end for anything that wants to read the result.
+
+`check()` runs the next assertion for its verdict instead:
+
+```python
+response = {"user": {"name": "Alice", "role": "superadmin"}, "status": "active"}
+expected = {"user": {"name": "Alice", "role": "admin"}, "status": "active"}
+
+outcome = assert_that(response).check().is_equal_to(expected)
+
+if not outcome and outcome.diff:
+    print(outcome.diff.entries[0].path)  # user.role
+```
+
+It is truthy when the assertion held. When it did not, it carries `.message`, `.actual`, `.expected`
+and a walkable `.diff`, and so does `AssertionFailure`.
+
+So a reporter reads structure instead of parsing a string. That is how the
+[Allure integration](https://solganis.github.io/assertpy2/extending/integrations/#allure) works, and it
+is open to anything else you build.
+
 <h2 align="center">Features</h2>
 
 **Fluent API**
 
-- [**Composable matchers**](https://solganis.github.io/assertpy2/guides/matchers/): `match.greater_than(5)`, `match.is_uuid()`, combine with `&`, `|`, `~`, usable in plain `assert ==`.
 - [**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.
 - [**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.
-- [**Fluent chaining**](https://solganis.github.io/assertpy2/guides/fluent/#chaining): chain assertions into readable one-liners.
 
 **Type safety**
 
-- [**Type-aware autocomplete**](https://solganis.github.io/assertpy2/concepts/type-safety/): 9 Protocols, IDE shows only relevant methods per type.
-- [**Typed narrowing**](https://solganis.github.io/assertpy2/concepts/type-safety/#typed-narrowing-with-value): `.value` hands the checked value back, statically narrowed by `is_not_none()`, `is_instance_of()`, and a [`satisfies()` `TypeIs` predicate](https://solganis.github.io/assertpy2/concepts/type-safety/#refinement-narrowing-with-a-typeis-predicate-advanced).
+- [**Refinement predicates**](https://solganis.github.io/assertpy2/concepts/type-safety/#refinement-narrowing-with-a-typeis-predicate-advanced): `satisfies()` takes a `TypeIs` predicate, so a domain check narrows the chain too.
 - [**Contract testing**](https://solganis.github.io/assertpy2/concepts/type-safety/#contract-narrowing-with-assert_conforms): `assert_conforms()` validates a raw payload against a Pydantic model and narrows to it. [`exact=True`](https://solganis.github.io/assertpy2/concepts/type-safety/#contract-drift-with-exacttrue) catches contract drift, `each=True` validates list endpoints.
 
 **Built-in types**
@@ -169,18 +233,19 @@ data = assert_conforms(response.json(), OrderModel).value  # data: OrderModel
 
 - [**Soft assertions**](https://solganis.github.io/assertpy2/guides/testing/#soft-assertions): thread-safe and async-safe via `contextvars`, each failure reported with its `file:line`. Group with `sa.group()` or `assert_all()`.
 - [**Polling assertions**](https://solganis.github.io/assertpy2/guides/testing/#async-assertions): `eventually()` (async) / `eventually_sync()` (blocking) retry for eventual consistency, with a convergence trace on timeout.
-- [**Expected exceptions**](https://solganis.github.io/assertpy2/guides/errors/#expected-exceptions): `raises().when_called_with()`, walk the cause chain (`caused_by()`, `has_root_cause()`), match `ExceptionGroup` (`contains_error()`), or pivot to the object (`raised()`).
-- [**Structured errors**](https://solganis.github.io/assertpy2/guides/errors/#structured-errors): `AssertionFailure` carries `.actual`, `.expected`, `.diff`, and the diff renders into the message itself, so it shows off pytest too.
-- [**Assertions as values**](https://solganis.github.io/assertpy2/guides/errors/#asking-instead-of-asserting): `check()` runs the next assertion for its verdict instead of raising, returning an `AssertionOutcome` that is truthy when it held and carries the message, values and diff when it did not.
-- [**Rich pytest diffs**](https://solganis.github.io/assertpy2/guides/errors/#rich-pytest-diffs): recursive structural diffs across containers, dataclasses, attrs, and Pydantic models, with intra-line carets for strings and circular-reference protection.
-- [**Snapshot testing**](https://solganis.github.io/assertpy2/guides/testing/#snapshot-testing): three modes under one typed API, all updated with `--assertpy2-snapshot-update`: `snapshot()` (external JSON file), [`matches_inline()`](https://solganis.github.io/assertpy2/guides/testing/#inline-snapshots) (recorded into the test source), and [`matches_contract_snapshot()`](https://solganis.github.io/assertpy2/guides/testing/#contract-snapshots) (value-tolerant structural regressions).
-- [**OpenAPI response contracts**](https://solganis.github.io/assertpy2/reference/json/#assertpy2.json_mixin.JsonMixin.conforms_to_openapi): `conforms_to_openapi(spec, path, method)` validates a JSON response body against an operation's response schema (OpenAPI 3.0/3.1 and Swagger 2.0), reporting every violation with its JSON path.
+- [**Expected exceptions**](https://solganis.github.io/assertpy2/guides/errors/#expected-exceptions): `raises().when_called_with()`, walk the cause chain (`caused_by()`, `has_root_cause()`), search an `ExceptionGroup` (`contains_error()`, `errors()`, `error_of()`), or pivot to the object (`raised()`).
+- [**HTTP responses**](https://solganis.github.io/assertpy2/recipes/#test-an-http-api-response): assert on the response itself and every failure names the request it came from, with `decoded_as_json()` to step into the body. No client library is a dependency.
+- [**Structured errors**](https://solganis.github.io/assertpy2/guides/errors/#structured-errors): `AssertionFailure` carries `.actual`, `.expected` and `.diff`, and the diff renders into the message, so it shows off pytest too.
+- [**Assertions as values**](https://solganis.github.io/assertpy2/guides/errors/#asking-instead-of-asserting): `check()` runs the next assertion for its verdict instead of raising, handing back an `AssertionOutcome`.
+- [**Rich pytest diffs**](https://solganis.github.io/assertpy2/guides/errors/#rich-pytest-diffs): recursive diffs across containers, dataclasses, attrs and Pydantic models, with intra-line carets for strings.
+- [**Snapshot testing**](https://solganis.github.io/assertpy2/guides/testing/#snapshot-testing): an external JSON file, an [inline](https://solganis.github.io/assertpy2/guides/testing/#inline-snapshots) value recorded into the test source, or a [value-tolerant contract](https://solganis.github.io/assertpy2/guides/testing/#contract-snapshots), all updated with `--assertpy2-snapshot-update`.
+- [**OpenAPI response contracts**](https://solganis.github.io/assertpy2/reference/json/#assertpy2.json_mixin.JsonMixin.conforms_to_openapi): `conforms_to_openapi()` checks a JSON body against an operation's response schema, reporting every violation with its JSON path.
 
 **Extensibility**
 
-- [**Custom matchers**](https://solganis.github.io/assertpy2/guides/matchers/#custom-matchers): `register_matcher()` to compose existing ones, or subclass `BaseMatcher` for a rule that needs its own predicate. Both compose with `&`, `|`, `~`.
+- [**Custom matchers**](https://solganis.github.io/assertpy2/guides/matchers/#custom-matchers): `register_matcher()` composes existing ones, `BaseMatcher` carries its own predicate. Both compose with `&`, `|`, `~`.
+- [**Custom assertions**](https://solganis.github.io/assertpy2/extending/custom-assertions/): `add_extension()` adds a method to the builder.
 - [**Regex group extraction**](https://solganis.github.io/assertpy2/guides/data/#regex-group-extraction): `extracting_group()` and `matches_with_groups()` for regex captures.
-- [**Extensions**](https://solganis.github.io/assertpy2/extending/custom-assertions/): `add_extension()` for custom assertion methods.
 
 <h2 align="center"><a href="https://solganis.github.io/assertpy2/extending/integrations/">Integrations</a></h2>
 

{assertpy2-2.20.1 → assertpy2-2.22.0}/assertpy2/__init__.py

@@ -17,6 +17,7 @@ from .assertpy import (
 from .async_assertions import AsyncAssertionBuilder, SyncAssertionBuilder
 from .errors import (
     AssertionFailure,
+    DanglingAssertionWarning,
     DiffEntry,
     DiffResult,
     PollSample,
@@ -48,6 +49,7 @@ __all__ = [
     "AsyncAssertionBuilder",
     "BaseMatcher",
     "CheckBuilder",
+    "DanglingAssertionWarning",
     "DiffEntry",
     "DiffResult",
     "MatchResult",