assertpy2 2.24.0__tar.gz → 2.26.0__tar.gz

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

@@ -25,7 +25,7 @@ Read more about how pulls work on GitHub's [About pull requests](https://help.gi
 
 ## Before you change a public signature
 
-Read [ARCHITECTURE.md](ARCHITECTURE.md). Four files under `assertpy2/_engine/` are generated, the public
+Read [ARCHITECTURE.md](ARCHITECTURE.md). Five 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
@@ -86,15 +86,16 @@ Run these after the main gate, not before. `uv run --group typecheck` adds the c
 
 ```bash
 uv run --group typecheck mypy --strict --follow-imports=silent tests/test_typing.py
-PYRIGHT_PYTHON_FORCE_VERSION=1.1.413 uv run --group typecheck pyright --pythonversion 3.14 tests/test_typing.py
+PYRIGHT_PYTHON_FORCE_VERSION=1.1.414 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
 ```
 
 `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.
+PyPI is released separately from the npm engine it launches, and the two have drifted apart before: PyPI
+stayed at 1.1.411 from June to September while npm shipped two builds. 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
@@ -123,9 +124,11 @@ Write tests for every new feature or bug fix. Use `assertpy2` assertions in test
 
 ## Documentation examples
 
-Guide code blocks are executed and type-checked in CI, so an example you add has to run. A block that
+Guide code blocks are type-checked in CI, and every page that can run in the suite is executed, with what
+each block prints compared with the comment beside it, 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.
+above the fence. `tests/test_docs_examples.py` lists the markers and what each one exempts, and it and
+`tests/test_docs_typing.py` each name the pages they leave out, with the reason.
 
 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.24.0 → assertpy2-2.26.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: assertpy2
-Version: 2.24.0
+Version: 2.26.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'
@@ -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"]}
@@ -210,7 +210,7 @@ Your IDE shows only methods relevant to the value you're testing, not the whole
 - `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>
 
@@ -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.24.0 → assertpy2-2.26.0}/README.md

