lawcheck 0.2.0__py3-none-any.whl

lawcheck/__init__.py

@@ -0,0 +1,126 @@
+"""lawcheck: property-based algebraic law testing for Python.
+
+Provides ready-made Hypothesis law suites for algebraic structures
+(semigroup, monoid, commutative, functor, applicative, monad) with a pluggable
+equality oracle. The equality oracle is always explicit; there is no default
+``eq`` parameter anywhere in lawcheck.
+
+Public API
+----------
+Pure primitives (deterministic, no Hypothesis):
+
+    holds_associative, assert_associative
+    holds_left_identity, assert_left_identity
+    holds_right_identity, assert_right_identity
+    holds_commutative, assert_commutative
+    holds_functor_identity, assert_functor_identity
+    holds_functor_composition, assert_functor_composition
+    holds_applicative_identity, assert_applicative_identity
+    holds_applicative_homomorphism, assert_applicative_homomorphism
+    holds_applicative_interchange, assert_applicative_interchange
+    holds_applicative_composition, assert_applicative_composition
+    holds_monad_left_identity, assert_monad_left_identity
+    holds_monad_right_identity, assert_monad_right_identity
+    holds_monad_associativity, assert_monad_associativity
+
+Hypothesis runners (search for counterexamples):
+
+    verify_semigroup
+    verify_monoid
+    verify_commutative
+    verify_functor
+    verify_applicative
+    verify_monad
+
+Equality oracle helpers:
+
+    value_eq
+    by_repr_eq
+    normalized_eq
+    lifted_eq
+"""
+
+from __future__ import annotations
+
+from lawcheck.oracle import by_repr_eq, lifted_eq, normalized_eq, value_eq
+from lawcheck.primitives import (
+    assert_applicative_composition,
+    assert_applicative_homomorphism,
+    assert_applicative_identity,
+    assert_applicative_interchange,
+    assert_associative,
+    assert_commutative,
+    assert_functor_composition,
+    assert_functor_identity,
+    assert_left_identity,
+    assert_monad_associativity,
+    assert_monad_left_identity,
+    assert_monad_right_identity,
+    assert_right_identity,
+    holds_applicative_composition,
+    holds_applicative_homomorphism,
+    holds_applicative_identity,
+    holds_applicative_interchange,
+    holds_associative,
+    holds_commutative,
+    holds_functor_composition,
+    holds_functor_identity,
+    holds_left_identity,
+    holds_monad_associativity,
+    holds_monad_left_identity,
+    holds_monad_right_identity,
+    holds_right_identity,
+)
+from lawcheck.runners import (
+    verify_applicative,
+    verify_commutative,
+    verify_functor,
+    verify_monad,
+    verify_monoid,
+    verify_semigroup,
+)
+
+__all__ = [
+    # primitives - holds_*
+    "holds_associative",
+    "holds_left_identity",
+    "holds_right_identity",
+    "holds_commutative",
+    "holds_functor_identity",
+    "holds_functor_composition",
+    "holds_applicative_identity",
+    "holds_applicative_homomorphism",
+    "holds_applicative_interchange",
+    "holds_applicative_composition",
+    "holds_monad_left_identity",
+    "holds_monad_right_identity",
+    "holds_monad_associativity",
+    # primitives - assert_*
+    "assert_associative",
+    "assert_left_identity",
+    "assert_right_identity",
+    "assert_commutative",
+    "assert_functor_identity",
+    "assert_functor_composition",
+    "assert_applicative_identity",
+    "assert_applicative_homomorphism",
+    "assert_applicative_interchange",
+    "assert_applicative_composition",
+    "assert_monad_left_identity",
+    "assert_monad_right_identity",
+    "assert_monad_associativity",
+    # runners
+    "verify_semigroup",
+    "verify_monoid",
+    "verify_commutative",
+    "verify_functor",
+    "verify_applicative",
+    "verify_monad",
+    # oracle helpers
+    "value_eq",
+    "by_repr_eq",
+    "normalized_eq",
+    "lifted_eq",
+]
+
+__version__ = "0.2.0"

lawcheck/_types.py

