assertpy2 2.18.0__tar.gz → 2.20.0__tar.gz

{assertpy2-2.18.0 → assertpy2-2.20.0}/.github/workflows/ci.yml

@@ -15,6 +15,7 @@ permissions:
 
 jobs:
   test:
+    timeout-minutes: 15
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
@@ -31,15 +32,15 @@ jobs:
           - os: macos-latest
             python-version: "3.14"
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
 
       - name: Install uv
-        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
 
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
           python-version: ${{ matrix.python-version }}
           allow-prereleases: true
@@ -71,24 +72,63 @@ jobs:
         run: uv run pytest tests/test_docs_examples.py
 
       - name: Upload coverage to Codecov
-        if: matrix.python-version == '3.14' && matrix.os == 'ubuntu-latest'
+        # Only the full-deps cell. The bare 3.14/ubuntu cell skips every integration test and used
+        # to upload too: Codecov merges reports so the number stayed right, but one of the two was
+        # always a partial report sent at a 100% target.
+        if: matrix.full-deps
         uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f # v7.0.0
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
           files: coverage.xml
+          # A failed upload is a broken report, not a passing build. The 100% gate above is the hard
+          # guard either way, so this cannot turn a real coverage drop into a green run.
+          fail_ci_if_error: true
+
+  optional-integrations:
+    # allure and behave get their own job because installing them is incompatible with the coverage
+    # gate: with allure present the `except ImportError` fallback in pytest_plugin.py never runs, and
+    # without it the import itself never runs. The gating cell keeps the second state, this one holds
+    # the first. Everywhere else the two are tested against mocks, which accept any call and would
+    # wave through the renamed parameter or moved attribute a Dependabot bump can bring.
+    timeout-minutes: 10
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+
+      - name: Set up Python
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.14"
+
+      - name: Install dependencies
+        run: uv sync --extra json --extra allure --extra behave
+
+      - name: Contract tests against the real libraries
+        run: uv run pytest -v tests/test_optional_integration_contracts.py
+
+      - name: The rest of the suite must also pass with both installed
+        # Installing allure flips `_HAS_ALLURE`, so every failing assertion in the suite takes the
+        # real attach path. That must not change any other test's outcome.
+        run: uv run pytest -q --ignore=tests/test_docs_examples.py tests
 
   lint:
+    timeout-minutes: 10
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
 
       - name: Install uv
-        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
 
       - name: Set up Python
-        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
           python-version: "3.14"
 
@@ -110,13 +150,24 @@ jobs:
       - name: Type check (pyright, public typing surface)
         run: uv run pyright tests/test_typing.py
 
+      # the package itself carries diagnostics that are not defects (values typed `object`, guarded
+      # optional imports, deliberate overloads). They are recorded per rule with a reason, so a new
+      # one fails here instead of hiding in a count nobody reads.
+      - name: Type check (pyright, package baseline)
+        run: uv run pytest tests/test_pyright_baseline.py -q
+
   ci-ok:
-    needs: [test, lint]
+    timeout-minutes: 5
+    needs: [test, optional-integrations, lint]
     if: always()
     runs-on: ubuntu-latest
     steps:
       - name: Verify required jobs succeeded
         env:
           TEST_RESULT: ${{ needs.test.result }}
+          INTEGRATIONS_RESULT: ${{ needs.optional-integrations.result }}
           LINT_RESULT: ${{ needs.lint.result }}
-        run: '[ "$TEST_RESULT" = "success" ] && [ "$LINT_RESULT" = "success" ]'
+        run: |
+          [ "$TEST_RESULT" = "success" ] &&
+          [ "$INTEGRATIONS_RESULT" = "success" ] &&
+          [ "$LINT_RESULT" = "success" ]

{assertpy2-2.18.0 → assertpy2-2.20.0}/.github/workflows/codeql.yml

@@ -13,14 +13,15 @@ permissions:
 
 jobs:
   analyze:
