lawcheck 0.2.0__tar.gz

lawcheck-0.2.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,26 @@
+---
+name: Bug report
+about: Report a bug in lawcheck
+title: "[bug] "
+labels: bug
+---
+
+**Describe the bug**
+A clear description of what the bug is.
+
+**Minimal reproducer**
+```python
+# Paste the smallest code that triggers the bug
+```
+
+**Expected behavior**
+What you expected to happen.
+
+**Actual behavior**
+What actually happened, including any tracebacks.
+
+**Environment**
+- lawcheck version:
+- Python version:
+- hypothesis version:
+- OS:

lawcheck-0.2.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,17 @@
+---
+name: Feature request
+about: Suggest a new law suite or improvement
+title: "[feature] "
+labels: enhancement
+---
+
+**What algebraic law or feature would you like added?**
+Describe the law and why it would be useful.
+
+**Example usage**
+```python
+# How would you use this feature?
+```
+
+**Are you willing to implement it?**
+Yes / No / Maybe.

lawcheck-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,22 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - run: pip install -e ".[dev]"
+      - run: ruff check .
+      - run: mypy src
+      - run: pytest -q

lawcheck-0.2.0/.gitignore

@@ -0,0 +1,40 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg
+*.egg-info/
+dist/
+build/
+.eggs/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.hypothesis/
+*.coverage
+.coverage
+htmlcov/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Distribution / packaging
+*.tar.gz
+*.whl
+
+# Editor
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# uv lockfile (library: not committed)
+uv.lock

