assertpy2 2.23.0__tar.gz → 2.25.0__tar.gz

{assertpy2-2.23.0 → assertpy2-2.25.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,22 +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 --pythonversion 3.14 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
 ```
 
-`--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.
+`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:
+### 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.
@@ -68,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.23.0 → assertpy2-2.25.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: assertpy2
-Version: 2.23.0
+Version: 2.25.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
@@ -30,13 +30,13 @@ Requires-Dist: typing-extensions>=4.0; python_version < '3.11'
 Provides-Extra: allure
 Requires-Dist: allure-pytest>=2.13; extra == 'allure'
 Provides-Extra: behave
-Requires-Dist: behave>=1.2.6; extra == 'behave'
+Requires-Dist: behave>=1.3.0; extra == 'behave'
 Provides-Extra: data
 Requires-Dist: numpy>=1.26; extra == 'data'
 Requires-Dist: pandas>=2.0; extra == 'data'
 Requires-Dist: polars>=1.0; extra == 'data'
 Provides-Extra: inline
-Requires-Dist: asttokens>=2.0; extra == 'inline'
+Requires-Dist: asttokens>=2.0.4; extra == 'inline'
 Requires-Dist: executing>=2.2; extra == 'inline'
 Provides-Extra: json
 Requires-Dist: jsonpath-ng>=1.8; extra == 'json'
@@ -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>
@@ -130,7 +130,7 @@ Allure, Behave, JSON Path and Schema, pandas, polars, numpy, and OpenAPI respons
 
 <h2 align="center"><a href="https://solganis.github.io/assertpy2/getting-started/comparison/">Why fluent assertions?</a></h2>
 
-`assert` states a condition well, and pytest reports it well.
+`assert` states a condition well. pytest reports it well.
 
 What it cannot say is *where* two structures differ. It prints both and leaves the reading to you:
 
@@ -154,12 +154,12 @@ 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>
 
-It recurses through nested containers, and matcher predicates get the same treatment.
+It recurses through nested containers. Matcher predicates get the same treatment.
 
 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
+The chain is the other half. Your IDE offers only the
 [methods that fit the value](https://solganis.github.io/assertpy2/concepts/type-safety/).
 
 <!-- docs-guard: skip -->
@@ -169,7 +169,7 @@ 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:
+Nothing is patched, so a matcher can sit inside the expected structure at any depth:
 
 ```python
 response = {"id": 7, "user": {"name": "Alice", "age": 30}, "tags": ["a", "b"]}
@@ -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`, ...
@@ -210,7 +210,7 @@ Your IDE shows only methods relevant to the value you're testing, not all 100+:
 - `assert_that(b"\x89PNG").` &rarr; bytes methods: `starts_with_bytes`, `is_valid_utf8`, `decoded_as`, ...
 
 15 type-specific Protocols instead of one `Any`.<br>
-Works in PyCharm, VS Code, and any LSP-compatible editor.
+Works in PyCharm, VS Code, and any editor that runs a type checker.
 
 <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,
@@ -235,7 +235,7 @@ 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.
+An exception is the right default. Reading the result means catching it.
 
 `check()` runs the next assertion for its verdict instead:
 
@@ -250,11 +250,11 @@ if not outcome and outcome.diff:
 ```
 
 It is truthy when the assertion held. When it did not, it carries `.message`, `.actual`, `.expected`
-and a walkable `.diff`, and so does `AssertionFailure`.
+and a walkable `.diff`. 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.
+[Allure integration](https://solganis.github.io/assertpy2/extending/integrations/#allure) works.
+Anything else you build can too.
 
 <h2 align="center">Features</h2>
 
@@ -262,8 +262,6 @@ 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.
@@ -281,6 +279,7 @@ is open to anything else you build.
 - [**Dict comparison**](https://solganis.github.io/assertpy2/guides/assertions/#selective-comparison-ignore--include): `is_equal_to(ignore=..., include=...)` for selective key/field matching by name, regex, or type.
 - [**Recursive comparison**](https://solganis.github.io/assertpy2/guides/assertions/#recursive-comparison-tolerance--custom-comparators): `is_equal_to()` with `tolerance`, `comparators`, or `ignore_null` for nested structures.
 - [**Extracting**](https://solganis.github.io/assertpy2/guides/assertions/#extracting-attributes-from-objects): flatten collections on attributes with `filter` and `sort` support.
+- [**Regex group extraction**](https://solganis.github.io/assertpy2/guides/data/#regex-group-extraction): `extracting_group()` and `matches_with_groups()` for regex captures.
 
 **Testing**
 
@@ -288,17 +287,28 @@ is open to anything else you build.
 - [**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()`), 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.
+- [**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.
+
+**Failure reporting**
+
 - [**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.
+
+**Plugin for pytest**
+
+Set from the command line or from `[tool.pytest.ini_options]`, not from a call.
+
+- [**Failure clustering**](https://solganis.github.io/assertpy2/guides/errors/#what-the-failures-had-in-common): forty failing tests are usually not forty problems. Where three or more differ at the same place, the run ends with a line saying where. On by default, `assertpy2_failure_clusters = "off"` turns it off.
+- [**Diagnostic profiles**](https://solganis.github.io/assertpy2/guides/errors/#configuration): `assertpy2_profile` turns the guards below on in one line. `compatible` (default) leaves them off, `safe` warns, `strict` fails the tests they find. A setting you name yourself still wins.
+- [**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.
 
 **Extensibility**
 
 - [**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.
 
 <h2 align="center"><a href="https://solganis.github.io/assertpy2/extending/integrations/">Integrations</a></h2>
 

{assertpy2-2.23.0 → assertpy2-2.25.0}/README.md

@@ -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>
@@ -78,7 +78,7 @@ Allure, Behave, JSON Path and Schema, pandas, polars, numpy, and OpenAPI respons
 
 <h2 align="center"><a href="https://solganis.github.io/assertpy2/getting-started/comparison/">Why fluent assertions?</a></h2>
 
-`assert` states a condition well, and pytest reports it well.
+`assert` states a condition well. pytest reports it well.
 
 What it cannot say is *where* two structures differ. It prints both and leaves the reading to you:
 
@@ -102,12 +102,12 @@ 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>
 
-It recurses through nested containers, and matcher predicates get the same treatment.
+It recurses through nested containers. Matcher predicates get the same treatment.
 
 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
+The chain is the other half. Your IDE offers only the
 [methods that fit the value](https://solganis.github.io/assertpy2/concepts/type-safety/).
 
 <!-- docs-guard: skip -->
@@ -117,7 +117,7 @@ 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:
+Nothing is patched, so a matcher can sit inside the expected structure at any depth:
 
 ```python
 response = {"id": 7, "user": {"name": "Alice", "age": 30}, "tags": ["a", "b"]}
@@ -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`, ...
@@ -158,7 +158,7 @@ Your IDE shows only methods relevant to the value you're testing, not all 100+:
 - `assert_that(b"\x89PNG").` &rarr; bytes methods: `starts_with_bytes`, `is_valid_utf8`, `decoded_as`, ...
 
 15 type-specific Protocols instead of one `Any`.<br>
-Works in PyCharm, VS Code, and any LSP-compatible editor.
+Works in PyCharm, VS Code, and any editor that runs a type checker.
 
 <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,
@@ -183,7 +183,7 @@ 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.
+An exception is the right default. Reading the result means catching it.
 
 `check()` runs the next assertion for its verdict instead:
 
@@ -198,11 +198,11 @@ if not outcome and outcome.diff:
 ```
 
 It is truthy when the assertion held. When it did not, it carries `.message`, `.actual`, `.expected`
-and a walkable `.diff`, and so does `AssertionFailure`.
+and a walkable `.diff`. 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.
+[Allure integration](https://solganis.github.io/assertpy2/extending/integrations/#allure) works.
+Anything else you build can too.
 
 <h2 align="center">Features</h2>
 
@@ -210,8 +210,6 @@ 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.
@@ -229,6 +227,7 @@ is open to anything else you build.
 - [**Dict comparison**](https://solganis.github.io/assertpy2/guides/assertions/#selective-comparison-ignore--include): `is_equal_to(ignore=..., include=...)` for selective key/field matching by name, regex, or type.
 - [**Recursive comparison**](https://solganis.github.io/assertpy2/guides/assertions/#recursive-comparison-tolerance--custom-comparators): `is_equal_to()` with `tolerance`, `comparators`, or `ignore_null` for nested structures.
 - [**Extracting**](https://solganis.github.io/assertpy2/guides/assertions/#extracting-attributes-from-objects): flatten collections on attributes with `filter` and `sort` support.
+- [**Regex group extraction**](https://solganis.github.io/assertpy2/guides/data/#regex-group-extraction): `extracting_group()` and `matches_with_groups()` for regex captures.
 
 **Testing**
 
@@ -236,17 +235,28 @@ is open to anything else you build.
 - [**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()`), 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.
+- [**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.
+
+**Failure reporting**
+
 - [**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.
+
+**Plugin for pytest**
+
+Set from the command line or from `[tool.pytest.ini_options]`, not from a call.
+
+- [**Failure clustering**](https://solganis.github.io/assertpy2/guides/errors/#what-the-failures-had-in-common): forty failing tests are usually not forty problems. Where three or more differ at the same place, the run ends with a line saying where. On by default, `assertpy2_failure_clusters = "off"` turns it off.
+- [**Diagnostic profiles**](https://solganis.github.io/assertpy2/guides/errors/#configuration): `assertpy2_profile` turns the guards below on in one line. `compatible` (default) leaves them off, `safe` warns, `strict` fails the tests they find. A setting you name yourself still wins.
+- [**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.
 
 **Extensibility**
 
 - [**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.
 
 <h2 align="center"><a href="https://solganis.github.io/assertpy2/extending/integrations/">Integrations</a></h2>
 

{assertpy2-2.23.0 → assertpy2-2.25.0}/assertpy2/_clustering.py

@@ -188,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, so `set()` and the `frozenset()` it equals
-            # read apart
+            # 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())
@@ -287,8 +286,7 @@ def is_well_formed(key: Signature) -> bool:
         )
     if key.steps:
         return False
-    # 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
+    # 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
@@ -327,8 +325,7 @@ def clusters(
     """
     if total_failures <= 0:
         return []
-    # keyed on the node id: `pytest-rerunfailures` reports one test failing per retry, and counting attempts 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]] = {}
@@ -473,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