pytest-probatio 0.2.0__tar.gz

pytest_probatio-0.2.0/.gitignore

@@ -0,0 +1,80 @@
+# --- Python ---
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg
+*.egg-info/
+.eggs/
+build/
+dist/
+sdist/
+.Python
+.installed.cfg
+
+# --- Python: tooling caches and coverage ---
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.ty/
+.hypothesis/
+.cache/
+.codspeed/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+.tox/
+.python-version
+
+# --- Virtual environments ---
+.venv/
+.venv-*/
+venv/
+ENV/
+env/
+
+# --- C extensions ---
+*.so
+*.pyd
+
+# --- Documentation site (Node / Astro) ---
+node_modules/
+.astro/
+docs/dist/
+
+# --- Tooling and agents ---
+.claude/
+.dccache
+
+# --- OS cruft ---
+.DS_Store
+._*
+.AppleDouble
+.LSOverride
+.Spotlight-V100
+.Trashes
+Thumbs.db
+ehthumbs.db
+Desktop.ini
+
+# --- Editors ---
+.vscode/
+.idea/
+*.iml
+*.swp
+*~
+
+# --- Secrets and stray files ---
+.env
+*.orig
+*.rej
+
+# --- Fuzzing crash artifacts (libFuzzer/atheris) ---
+crash-*
+oom-*
+timeout-*
+leak-*
+
+# voluptuous's own test suite, copied in for the drop-in proof (BSD-licensed,
+# not vendored). See compat/voluptuous/README.md.
+compat/voluptuous/tests.py

pytest_probatio-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Franck Nijhof
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pytest_probatio-0.2.0/PKG-INFO

