assertpy2 2.3.7__tar.gz → 2.4.0__tar.gz

{assertpy2-2.3.7 → assertpy2-2.4.0}/.github/dependabot.yml

@@ -4,6 +4,9 @@ updates:
     directory: "/"
     schedule:
       interval: "weekly"
+    cooldown:
+      default-days: 7
+      semver-major-days: 7
     commit-message:
       prefix: "chore"
 
@@ -11,5 +14,7 @@ updates:
     directory: "/"
     schedule:
       interval: "weekly"
+    cooldown:
+      default-days: 7
     commit-message:
       prefix: "ci"

{assertpy2-2.3.7 → assertpy2-2.4.0}/.github/workflows/ci.yml

@@ -17,6 +17,8 @@ jobs:
         python-version: ["3.10", "3.11", "3.12", "3.13", "3.14", "3.15"]
     steps:
       - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        with:
+          persist-credentials: false
 
       - name: Install uv
         uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
@@ -28,7 +30,7 @@ jobs:
           allow-prereleases: true
 
       - name: Install dependencies
-        run: uv sync
+        run: uv sync --extra json
 
       - name: Lint
         run: uv run ruff check .
@@ -38,7 +40,7 @@ jobs:
 
       - name: Upload coverage to Codecov
         if: matrix.python-version == '3.14'
-        uses: codecov/codecov-action@e79a6962e0d4c0c17b229090214935d2e33f8354 # v6.0.1
+        uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f # v7.0.0
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
           files: coverage.xml
@@ -47,6 +49,8 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        with:
+          persist-credentials: false
 
       - name: Install uv
         uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
@@ -57,7 +61,7 @@ jobs:
           python-version: "3.14"
 
       - name: Install dependencies
-        run: uv sync
+        run: uv sync --extra json
 
       - name: Ruff check
         run: uv run ruff check .

{assertpy2-2.3.7 → assertpy2-2.4.0}/.github/workflows/codeql.yml

@@ -18,7 +18,9 @@ jobs:
       security-events: write
     steps:
       - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
-      - uses: github/codeql-action/init@f52b05f4acaaa234e44466e66d29050e135ea9ef # v4.36.0
+        with:
+          persist-credentials: false
+      - uses: github/codeql-action/init@8aad20d150bbac5944a9f9d289da16a4b0d87c1e # v4.36.2
         with:
           languages: python
-      - uses: github/codeql-action/analyze@f52b05f4acaaa234e44466e66d29050e135ea9ef # v4.36.0
+      - uses: github/codeql-action/analyze@8aad20d150bbac5944a9f9d289da16a4b0d87c1e # v4.36.2

{assertpy2-2.3.7 → assertpy2-2.4.0}/.github/workflows/publish.yml

@@ -17,9 +17,13 @@ jobs:
       attestations: write
     steps:
       - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        with:
+          persist-credentials: false
 
       - name: Install uv
         uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        with:
+          enable-cache: false
 
       - name: Set up Python
         uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
@@ -45,13 +49,17 @@ jobs:
       - name: Prepare provenance bundles
         run: |
           mkdir -p provenance
-          cp "${{ steps.attest-wheel.outputs.bundle-path }}" "provenance/$(basename dist/*.whl).sigstore.json"
-          cp "${{ steps.attest-sdist.outputs.bundle-path }}" "provenance/$(basename dist/*.tar.gz).sigstore.json"
+          cp "$WHEEL_BUNDLE" "provenance/$(basename dist/*.whl).sigstore.json"
+          cp "$SDIST_BUNDLE" "provenance/$(basename dist/*.tar.gz).sigstore.json"
+        env:
+          WHEEL_BUNDLE: ${{ steps.attest-wheel.outputs.bundle-path }}
+          SDIST_BUNDLE: ${{ steps.attest-sdist.outputs.bundle-path }}
 
       - name: Publish to PyPI
         uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # v1.14.0
 
       - name: Upload to GitHub Release