lawcheck-0.2.0/CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog
+
+All notable changes to lawcheck are documented in this file.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+lawcheck uses [semantic versioning](https://semver.org/).
+
+## [0.2.0] - 2026-06-17
+
+### Added
+
+- Applicative laws: four pure primitives (`holds_applicative_identity`,
+  `holds_applicative_homomorphism`, `holds_applicative_interchange`,
+  `holds_applicative_composition`) and their `assert_*` counterparts.
+- `verify_applicative` Hypothesis runner: verifies all four applicative laws
+  given `pure`, `ap`, a homomorphism function, and three strategies.
+- The applicative law suite accepts `pure: Callable[[object], object]` and
+  `ap: Callable[[object, object], object]`, consistent with the existing
+  functor/monad object-typed signatures.
+- `eq` is required everywhere; no default.
+- Meta-tests: Maybe extended with `maybe_pure` and `maybe_ap`; lawful Maybe
+  passes all four laws; `broken_ap` (always returns Nothing) is caught by
+  identity and homomorphism; custom eq oracle is honored.
+
+### Note
+
+PyPI publication is pending new-project quota approval. The dist artifact
+is built and twine-checked; publication will proceed once the quota clears.
+
+## [0.1.0] - 2026-06-17
+
+### Added
+
+- Pure assertion primitives for semigroup, monoid, commutativity, functor, and monad laws.
+- Hypothesis-powered runners: `verify_semigroup`, `verify_monoid`, `verify_commutative`, `verify_functor`, `verify_monad`.
+- Pluggable equality oracle: `eq` is required everywhere, no default.
+- Oracle helpers: `value_eq`, `by_repr_eq`, `normalized_eq`, `lifted_eq`.
+- Self-verifying meta-tests: lawful structures pass, unlawful structures are caught.
+- Full strict mypy typing, `py.typed` marker.
+- Example script (`examples/int_monoid.py`) demonstrating both layers.
+- CI: pytest, ruff, mypy on Python 3.10-3.13.

lawcheck-0.2.0/CLAUDE.md

@@ -0,0 +1,69 @@
+# lawcheck - CLAUDE.md
+
+## Project overview
+
+lawcheck is a property-based algebraic law testing library for Python. It provides ready-made Hypothesis law suites for semigroups, monoids, commutative structures, functors, and monads, with a pluggable equality oracle. The equality oracle is the central design point: `eq` is always required, never defaulted.
+
+## Stack
+
+- Python 3.10+
+- Build: hatchling, src layout
+- Runtime dep: hypothesis only
+- Dev: pytest, ruff, mypy
+- Package manager: uv
+
+## Commands
+
+```bash
+uv venv
+uv pip install -e ".[dev]"
+uv run pytest -q
+uv run ruff check .
+uv run mypy src
+uv build
+uv run --with twine twine check dist/*
+```
+
+## Module layout
+
+```
+src/lawcheck/
+    __init__.py      # public API, __all__
+    _types.py        # TypeVar aliases
+    primitives.py    # holds_* and assert_* (no Hypothesis)
+    runners.py       # verify_* (Hypothesis-powered)
+    oracle.py        # equality oracle helpers
+    py.typed
+tests/
+    maybe.py         # minimal Maybe type for tests only
+    conftest.py      # Hypothesis profile
+    test_semigroup.py
+    test_monoid.py
+    test_commutative.py
+    test_functor.py
+    test_monad.py
+    test_oracle.py
+examples/
+    int_monoid.py
+```
+
+## Key design rules
+
+1. `eq` is required at every call site; no default.
+2. No default parameter values anywhere. Use a second named function instead.
+3. Pure primitives (`holds_*`, `assert_*`) in primitives.py; Hypothesis runners (`verify_*`) in runners.py.
+4. No em dash characters anywhere.
+5. Strict mypy, ruff clean.
+6. Git author: Amaar Chughtai, no Co-authored-by trailers.
+
+## Adding a new law suite
+
+1. Add `holds_*` and `assert_*` to `primitives.py`.
+2. Add `verify_*` to `runners.py`.
+3. Export from `__init__.py`, add to `__all__`.
+4. Add meta-tests: one lawful pass, one unlawful fail.
+
+## Deferred
+
+- Applicative laws (next addition after v0.1.0).
+- pytest plugin for auto law collection.

lawcheck-0.2.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,28 @@
+# Code of Conduct
+
+## Our Pledge
+
+We as contributors and maintainers pledge to make participation in lawcheck a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experiences
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+
+Examples of unacceptable behavior:
+
+- Harassment, insults, or derogatory comments
+- Publishing private information without explicit permission
+- Other conduct that could reasonably be considered inappropriate
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by opening an issue or contacting the maintainers directly. All complaints will be reviewed and investigated promptly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1.

lawcheck-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,36 @@
+# Contributing
+
+Contributions are welcome. Please open an issue first to discuss significant changes.
+
+## Setup
+
+```
+git clone https://github.com/amaar-mc/lawcheck
+cd lawcheck
+uv venv
+uv pip install -e ".[dev]"
+```
+
+## Running checks
+
+```
+uv run pytest -q
+uv run ruff check .
+uv run mypy src
+```
+
+All three must pass before opening a pull request.
+
+## Adding a new law suite
+
+1. Add pure `holds_*` and `assert_*` primitives to `src/lawcheck/primitives.py`.
+2. Add a `verify_*` runner to `src/lawcheck/runners.py`.
+3. Export from `src/lawcheck/__init__.py` and add to `__all__`.
+4. Add meta-tests: at least one lawful case and one unlawful case.
+
+## Style
+
+- Python 3.10+, strict mypy, ruff.
+- No default parameter values. Provide a second named function where ergonomics require it.
+- No em dash characters in code, comments, or commit messages.
+- Commit format: `type(scope): description`.

lawcheck-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Amaar Chughtai
+
+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.

lawcheck-0.2.0/PKG-INFO

@@ -0,0 +1,185 @@
+Metadata-Version: 2.4
+Name: lawcheck
+Version: 0.2.0
+Summary: Property-based algebraic law testing for Python: Hypothesis-driven law suites for semigroups, monoids, functors, applicatives, and monads, with a pluggable equality oracle.
+Project-URL: Homepage, https://github.com/amaar-mc/lawcheck
+Project-URL: Repository, https://github.com/amaar-mc/lawcheck
+Project-URL: Issues, https://github.com/amaar-mc/lawcheck/issues
+Project-URL: Changelog, https://github.com/amaar-mc/lawcheck/blob/main/CHANGELOG.md
+Author-email: Amaar Chughtai <amaardevx@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Amaar Chughtai
+        
+        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.
+License-File: LICENSE
+Keywords: algebra,applicative,functor,hypothesis,laws,monad,monoid,property-based-testing,semigroup,testing
+Classifier: Development Status :: 4 - Beta
+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.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Testing
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: hypothesis>=6.0.0
+Provides-Extra: dev
+Requires-Dist: hypothesis>=6.0.0; extra == 'dev'
+Requires-Dist: mypy>=1.9.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# lawcheck
+
+<p align="center">
+  <img src="assets/logo.png" alt="lawcheck logo" width="160">
+</p>
+
+Property-based algebraic law testing for Python. Ready-made [Hypothesis](https://hypothesis.readthedocs.io) law suites for semigroups, monoids, commutative structures, functors, applicatives, and monads, with a pluggable equality oracle.
+
+## The problem
+
+Algebraic laws (associativity, identity, functor composition, monad associativity) are easy to state but hard to test systematically. You want Hypothesis to search for counterexamples, not to write the laws yourself every time.
+
+The bigger problem: **what does "equal" mean for your type?**
+
+For `int` it's obvious. For `IO[A]`, `Task`, async wrappers, or any effectful type, two logically equal values are often physically distinct objects. Python's `==` is wrong or absent. The [cats-effect](https://typelevel.org/cats-effect/) Scala library confronted this exactly and introduced a formal `Eq` type-class hierarchy. lawcheck asks you to supply `eq` explicitly so the meaning of "equal" is always unambiguous.
+
+## Install
+
+```
+pip install lawcheck
+```
+
+Sole runtime dependency: `hypothesis`.
+
+## Usage
+
+### Layer 1: pure primitives (no Hypothesis, deterministic)
+
+```python
+import operator
+from lawcheck import holds_associative, assert_associative
+
+# Check one triple
+holds_associative(operator.add, 1, 2, 3, eq=operator.eq)  # True
+holds_associative(operator.sub, 1, 2, 3, eq=operator.eq)  # False
+
+# Assert or raise with a precise message
+assert_associative(operator.sub, 1, 2, 3, eq=operator.eq)
+# AssertionError: Associativity violated: (op(1, 2)) op 3 = -4, but 1 op (op(2, 3)) = 2
+```
+
+### Layer 2: Hypothesis runners (search for counterexamples)
+
+```python
+import operator
+from hypothesis import strategies as st
+from lawcheck import verify_monoid, verify_commutative, verify_semigroup
+
+# Passes for int addition (associative, left and right identity at 0, commutative)
+verify_monoid(operator.add, 0, strategy=st.integers(), eq=operator.eq)
+verify_commutative(operator.add, strategy=st.integers(), eq=operator.eq)
+
+# Finds a counterexample for subtraction
+verify_semigroup(operator.sub, strategy=st.integers(), eq=operator.eq)
+# Raises with Hypothesis's shrunk minimal counterexample
+```
+
+### Functor, applicative, and monad laws
+
+```python
+from lawcheck import verify_functor, verify_applicative, verify_monad
+
+# fmap: (f: A -> B, fa: F[A]) -> F[B]
+verify_functor(
+    my_fmap,
+    f=lambda x: x * 2,
+    g=lambda x: x + 1,
+    strategy=my_strategy,
+    eq=my_eq,
+)
+
+# pure: A -> F[A];  ap: (F[A -> B], F[A]) -> F[B]
+verify_applicative(
+    my_pure,
+    my_ap,
+    lambda x: x * 2,
+    value_strategy=st.integers(),
+    functor_strategy=my_fa_strategy,
+    ap_strategy=my_fn_strategy,
+    eq=my_eq,
+)
+
+verify_monad(
+    ret=my_return,
+    bind=my_bind,
+    f_arrow=lambda x: my_return(x + 1),
+    g_arrow=lambda x: my_return(x * 2),
+    strategy=st.integers(),
+    monad_strategy=my_monad_strategy,
+    eq=my_eq,
+)
+```
+
+### Pluggable equality oracle
+
+```python
+from lawcheck import normalized_eq, lifted_eq, value_eq
+
+# Compare after normalization (e.g. abs value, canonical form)
+abs_eq = normalized_eq(abs)
+
+# Unwrap a container and compare inner values
+box_eq = lifted_eq(lambda b: b.value, operator.eq)
+
+# Plain == (correct for ints, strings, lists)
+value_eq(1, 1)  # True
+```
+
+## Laws implemented
+
+| Structure | Laws |
+|-----------|------|
+| Semigroup | Associativity: `(a op b) op c == a op (b op c)` |
+| Monoid | Associativity + left identity + right identity |
+| Commutative | `a op b == b op a` |
+| Functor | Identity: `fmap(id) == id`; Composition: `fmap(f.g) == fmap(f).fmap(g)` |
+| Applicative | Identity: `ap(pure(id), v) == v`; Homomorphism: `ap(pure(f), pure(x)) == pure(f(x))`; Interchange: `ap(u, pure(y)) == ap(pure(lambda f: f(y)), u)`; Composition: `ap(ap(ap(pure(compose), u), v), w) == ap(u, ap(v, w))` |
+| Monad | Left identity, right identity, associativity of bind |
+
+## The `eq` parameter is required everywhere
+
+lawcheck has no default for `eq`. Where ergonomics would tempt a default, there is an explicit second function instead (e.g., `value_eq` for plain types). This is by design: the cats-effect equality-oracle problem is real, and baking in `==` would silently produce wrong answers for effects, async types, and custom containers.
+
+See [`docs/architecture.md`](docs/architecture.md) for the full design rationale.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).
+
+## License
+
+MIT. See [LICENSE](LICENSE).

lawcheck-0.2.0/README.md

@@ -0,0 +1,132 @@
+# lawcheck
+
+<p align="center">
+  <img src="assets/logo.png" alt="lawcheck logo" width="160">
+</p>
+
+Property-based algebraic law testing for Python. Ready-made [Hypothesis](https://hypothesis.readthedocs.io) law suites for semigroups, monoids, commutative structures, functors, applicatives, and monads, with a pluggable equality oracle.
+
+## The problem
+
+Algebraic laws (associativity, identity, functor composition, monad associativity) are easy to state but hard to test systematically. You want Hypothesis to search for counterexamples, not to write the laws yourself every time.
+
+The bigger problem: **what does "equal" mean for your type?**
+
+For `int` it's obvious. For `IO[A]`, `Task`, async wrappers, or any effectful type, two logically equal values are often physically distinct objects. Python's `==` is wrong or absent. The [cats-effect](https://typelevel.org/cats-effect/) Scala library confronted this exactly and introduced a formal `Eq` type-class hierarchy. lawcheck asks you to supply `eq` explicitly so the meaning of "equal" is always unambiguous.
+
+## Install
+
+```
+pip install lawcheck
+```
+
+Sole runtime dependency: `hypothesis`.
+
+## Usage
+
+### Layer 1: pure primitives (no Hypothesis, deterministic)
+
+```python
+import operator
+from lawcheck import holds_associative, assert_associative
+
+# Check one triple
+holds_associative(operator.add, 1, 2, 3, eq=operator.eq)  # True
+holds_associative(operator.sub, 1, 2, 3, eq=operator.eq)  # False
+
+# Assert or raise with a precise message
+assert_associative(operator.sub, 1, 2, 3, eq=operator.eq)
+# AssertionError: Associativity violated: (op(1, 2)) op 3 = -4, but 1 op (op(2, 3)) = 2
+```
+
+### Layer 2: Hypothesis runners (search for counterexamples)
+
+```python
+import operator
+from hypothesis import strategies as st
+from lawcheck import verify_monoid, verify_commutative, verify_semigroup
+
+# Passes for int addition (associative, left and right identity at 0, commutative)
+verify_monoid(operator.add, 0, strategy=st.integers(), eq=operator.eq)
+verify_commutative(operator.add, strategy=st.integers(), eq=operator.eq)
+
+# Finds a counterexample for subtraction
+verify_semigroup(operator.sub, strategy=st.integers(), eq=operator.eq)
+# Raises with Hypothesis's shrunk minimal counterexample
+```
+
+### Functor, applicative, and monad laws
+
+```python
+from lawcheck import verify_functor, verify_applicative, verify_monad
+
+# fmap: (f: A -> B, fa: F[A]) -> F[B]
+verify_functor(
+    my_fmap,
+    f=lambda x: x * 2,
+    g=lambda x: x + 1,
+    strategy=my_strategy,
+    eq=my_eq,
+)
+
+# pure: A -> F[A];  ap: (F[A -> B], F[A]) -> F[B]
+verify_applicative(
+    my_pure,
+    my_ap,
+    lambda x: x * 2,
+    value_strategy=st.integers(),
+    functor_strategy=my_fa_strategy,
+    ap_strategy=my_fn_strategy,
+    eq=my_eq,
+)
+
+verify_monad(
+    ret=my_return,
+    bind=my_bind,
+    f_arrow=lambda x: my_return(x + 1),
+    g_arrow=lambda x: my_return(x * 2),
+    strategy=st.integers(),
+    monad_strategy=my_monad_strategy,
+    eq=my_eq,
+)
+```
+
+### Pluggable equality oracle
+
+```python
+from lawcheck import normalized_eq, lifted_eq, value_eq
+
+# Compare after normalization (e.g. abs value, canonical form)
+abs_eq = normalized_eq(abs)
+
+# Unwrap a container and compare inner values
+box_eq = lifted_eq(lambda b: b.value, operator.eq)
+
+# Plain == (correct for ints, strings, lists)
+value_eq(1, 1)  # True
+```
+
+## Laws implemented
+
+| Structure | Laws |
+|-----------|------|
+| Semigroup | Associativity: `(a op b) op c == a op (b op c)` |
+| Monoid | Associativity + left identity + right identity |
+| Commutative | `a op b == b op a` |
+| Functor | Identity: `fmap(id) == id`; Composition: `fmap(f.g) == fmap(f).fmap(g)` |
+| Applicative | Identity: `ap(pure(id), v) == v`; Homomorphism: `ap(pure(f), pure(x)) == pure(f(x))`; Interchange: `ap(u, pure(y)) == ap(pure(lambda f: f(y)), u)`; Composition: `ap(ap(ap(pure(compose), u), v), w) == ap(u, ap(v, w))` |
+| Monad | Left identity, right identity, associativity of bind |
+
+## The `eq` parameter is required everywhere
+
+lawcheck has no default for `eq`. Where ergonomics would tempt a default, there is an explicit second function instead (e.g., `value_eq` for plain types). This is by design: the cats-effect equality-oracle problem is real, and baking in `==` would silently produce wrong answers for effects, async types, and custom containers.
+
+See [`docs/architecture.md`](docs/architecture.md) for the full design rationale.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).
+
+## License
+
+MIT. See [LICENSE](LICENSE).

lawcheck-0.2.0/SECURITY.md

@@ -0,0 +1,13 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported |
+|---------|-----------|
+| 0.1.x   | Yes       |
+
+## Reporting a Vulnerability
+
+lawcheck is a testing utility library with no network access, no credential handling, and no execution of untrusted code. Security vulnerabilities are unlikely but not impossible (e.g., a dependency vulnerability in hypothesis).
+
+To report a vulnerability, open a GitHub issue marked "security" or contact the maintainer at amaardevx@gmail.com. You will receive a response within 7 days.