assertpy2 2.19.0__tar.gz → 2.20.0__tar.gz

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

@@ -72,11 +72,49 @@ 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
@@ -112,14 +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:
     timeout-minutes: 5
-    needs: [test, lint]
+    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.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.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.19.0 → assertpy2-2.20.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: assertpy2
-Version: 2.19.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
@@ -223,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.19.0 → assertpy2-2.20.0}/README.md

@@ -171,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.
 

{assertpy2-2.19.0 → assertpy2-2.20.0}/assertpy2/__init__.py

@@ -1,4 +1,5 @@
 from .assertpy import (
+    CheckBuilder,
     NegatedBuilder,
     SoftAssertionCollector,
     WarningLoggingAdapter,
@@ -14,9 +15,26 @@ from .assertpy import (
     soft_fail,
 )
 from .async_assertions import AsyncAssertionBuilder, SyncAssertionBuilder
-from .errors import AssertionFailure, DiffEntry, DiffResult, PollSample, PollTrace, VacuousAssertionWarning
+from .errors import (
+    AssertionFailure,
+    DiffEntry,
+    DiffResult,
+    PollSample,
+    PollTrace,
+    Step,
+    VacuousAssertionWarning,
+)
 from .file import contents_of
-from .matchers import Matcher, clear_custom_matchers, match, register_matcher, unregister_matcher
+from .matchers import (
+    BaseMatcher,
+    Matcher,
+    MatchResult,
+    clear_custom_matchers,
+    match,
+    register_matcher,
+    unregister_matcher,
+)
+from .outcome import AssertionOutcome
 from .snapshot import (
     SnapshotCreatedWarning,
     SnapshotKeyReusedWarning,
@@ -26,9 +44,13 @@ from .snapshot import (
 
 __all__ = [
     "AssertionFailure",
+    "AssertionOutcome",
     "AsyncAssertionBuilder",
+    "BaseMatcher",
+    "CheckBuilder",
     "DiffEntry",
     "DiffResult",
+    "MatchResult",
     "Matcher",
     "NegatedBuilder",
     "PollSample",
@@ -37,6 +59,7 @@ __all__ = [
     "SnapshotKeyReusedWarning",
     "SnapshotUpdatedWarning",
     "SoftAssertionCollector",
+    "Step",
     "SyncAssertionBuilder",
     "VacuousAssertionWarning",
     "WarningLoggingAdapter",

{assertpy2-2.19.0 → assertpy2-2.20.0}/assertpy2/_engine/_compare.py

@@ -331,3 +331,30 @@ def _spec_matches(key, value, specs) -> bool:
         elif spec == key:
             return True
     return False
+
+
+def _config_note(config: _CompareConfig | None) -> str:
+    """A newline plus an echo of the comparison settings that were in force, or ``""`` when none were.
+
+    ``is_equal_to`` already names ``ignore`` and ``include`` inside its sentence, but nothing reports
+    the rest, and they are what a reader is questioning when a field they thought was tolerated still
+    failed.  Rendered only for a non-default config: `_build_compare_config()` returns ``None`` when
+    every setting is at its default, so the check costs nothing and the line never appears on the
+    ordinary failure.
+
+    It goes on its own line rather than into the sentence, so the original message stays a prefix and
+    a `match=` or ``startswith`` written against it keeps working.
+    """
+    if config is None:
+        return ""
+    parts = []
+    if config.tolerance is not None:
+        parts.append(f"tolerance={config.tolerance!r}")
+    if config.comparators:
+        keys = ", ".join(sorted(key.__name__ if isinstance(key, type) else str(key) for key in config.comparators))
+        parts.append(f"comparators for {keys}")
+    if config.ignore_null:
+        parts.append("ignore_null=True")
+    if config.strict_types:
+        parts.append("strict_types=True")
+    return "\ncompared with " + ", ".join(parts) if parts else ""

{assertpy2-2.19.0 → assertpy2-2.20.0}/assertpy2/_engine/_contract.py

@@ -17,6 +17,8 @@ def _submodel(annotation: object) -> type | None:
     """The nested model class for an annotation, peeling ``Optional`` / ``list`` / ``tuple``; else ``None``."""
     origin = typing.get_origin(annotation)
     args = typing.get_args(annotation)
+    # both names are needed below 3.14, where `Optional[X]` and `X | None` had distinct origins; from
+    # 3.14 they are the same object and the second test is redundant on the interpreters we gate on
     if origin is typing.Union or origin is types.UnionType:
         non_none = [arg for arg in args if arg is not type(None)]
         return _submodel(non_none[0]) if len(non_none) == 1 else None