-        run: gh release upload "${{ github.event.release.tag_name }}" dist/* provenance/*
+        run: gh release upload "$TAG_NAME" dist/* provenance/*
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          TAG_NAME: ${{ github.event.release.tag_name }}

{assertpy2-2.3.7 → assertpy2-2.4.0}/.github/workflows/scorecard.yml

@@ -29,6 +29,6 @@ jobs:
           name: SARIF file
           path: results.sarif
           retention-days: 5
-      - uses: github/codeql-action/upload-sarif@e46ed2cbd01164d986452f91f178727624ae40d7 # v4.35.3
+      - uses: github/codeql-action/upload-sarif@8aad20d150bbac5944a9f9d289da16a4b0d87c1e # v4.36.2
         with:
           sarif_file: results.sarif

assertpy2-2.4.0/.github/workflows/zizmor.yml

@@ -0,0 +1,21 @@
+name: Zizmor
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  zizmor:
+    runs-on: ubuntu-latest
+    permissions:
+      security-events: write
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        with:
+          persist-credentials: false
+      - uses: zizmorcore/zizmor-action@5f14fd08f7cf1cb1609c1e344975f152c7ee938d # v0.5.6

{assertpy2-2.3.7 → assertpy2-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: assertpy2
-Version: 2.3.7
+Version: 2.4.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
@@ -64,6 +64,7 @@ Description-Content-Type: text/markdown
   <a href="https://www.bestpractices.dev/projects/12990"><img src="https://www.bestpractices.dev/projects/12990/badge" alt="OpenSSF Best Practices"></a>
 </p>
 
+---
 
 ## Quick start
 
@@ -100,7 +101,7 @@ assert_that(api_response).matches_structure({
 })
 ```
 
-Structured errors with rich data:
+Structured errors with rich diffs:
 
 ```py
 try:
@@ -118,8 +119,27 @@ FAILED test_example.py::test_comparison
 --- AssertionFailure ---
   actual:   {'a': 1, 'b': 2}
   expected: {'a': 1, 'b': 99}
+--- Structured Diff ---
+diff (dict):
+  b:
+    - 2
+    + 99
 ```
 
+## Type-aware autocomplete
+
+`assert_that()` uses `@overload` to return type-specific Protocols.
+Your IDE shows only methods relevant to the value you're testing, not all 100+:
+
+- `assert_that("hello").` &rarr; string methods: `starts_with`, `matches`, `is_alpha`, ...
+- `assert_that(42).` &rarr; numeric methods: `is_positive`, `is_between`, `is_close_to`, ...
+- `assert_that(Path("/tmp")).` &rarr; path methods: `exists`, `is_file`, `is_readable`, ...
+- `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`. Works in PyCharm, VS Code, and any LSP-compatible editor.
+
+---
 
 ## Comparison
 
@@ -128,14 +148,14 @@ FAILED test_example.py::test_comparison
 |  | pytest assert | PyHamcrest | assertpy | **assertpy2** |
 |---|:---:|:---:|:---:|:---:|
 | **Type safety** | Partial (mypy plugin) | No | No | **py.typed, @overload, Self** |
-| **IDE autocomplete** | Generic | Generic | Generic | **Type-specific per value** |
+| **IDE autocomplete** | Generic | Generic | Generic | **[Filtered by type](#type-aware-autocomplete)** |
 | **Fluent chaining** | No | No | Yes | **Yes** |
 | **Composable matchers** | No | Yes (functions) | No | **Yes (`&` `\|` `~` operators)** |
 | **Structural matching** | No | Flat (has_entries) | No | **Recursive with matchers** |
 | **Async assertions** | No | No | No | **eventually() with polling** |
 | **Soft assertions** | No | No | Yes (not thread-safe) | **Yes (thread-safe, async-safe)** |
 | **Structured errors** | Rewrite only | Mismatch string | String only | **.actual .expected .diff** |
-| **Maintained** | N/A | Minimal | 2020 | **Active** |
+| **Maintained** | Built-in | Minimal | 2020 | **Active** |
 
 </div>
 
@@ -160,32 +180,52 @@ assert "admin" in items
 assert_that(items).is_type_of(list).is_length(3).contains("admin")
 ```
 
+---
 
 ## Features
 
+**Fluent API**
+
 - [**Composable matchers**](docs/api.md#composable-matchers): `match.greater_than(5)`, `match.is_uuid()`, combine with `&`, `|`, `~`. Also work with plain `assert ==`.
 - [**Structural matching**](docs/api.md#structural-matching): `matches_structure()` for declarative dict/API response validation.
 - [**Universal negation**](docs/api.md#universal-negation): `.not_` inverts any assertion without dedicated `is_not_*` methods.
-- [**Collection pipeline**](docs/api.md#collection-pipeline): `filtered_on()`, `mapped()`, `flat_mapped()`, `first()`, `last()`, `element()`, `single()` for transforming collections before assertions.
-- [**Async assertions**](docs/api.md#async-assertions): `eventually()` with polling/retry for async and eventual consistency testing.
-- [**Structured errors**](docs/api.md#structured-errors): `AssertionFailure` with `.actual`, `.expected`, `.diff` attributes, pytest plugin with rich diff output.
-- **Typed overloads**: `assert_that()` returns type-specific Protocols, IDE shows only relevant methods per type.
-- **Type safety**: `Self` return types, `py.typed` ([PEP 561](https://peps.python.org/pep-0561/)).
-- [**Soft assertions**](docs/api.md#soft-assertions): thread-safe and async-safe via `contextvars`, collect all failures with `soft_assertions()`. Group errors with `sa.group()`, or use `assert_all()` for inline checks.
-- [**JSON assertions**](docs/api.md#json-path--schema-validation): JSONPath navigation (`at_json_path`, `has_json_path`) and JSON Schema validation (`matches_json_schema`).
+- [**Collection pipeline**](docs/api.md#collection-pipeline): `filtered_on()`, `mapped()`, `flat_mapped()`, `first()`, `last()`, `element()`, `single()`.
 - [**Fluent chaining**](docs/api.md#chaining): write assertions as readable one-liners that chain naturally.
-- [**Dynamic assertions**](docs/api.md#objects): `has_<name>()` for any attribute, property, or zero-argument method on objects and dicts.
+
+**Built-in types**
+
+- [Strings](docs/api.md#strings), [numbers](docs/api.md#numbers), [lists](docs/api.md#lists), [tuples](docs/api.md#tuples), [sets](docs/api.md#sets), [dicts](docs/api.md#dicts), [dates](docs/api.md#dates), [booleans](docs/api.md#booleans), [objects](docs/api.md#objects), [bytes](docs/api.md#bytes--bytearray-assertions), [files](docs/api.md#files), [exceptions](docs/api.md#failure).
+- [**Bytes assertions**](docs/api.md#bytes--bytearray-assertions): `is_valid_utf8()`, `starts_with_bytes()`, `is_hex_equal_to()`, `decoded_as()` for `bytes`/`bytearray`.
+- [**JSON assertions**](docs/api.md#json-path--schema-validation): JSONPath navigation and JSON Schema validation. `pip install assertpy2[json]`.
+- [**Dynamic assertions**](docs/api.md#objects): `has_<name>()` for any attribute, property, or zero-argument method.
 - [**Dict comparison**](docs/api.md#dicts): `is_equal_to()` with `ignore` and `include` for selective key matching.
 - [**Extracting**](docs/api.md#objects): flatten collections on attributes with `filter` and `sort` support.
-- [**File assertions**](docs/api.md#files): `exists()`, `is_file()`, `is_readable()`, `is_writable()`, `is_executable()` with `pathlib.Path` support.
-- [**Snapshot testing**](docs/api.md#snapshot-testing): store and compare data structures in JSON format, inspired by Jest.
-- [**Allure integration**](docs/api.md#allure-integration): auto-attach structured diff and actual/expected data to Allure reports.
-- [**Behave step matchers**](docs/api.md#behave-step-matchers): ready-made parameter types (`PositiveInt`, `BoolLike`, etc.) for Behave step definitions.
-- [**Custom matchers**](docs/api.md#custom-matchers---registering-domain-matchers): register domain-specific matchers via `register_matcher()`, composable with `&`, `|`, `~`.
-- [**Regex group extraction**](docs/api.md#regex-group-extraction): `extracting_group()` and `matches_with_groups()` to assert on regex captures fluently.
-- [**Extensions**](docs/api.md#extension-system---adding-custom-assertions): add custom assertions via `add_extension()`.
-- [Strings](docs/api.md#strings), [numbers](docs/api.md#numbers), [lists](docs/api.md#lists), [tuples](docs/api.md#tuples), [sets](docs/api.md#sets), [dicts](docs/api.md#dicts), [dates](docs/api.md#dates), [booleans](docs/api.md#booleans), [objects](docs/api.md#objects), [exceptions](docs/api.md#failure).
 
+**Testing**
+
+- [**Soft assertions**](docs/api.md#soft-assertions): thread-safe, async-safe via `contextvars`. Group errors with `sa.group()`, or use `assert_all()`.
+- [**Async assertions**](docs/api.md#async-assertions): `eventually()` with polling/retry for eventual consistency.
+- [**Structured errors**](docs/api.md#structured-errors): `AssertionFailure` with `.actual`, `.expected`, `.diff` attributes.
+- [**Rich pytest diffs**](docs/api.md#rich-pytest-diffs): recursive structural diffs for lists, sets, strings, dicts, dataclasses, namedtuples.
+- [**Snapshot testing**](docs/api.md#snapshot-testing): store and compare data structures in JSON format.
+
+**Type safety**
+
+- [**Type-aware autocomplete**](#type-aware-autocomplete): 9 Protocols, IDE shows only relevant methods per type.
+- **py.typed**: `Self` return types, PEP 561 compliant ([PEP 561](https://peps.python.org/pep-0561/)).
+
+**Extensibility**
+
+- [**Custom matchers**](docs/api.md#custom-matchers---registering-domain-matchers): `register_matcher()` for domain-specific matchers, composable with `&`, `|`, `~`.
+- [**Regex group extraction**](docs/api.md#regex-group-extraction): `extracting_group()` and `matches_with_groups()` for regex captures.
+- [**Extensions**](docs/api.md#extension-system---adding-custom-assertions): `add_extension()` for custom assertion methods.
+
+**Integrations**
+
+- [**Allure**](docs/api.md#allure-integration): auto-attach structured diff and actual/expected data to reports. `pip install assertpy2[allure]`.
+- [**Behave**](docs/api.md#behave-step-matchers): ready-made parameter types for step definitions. `pip install assertpy2[behave]`.
+
+---
 
 ## Composable matchers
 
@@ -241,120 +281,148 @@ assert_that(api_response).matches_structure({
 })
 ```
 
+---
 
-## Async assertions
-
-Poll a callable until the assertion passes or timeout is reached:
+## Fluent API
 
-```py
-from assertpy2 import assert_that
+### Universal negation
 
-async def test_eventual_consistency():
-    await assert_that(get_status).eventually().within(5).every(0.5).is_equal_to("ready")
+Invert any assertion with `.not_`:
 
-    # works with async callables
-    await assert_that(async_get_count).eventually().within(10).is_greater_than(100)
+```py
+assert_that(5).not_.is_none()
+assert_that("abc123").not_.is_alpha()
+assert_that([3, 1, 2]).not_.is_sorted()
+assert_that(value).described_as("check").not_.is_none().is_positive()
 ```
 
-Any assertion method is available after `eventually()`. Only `AssertionError` is retried, other exceptions propagate immediately.
-
+Works with soft assertions and warn mode.
 
-## Soft assertions
+### Collection pipeline
 
-Collect all failures instead of stopping at the first one:
+Transform collections before asserting:
 
 ```py
-from assertpy2 import assert_that, soft_assertions
+orders = [Order("DONE", 100), Order("FAILED", 50), Order("DONE", 200)]
 
-def test_user_profile():
-    with soft_assertions():
-        assert_that(user.name).is_equal_to("Alice")
-        assert_that(user.age).is_greater_than(0)
-        assert_that(user.email).contains("@")
+assert_that(orders).filtered_on(lambda o: o.status == "FAILED").is_length(1)
+assert_that(orders).mapped(lambda o: o.total).contains(100, 200)
+assert_that(orders).first().has_status("DONE")
+assert_that(orders).element(1).has_status("FAILED")
+assert_that([42]).single().is_equal_to(42)
+
+# chaining pipeline steps
+assert_that(items).filtered_on(match.is_positive()).mapped(str).contains("1")
 ```
 
-All failures are reported at the end of the block:
+Available methods: `filtered_on()`, `mapped()`, `flat_mapped()`, `first()`, `last()`, `element()`, `single()`.
 
-```
-AssertionError: soft assertion failures:
-1. Expected <Bob> to be equal to <Alice>, but was not.
-2. Expected <-1> to be greater than <0>, but was not.
-3. Expected <invalid> to contain <@>, but did not.
-```
+### Dict comparison with ignore/include
 
-Use `soft_fail("message")` inside the block for non-halting explicit failures (unlike `fail()`, which stops immediately).
+```py
+assert_that({"a": 1, "b": 2, "c": 3}).is_equal_to({"a": 1}, ignore=["b", "c"])
+assert_that({"a": 1, "b": {"c": 2, "d": 3}}).is_equal_to({"b": {"d": 3}}, include=("b", "d"))
+```
 
-Soft assertions are thread-safe and async-safe: each thread and each `asyncio` task gets independent state via `contextvars`.
+### Extracting with filter and sort
 
+```py
+users = [
+    {"user": "Fred", "age": 36, "active": True},
+    {"user": "Bob", "age": 40, "active": False},
+    {"user": "Johnny", "age": 13, "active": True},
+]
 
-## Structured errors
+assert_that(users).extracting("user", filter="active").is_equal_to(["Fred", "Johnny"])
+assert_that(users).extracting("user", sort="age").is_equal_to(["Johnny", "Fred", "Bob"])
+```
 
-When assertions fail, `AssertionFailure` carries structured data alongside the human-readable message:
+### Dynamic assertions
 
 ```py
-try:
-    assert_that(1).is_equal_to(2)
-except AssertionError as e:
-    e.actual    # 1
-    e.expected  # 2
+fred = {"first_name": "Fred", "last_name": "Smith", "shoe_size": 12}
+
+assert_that(fred).has_first_name("Fred")
+assert_that(fred).has_last_name("Smith")
+assert_that(fred).has_shoe_size(12)
 ```
 
-For dict comparisons, a `DiffResult` with per-key diff entries is available:
+### Expected exceptions
 
 ```py
-try:
-    assert_that({"a": 1, "b": 2}).is_equal_to({"a": 1, "b": 99})
-except AssertionError as e:
-    e.diff  # DiffResult(kind='dict', entries=[DiffEntry(path='b', actual=2, expected=99)])
+assert_that(some_func).raises(RuntimeError).when_called_with("bad_arg")\
+    .is_length(8).starts_with("some").is_equal_to("some err")
 ```
 
-`AssertionFailure` is a subclass of `AssertionError`, so all existing `except AssertionError` handlers work unchanged.
+---
 
-The pytest plugin (auto-registered, no configuration needed) renders structured data as extra sections in failure reports:
+## Built-in types
 
-```
-FAILED test_example.py::test_comparison
---- AssertionFailure ---
-  actual:   {'a': 1, 'b': 2}
-  expected: {'a': 1, 'b': 99}
---- Structured Diff ---
-DiffResult(kind='dict', entries=[DiffEntry(path='b', actual=2, expected=99)])
+### Bytes assertions
+
+Assert on `bytes` and `bytearray` values:
+
+```py
+data = b"\x89PNG\r\n\x1a\n"
+
+assert_that(data).starts_with_bytes(b"\x89PNG")
+assert_that(data).has_byte_at(0, 0x89)
+assert_that(data).is_hex_equal_to("89504e470d0a1a0a")
+assert_that(b"hello").is_valid_utf8()
+assert_that(b"hello").decoded_as("utf-8").starts_with("hel")
 ```
 
+Available methods: `is_valid_utf8()`, `is_valid_encoding()`, `starts_with_bytes()`, `contains_bytes()`, `has_byte_at()`, `is_hex_equal_to()`, `decoded_as()`.
 
-## More features
+### JSON path and schema validation
 
-### Universal negation
+Requires `pip install assertpy2[json]`.
 
-Invert any assertion with `.not_`:
+```py
+data = {"users": [{"name": "Alice"}, {"name": "Bob"}], "meta": {"total": 2}}
+
+assert_that(data).at_json_path("$.users[0].name").is_equal_to("Alice")
+assert_that(data).has_json_path("$.meta.total")
+assert_that(data).does_not_have_json_path("$.error")
+assert_that(data).matches_json_schema({"type": "object", "required": ["users"]})
+```
+
+### Snapshot testing
 
 ```py
-assert_that(5).not_.is_none()
-assert_that("abc123").not_.is_alpha()
-assert_that([3, 1, 2]).not_.is_sorted()
-assert_that(value).described_as("check").not_.is_none().is_positive()
+assert_that({"a": 1, "b": 2, "c": 3}).snapshot()
 ```
 
-Works with soft assertions and warn mode.
+---
 
-### Collection pipeline
+## Testing
 
-Transform collections before asserting:
+### Soft assertions
+
+Collect all failures instead of stopping at the first one:
 
 ```py
-orders = [Order("DONE", 100), Order("FAILED", 50), Order("DONE", 200)]
+from assertpy2 import assert_that, soft_assertions
 
-assert_that(orders).filtered_on(lambda o: o.status == "FAILED").is_length(1)
-assert_that(orders).mapped(lambda o: o.total).contains(100, 200)
-assert_that(orders).first().has_status("DONE")
-assert_that(orders).element(1).has_status("FAILED")
-assert_that([42]).single().is_equal_to(42)
+def test_user_profile():
+    with soft_assertions():
+        assert_that(user.name).is_equal_to("Alice")
+        assert_that(user.age).is_greater_than(0)
+        assert_that(user.email).contains("@")
+```
+
+All failures are reported at the end of the block:
 
-# chaining pipeline steps
-assert_that(items).filtered_on(match.is_positive()).mapped(str).contains("1")
+```
+AssertionError: soft assertion failures:
+1. Expected <Bob> to be equal to <Alice>, but was not.
+2. Expected <-1> to be greater than <0>, but was not.
+3. Expected <invalid> to contain <@>, but did not.
 ```
 
-Available methods: `filtered_on()`, `mapped()`, `flat_mapped()`, `first()`, `last()`, `element()`, `single()`.
+Use `soft_fail("message")` inside the block for non-halting explicit failures (unlike `fail()`, which stops immediately).
+
+Soft assertions are thread-safe and async-safe: each thread and each `asyncio` task gets independent state via `contextvars`.
 
 ### Grouped soft assertions
 
@@ -373,62 +441,75 @@ assert_all(
 )
 ```
 
-### JSON path and schema validation
+### Async assertions
 
-Requires `pip install assertpy2[json]`.
+Poll a callable until the assertion passes or timeout is reached:
 
 ```py
-data = {"users": [{"name": "Alice"}, {"name": "Bob"}], "meta": {"total": 2}}
+from assertpy2 import assert_that
 
-assert_that(data).at_json_path("$.users[0].name").is_equal_to("Alice")
-assert_that(data).has_json_path("$.meta.total")
-assert_that(data).does_not_have_json_path("$.error")
-assert_that(data).matches_json_schema({"type": "object", "required": ["users"]})
+async def test_eventual_consistency():
+    await assert_that(get_status).eventually().within(5).every(0.5).is_equal_to("ready")
+
+    # works with async callables
+    await assert_that(async_get_count).eventually().within(10).is_greater_than(100)
 ```
 
-### Dict comparison with ignore/include
+Any assertion method is available after `eventually()`. Only `AssertionError` is retried, other exceptions propagate immediately.
 
-```py
-assert_that({"a": 1, "b": 2, "c": 3}).is_equal_to({"a": 1}, ignore=["b", "c"])
-assert_that({"a": 1, "b": {"c": 2, "d": 3}}).is_equal_to({"b": {"d": 3}}, include=("b", "d"))
-```
+### Structured errors
 
-### Extracting with filter and sort
+When assertions fail, `AssertionFailure` carries structured data alongside the human-readable message:
 
 ```py
-users = [
-    {"user": "Fred", "age": 36, "active": True},
-    {"user": "Bob", "age": 40, "active": False},
-    {"user": "Johnny", "age": 13, "active": True},
-]
-
-assert_that(users).extracting("user", filter="active").is_equal_to(["Fred", "Johnny"])
-assert_that(users).extracting("user", sort="age").is_equal_to(["Johnny", "Fred", "Bob"])
+try:
+    assert_that(1).is_equal_to(2)
+except AssertionError as e:
+    e.actual    # 1
+    e.expected  # 2
 ```
 
-### Expected exceptions
+For comparisons, a `DiffResult` with structural diff entries is available:
 
 ```py
-assert_that(some_func).raises(RuntimeError).when_called_with("bad_arg")\
-    .is_length(8).starts_with("some").is_equal_to("some err")
+try:
+    assert_that({"a": 1, "b": 2}).is_equal_to({"a": 1, "b": 99})
+except AssertionError as e:
+    e.diff  # DiffResult(kind='dict', entries=[DiffEntry(path='b', actual=2, expected=99)])
 ```
 
-### Dynamic assertions
+`AssertionFailure` is a subclass of `AssertionError`, so all existing `except AssertionError` handlers work unchanged.
 
-```py
-fred = {"first_name": "Fred", "last_name": "Smith", "shoe_size": 12}
+### Rich pytest diffs
 
-assert_that(fred).has_first_name("Fred")
-assert_that(fred).has_last_name("Smith")
-assert_that(fred).has_shoe_size(12)
+The pytest plugin (auto-registered, no configuration needed) renders structural diffs with recursive descent:
+
+```
+FAILED test_example.py::test_api
+--- AssertionFailure ---
+  actual:   [{'id': 1, 'name': 'Alice'}, {'id': 2, 'name': 'Bob'}]
+  expected: [{'id': 1, 'name': 'Alice'}, {'id': 2, 'name': 'Robert'}]
+--- Structured Diff ---
+diff (sequence):
+  [1].name:
+    - 'Bob'
+    + 'Robert'
 ```
 
-### Snapshot testing
+Supported types: list/tuple, set/frozenset, str, dict, dataclass, namedtuple. Nested structures are diffed recursively. Colored output when `--color=yes`.
 
-```py
-assert_that({"a": 1, "b": 2, "c": 3}).snapshot()
+Configure via `pyproject.toml`:
+
+```toml
+[tool.pytest.ini_options]
+assertpy2_diff = "off"              # disable diff sections
+assertpy2_diff_max_entries = "100"  # max entries shown (default 50, 0 = unlimited)
 ```
 
+---
+
+## Extensibility
+
 ### Custom matchers
 
 Register domain-specific matchers on the `match` namespace with `register_matcher()`:
@@ -491,8 +572,11 @@ assert_that(5).is_5()
 
 See the [full API reference](docs/api.md) for all assertion methods, examples, and advanced features.
 
+---
+
+## Integrations
 
-## Allure integration
+### Allure
 
 When `allure-pytest` is installed, the pytest plugin auto-attaches structured failure data to Allure reports as JSON attachments.
 
@@ -514,8 +598,7 @@ Three modes controlled via `pytest.ini` (or `pyproject.toml`):
 assertpy2_allure = "full"
 ```
 
-
-## Behave step matchers
+### Behave
 
 Ready-made parameter types for Behave step definitions:
 
@@ -539,6 +622,7 @@ def step_impl(context, age):
 
 Available types: `PositiveInt`, `NonNegativeInt`, `PositiveFloat`, `NonEmptyString`, `BoolLike`.
 
+---
 
 ## Migration from assertpy
 
@@ -555,8 +639,8 @@ from assertpy2 import assert_that, soft_assertions
 See the [comparison table](#comparison) above for feature differences with other libraries.
 
 
-## Contributing
-
-Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
-
+---
 
+<p align="center">
+  <a href="https://github.com/Solganis/assertpy2/blob/main/LICENSE">BSD 3-Clause License</a>
+</p>