@@ -0,0 +1,23 @@
+"""Shared type aliases used across lawcheck."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TypeVar
+
+T = TypeVar("T")
+A = TypeVar("A")
+B = TypeVar("B")
+C = TypeVar("C")
+
+# A binary operation on a carrier type.
+BinOp = Callable[[T, T], T]
+
+# An equality predicate for a carrier type.
+EqFn = Callable[[T, T], bool]
+
+# A unary map from A to B.
+MapFn = Callable[[A], B]
+
+# A function returning a functor/applicative/monad value.
+# These are left as generic Callable to avoid hard-coding structure types here.

lawcheck/oracle.py

@@ -0,0 +1,119 @@
+"""Equality oracle helpers.
+
+The equality-oracle problem
+----------------------------
+Every law in lawcheck requires an explicit ``eq: Callable[[T, T], bool]``
+argument. There is no default. This is intentional.
+
+For plain value types (int, str, tuple, frozenset), Python's built-in ``==``
+via ``operator.eq`` is correct. But for many types that benefit most from
+algebraic law testing, ``==`` is meaningless or absent:
+
+- Effects and IO wrappers (e.g. ``IO[A]``) are functions; two separately
+  constructed ``IO`` values are never ``==`` even if they produce the same
+  result.
+- Async values (``Coroutine``, ``Task``) have no structural equality.
+- Custom containers may intentionally omit ``__eq__`` (avoiding accidental
+  hashing bugs).
+- Lazy sequences compare equal only after materialization.
+
+The cats-effect Scala library confronted this exactly: without a formal
+``Eq[A]`` type class, law testing for ``IO`` was impossible. Their solution
+was a ``TestContext`` that runs effects and compares outcomes. lawcheck makes
+the oracle explicit so you can supply the right comparison for your type.
+
+This module provides:
+
+- ``value_eq``: wraps ``==``; correct for int, str, list, etc.
+- ``by_repr_eq``: compares repr strings; useful for debugging, NOT for
+  production law testing (repr can collide).
+- ``normalized_eq``: compares after applying a normalization function; useful
+  for types with multiple canonical representations (e.g. rational numbers).
+- ``lifted_eq``: lifts an element-level eq to a container by unwrapping;
+  suitable for simple single-value wrappers.
+
+None of these are ever injected as a default. They are offered as documented
+starting points.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TypeVar
+
+T = TypeVar("T")
+A = TypeVar("A")
+
+
+def value_eq(a: T, b: T) -> bool:
+    """Equality via Python's built-in ``==``.
+
+    Correct for int, str, list, tuple, frozenset, and any type that properly
+    implements ``__eq__``. Wrong for effects, async types, and custom containers
+    that intentionally omit ``__eq__``.
+    """
+    return bool(a == b)
+
+
+def by_repr_eq(a: T, b: T) -> bool:
+    """Equality by comparing ``repr`` strings.
+
+    Useful for quick debugging. NOT suitable for production law testing: repr
+    can collide (different objects producing the same repr) or differ for
+    logically equal objects.
+    """
+    return repr(a) == repr(b)
+
+
+def normalized_eq(
+    normalize: Callable[[T], A],
+) -> Callable[[T, T], bool]:
+    """Return an equality predicate that compares via a normalization function.
+
+    Parameters
+    ----------
+    normalize:
+        A function that maps the carrier type to a canonical form. Two values
+        are considered equal iff their normalized forms are equal under ``==``.
+
+    Example
+    -------
+    For a ``Fraction``-like type that can represent 1/2 and 2/4 as distinct
+    objects::
+
+        eq = normalized_eq(lambda f: (f.numerator // gcd, f.denominator // gcd))
+        holds_associative(add_fraction, a, b, c, eq=eq)
+    """
+
+    def _eq(a: T, b: T) -> bool:
+        return bool(normalize(a) == normalize(b))
+
+    return _eq
+
+
+def lifted_eq(
+    unwrap: Callable[[T], A],
+    inner_eq: Callable[[A, A], bool],
+) -> Callable[[T, T], bool]:
+    """Return an equality predicate for a wrapper type by unwrapping first.
+
+    Parameters
+    ----------
+    unwrap:
+        A function that extracts the inner value from the wrapper.
+    inner_eq:
+        Equality for the inner type.
+
+    Example
+    -------
+    For a simple ``Box(value)`` wrapper where law testing compares the
+    contained values::
+
+        eq = lifted_eq(lambda box: box.value, operator.eq)
+        verify_monoid(box_concat, Box(""), strategy=..., eq=eq)
+    """
+
+    def _eq(a: T, b: T) -> bool:
+        return inner_eq(unwrap(a), unwrap(b))
+
+    return _eq