+    timeout-minutes: 15
     runs-on: ubuntu-latest
     permissions:
       security-events: write
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
-      - uses: github/codeql-action/init@99df26d4f13ea111d4ec1a7dddef6063f76b97e9 # v4.37.0
+      - uses: github/codeql-action/init@e4fba868fa4b1b91e1fdab776edc8cfbe6e9fb81 # v4.37.3
         with:
           languages: python
-      - uses: github/codeql-action/analyze@99df26d4f13ea111d4ec1a7dddef6063f76b97e9 # v4.37.0
+      - uses: github/codeql-action/analyze@e4fba868fa4b1b91e1fdab776edc8cfbe6e9fb81 # v4.37.3

{assertpy2-2.18.0 → assertpy2-2.20.0}/.github/workflows/codspeed.yml

@@ -21,20 +21,21 @@ concurrency:
 
 jobs:
   benchmarks:
+    timeout-minutes: 20
     runs-on: ubuntu-latest
     permissions:
       contents: read
       id-token: write
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
 
       - name: Install uv
-        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
 
       - name: Run benchmarks under CodSpeed
-        uses: CodSpeedHQ/action@f99becdce5e5d51fd556489ebef684f4ecfd6286 # v4.18.5
+        uses: CodSpeedHQ/action@f22792bfac16f3e14eb9fbea76f4a48e9cc22b93 # v4.19.1
         with:
           mode: simulation
           run: uv run --locked --group benchmark pytest benchmarks/ --codspeed --no-cov

{assertpy2-2.18.0 → assertpy2-2.20.0}/.github/workflows/docs.yml

@@ -15,17 +15,18 @@ concurrency:
 
 jobs:
   build:
+    timeout-minutes: 10
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
 
       - name: Install uv
-        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
 
       - name: Set up Python
-        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
           python-version: "3.14"
 
@@ -42,6 +43,7 @@ jobs:
           path: site
 
   deploy:
+    timeout-minutes: 10
     if: github.ref == 'refs/heads/main'
     needs: build
     runs-on: ubuntu-latest

assertpy2-2.20.0/.github/workflows/mutation.yml

@@ -0,0 +1,78 @@
+name: Mutation
+
+# Coverage says a line ran; mutation testing asks whether anything would have NOTICED had it been
+# wrong. It is a review tool, not a gate: most survivors are equivalent mutants (message text no test
+# asserts on, formatting, `__repr__`), so the job stays green on survivors and publishes the list to
+# triage. Weekly, not nightly - the score only moves when assertpy2/ or tests/ move, and a recurring
+# red that means nothing is a red people learn to ignore.
+#
+# It does go red when the RUN itself is broken. mutmut runs the unmutated suite once to learn which
+# tests cover which function, and exits 1 if that fails, so a test the trampoline breaks stops the
+# whole run instead of quietly leaving mutants unjudged. That red is never routine: it means the
+# config rotted, which is the failure the previous cosmic-ray setup hid for five weeks behind a
+# stale module path.
+#
+# Linux only: mutmut forks and calls os.wait, and does not run on Windows.
+
+on:
+  schedule:
+    - cron: "0 4 * * 1" # weekly, Monday 04:00 UTC
+  workflow_dispatch: {}
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}
+  cancel-in-progress: true
+
+jobs:
+  mutation:
+    runs-on: ubuntu-latest
+    # 10 060 mutants over the whole package. Measured on four pinned cores with `--max-children 4`,
+    # which is this runner's shape: 41m15s. Slower runner cores put the real figure somewhere
+    # around an hour, so this leaves comfortable headroom without letting a hang burn two hours.
+    timeout-minutes: 120
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+
+      - name: Set up Python
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.14"
+
+      - name: Install dependencies
+        # Every optional integration, matching the full-deps cell of ci.yml. A skipped test cannot
+        # kill a mutant, so mutating dataframe.py or json_mixin.py without pandas/polars/jsonschema
+        # installed reports its whole surface as untested.
+        run: uv sync --extra json --extra data --extra inline --group integrations --group mutation
+
+      - name: Run the mutants
+        # Exits non-zero when it cannot collect stats, which is what a baseline failure looks like.
+        # Survivors alone do not fail it.
+        #
+        # `--no-sync` on every `uv run` below: without it uv re-resolves the environment to the
+        # project's default groups and uninstalls the extras the step above just installed, so the
+        # mutants would be judged by a suite that skips pandas, polars and jsonschema.
+        run: uv run --no-sync mutmut run
+
+      - name: Report
+        if: always()
+        run: |
+          uv run --no-sync python scripts/mutation_report.py >> "$GITHUB_STEP_SUMMARY"
+          uv run --no-sync mutmut results > not-killed.txt
+
+      - name: Upload the mutants that lived
+        # `mutmut results` lists every mutant that was not killed, which is survivors plus timeouts
+        # plus the ones no test covered. Each line carries its own status, so the file is named for
+        # what it holds rather than for survivors alone - reading it as a survivor list overcounts.
+        if: always()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: mutants-not-killed
+          path: not-killed.txt