@@ -0,0 +1,62 @@
+Metadata-Version: 2.4
+Name: pytest-probatio
+Version: 0.2.0
+Summary: Use a probatio schema as a pytest assertion matcher
+Project-URL: Homepage, https://github.com/frenck/probatio
+Project-URL: Repository, https://github.com/frenck/probatio
+Project-URL: Issues, https://github.com/frenck/probatio/issues
+Author-email: Franck Nijhof <opensource@frenck.dev>
+Maintainer-email: Franck Nijhof <opensource@frenck.dev>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: probatio,pytest,schema,testing,validation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Pytest
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Testing
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Requires-Dist: probatio>=0.1.0
+Requires-Dist: pytest>=8
+Description-Content-Type: text/markdown
+
+# pytest-probatio
+
+Use a [probatio](https://github.com/frenck/probatio) schema as a pytest assertion
+matcher. A schema reads as the expected shape, and a mismatch is explained by
+probatio's path-precise errors instead of a bare `assert`.
+
+```python
+from pytest_probatio import Exact, Partial
+from probatio import Port
+
+
+def test_response(response):
+    # Exact: extra keys make it unequal.
+    assert response == Exact({"name": str, "port": Port()})
+
+    # Partial: extra keys are allowed.
+    assert response == Partial({"name": str})
+    assert Exact({"name": str}) <= response
+```
+
+When the data does not match, the failure lists each error by its path:
+
+```
+data does not match the probatio schema (==):
+  data['port']: expected a port number between 1 and 65535
+```
+
+Install it alongside pytest; the plugin registers itself:
+
+```bash
+pip install pytest-probatio
+```
+
+This package lives in the probatio monorepo but ships separately, so the core
+`probatio` library stays dependency-free.

pytest_probatio-0.2.0/README.md

@@ -0,0 +1,35 @@
+# pytest-probatio
+
+Use a [probatio](https://github.com/frenck/probatio) schema as a pytest assertion
+matcher. A schema reads as the expected shape, and a mismatch is explained by
+probatio's path-precise errors instead of a bare `assert`.
+
+```python
+from pytest_probatio import Exact, Partial
+from probatio import Port
+
+
+def test_response(response):
+    # Exact: extra keys make it unequal.
+    assert response == Exact({"name": str, "port": Port()})
+
+    # Partial: extra keys are allowed.
+    assert response == Partial({"name": str})
+    assert Exact({"name": str}) <= response
+```
+
+When the data does not match, the failure lists each error by its path:
+
+```
+data does not match the probatio schema (==):
+  data['port']: expected a port number between 1 and 65535
+```
+
+Install it alongside pytest; the plugin registers itself:
+
+```bash
+pip install pytest-probatio
+```
+
+This package lives in the probatio monorepo but ships separately, so the core
+`probatio` library stays dependency-free.

pytest_probatio-0.2.0/pyproject.toml

@@ -0,0 +1,57 @@
+[build-system]
+requires = ["hatchling>=1.27,<2"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pytest-probatio"
+description = "Use a probatio schema as a pytest assertion matcher"
+readme = "README.md"
+requires-python = ">=3.13"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Franck Nijhof", email = "opensource@frenck.dev" }]
+maintainers = [{ name = "Franck Nijhof", email = "opensource@frenck.dev" }]
+keywords = ["pytest", "probatio", "validation", "schema", "testing"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Framework :: Pytest",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Software Development :: Testing",
+  "Typing :: Typed",
+]
+# Stays 0.0.0 in development; the release workflow stamps the real version from
+# the git tag at publish time, the same as the core package.
+version = "0.2.0"
+# Released lock-step with probatio (same version), but the matcher only uses
+# probatio's stable public surface, so a floor is enough rather than an exact pin.
+dependencies = ["probatio>=0.1.0", "pytest>=8"]
+
+[project.urls]
+Homepage = "https://github.com/frenck/probatio"
+Repository = "https://github.com/frenck/probatio"
+Issues = "https://github.com/frenck/probatio/issues"
+
+# Register the plugin so pytest loads its assertion-explaining hook automatically.
+[project.entry-points.pytest11]
+probatio = "pytest_probatio.plugin"
+
+[tool.uv.sources]
+# Always build against the in-repo core, not a published release.
+probatio = { workspace = true }
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pytest_probatio"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/pytest_probatio", "tests", "pyproject.toml", "README.md", "LICENSE"]
+
+# Self-contained test config: this package is not held to the core's 100%-coverage
+# gate, so it runs its own plain pytest rather than inheriting the root addopts.
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"

pytest_probatio-0.2.0/src/pytest_probatio/__init__.py

@@ -0,0 +1,7 @@
+"""pytest-probatio: use a probatio schema as a pytest assertion matcher."""
+
+from __future__ import annotations
+
+from pytest_probatio.plugin import Exact, Partial
+
+__all__ = ["Exact", "Partial"]

pytest_probatio-0.2.0/src/pytest_probatio/plugin.py

@@ -0,0 +1,149 @@
+"""Use a probatio schema as a pytest assertion matcher.
+
+``assert response == Exact({"name": str, "port": Port()})`` validates ``response``
+against the schema. On a mismatch, pytest's assertion rewriting calls the
+``pytest_assertrepr_compare`` hook below, which renders each probatio error by its
+path, so the failure points at the exact offending value instead of a bare
+``assert ... == ...``.
+
+Two matchers are exposed:
+
+- ``Exact(schema)``: extra dict keys make it unequal; ``<=`` relaxes that to a
+  partial match (extra keys allowed).
+- ``Partial(schema)``: a partial match under ``==`` (extra keys allowed).
+
+This lives outside the ``probatio`` package on purpose: the core library is
+dependency-free, and a pytest plugin is a test-framework concern.
+"""
+
+from __future__ import annotations
+
+import typing
+
+from probatio import ALLOW_EXTRA, PREVENT_EXTRA, Invalid, MultipleInvalid, Schema
+
+
+def _compile(schema: typing.Any, extra: int) -> Schema:
+    """Return ``schema`` as a ``Schema`` with the given extra-key policy.
+
+    A ready-made ``Schema`` (you can build one once and reuse it across tests) is
+    rebuilt with the requested policy, its underlying schema and ``required`` flag
+    preserved, so ``Exact`` and ``Partial`` control extra keys the same way whether
+    they are given a raw shape or a ``Schema``.
+    """
+    if isinstance(schema, Schema):
+        return Schema(schema.schema, required=schema.required, extra=extra)
+    return Schema(schema, extra=extra)
+
+
+class _Matcher:
+    """A schema that compares equal to data validating against it.
+
+    ``__eq__`` runs the schema and records the errors, so the assertion hook can
+    show them. It is not hashable (the recorded errors make it mutable), which also
+    keeps it out of places that expect a stable hash.
+    """
+
+    __slots__ = ("_errors", "_loose", "_strict", "_strict_eq")
+
+    def __init__(self, schema: typing.Any, *, partial: bool) -> None:
+        """Build the strict and partial schemas; ``partial`` picks which ``==`` uses."""
+        self._strict = _compile(schema, PREVENT_EXTRA)
+        self._loose = _compile(schema, ALLOW_EXTRA)
+        # ``Partial`` validates loosely under ``==``; ``Exact`` validates strictly.
+        self._strict_eq = not partial
+        self._errors: list[Invalid] = []
+
+    @property
+    def errors(self) -> list[Invalid]:
+        """The probatio errors from the most recent comparison (empty if it matched)."""
+        return self._errors
+
+    def _run(self, data: typing.Any, schema: Schema) -> bool:
+        """Validate ``data``, recording any errors, returning whether it matched."""
+        try:
+            schema(data)
+        except MultipleInvalid as exc:
+            self._errors = list(exc.errors)
+            return False
+        except Invalid as exc:
+            self._errors = [exc]
+            return False
+        self._errors = []
+        return True
+
+    def __eq__(self, data: object) -> bool:
+        """Whether ``data`` validates (strictly for ``Exact``, loosely for ``Partial``)."""
+        return self._run(data, self._strict if self._strict_eq else self._loose)
+
+    def __ne__(self, data: object) -> bool:
+        """Return the negation of ``__eq__``."""
+        return not self.__eq__(data)
+
+    def __le__(self, data: object) -> bool:
+        """Return a partial match: ``data`` validates with extra keys allowed."""
+        return self._run(data, self._loose)
+
+    def __ge__(self, data: object) -> bool:
+        """Support the reversed ``data <= matcher`` form (also a partial match)."""
+        return self._run(data, self._loose)
+
+    __hash__ = None  # type: ignore[assignment]
+
+    def __repr__(self) -> str:
+        """Render with the underlying schema, so a failing assert reads clearly."""
+        return f"{type(self).__name__}({self._strict.schema!r})"
+
+
+class Exact(_Matcher):
+    """A schema matcher: ``==`` requires an exact match, ``<=`` a partial one.
+
+    Exact means an extra dictionary key makes the data unequal; ``<=`` relaxes
+    that to allow extra keys, the same as ``Partial`` under ``==``.
+    """
+
+    def __init__(self, schema: typing.Any) -> None:
+        """Wrap ``schema`` as an exact-by-equality matcher."""
+        super().__init__(schema, partial=False)
+
+
+class Partial(_Matcher):
+    """A schema matcher whose ``==`` allows extra keys (a partial match)."""
+
+    def __init__(self, schema: typing.Any) -> None:
+        """Wrap ``schema`` as a partial-by-equality matcher."""
+        super().__init__(schema, partial=True)
+
+
+def _format_path(path: list[typing.Any]) -> str:
+    """Render an error path as ``data['a'][0]``, or ``<root>`` when empty."""
+    if not path:
+        return "<root>"
+    return "data" + "".join(f"[{segment!r}]" for segment in path)
+
+
+def pytest_assertrepr_compare(
+    op: str,
+    left: object,
+    right: object,
+) -> list[str] | None:
+    """Explain a failed schema comparison by listing each error with its path."""
+    if op not in ("==", "!=", "<=", ">="):
+        return None
+    if isinstance(left, _Matcher):
+        matcher: _Matcher = left
+    elif isinstance(right, _Matcher):
+        matcher = right
+    else:
+        return None
+    if not matcher.errors:
+        # A negated comparison (``!=``) that failed because the data *did* match.
+        return [
+            f"data matches the probatio schema, but the assertion ({op}) required it not to"
+        ]
+    lines = [f"data does not match the probatio schema ({op}):"]
+    lines.extend(
+        f"  {_format_path(error.path)}: {error.error_message or str(error)}"
+        for error in matcher.errors
+    )
+    return lines

pytest_probatio-0.2.0/tests/conftest.py

@@ -0,0 +1,3 @@
+"""Enable the pytester fixture for the end-to-end plugin test."""
+
+pytest_plugins = ["pytester"]

pytest_probatio-0.2.0/tests/test_matchers.py

@@ -0,0 +1,121 @@
+"""Tests for the probatio schema matchers and the assertion-explaining hook."""
+
+from __future__ import annotations
+
+from pytest_probatio import Exact, Partial
+from pytest_probatio.plugin import pytest_assertrepr_compare
+
+from probatio import Port
+
+
+def test_strict_match_passes() -> None:
+    """A value matching the schema exactly compares equal."""
+    assert {"name": "app", "port": 8080} == Exact({"name": str, "port": Port()})
+
+
+def test_strict_match_rejects_extra_keys() -> None:
+    """An extra key makes an Exact matcher unequal."""
+    assert {"name": "app", "extra": 1} != Exact({"name": str})
+
+
+def test_strict_match_rejects_a_bad_value() -> None:
+    """A value of the wrong type compares unequal."""
+    assert {"port": "nope"} != Exact({"port": Port()})
+
+
+def test_partial_allows_extra_keys() -> None:
+    """Partial accepts extra keys under ==."""
+    assert {"name": "app", "extra": 1} == Partial({"name": str})
+
+
+def test_accepts_a_prebuilt_schema() -> None:
+    """A ready-made Schema can be reused; Exact/Partial still govern extra keys."""
+    from probatio import Schema  # noqa: PLC0415
+
+    user = Schema({"id": int, "name": str})
+    assert {"id": 1, "name": "ada"} == Exact(user)
+    assert {"id": 1, "name": "ada", "extra": 1} != Exact(user)
+    assert {"id": 1, "name": "ada", "extra": 1} == Partial(user)
+
+
+def test_le_operator_is_a_partial_match() -> None:
+    """The <= operator relaxes Exact to a partial match (extra keys allowed)."""
+    assert Exact({"name": str}) <= {"name": "app", "extra": 1}
+
+
+def test_ge_operator_is_a_reversed_partial_match() -> None:
+    """Data on the left of <= reaches __ge__, still a partial match (extra keys allowed)."""
+    assert {"name": "app", "extra": 1} <= Exact({"name": str})
+
+
+def test_assertrepr_hook_explains_partial_match_operators() -> None:
+    """The hook renders explanations for the <= and >= operators, not just ==/!=."""
+    matcher = Exact({"port": Port()})
+    matcher <= {"port": "nope"}  # noqa: B015 - run the comparison to record errors
+    for op in ("<=", ">="):
+        lines = pytest_assertrepr_compare(op, matcher, {"port": "nope"})
+        assert lines is not None
+        assert any("data['port']" in line for line in lines)
+
+
+def test_matcher_records_errors_with_paths() -> None:
+    """A failed comparison records probatio errors carrying the offending path."""
+    matcher = Exact({"server": {"port": Port()}})
+    assert {"server": {"port": 70000}} != matcher
+    assert matcher.errors
+    assert matcher.errors[0].path == ["server", "port"]
+
+
+def test_assertrepr_hook_lists_errors_by_path() -> None:
+    """The pytest hook renders each error as a path and message."""
+    matcher = Exact({"port": Port()})
+    matcher == {"port": "nope"}  # noqa: B015 - run the comparison to record errors
+    lines = pytest_assertrepr_compare("==", matcher, {"port": "nope"})
+    assert lines is not None
+    assert any("data['port']" in line for line in lines)
+
+
+def test_assertrepr_hook_ignores_unrelated_comparisons() -> None:
+    """The hook returns None when neither side is a matcher (no interference)."""
+    assert pytest_assertrepr_compare("==", 1, 2) is None
+
+
+def test_assertrepr_hook_explains_a_failed_negation() -> None:
+    """A failed `!=` (the data did match) gets a clear, non-contradictory message."""
+    matcher = Exact({"id": int})
+    matcher != {"id": 1}  # noqa: B015 - the data matches, so != fails; records no errors
+    lines = pytest_assertrepr_compare("!=", matcher, {"id": 1})
+    assert lines is not None
+    assert lines == [
+        "data matches the probatio schema, but the assertion (!=) required it not to"
+    ]
+
+
+def test_matcher_is_unhashable() -> None:
+    """The matcher is not hashable, since it records mutable error state."""
+    import pytest  # noqa: PLC0415
+
+    with pytest.raises(TypeError):
+        hash(Exact({"a": int}))
+
+
+def test_plugin_explains_a_failed_assertion_end_to_end(pytester) -> None:
+    """A failing `data == Exact(...)` under pytest shows the schema error, via the hook.
+
+    This exercises the registered pytest11 plugin, not just the hook function: the
+    entry point must be active for the explanation to appear in a real run.
+    """
+    pytester.makepyfile(
+        """
+        from pytest_probatio import Exact
+        from probatio import Port
+
+        def test_response():
+            assert {"port": "nope"} == Exact({"port": Port()})
+        """
+    )
+    result = pytester.runpytest()
+    result.assert_outcomes(failed=1)
+    output = result.stdout.str()
+    assert "does not match the probatio schema" in output
+    assert "data['port']" in output