@@ -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"]}
@@ -158,7 +158,7 @@ Your IDE shows only methods relevant to the value you're testing, not the whole
 - `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>
 
@@ -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.24.0 → assertpy2-2.26.0}/assertpy2/__init__.py

@@ -35,7 +35,7 @@ from .matchers import (
     register_matcher,
     unregister_matcher,
 )
-from .outcome import AssertionOutcome
+from .outcome import AssertionOutcome, Requirement
 from .snapshot import (
     SnapshotCreatedWarning,
     SnapshotKeyReusedWarning,
@@ -57,6 +57,7 @@ __all__ = [
     "NegatedBuilder",
     "PollSample",
     "PollTrace",
+    "Requirement",
     "SnapshotCreatedWarning",
     "SnapshotKeyReusedWarning",
     "SnapshotUpdatedWarning",

{assertpy2-2.24.0 → assertpy2-2.26.0}/assertpy2/_engine/_builder_check_typing.py

@@ -26,7 +26,15 @@ if TYPE_CHECKING:
     from .._matcher_impls import ClassInfo
     from ..matchers import Matcher
     from ..outcome import AssertionOutcome
-    from ._capable_typing import _Callable, _Orderable, _PathLike
+    from ._capable_typing import (
+        _Callable,
+        _Indexed,
+        _Keyed,
+        _KeyedWithItems,
+        _KeyedWithValues,
+        _Orderable,
+        _PathLike,
+    )
     from ._introspection import MappingLike
     from ._typing import (
         _U,
@@ -551,6 +559,53 @@ if TYPE_CHECKING:
 
         def matches_with_groups(self: _CheckAnyValue[str], pattern: str) -> AssertionOutcome: ...
 
+        @overload
+        def exists(self: _CheckAnyValue[str] | _CheckAnyValue[pathlib.Path]) -> AssertionOutcome: ...
+        @overload
+        def exists(self: _CheckAnyValue[_PathLike]) -> AssertionOutcome: ...
+
+        @overload
+        def does_not_exist(self: _CheckAnyValue[str] | _CheckAnyValue[pathlib.Path]) -> AssertionOutcome: ...
+        @overload
+        def does_not_exist(self: _CheckAnyValue[_PathLike]) -> AssertionOutcome: ...
+
+        @overload
+        def is_file(self: _CheckAnyValue[str] | _CheckAnyValue[pathlib.Path]) -> AssertionOutcome: ...
+        @overload
+        def is_file(self: _CheckAnyValue[_PathLike]) -> AssertionOutcome: ...
+
+        @overload
+        def is_directory(self: _CheckAnyValue[str] | _CheckAnyValue[pathlib.Path]) -> AssertionOutcome: ...
+        @overload
+        def is_directory(self: _CheckAnyValue[_PathLike]) -> AssertionOutcome: ...
+
+        @overload
+        def is_named(self: _CheckAnyValue[str] | _CheckAnyValue[pathlib.Path], filename: str) -> AssertionOutcome: ...
+        @overload
+        def is_named(self: _CheckAnyValue[_PathLike], filename: str) -> AssertionOutcome: ...
+
+        @overload
+        def is_child_of(
+            self: _CheckAnyValue[str] | _CheckAnyValue[pathlib.Path], parent: object
+        ) -> AssertionOutcome: ...
+        @overload
+        def is_child_of(self: _CheckAnyValue[_PathLike], parent: object) -> AssertionOutcome: ...
+
+        @overload
+        def is_readable(self: _CheckAnyValue[str] | _CheckAnyValue[pathlib.Path]) -> AssertionOutcome: ...
+        @overload
+        def is_readable(self: _CheckAnyValue[_PathLike]) -> AssertionOutcome: ...
+
+        @overload
+        def is_writable(self: _CheckAnyValue[str] | _CheckAnyValue[pathlib.Path]) -> AssertionOutcome: ...
+        @overload
+        def is_writable(self: _CheckAnyValue[_PathLike]) -> AssertionOutcome: ...
+
+        @overload
+        def is_executable(self: _CheckAnyValue[str] | _CheckAnyValue[pathlib.Path]) -> AssertionOutcome: ...
+        @overload
+        def is_executable(self: _CheckAnyValue[_PathLike]) -> AssertionOutcome: ...
+
         @overload
         def is_subset_of(
             self: _CheckAnyValue[str]
@@ -574,10 +629,11 @@ if TYPE_CHECKING:
             self: _CheckAnyValue[_CapableT], *supersets: object, allow_empty: bool = ...
         ) -> AssertionOutcome: ...
 
+        @overload
+        def contains_duplicates(self: _CheckAnyValue[str]) -> AssertionOutcome: ...
         @overload
         def contains_duplicates(
-            self: _CheckAnyValue[str]
-            | _CheckAnyValue[list[_E]]
+            self: _CheckAnyValue[list[_E]]
             | _CheckAnyValue[tuple[_E, ...]]
             | _CheckAnyValue[set[_E]]
             | _CheckAnyValue[frozenset[_E]],
@@ -585,10 +641,11 @@ if TYPE_CHECKING:
         @overload
         def contains_duplicates(self: _CheckAnyValue[_CapableT]) -> AssertionOutcome: ...
 
+        @overload
+        def does_not_contain_duplicates(self: _CheckAnyValue[str]) -> AssertionOutcome: ...
         @overload
         def does_not_contain_duplicates(
-            self: _CheckAnyValue[str]
-            | _CheckAnyValue[list[_E]]
+            self: _CheckAnyValue[list[_E]]
             | _CheckAnyValue[tuple[_E, ...]]
             | _CheckAnyValue[set[_E]]
             | _CheckAnyValue[frozenset[_E]],
@@ -596,10 +653,11 @@ if TYPE_CHECKING:
         @overload
         def does_not_contain_duplicates(self: _CheckAnyValue[_CapableT]) -> AssertionOutcome: ...
 
+        @overload
+        def contains_only_once(self: _CheckAnyValue[str], *items: object) -> AssertionOutcome: ...
         @overload
         def contains_only_once(
-            self: _CheckAnyValue[str]
-            | _CheckAnyValue[list[_E]]
+            self: _CheckAnyValue[list[_E]]
             | _CheckAnyValue[tuple[_E, ...]]
             | _CheckAnyValue[set[_E]]
             | _CheckAnyValue[frozenset[_E]],
@@ -608,17 +666,20 @@ if TYPE_CHECKING:
         @overload
         def contains_only_once(self: _CheckAnyValue[_CapableT], *items: object) -> AssertionOutcome: ...
 
+        @overload
+        def contains_in_order(self: _CheckAnyValue[str], *items: str | Matcher[str]) -> AssertionOutcome: ...
         @overload
         def contains_in_order(
-            self: _CheckAnyValue[str]
-            | _CheckAnyValue[list[_E]]
+            self: _CheckAnyValue[list[_E]]
             | _CheckAnyValue[tuple[_E, ...]]
             | _CheckAnyValue[set[_E]]
             | _CheckAnyValue[frozenset[_E]],
             *items: _E | Matcher[_E],
         ) -> AssertionOutcome: ...
         @overload
-        def contains_in_order(self: _CheckAnyValue[_CapableT], *items: _E | Matcher[_E]) -> AssertionOutcome: ...
+        def contains_in_order(
+            self: _CheckAnyValue[Iterable[_E] | _Indexed[_E]], *items: _E | Matcher[_E]
+        ) -> AssertionOutcome: ...
 
         @overload
         def has_same_size_as(
@@ -721,53 +782,6 @@ if TYPE_CHECKING:
         @overload
         def is_not_empty(self: _CheckAnyValue[_CapableT]) -> AssertionOutcome: ...
 
-        @overload
-        def exists(self: _CheckAnyValue[str] | _CheckAnyValue[pathlib.Path]) -> AssertionOutcome: ...
-        @overload
-        def exists(self: _CheckAnyValue[_PathLike]) -> AssertionOutcome: ...
-
-        @overload
-        def does_not_exist(self: _CheckAnyValue[str] | _CheckAnyValue[pathlib.Path]) -> AssertionOutcome: ...
-        @overload
-        def does_not_exist(self: _CheckAnyValue[_PathLike]) -> AssertionOutcome: ...
-
-        @overload
-        def is_file(self: _CheckAnyValue[str] | _CheckAnyValue[pathlib.Path]) -> AssertionOutcome: ...
-        @overload
-        def is_file(self: _CheckAnyValue[_PathLike]) -> AssertionOutcome: ...
-
-        @overload
-        def is_directory(self: _CheckAnyValue[str] | _CheckAnyValue[pathlib.Path]) -> AssertionOutcome: ...
-        @overload
-        def is_directory(self: _CheckAnyValue[_PathLike]) -> AssertionOutcome: ...
-
-        @overload
-        def is_named(self: _CheckAnyValue[str] | _CheckAnyValue[pathlib.Path], filename: str) -> AssertionOutcome: ...
-        @overload
-        def is_named(self: _CheckAnyValue[_PathLike], filename: str) -> AssertionOutcome: ...
-
-        @overload
-        def is_child_of(
-            self: _CheckAnyValue[str] | _CheckAnyValue[pathlib.Path], parent: object
-        ) -> AssertionOutcome: ...
-        @overload
-        def is_child_of(self: _CheckAnyValue[_PathLike], parent: object) -> AssertionOutcome: ...
-
-        @overload
-        def is_readable(self: _CheckAnyValue[str] | _CheckAnyValue[pathlib.Path]) -> AssertionOutcome: ...
-        @overload
-        def is_readable(self: _CheckAnyValue[_PathLike]) -> AssertionOutcome: ...
-
-        @overload
-        def is_writable(self: _CheckAnyValue[str] | _CheckAnyValue[pathlib.Path]) -> AssertionOutcome: ...
-        @overload
-        def is_writable(self: _CheckAnyValue[_PathLike]) -> AssertionOutcome: ...
-
-        @overload
-        def is_executable(self: _CheckAnyValue[str] | _CheckAnyValue[pathlib.Path]) -> AssertionOutcome: ...
-        @overload
-        def is_executable(self: _CheckAnyValue[_PathLike]) -> AssertionOutcome: ...
-
         @overload
         def is_positive(
             self: _CheckAnyValue[bool] | _CheckAnyValue[int] | _CheckAnyValue[float],
@@ -906,29 +920,33 @@ if TYPE_CHECKING:
         @overload
         def contains_key(self: _CheckAnyValue[dict[_K, _V]], *keys: _K | Matcher[_K]) -> AssertionOutcome: ...
         @overload
-        def contains_key(self: _CheckAnyValue[_CapableT], *keys: _K | Matcher[_K]) -> AssertionOutcome: ...
+        def contains_key(self: _CheckAnyValue[_Keyed], *keys: _K | Matcher[_K]) -> AssertionOutcome: ...
 
         @overload
         def does_not_contain_key(self: _CheckAnyValue[dict[_K, _V]], *keys: _K | Matcher[_K]) -> AssertionOutcome: ...
         @overload
-        def does_not_contain_key(self: _CheckAnyValue[_CapableT], *keys: _K | Matcher[_K]) -> AssertionOutcome: ...
+        def does_not_contain_key(self: _CheckAnyValue[_Keyed], *keys: _K | Matcher[_K]) -> AssertionOutcome: ...
 
         @overload
         def contains_value(self: _CheckAnyValue[dict[_K, _V]], *values: _V | Matcher[_V]) -> AssertionOutcome: ...
         @overload
-        def contains_value(self: _CheckAnyValue[_CapableT], *values: _V | Matcher[_V]) -> AssertionOutcome: ...
+        def contains_value(self: _CheckAnyValue[_KeyedWithValues], *values: _V | Matcher[_V]) -> AssertionOutcome: ...
 
         @overload
         def does_not_contain_value(
             self: _CheckAnyValue[dict[_K, _V]], *values: _V | Matcher[_V]
         ) -> AssertionOutcome: ...
         @overload
-        def does_not_contain_value(self: _CheckAnyValue[_CapableT], *values: _V | Matcher[_V]) -> AssertionOutcome: ...
+        def does_not_contain_value(
+            self: _CheckAnyValue[_KeyedWithValues], *values: _V | Matcher[_V]
+        ) -> AssertionOutcome: ...
 
         @overload
         def contains_entry(self: _CheckAnyValue[dict[_K, _V]], *args: object, **kwargs: object) -> AssertionOutcome: ...
         @overload
-        def contains_entry(self: _CheckAnyValue[_CapableT], *args: object, **kwargs: object) -> AssertionOutcome: ...
+        def contains_entry(
+            self: _CheckAnyValue[_KeyedWithItems], *args: object, **kwargs: object
+        ) -> AssertionOutcome: ...
 
         @overload
         def does_not_contain_entry(
@@ -936,7 +954,7 @@ if TYPE_CHECKING:
         ) -> AssertionOutcome: ...
         @overload
         def does_not_contain_entry(
-            self: _CheckAnyValue[_CapableT], *args: object, **kwargs: object
+            self: _CheckAnyValue[_KeyedWithItems], *args: object, **kwargs: object
         ) -> AssertionOutcome: ...
 
         @overload