{assertpy2-2.18.0 → assertpy2-2.20.0}/.github/workflows/publish.yml

@@ -9,6 +9,7 @@ permissions:
 
 jobs:
   publish:
+    timeout-minutes: 20
     runs-on: ubuntu-latest
     environment: pypi
     permissions:
@@ -16,17 +17,17 @@ jobs:
       contents: write
       attestations: write
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
 
       - name: Install uv
-        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
         with:
           enable-cache: false
 
       - name: Set up Python
-        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
           python-version: "3.15"
           allow-prereleases: true
@@ -65,7 +66,7 @@ jobs:
         run: syft scan dir:dist -o "cyclonedx-json=provenance/assertpy2.sbom.cdx.json"
 
       - name: Publish to PyPI
-        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # v1.14.0
+        uses: pypa/gh-action-pypi-publish@ba38be9e461d3875417946c167d0b5f3d385a247 # v1.14.1
 
       - name: Upload to GitHub Release
         run: gh release upload "$TAG_NAME" dist/* provenance/*

{assertpy2-2.18.0 → assertpy2-2.20.0}/.github/workflows/scorecard.yml

@@ -11,15 +11,16 @@ permissions: read-all
 
 jobs:
   analysis:
+    timeout-minutes: 10
     runs-on: ubuntu-latest
     permissions:
       security-events: write
       id-token: write
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
-      - uses: ossf/scorecard-action@4eaacf0543bb3f2c246792bd56e8cdeffafb205a # v2.4.3
+      - uses: ossf/scorecard-action@2d1146689b8cda280b9bc96326124645441f03bc # v2.4.4
         with:
           results_file: results.sarif
           results_format: sarif
@@ -29,6 +30,6 @@ jobs:
           name: SARIF file
           path: results.sarif
           retention-days: 5
-      - uses: github/codeql-action/upload-sarif@99df26d4f13ea111d4ec1a7dddef6063f76b97e9 # v4.37.0
+      - uses: github/codeql-action/upload-sarif@e4fba868fa4b1b91e1fdab776edc8cfbe6e9fb81 # v4.37.3
         with:
           sarif_file: results.sarif

{assertpy2-2.18.0 → assertpy2-2.20.0}/.github/workflows/zizmor.yml

@@ -15,11 +15,12 @@ permissions:
 
 jobs:
   zizmor:
+    timeout-minutes: 10
     runs-on: ubuntu-latest
     permissions:
       security-events: write
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
-      - uses: zizmorcore/zizmor-action@192e21d79ab29983730a13d1382995c2307fbcaa # v0.5.7
+      - uses: zizmorcore/zizmor-action@6fc4b006235f201fdab3722e17240ab420d580e5 # v0.6.1

assertpy2-2.20.0/CONTRIBUTING.md

@@ -0,0 +1,67 @@
+# Contributing
+
+Contributions of docs, tests, or code are welcome.
+
+## Workflow
+
+1. For a new assertion or matcher, open an issue first. The API grows from demand, and a working
+   implementation on its own is not enough to land one
+2. Fork the repo
+3. Clone your fork (`git clone <your_fork_url>`)
+4. Create a branch (`git checkout -b my_branch`)
+5. Install dependencies: `uv sync`
+6. Make your changes
+7. Run the [verification pipeline](#verification-pipeline) and fix any issues
+8. Commit using [Conventional Commits](#commit-style)
+9. Push your branch (`git push origin my_branch`)
+10. Open a [Pull Request](http://github.com/Solganis/assertpy2/pulls)
+
+Read more about how pulls work on GitHub's [About pull requests](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests) page.
+
+## Requirements
+
+- Python 3.10+
+- [uv](https://docs.astral.sh/uv/) as the package manager
+
+## Verification pipeline
+
+Run all checks before submitting a PR. Every step must pass.
+
+```bash
+# lint
+uv run ruff check assertpy2/ tests/
+
+# format
+uv run ruff format --check assertpy2/ tests/
+
+# type check
+uv run ty check
+
+# tests with coverage (must be 100%)
+uv run pytest tests/ -v --cov=assertpy2 --cov-report=term-missing
+```
+
+CI requires 100% code coverage.
+
+## Commit style
+
+Use [Conventional Commits](https://www.conventionalcommits.org/): `feat:`, `fix:`, `refactor:`, `test:`, `docs:`, `chore:`, etc.
+
+## Tests
+
+Write tests for every new feature or bug fix. Use `assertpy2` assertions in tests.
+
+## Documentation examples
+
+Guide code blocks are executed (`tests/test_docs_examples.py`) and type-checked
+(`tests/test_docs_typing.py`). To skip one, put an HTML comment above the fence:
+
+| Marker | Executed | Type-checked | Use it for |
+|---|---|---|---|
+| `<!-- docs-guard: skip -->` | no | no | pseudo-context, neither runnable nor checkable |
+| `<!-- docs-guard: untyped -->` | yes | no | a dynamic assertion (`has_<attr>()`) |
+| `<!-- docs-guard: raises -->` | no | yes | a block showing what a failure looks like |
+| `<!-- docs-guard: type-error -->` | no | yes, and it **must** fail | a counter-example the page presents as rejected |
+
+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.18.0 → assertpy2-2.20.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: assertpy2
-Version: 2.18.0
+Version: 2.20.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
@@ -88,9 +88,9 @@ def test_user():
     user = {"name": "Alice", "age": 30, "roles": ["viewer", "editor"]}
 
     assert_that(user).contains_key("name", "age")
+    assert_that(user).contains_entry({"name": "Alice"})
     assert_that(user["age"]).is_between(18, 120)
     assert_that(user["roles"]).contains("viewer").does_not_contain("admin")
-    assert_that(user).has_name("Alice")
 ```
 
 The [full documentation](https://solganis.github.io/assertpy2/) covers every assertion, matcher, and integration.
@@ -100,6 +100,7 @@ The [full documentation](https://solganis.github.io/assertpy2/) covers every ass
 A fluent chain reads as one intent and replaces several bare asserts -<br>
 and your IDE offers only the [methods that fit the value's type](https://solganis.github.io/assertpy2/concepts/type-safety/):
 
+<!-- docs-guard: skip -->
 ```python
 # bare - three statements, no autocomplete help
 assert isinstance(items, list)
@@ -123,6 +124,7 @@ E     {'status': 'active'} != {'status': 'disabled'}
 
 assertpy2 reports the [exact path to every difference](https://solganis.github.io/assertpy2/guides/errors/#rich-pytest-diffs), in color:
 
+<!-- docs-guard: skip -->
 ```python
 assert_that(response).is_equal_to(expected)
 ```
@@ -133,6 +135,23 @@ assert_that(response).is_equal_to(expected)
 
 The diff recurses through nested containers, and matcher predicates get the same path-level treatment. For dynamic fields like IDs or timestamps, assert a subset with [`matches_structure()`](https://solganis.github.io/assertpy2/guides/matchers/#structural-matching).
 
+Matchers are ordinary values, so they also compose inside the expected structure itself, at any depth,
+with or without the fluent chain:
+
+```python
+response = {"id": 7, "user": {"name": "Alice", "age": 30}, "tags": ["a", "b"]}
+
+assert_that(response).is_equal_to(
+    {"id": match.greater_than(0), "user": {"name": "Alice", "age": match.between(18, 120)}, "tags": ["a", "b"]}
+)
+
+# or keep the bare `assert`, and pytest's own rewriting reports it
+assert response == {"id": match.greater_than(0), "user": match.ignore(), "tags": ["a", "b"]}
+```
+
+The fluent form keeps the path-level diff, the bare form keeps pytest's. There are
+[39 matchers](https://solganis.github.io/assertpy2/guides/matchers/), and they combine with `&`, `|` and `~`.
+
 <p align="center">
   <img src="https://raw.githubusercontent.com/Solganis/assertpy2/main/docs/assets/diff-gallery.png" width="640" alt="Structured diffs in the terminal: dict path, list element, set extra/missing, and structural-matcher predicate diffs, side by side">
 </p>
@@ -156,6 +175,7 @@ Works in PyCharm, VS Code, and any LSP-compatible editor.
 An assertion hands the value back, statically narrowed. `is_not_none()` strips `None`,
 `is_instance_of()` narrows to the class, and `.value` returns it with no `cast` and no bare `assert`:
 
+<!-- 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
@@ -164,6 +184,7 @@ order.refund()  # statically PaidOrder - verified by ty, mypy, and pyright
 For API tests, [`assert_conforms()`](https://solganis.github.io/assertpy2/concepts/type-safety/#contract-narrowing-with-assert_conforms) validates a raw payload against a Pydantic model and narrows the chain to it,<br>
 with `exact=True` catching silent contract drift:
 
+<!-- docs-guard: skip -->
 ```python
 data = assert_conforms(response.json(), OrderModel).value  # data: OrderModel
 ```
@@ -202,13 +223,14 @@ data = assert_conforms(response.json(), OrderModel).value  # data: OrderModel
 - [**Polling assertions**](https://solganis.github.io/assertpy2/guides/testing/#async-assertions): `eventually()` (async) / `eventually_sync()` (blocking) retry for eventual consistency, with a convergence trace on timeout.
 - [**Expected exceptions**](https://solganis.github.io/assertpy2/guides/errors/#expected-exceptions): `raises().when_called_with()`, walk the cause chain (`caused_by()`, `has_root_cause()`), match `ExceptionGroup` (`contains_error()`), or pivot to the object (`raised()`).
 - [**Structured errors**](https://solganis.github.io/assertpy2/guides/errors/#structured-errors): `AssertionFailure` carries `.actual`, `.expected`, `.diff`, and the diff renders into the message itself, so it shows off pytest too.
+- [**Assertions as values**](https://solganis.github.io/assertpy2/guides/errors/#asking-instead-of-asserting): `check()` runs the next assertion for its verdict instead of raising, returning an `AssertionOutcome` that is truthy when it held and carries the message, values and diff when it did not.
 - [**Rich pytest diffs**](https://solganis.github.io/assertpy2/guides/errors/#rich-pytest-diffs): recursive structural diffs across containers, dataclasses, attrs, and Pydantic models, with intra-line carets for strings and circular-reference protection.
 - [**Snapshot testing**](https://solganis.github.io/assertpy2/guides/testing/#snapshot-testing): three modes under one typed API, all updated with `--assertpy2-snapshot-update`: `snapshot()` (external JSON file), [`matches_inline()`](https://solganis.github.io/assertpy2/guides/testing/#inline-snapshots) (recorded into the test source), and [`matches_contract_snapshot()`](https://solganis.github.io/assertpy2/guides/testing/#contract-snapshots) (value-tolerant structural regressions).
 - [**OpenAPI response contracts**](https://solganis.github.io/assertpy2/reference/json/#assertpy2.json_mixin.JsonMixin.conforms_to_openapi): `conforms_to_openapi(spec, path, method)` validates a JSON response body against an operation's response schema (OpenAPI 3.0/3.1 and Swagger 2.0), reporting every violation with its JSON path.
 
 **Extensibility**
 
-- [**Custom matchers**](https://solganis.github.io/assertpy2/guides/matchers/#custom-matchers): `register_matcher()` for domain-specific matchers, composable with `&`, `|`, `~`.
+- [**Custom matchers**](https://solganis.github.io/assertpy2/guides/matchers/#custom-matchers): `register_matcher()` to compose existing ones, or subclass `BaseMatcher` for a rule that needs its own predicate. Both compose with `&`, `|`, `~`.
 - [**Regex group extraction**](https://solganis.github.io/assertpy2/guides/data/#regex-group-extraction): `extracting_group()` and `matches_with_groups()` for regex captures.
 - [**Extensions**](https://solganis.github.io/assertpy2/extending/custom-assertions/): `add_extension()` for custom assertion methods.
 

{assertpy2-2.18.0 → assertpy2-2.20.0}/README.md

@@ -36,9 +36,9 @@ def test_user():
     user = {"name": "Alice", "age": 30, "roles": ["viewer", "editor"]}
 
     assert_that(user).contains_key("name", "age")
+    assert_that(user).contains_entry({"name": "Alice"})
     assert_that(user["age"]).is_between(18, 120)
     assert_that(user["roles"]).contains("viewer").does_not_contain("admin")
-    assert_that(user).has_name("Alice")
 ```
 
 The [full documentation](https://solganis.github.io/assertpy2/) covers every assertion, matcher, and integration.
@@ -48,6 +48,7 @@ The [full documentation](https://solganis.github.io/assertpy2/) covers every ass
 A fluent chain reads as one intent and replaces several bare asserts -<br>
 and your IDE offers only the [methods that fit the value's type](https://solganis.github.io/assertpy2/concepts/type-safety/):
 
+<!-- docs-guard: skip -->
 ```python
 # bare - three statements, no autocomplete help
 assert isinstance(items, list)
@@ -71,6 +72,7 @@ E     {'status': 'active'} != {'status': 'disabled'}
 
 assertpy2 reports the [exact path to every difference](https://solganis.github.io/assertpy2/guides/errors/#rich-pytest-diffs), in color:
 
+<!-- docs-guard: skip -->
 ```python
 assert_that(response).is_equal_to(expected)
 ```
@@ -81,6 +83,23 @@ assert_that(response).is_equal_to(expected)
 
 The diff recurses through nested containers, and matcher predicates get the same path-level treatment. For dynamic fields like IDs or timestamps, assert a subset with [`matches_structure()`](https://solganis.github.io/assertpy2/guides/matchers/#structural-matching).
 
+Matchers are ordinary values, so they also compose inside the expected structure itself, at any depth,
+with or without the fluent chain:
+
+```python
+response = {"id": 7, "user": {"name": "Alice", "age": 30}, "tags": ["a", "b"]}
+
+assert_that(response).is_equal_to(
+    {"id": match.greater_than(0), "user": {"name": "Alice", "age": match.between(18, 120)}, "tags": ["a", "b"]}
+)
+
+# or keep the bare `assert`, and pytest's own rewriting reports it
+assert response == {"id": match.greater_than(0), "user": match.ignore(), "tags": ["a", "b"]}
+```
+
+The fluent form keeps the path-level diff, the bare form keeps pytest's. There are
+[39 matchers](https://solganis.github.io/assertpy2/guides/matchers/), and they combine with `&`, `|` and `~`.
+
 <p align="center">
   <img src="https://raw.githubusercontent.com/Solganis/assertpy2/main/docs/assets/diff-gallery.png" width="640" alt="Structured diffs in the terminal: dict path, list element, set extra/missing, and structural-matcher predicate diffs, side by side">
 </p>
@@ -104,6 +123,7 @@ Works in PyCharm, VS Code, and any LSP-compatible editor.
 An assertion hands the value back, statically narrowed. `is_not_none()` strips `None`,
 `is_instance_of()` narrows to the class, and `.value` returns it with no `cast` and no bare `assert`:
 
+<!-- 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
@@ -112,6 +132,7 @@ order.refund()  # statically PaidOrder - verified by ty, mypy, and pyright
 For API tests, [`assert_conforms()`](https://solganis.github.io/assertpy2/concepts/type-safety/#contract-narrowing-with-assert_conforms) validates a raw payload against a Pydantic model and narrows the chain to it,<br>
 with `exact=True` catching silent contract drift:
 
+<!-- docs-guard: skip -->
 ```python
 data = assert_conforms(response.json(), OrderModel).value  # data: OrderModel
 ```
@@ -150,13 +171,14 @@ data = assert_conforms(response.json(), OrderModel).value  # data: OrderModel
 - [**Polling assertions**](https://solganis.github.io/assertpy2/guides/testing/#async-assertions): `eventually()` (async) / `eventually_sync()` (blocking) retry for eventual consistency, with a convergence trace on timeout.
 - [**Expected exceptions**](https://solganis.github.io/assertpy2/guides/errors/#expected-exceptions): `raises().when_called_with()`, walk the cause chain (`caused_by()`, `has_root_cause()`), match `ExceptionGroup` (`contains_error()`), or pivot to the object (`raised()`).
 - [**Structured errors**](https://solganis.github.io/assertpy2/guides/errors/#structured-errors): `AssertionFailure` carries `.actual`, `.expected`, `.diff`, and the diff renders into the message itself, so it shows off pytest too.
+- [**Assertions as values**](https://solganis.github.io/assertpy2/guides/errors/#asking-instead-of-asserting): `check()` runs the next assertion for its verdict instead of raising, returning an `AssertionOutcome` that is truthy when it held and carries the message, values and diff when it did not.
 - [**Rich pytest diffs**](https://solganis.github.io/assertpy2/guides/errors/#rich-pytest-diffs): recursive structural diffs across containers, dataclasses, attrs, and Pydantic models, with intra-line carets for strings and circular-reference protection.
 - [**Snapshot testing**](https://solganis.github.io/assertpy2/guides/testing/#snapshot-testing): three modes under one typed API, all updated with `--assertpy2-snapshot-update`: `snapshot()` (external JSON file), [`matches_inline()`](https://solganis.github.io/assertpy2/guides/testing/#inline-snapshots) (recorded into the test source), and [`matches_contract_snapshot()`](https://solganis.github.io/assertpy2/guides/testing/#contract-snapshots) (value-tolerant structural regressions).
 - [**OpenAPI response contracts**](https://solganis.github.io/assertpy2/reference/json/#assertpy2.json_mixin.JsonMixin.conforms_to_openapi): `conforms_to_openapi(spec, path, method)` validates a JSON response body against an operation's response schema (OpenAPI 3.0/3.1 and Swagger 2.0), reporting every violation with its JSON path.
 
 **Extensibility**
 
-- [**Custom matchers**](https://solganis.github.io/assertpy2/guides/matchers/#custom-matchers): `register_matcher()` for domain-specific matchers, composable with `&`, `|`, `~`.
+- [**Custom matchers**](https://solganis.github.io/assertpy2/guides/matchers/#custom-matchers): `register_matcher()` to compose existing ones, or subclass `BaseMatcher` for a rule that needs its own predicate. Both compose with `&`, `|`, `~`.
 - [**Regex group extraction**](https://solganis.github.io/assertpy2/guides/data/#regex-group-extraction): `extracting_group()` and `matches_with_groups()` for regex captures.
 - [**Extensions**](https://solganis.github.io/assertpy2/extending/custom-assertions/): `add_extension()` for custom assertion methods.