pytest-probatio 0.2.0__py3-none-any.whl

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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,8 @@
+pytest_probatio/__init__.py,sha256=s-S0nBcMm4wXs81cn9IYHFP6MNJPACmPjKPozAgTxlc,195
+pytest_probatio/plugin.py,sha256=mXNR0lG5OQC_JKhWioUqg7FzCEKgmayL7v1_1yGGyu4,5600
+pytest_probatio/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pytest_probatio-0.2.0.dist-info/METADATA,sha256=qKB2-ADAgfIueEMcURO26jYX4-7wQsecIkQ1_qX-UQg,2069
+pytest_probatio-0.2.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+pytest_probatio-0.2.0.dist-info/entry_points.txt,sha256=-3C_rZOBSZPp9mqG-exojMsjiZTYDFgqkjn4naPq9oQ,45
+pytest_probatio-0.2.0.dist-info/licenses/LICENSE,sha256=xey_9Ex7UIJ45DSFo_Gzo0HN_fsyUJ6ANF2SKQDwaJA,1070
+pytest_probatio-0.2.0.dist-info/RECORD,,

pytest_probatio-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

pytest_probatio-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[pytest11]
+probatio = pytest_probatio.plugin

pytest_probatio-0.2.0.dist-info/licenses/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.