contractme 2.0.0__tar.gz → 2.2.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (67) hide show
  1. {contractme-2.0.0 → contractme-2.2.0}/.gitlab-ci.yml +17 -12
  2. contractme-2.2.0/.pre-commit-config.yaml +27 -0
  3. {contractme-2.0.0 → contractme-2.2.0}/.vscode/settings.json +1 -1
  4. {contractme-2.0.0 → contractme-2.2.0}/CHANGELOG.md +22 -0
  5. {contractme-2.0.0 → contractme-2.2.0}/CLAUDE.md +76 -42
  6. {contractme-2.0.0 → contractme-2.2.0}/PKG-INFO +57 -22
  7. {contractme-2.0.0 → contractme-2.2.0}/README.md +56 -21
  8. contractme-2.2.0/context7.json +4 -0
  9. contractme-2.2.0/docs/comparison.md +265 -0
  10. contractme-2.2.0/justfile +70 -0
  11. {contractme-2.0.0 → contractme-2.2.0}/pyproject.toml +4 -2
  12. contractme-2.2.0/release_notes.md +7 -0
  13. {contractme-2.0.0 → contractme-2.2.0}/src/contractme/__init__.py +9 -2
  14. {contractme-2.0.0 → contractme-2.2.0}/src/contractme/annotations.py +3 -3
  15. {contractme-2.0.0 → contractme-2.2.0}/src/contractme/contracting.py +10 -0
  16. contractme-2.2.0/src/contractme/probing.py +119 -0
  17. {contractme-2.0.0 → contractme-2.2.0}/src/contractme/records.py +7 -31
  18. {contractme-2.0.0 → contractme-2.2.0}/src/contractme/skills/contractme/SKILL.md +78 -12
  19. {contractme-2.0.0 → contractme-2.2.0}/src/contractme/typecheck.py +21 -6
  20. {contractme-2.0.0 → contractme-2.2.0}/src/contractme/typeshape.py +17 -4
  21. {contractme-2.0.0 → contractme-2.2.0}/tests/test_annotations.py +28 -1
  22. contractme-2.2.0/tests/test_layering.py +107 -0
  23. contractme-2.2.0/tests/test_probing.py +101 -0
  24. {contractme-2.0.0 → contractme-2.2.0}/tests/test_records.py +18 -14
  25. {contractme-2.0.0 → contractme-2.2.0}/tests/test_typechecks.py +12 -1
  26. {contractme-2.0.0 → contractme-2.2.0}/tests/test_typeshape.py +25 -1
  27. {contractme-2.0.0 → contractme-2.2.0}/uv.lock +27 -1
  28. contractme-2.0.0/.pre-commit-config.yaml +0 -31
  29. contractme-2.0.0/docs/comparison.md +0 -190
  30. contractme-2.0.0/release_notes.md +0 -87
  31. {contractme-2.0.0 → contractme-2.2.0}/.flake8 +0 -0
  32. {contractme-2.0.0 → contractme-2.2.0}/.gitignore +0 -0
  33. {contractme-2.0.0 → contractme-2.2.0}/.python-version +0 -0
  34. {contractme-2.0.0 → contractme-2.2.0}/LICENSE +0 -0
  35. {contractme-2.0.0 → contractme-2.2.0}/docs/types.md +0 -0
  36. {contractme-2.0.0 → contractme-2.2.0}/release/prerelease.py +0 -0
  37. {contractme-2.0.0 → contractme-2.2.0}/release/pypi_mint_token.py +0 -0
  38. {contractme-2.0.0 → contractme-2.2.0}/release/release_notes.py +0 -0
  39. {contractme-2.0.0 → contractme-2.2.0}/src/contractme/config.py +0 -0
  40. {contractme-2.0.0 → contractme-2.2.0}/src/contractme/policy.py +0 -0
  41. {contractme-2.0.0 → contractme-2.2.0}/src/contractme/py.typed +0 -0
  42. {contractme-2.0.0 → contractme-2.2.0}/src/contractme/result.py +0 -0
  43. {contractme-2.0.0 → contractme-2.2.0}/src/contractme/testing.py +0 -0
  44. {contractme-2.0.0 → contractme-2.2.0}/src/contractme/types/__init__.py +0 -0
  45. {contractme-2.0.0 → contractme-2.2.0}/src/contractme/types/containers.py +0 -0
  46. {contractme-2.0.0 → contractme-2.2.0}/src/contractme/types/data.py +0 -0
  47. {contractme-2.0.0 → contractme-2.2.0}/src/contractme/types/identifiers.py +0 -0
  48. {contractme-2.0.0 → contractme-2.2.0}/src/contractme/types/network.py +0 -0
  49. {contractme-2.0.0 → contractme-2.2.0}/src/contractme/types/numeric.py +0 -0
  50. {contractme-2.0.0 → contractme-2.2.0}/src/contractme/types/paths.py +0 -0
  51. {contractme-2.0.0 → contractme-2.2.0}/src/contractme/types/predicates.py +0 -0
  52. {contractme-2.0.0 → contractme-2.2.0}/src/contractme/types/system.py +0 -0
  53. {contractme-2.0.0 → contractme-2.2.0}/src/contractme/types/temporal.py +0 -0
  54. {contractme-2.0.0 → contractme-2.2.0}/src/contractme/types/text.py +0 -0
  55. {contractme-2.0.0 → contractme-2.2.0}/tests/conftest.py +0 -0
  56. {contractme-2.0.0 → contractme-2.2.0}/tests/test_annotations_future.py +0 -0
  57. {contractme-2.0.0 → contractme-2.2.0}/tests/test_canaries.py +0 -0
  58. {contractme-2.0.0 → contractme-2.2.0}/tests/test_contracting.py +0 -0
  59. {contractme-2.0.0 → contractme-2.2.0}/tests/test_contracting_optimized_python.py +0 -0
  60. {contractme-2.0.0 → contractme-2.2.0}/tests/test_hypothesis.py +0 -0
  61. {contractme-2.0.0 → contractme-2.2.0}/tests/test_optimized_policy.py +0 -0
  62. {contractme-2.0.0 → contractme-2.2.0}/tests/test_policy.py +0 -0
  63. {contractme-2.0.0 → contractme-2.2.0}/tests/test_reentrancy.py +0 -0
  64. {contractme-2.0.0 → contractme-2.2.0}/tests/test_show_source.py +0 -0
  65. {contractme-2.0.0 → contractme-2.2.0}/tests/test_types.py +0 -0
  66. {contractme-2.0.0 → contractme-2.2.0}/tests/test_types_advanced.py +0 -0
  67. {contractme-2.0.0 → contractme-2.2.0}/tests/test_types_extra.py +0 -0
@@ -20,6 +20,10 @@ stages:
20
20
  .uv:
21
21
  image: ghcr.io/astral-sh/uv:$UV_VERSION-python$PYTHON_VERSION-$BASE_LAYER
22
22
 
23
+ # The scripts are one-liner justfile recipe calls (`uv run just ...`, the just
24
+ # binary comes from the dev deps) so CI runs exactly what `just check` runs
25
+ # locally; only the report/artifact flags are CI extras, passed through the
26
+ # recipes' *args.
23
27
  checks:
24
28
  extends: .uv
25
29
  stage: test
@@ -27,11 +31,12 @@ checks:
27
31
  - |
28
32
  if echo "$CI_MERGE_REQUEST_TITLE" | grep -iq "^draft:\|^wip:"; then
29
33
  echo "🚧 Draft MR: run pytest in lax mode"
30
- export PYTEST_EXTRA_ARGS=""
34
+ # last --cov-fail-under wins: 0 overrides the recipe's baked-in 100
35
+ export PYTEST_EXTRA_ARGS="--cov-fail-under=0"
31
36
  export PYTEST_ALLOW_EXIT_CODES="0 1"
32
37
  else
33
38
  echo "✅ MR ready: run pytest in strict mode"
34
- export PYTEST_EXTRA_ARGS="--strict-markers --runxfail --cov-fail-under=100"
39
+ export PYTEST_EXTRA_ARGS="--strict-markers --runxfail"
35
40
  export PYTEST_ALLOW_EXIT_CODES="0"
36
41
  fi
37
42
  - |
@@ -42,11 +47,11 @@ checks:
42
47
  - apt-get update
43
48
  - apt-get --yes install libatomic1
44
49
  script:
45
- - uv run pytest $PYTEST_EXTRA_ARGS --cov --cov-report term-missing --cov-report xml:obj/cov.xml --junitxml=obj/tests_report.xml
46
- - pytest_exit_code=$?
47
- - is_exit_code_allowed $pytest_exit_code
48
- - uv run black --check .
49
- - uv run pyright . --outputjson > obj/pyright.json || true
50
+ # `|| is_exit_code_allowed $?` must stay on the pytest line: a separate
51
+ # capture line never runs under GitLab's fail-fast script execution.
52
+ - uv run just cov --cov-report xml:obj/cov.xml --junitxml=obj/tests_report.xml $PYTEST_EXTRA_ARGS || is_exit_code_allowed $?
53
+ - uv run just lint
54
+ - uv run just types --outputjson > obj/pyright.json || true
50
55
  - uvx pyright-to-gitlab-ci --src obj/pyright.json --out obj/pyright-codeclimate.json
51
56
  coverage: /TOTAL.*? (100(?:\.0+)?\%|[1-9]?\d(?:\.\d+)?\%).*$/
52
57
  artifacts:
@@ -72,7 +77,7 @@ checks-optimized:
72
77
  extends: .uv
73
78
  stage: test
74
79
  script:
75
- - uv run python -O -m pytest -W "ignore::pytest.PytestConfigWarning" --junitxml=obj/tests_report_optimized.xml
80
+ - uv run just test-optimized --junitxml=obj/tests_report_optimized.xml
76
81
  artifacts:
77
82
  reports:
78
83
  junit: obj/tests_report_optimized.xml
@@ -92,10 +97,10 @@ build:
92
97
  before_script: # gate: refuse to build unless uv.lock is in sync with pyproject.toml
93
98
  - uv lock --check # (no git needed)
94
99
  script:
95
- # release_notes.py checks tag == pyproject version and a matching CHANGELOG
100
+ # release-notes checks tag == pyproject version and a matching CHANGELOG
96
101
  # section exists, then writes release_notes.md (for the release: job below).
97
- - uv run python release/release_notes.py
98
- - uv build --out-dir dist
102
+ - uv run just release-notes
103
+ - uv run just build
99
104
  artifacts:
100
105
  paths:
101
106
  - dist/
@@ -136,4 +141,4 @@ release:
136
141
  release:
137
142
  tag_name: $CI_COMMIT_TAG
138
143
  name: contractme $CI_COMMIT_TAG
139
- description: ./release_notes.md
144
+ description: ./release_notes.md
@@ -0,0 +1,27 @@
1
+ # See https://pre-commit.com for more information
2
+ # See https://pre-commit.com/hooks.html for more hooks
3
+ repos:
4
+ - repo: https://github.com/pre-commit/pre-commit-hooks
5
+ rev: v5.0.0
6
+ hooks:
7
+ - id: trailing-whitespace
8
+ - id: end-of-file-fixer
9
+ - id: check-yaml
10
+ - id: check-added-large-files
11
+ # Project checks go through the justfile, so pre-commit, CI and a dev shell
12
+ # all run the same recipes with tool versions pinned once, in uv.lock (the
13
+ # previous black/pyright/flake8 mirror hooks had drifted from the dev deps).
14
+ - repo: local
15
+ hooks:
16
+ - id: fmt
17
+ name: just fmt
18
+ entry: uv run just fmt
19
+ language: system
20
+ types: [python]
21
+ pass_filenames: false
22
+ - id: check
23
+ name: just check
24
+ entry: uv run just check
25
+ language: system
26
+ pass_filenames: false
27
+ always_run: true
@@ -17,4 +17,4 @@
17
17
  "runIn": "vscode"
18
18
  },
19
19
  ],
20
- }
20
+ }
@@ -7,6 +7,28 @@ section whose heading matches the tag via
7
7
  and GitLab release description — so every `## vX.Y.Z` heading must match its
8
8
  tag exactly.
9
9
 
10
+ ## v2.2.0
11
+
12
+ * `ClassVar[T]` and `Final[T]` now check everywhere a type does: the marker is
13
+ static-only, so the content checks as a plain `T` (nested `Annotated`
14
+ constraints included; a bare marker reads as `Any`). They used to raise
15
+ `NotImplementedError` — at call time, even from the never-raising probes —
16
+ for e.g. a PEP 544 protocol class attribute (`ClassVar[str]`) or a `Final`
17
+ record field.
18
+ * `context7.json` claim so the docs index under the project's name
19
+
20
+ ## v2.1.0
21
+
22
+ * `probes()` now takes any target: contracted function, `@record`, bare
23
+ function (probed through its type annotations), or any type annotation
24
+ ("does this value parse as `T`?")
25
+ * New export `type_error(value, T)`: the value-vs-type check as one plain
26
+ function call — the error message, or `None` when the value parses
27
+ * Split-ready layering of the two halves (contracts / dynamic type checking),
28
+ enforced by `tests/test_layering.py`; `is_evaluating_contracts()` made public
29
+ * Internal: `probes` moved to the new `probing.py`; `records.RecordProbes` is
30
+ now `probing.Probes`
31
+
10
32
  ## v2.0.0
11
33
 
12
34
  The API now speaks six words — *contract*, *pre/postcondition*, *violation*,
@@ -4,43 +4,40 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
4
4
 
5
5
  ## Commands
6
6
 
7
- ```bash
8
- # Run all tests
9
- uv run pytest
10
-
11
- # Run a single test file
12
- uv run pytest tests/test_contracting.py
13
-
14
- # Run a single test function
15
- uv run pytest tests/test_contracting.py::test_square_root
16
-
17
- # Run tests with coverage (100% required)
18
- uv run pytest --cov --cov-fail-under=100
19
-
20
- # Differential run: contracts compiled out via -O, valid-path behavior must be
21
- # identical (mirrors the checks-optimized CI job). Contract-violation tests
22
- # skip themselves via tests/conftest.py:contract_violation().
23
- uv run python -O -m pytest -W "ignore::pytest.PytestConfigWarning"
24
-
25
- # Format code
26
- uv run black .
7
+ All dev commands are `just` recipes (see [justfile](justfile)) — always prefer a
8
+ recipe over the equivalent ad-hoc `uv run ...` invocation, and when a new command
9
+ starts getting repeated, promote it to a recipe. CI and pre-commit run the same recipes
10
+ (`uv run just ...` in [.gitlab-ci.yml](.gitlab-ci.yml); the just binary comes from
11
+ the dev deps as `rust-just`), adding only report flags through the recipes' `*args`
12
+ — keep job scripts one-liner recipe calls.
27
13
 
28
- # Lint
29
- uv run flake8
30
-
31
- # Type checking (pinned pyright from the dev deps — matches the CI job)
32
- uv run pyright .
33
- # NOTE: the whole repo is at 0 errors since the #12 typing work (the stale
34
- # __init__.pyi stub is gone; inline types are the single source of truth:
35
- # ParamSpec'd ContractedFunction, dataclass_transform on @record, the
36
- # probes() record accessor). Keep it at 0. `# type: ignore` is reserved
37
- # for test calls that are *deliberately* ill-typed (probing runtime rejection);
38
- # CI still runs pyright advisorily (`|| true`, code-quality report only).
39
-
40
- # Build distribution
41
- uv build
14
+ ```bash
15
+ just # list recipes
16
+ just check # the full local gate: cov + test-optimized + lint + types.
17
+ # No fail-fast — one run reports every failing step by recipe
18
+ # name, so each can be rerun on its own.
19
+ just test [args...] # pytest passthrough:
20
+ # just test tests/test_contracting.py
21
+ # just test tests/test_contracting.py::test_square_root -x
22
+ just cov # tests + coverage gate (100% required, statements and branches)
23
+ just test-optimized # differential run: contracts compiled out via -O, valid-path
24
+ # behavior must be identical (mirrors the checks-optimized CI
25
+ # job). Contract-violation tests skip themselves via
26
+ # tests/conftest.py:contract_violation().
27
+ just fmt # format code (black)
28
+ just lint # black --check + flake8
29
+ just types # type checking (pinned pyright from the dev deps — matches CI)
30
+ just build # local sdist+wheel (real releases are built by CI)
31
+ just prerelease <v> # versioning script (see Release process below)
42
32
  ```
43
33
 
34
+ NOTE on `just types`: the whole repo is at 0 errors since the #12 typing work (the
35
+ stale `__init__.pyi` stub is gone; inline types are the single source of truth:
36
+ ParamSpec'd `ContractedFunction`, `dataclass_transform` on `@record`, the
37
+ `probes()` record accessor). Keep it at 0. `# type: ignore` is reserved
38
+ for test calls that are *deliberately* ill-typed (probing runtime rejection);
39
+ CI still runs pyright advisorily (`|| true`, code-quality report only).
40
+
44
41
  ## Architecture
45
42
 
46
43
  ContractMe is a design-by-contract framework for Python. The public API is exported from [src/contractme/__init__.py](src/contractme/__init__.py):
@@ -49,6 +46,30 @@ ContractMe is a design-by-contract framework for Python. The public API is expor
49
46
  - `@postcondition(lambda result, ...: ...)` — validates function outputs after execution
50
47
  - `@annotated` — automatically validates PEP-593 `Annotated` type constraints at call boundaries
51
48
  - Runtime control — **policy** is *the* word for "what a violation does", one word at three scopes: `set_policy(...)` (global), `local_policy(...)` (a `with` block), and the decorators' `policy=` argument (per contract). A policy is a `Policy` enum member, its plain-string name (`set_policy("observe")`), or a custom handler callable.
49
+ - Boundary toolkit — `probes(target)` gives the `accepts`/`rejects` pair for *any* target: a contracted function (handed back as-is), a `@record` (its attached constructor probes), or any other type annotation (value probes — "does this value parse as `T`?"). `type_error(value, T)` is the same value-vs-type check as one plain function call: the error message, or `None` when the value parses.
50
+
51
+ ### The two halves (split-ready layering)
52
+
53
+ The codebase is deliberately structured as **two co-dependent libraries in one
54
+ repo**, ready to be split into separate distributions:
55
+
56
+ - the **contracts half** — `contracting.py`, `policy.py`, `config.py`,
57
+ `result.py`, `testing.py` — the DbC engine, standalone: zero runtime imports
58
+ of the other half. It *dogfoods* `contractme.types` in its own annotations,
59
+ but only statically (`TYPE_CHECKING`-only imports): the contracts profit from
60
+ the type checking to validate their own implementation, never to run.
61
+ - the **dynamic type-checking half** — `typeshape.py`, `typecheck.py`,
62
+ `types/` — standalone too: imports nothing from the contracts half, ever.
63
+ `typecheck.type_error(value, T)` is its public programmatic entry.
64
+ - the **bridges** — `annotations.py`, `records.py`, `probing.py` — are what
65
+ makes the two halves one distribution today: *users* of the contracts half
66
+ through public names only (they extend nothing — e.g.
67
+ `is_evaluating_contracts()` was made public so `@record` honours the Eiffel
68
+ suspension without touching engine internals), so the split stays mechanical.
69
+
70
+ [tests/test_layering.py](tests/test_layering.py) **enforces** the boundary
71
+ (import direction, `TYPE_CHECKING`-only dogfooding, no private cross-imports,
72
+ every module classified into a half): a new module must pick a side there.
52
73
 
53
74
  ### Core modules
54
75
 
@@ -71,29 +92,42 @@ ContractMe is a design-by-contract framework for Python. The public API is expor
71
92
  **[records.py](src/contractme/records.py)** — The `@record` decorator: a frozen
72
93
  dataclass that validates every constructor-visible field against its declared type
73
94
  (structure + `annotated-types` constraints) at construction, delegating to
74
- `typecheck.get_types_and_annotations_errors` (the same engine `@annotated` uses,
95
+ `typecheck.type_error` (the same engine `@annotated` uses,
75
96
  so any field type it understands works, and a `@record` nests recursively inside
76
97
  `@annotated` signatures). Implements *parse, don't validate*: the check runs in a
77
98
  generated `__post_init__` (after any user `__post_init__`), is a precondition (bad
78
99
  field = **caller** bug) so it honours `__debug__`/`is_checked()` and the Eiffel
79
- suspension via `_evaluating_contracts`, and is compiled out under `-O`. A record
100
+ suspension via `is_evaluating_contracts()`, and is compiled out under `-O`. A record
80
101
  probes like a contracted function: the decorator attaches `accepts`/`rejects`
81
102
  classmethods — *"would these constructor arguments build a valid record?"* as a
82
103
  `bool`, without building or raising. The attach is invisible to pyright (a class
83
104
  decorator cannot *type* dynamically attached members: its return must stay `type[T]`
84
105
  for the class to remain a class — Python has no intersection types), so the typed way
85
- in is the `probes(cls)` accessor (`dataclasses.fields()`-style): its
86
- `assert isinstance(cls, RecordProbes)` — a `runtime_checkable` structural Protocol —
87
- both enforces at runtime (plus the `@record` marker assert) and narrows for pyright,
88
- no cast. Only `field(init=True)` fields are checked (`init=False`/`InitVar`
106
+ in is the `probes(cls)` accessor (see `probing.py` below). Only `field(init=True)`
107
+ fields are checked (`init=False`/`InitVar`
89
108
  are the author's concern). Statically, `record` is
90
109
  `@dataclass_transform(frozen_default=True)` so pyright synthesizes the constructor.
91
110
 
111
+ **[probing.py](src/contractme/probing.py)** — One probe vocabulary for everything:
112
+ `probes(target)` is the typed, `dataclasses.fields()`-style accessor to the
113
+ `accepts`/`rejects` pair, whatever carries it. A contracted function is handed
114
+ back as-is; a `@record` class is narrowed by `assert isinstance(target, Probes)`
115
+ (a `runtime_checkable` structural Protocol — the classmethod attach is invisible
116
+ to pyright, the assert both enforces and narrows, no cast); **any other type
117
+ annotation** gets value probes (`TypeProbes`, built on `typecheck.type_error`) —
118
+ *"does this value parse as `T`?"*, same guarantees as every probe (a plain `bool`,
119
+ never raises, always evaluates, survives `-O`). A *bare* routine is probed through
120
+ its type annotations — the `@annotated` view of it, built on the fly, the routine
121
+ itself staying unwrapped; with no hints at all the signature is still a spec, so a
122
+ hint-less routine gets call-shape probes (`CallProbes`: *"does this call bind?"*).
123
+ The probe syntax is sugar — `type_error` is the same check as a plain
124
+ function call, for anyone who finds the accessor exotic.
125
+
92
126
  **[annotations.py](src/contractme/annotations.py)** — The `@annotated` decorator introspects a function's `Annotated[T, constraints...]` signatures and auto-generates preconditions for inputs and postconditions for the return value by delegating to `typecheck.py`. Dataclasses are supported as named products (`ChildMod.RECORD`): the checker recurses into each field by name, validating nested types and per-field `Annotated` constraints. Enums are supported as sums of singletons (`ChildMod.ENUM`): membership is an `isinstance` check (so `Flag` combinations stay valid), and `Annotated` constraints on the member value (e.g. on an `IntEnum`) are enforced. `typing.Protocol` types are supported as structural products (`ChildMod.STRUCTURAL`): basic duck typing where each declared member must be present (a `hasattr` predicate) and members carrying a type are checked against it (no nominal `isinstance`, so neither inheritance nor `@runtime_checkable` is required). **Known limitations**: nominal class inheritance and exact type matching (e.g. distinguishing `int` from `bool`) are not supported and untested; `autotest`/Hypothesis cannot generate values for `Protocol` parameters (no concrete type to instantiate).
93
127
 
94
128
  **[typeshape.py](src/contractme/typeshape.py)** — Standalone type *meta*-manipulation library (no value inspection). Answers "what kind of type is this, and what is it homomorphic to?" by mapping any annotation onto a small algebra via `ChildMod` (atom/product → `NONE`, sum → `OPTION`, sequence → `REPEAT`, map → `REPEAT_KV`, dataclass/named-product → `RECORD`, whose `field_names` carry the field names parallel to `children`, enum/sum-of-singletons → `ENUM`, a leaf checked by `isinstance`, and protocol/structural-product → `STRUCTURAL`, a named product matched by `hasattr` instead of nominal inheritance). `CompositeTypeInfo` is the carrier of that homomorphism (origin + constraints + children, with `arity()`); `resolve_type()` strips `TypeVar`/alias indirection, `normalize_constraint()`/`flatten_constraints()` canonicalise constraints, and `get_recursive_composite_type_info()` walks the tree. This is the reusable "hidden library" inside ContractMe; `typecheck.py` and `annotations.py` are its first consumers. It dogfoods `contractme.types` (e.g. `Natural`) via `TYPE_CHECKING`-only imports so it stays a leaf module.
95
129
 
96
- **[typecheck.py](src/contractme/typecheck.py)** — Two-phase *value* validation built on `typeshape`: `get_first_structure_error()` checks structural correctness (e.g., is this actually a `list`?), then `get_constraints_errors()` checks value constraints (e.g., `Ge`, `Lt`, `MinLen`). Handles nested and recursive types, unions, tuples, sets, dicts, and `annotated-types` predicates. Both walkers are purely recursive, and errors carry a path to the offending node (`[2]: `, `key 'a': `, `field x: `).
130
+ **[typecheck.py](src/contractme/typecheck.py)** — Two-phase *value* validation built on `typeshape`: `get_first_structure_error()` checks structural correctness (e.g., is this actually a `list`?), then `get_constraints_errors()` checks value constraints (e.g., `Ge`, `Lt`, `MinLen`). `type_error(value, an)` (exported from the top-level package; renamed from `get_types_and_annotations_errors`) chains the two phases into the public programmatic entry: the error message, or `None` when the value parses — never raises, open world. Handles nested and recursive types, unions, tuples, sets, dicts, and `annotated-types` predicates. Both walkers are purely recursive, and errors carry a path to the offending node (`[2]: `, `key 'a': `, `field x: `).
97
131
 
98
132
  **[testing.py](src/contractme/testing.py)** — Hypothesis integration. `property_test(f)` builds the ready-to-run property-based test (a `@given`-wrapped callable — *not* a Hypothesis strategy; the strategy inside comes from `f`'s type hints, filtered through the `accepts` probe). `autotest(f)` runs it; `test_with_examples(f, *examples)` pins specific inputs, checked against the contracts at collection time.
99
133
 
@@ -103,7 +137,7 @@ Work on the main branch, never create a MR or dedicated branch unless asked to.
103
137
 
104
138
  ### Release process
105
139
 
106
- Changelog entries go in [CHANGELOG.md](CHANGELOG.md) as a `## v<number>` section (README only links to it). Keep sections terse and in executive-summary order: most important first (DX impact — new capabilities, then correctness fixes users could hit), laconic one-liners for details invisible from outside (cosmetics, internals). Releases are built and published to PyPI, and a GitLab Release is created, by GitLab CI (the `build`/`publish`/`release` jobs in [.gitlab-ci.yml](.gitlab-ci.yml)), **not** locally — the `.on-release-tag` rule fires them automatically when a `v<number>` tag is pushed. To release a new version: add a `## v<number>` section in `CHANGELOG.md`, then run the versioning script `uv run python release/prerelease.py <number>` — it sets the version in `pyproject.toml`, refreshes `uv.lock`, and checks the changelog section exists (all three must agree or the CI `build` gate aborts). Then commit and push to `main`, git-tag as `v<number>` and push the tag; the tag pipeline validates and publishes. The gate is [release/release_notes.py](release/release_notes.py): it checks the tag matches `pyproject.toml` and `CHANGELOG.md`, then extracts that section to `release_notes.md` (the PyPI/GitLab release description). Do not run `uv build`/`uv publish` yourself; the script does not run lint/type/tests either (pre-commit and CI own those).
140
+ Changelog entries go in [CHANGELOG.md](CHANGELOG.md) as a `## v<number>` section (README only links to it). Keep sections terse and in executive-summary order: most important first (DX impact — new capabilities, then correctness fixes users could hit), laconic one-liners for details invisible from outside (cosmetics, internals). Releases are built and published to PyPI, and a GitLab Release is created, by GitLab CI (the `build`/`publish`/`release` jobs in [.gitlab-ci.yml](.gitlab-ci.yml)), **not** locally — the `.on-release-tag` rule fires them automatically when a `v<number>` tag is pushed. To release a new version: add a `## v<number>` section in `CHANGELOG.md`, then run the versioning script `just prerelease <number>` — it sets the version in `pyproject.toml`, refreshes `uv.lock`, and checks the changelog section exists (all three must agree or the CI `build` gate aborts). Then commit and push to `main`, git-tag as `v<number>` and push the tag; the tag pipeline validates and publishes. The gate is [release/release_notes.py](release/release_notes.py): it checks the tag matches `pyproject.toml` and `CHANGELOG.md`, then extracts that section to `release_notes.md` (the PyPI/GitLab release description). Do not run `uv build`/`uv publish` yourself; the script does not run lint/type/tests either (pre-commit and CI own those).
107
141
 
108
142
  If the release process in `README.md` changes, update this section accordingly.
109
143
 
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: contractme
3
- Version: 2.0.0
3
+ Version: 2.2.0
4
4
  Summary: Executable specifications for python. Keep control of the code AI writes for you.
5
5
  Project-URL: Repository, https://gitlab.com/leogermond/contractme
6
6
  Author-email: Leo Germond <leo.germond@gmail.com>
@@ -18,16 +18,16 @@ Requires-Dist: pyyaml>=6.0; extra == 'yaml'
18
18
  Description-Content-Type: text/markdown
19
19
 
20
20
  # ContractMe — executable specifications for Python
21
-
21
+
22
22
  ## Code is free. Bugs are not. Write the spec instead.
23
23
 
24
- [![pipeline status](https://gitlab.com/leogermond/contractme/badges/main/pipeline.svg)](https://gitlab.com/leogermond/contractme/-/commits/main)
24
+ [![pipeline status](https://gitlab.com/leogermond/contractme/badges/main/pipeline.svg)](https://gitlab.com/leogermond/contractme/-/commits/main)
25
25
  ![coverage](https://gitlab.com/leogermond/contractme/badges/main/coverage.svg?job=checks)
26
26
  [![Checked with pyright](https://microsoft.github.io/pyright/img/pyright_badge.svg)](https://microsoft.github.io/pyright/)
27
27
  [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
28
28
  [![Code style: flake8](https://img.shields.io/badge/code%20style-flake8-000000.svg)](https://github.com/PyCQA/flake8)
29
29
 
30
-
30
+
31
31
  You let an AI write more and more of your code. `contractme` is how you keep
32
32
  control without reading all of it: state a few plain-Python rules on top of a
33
33
  function, and every call — in dev, in CI, under your agent's iterations —
@@ -163,21 +163,21 @@ hundreds of generated inputs, with expected behavior taken from the rules —
163
163
  not from the code under test.
164
164
 
165
165
  ## Why contracts, why now
166
-
166
+
167
167
  - **The economics of code flipped.** Implementation used to be expensive, so nobody wrote specs. Now implementation is generated in seconds,
168
168
  and the bottleneck moved: *how do you know the generated code does what you meant?*
169
169
  Reading a 400-line diff is not an answer. Reading 4 lines of contract is.
170
-
171
- - **Types and tests don't cover this ground.** `mypy` and `pyright` verify shapes, not meaning: they will happily let you swap two `int` arguments,
170
+
171
+ - **Types and tests don't cover this ground.** `mypy` and `pyright` verify shapes, not meaning: they will happily let you swap two `int` arguments,
172
172
  return an unsorted list, or lose a cent to integer division. Unit tests check the examples someone thought of, on the day they thought of them.
173
173
  Contracts state the property itself, and check it on every call, with the real data.
174
-
175
- - **Trust needs a small surface.** When code, tests and docs are all regenerated by agents — cheaply, independently, repeatedly — they can silently
174
+
175
+ - **Trust needs a small surface.** When code, tests and docs are all regenerated by agents — cheaply, independently, repeatedly — they can silently
176
176
  drift apart. The contract is the one artifact everything else must agree with: the implementation is checked against it at runtime, and tests can
177
177
  be *derived from it* instead of guessed. You audit one small thing, not a thousand generated ones.
178
178
 
179
179
  ## Batteries included
180
-
180
+
181
181
  - **Plain Python conditions.** Lambdas over your own parameter names. If you can write an `if`, you can write a contract.
182
182
  - **Dataclasses and enums supported natively.** Your domain types work out of the box.
183
183
  - **Predefined contracts for the common cases** — non-empty, sorted, in-range — so the easy specs are one word long.
@@ -185,9 +185,9 @@ drift apart. The contract is the one artifact everything else must agree with: t
185
185
  - **Violation messages designed to be actionable** — by humans and by coding agents. Structured, self-contained, ready to paste.
186
186
 
187
187
  ## How it compares
188
-
188
+
189
189
  Honest version, because you will ask:
190
-
190
+
191
191
  - **[pydantic](https://docs.pydantic.dev/) / [beartype](https://github.com/beartype/beartype)** validate types and data shapes at boundaries, and do it very well. They cannot express *relationships*: "the result sums to the input", "output is sorted", "these two arguments must be consistent". That is postcondition territory — that is `contractme`.
192
192
  - **[deal](https://github.com/life4/deal)** is the most featureful design-by-contract library for Python (linter, property-based testing, experimental formal verification). `contractme` deliberately trades that breadth for a smaller, easier-to-trust core and first-class ergonomics for AI-assisted workflows.
193
193
  - **[icontract](https://github.com/Parquery/icontract)** pioneered informative violation messages and contract inheritance, with a research-grade ecosystem around it. If you need contract inheritance across deep class hierarchies today, use it. If you want contracts your whole team — and your agents — actually write, start here.
@@ -208,11 +208,11 @@ say what you mean. The theory can wait until it has caught a bug for you.
208
208
  ### What is design by contract, in one sentence?
209
209
 
210
210
  Executable specifications: each function declares what it requires and what it guarantees, and the runtime checks both — turning silent wrong answers into loud, explained failures.
211
-
211
+
212
212
  ### Why not just type hints and pytest?
213
213
 
214
214
  Keep both. Type hints catch shape errors before running; tests pin known examples. Contracts cover what neither can: semantic properties, checked on every call, against real data — including the calls your tests never imagined.
215
-
215
+
216
216
  ### Can an LLM write the contracts too?
217
217
 
218
218
  Yes, and that's fine — what matters is not who writes the spec, but that you *can* read it when you need to, and that a tool more reliable than the code enforces it. Keep contracts terse enough to audit at a glance; review the contract lines in the diff, not the regenerated body.
@@ -227,7 +227,7 @@ tests are generated from it, and it reads as documentation. One short,
227
227
  auditable text instead of four long ones. You don't have to buy this today —
228
228
  catch one bug first, then reread this paragraph.
229
229
 
230
- ## Integrated to python type-system, and more
230
+ ## Integrated to python type-system, and more
231
231
 
232
232
  Supports annotations and [PEP-593](https://peps.python.org/pep-0593/)
233
233
  using the [annotated-types](https://pypi.org/project/annotated-types/) library.
@@ -246,9 +246,9 @@ See the practical guide: [docs/types.md](docs/types.md).
246
246
  **Note 2:** Following an open-world reasoning, any unknown annotation is considered
247
247
  to be correct, so it won't cause a check failure.
248
248
 
249
- **Note 3:** Type checking follows Python's `isinstance` semantics, which means subclass
250
- relationships are respected. Since `bool` is a subclass of `int` in Python, boolean values
251
- will pass `int` type checks. Currently there's no built-in way to specify "exactly int, not bool"
249
+ **Note 3:** Type checking follows Python's `isinstance` semantics, which means subclass
250
+ relationships are respected. Since `bool` is a subclass of `int` in Python, boolean values
251
+ will pass `int` type checks. Currently there's no built-in way to specify "exactly int, not bool"
252
252
  in type annotations.
253
253
 
254
254
  ```python
@@ -305,6 +305,38 @@ signatures and other records, validated recursively. Its construction check is a
305
305
  precondition (a bad field is a *caller* bug), so it obeys the usual switches:
306
306
  compiled out under `python -O`, suspended by `set_policy("off")`.
307
307
 
308
+ ## Probing any type — and the check as one function call
309
+
310
+ Probes are not limited to records: `probes(T)` builds `accepts`/`rejects` for
311
+ **any type annotation** — the same engine as `@annotated`, the same guarantees
312
+ (a plain `bool`, never raises, survives `python -O`):
313
+
314
+ ```python
315
+ from contractme import probes
316
+ from contractme.types import Natural
317
+
318
+ probes(list[Natural]).accepts([1, 2, 3]) # True
319
+ probes(list[Natural]).rejects([1, -2]) # True
320
+ ```
321
+
322
+ One accessor, one vocabulary: `probes(f)` on a contracted function hands back
323
+ its call probes (`probes(f) is f`), a bare function is probed through its type
324
+ annotations (exactly what `@annotated` would enforce, without wrapping it — and
325
+ down to its bare signature when it has no hints: does the call bind?), and
326
+ a `@record` class keeps its constructor probes. Probing a bare function is how
327
+ you interface safely with *uncontracted* code — third-party, legacy, not yours
328
+ to decorate: screen the call, then make it, no wrapper. And if the accessor syntax is
329
+ one indirection too many, the same check is a plain function call —
330
+ `type_error(value, T)` returns the error message, or `None` when the value
331
+ parses, so anything can plug into the engine:
332
+
333
+ ```python
334
+ from contractme import type_error
335
+
336
+ if err := type_error(payload, list[Natural]):
337
+ return bad_request(err) # "structure ok, but value does not match constraints: [1]: …"
338
+ ```
339
+
308
340
  ## Writing tests and having test generation
309
341
 
310
342
  The hypothesis plugin can be used easily through the `contractme.testing.autotest`
@@ -448,7 +480,10 @@ cost nothing where it matters.
448
480
 
449
481
  # Test
450
482
 
451
- `uv run pytest`
483
+ `just test`
484
+
485
+ Dev commands are `just` recipes — bare `just` lists them; `just check` runs the
486
+ full local gate (tests + coverage, the `-O` differential run, lint, types).
452
487
 
453
488
  # Deploy new version
454
489
 
@@ -460,7 +495,7 @@ You only prepare the commit and the tag:
460
495
  * Run the pre-release script to version the tree and check everything lines up:
461
496
 
462
497
  ```bash
463
- uv run python release/prerelease.py 1.9.0 # or omit the arg to reuse pyproject's version
498
+ just prerelease 1.9.0 # or omit the arg to reuse pyproject's version
464
499
  ```
465
500
 
466
501
  It sets the version in `pyproject.toml`, refreshes `uv.lock`, verifies the `## v1.9.0`
@@ -477,5 +512,5 @@ You only prepare the commit and the tag:
477
512
  See [CHANGELOG.md](CHANGELOG.md)
478
513
 
479
514
  ---
480
-
481
- *Python design by contract · runtime verification · preconditions, postconditions, `old` state · executable specifications for AI-generated code*
515
+
516
+ *Python design by contract · runtime verification · preconditions, postconditions, `old` state · executable specifications for AI-generated code*
@@ -1,14 +1,14 @@
1
1
  # ContractMe — executable specifications for Python
2
-
2
+
3
3
  ## Code is free. Bugs are not. Write the spec instead.
4
4
 
5
- [![pipeline status](https://gitlab.com/leogermond/contractme/badges/main/pipeline.svg)](https://gitlab.com/leogermond/contractme/-/commits/main)
5
+ [![pipeline status](https://gitlab.com/leogermond/contractme/badges/main/pipeline.svg)](https://gitlab.com/leogermond/contractme/-/commits/main)
6
6
  ![coverage](https://gitlab.com/leogermond/contractme/badges/main/coverage.svg?job=checks)
7
7
  [![Checked with pyright](https://microsoft.github.io/pyright/img/pyright_badge.svg)](https://microsoft.github.io/pyright/)
8
8
  [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
9
9
  [![Code style: flake8](https://img.shields.io/badge/code%20style-flake8-000000.svg)](https://github.com/PyCQA/flake8)
10
10
 
11
-
11
+
12
12
  You let an AI write more and more of your code. `contractme` is how you keep
13
13
  control without reading all of it: state a few plain-Python rules on top of a
14
14
  function, and every call — in dev, in CI, under your agent's iterations —
@@ -144,21 +144,21 @@ hundreds of generated inputs, with expected behavior taken from the rules —
144
144
  not from the code under test.
145
145
 
146
146
  ## Why contracts, why now
147
-
147
+
148
148
  - **The economics of code flipped.** Implementation used to be expensive, so nobody wrote specs. Now implementation is generated in seconds,
149
149
  and the bottleneck moved: *how do you know the generated code does what you meant?*
150
150
  Reading a 400-line diff is not an answer. Reading 4 lines of contract is.
151
-
152
- - **Types and tests don't cover this ground.** `mypy` and `pyright` verify shapes, not meaning: they will happily let you swap two `int` arguments,
151
+
152
+ - **Types and tests don't cover this ground.** `mypy` and `pyright` verify shapes, not meaning: they will happily let you swap two `int` arguments,
153
153
  return an unsorted list, or lose a cent to integer division. Unit tests check the examples someone thought of, on the day they thought of them.
154
154
  Contracts state the property itself, and check it on every call, with the real data.
155
-
156
- - **Trust needs a small surface.** When code, tests and docs are all regenerated by agents — cheaply, independently, repeatedly — they can silently
155
+
156
+ - **Trust needs a small surface.** When code, tests and docs are all regenerated by agents — cheaply, independently, repeatedly — they can silently
157
157
  drift apart. The contract is the one artifact everything else must agree with: the implementation is checked against it at runtime, and tests can
158
158
  be *derived from it* instead of guessed. You audit one small thing, not a thousand generated ones.
159
159
 
160
160
  ## Batteries included
161
-
161
+
162
162
  - **Plain Python conditions.** Lambdas over your own parameter names. If you can write an `if`, you can write a contract.
163
163
  - **Dataclasses and enums supported natively.** Your domain types work out of the box.
164
164
  - **Predefined contracts for the common cases** — non-empty, sorted, in-range — so the easy specs are one word long.
@@ -166,9 +166,9 @@ drift apart. The contract is the one artifact everything else must agree with: t
166
166
  - **Violation messages designed to be actionable** — by humans and by coding agents. Structured, self-contained, ready to paste.
167
167
 
168
168
  ## How it compares
169
-
169
+
170
170
  Honest version, because you will ask:
171
-
171
+
172
172
  - **[pydantic](https://docs.pydantic.dev/) / [beartype](https://github.com/beartype/beartype)** validate types and data shapes at boundaries, and do it very well. They cannot express *relationships*: "the result sums to the input", "output is sorted", "these two arguments must be consistent". That is postcondition territory — that is `contractme`.
173
173
  - **[deal](https://github.com/life4/deal)** is the most featureful design-by-contract library for Python (linter, property-based testing, experimental formal verification). `contractme` deliberately trades that breadth for a smaller, easier-to-trust core and first-class ergonomics for AI-assisted workflows.
174
174
  - **[icontract](https://github.com/Parquery/icontract)** pioneered informative violation messages and contract inheritance, with a research-grade ecosystem around it. If you need contract inheritance across deep class hierarchies today, use it. If you want contracts your whole team — and your agents — actually write, start here.
@@ -189,11 +189,11 @@ say what you mean. The theory can wait until it has caught a bug for you.
189
189
  ### What is design by contract, in one sentence?
190
190
 
191
191
  Executable specifications: each function declares what it requires and what it guarantees, and the runtime checks both — turning silent wrong answers into loud, explained failures.
192
-
192
+
193
193
  ### Why not just type hints and pytest?
194
194
 
195
195
  Keep both. Type hints catch shape errors before running; tests pin known examples. Contracts cover what neither can: semantic properties, checked on every call, against real data — including the calls your tests never imagined.
196
-
196
+
197
197
  ### Can an LLM write the contracts too?
198
198
 
199
199
  Yes, and that's fine — what matters is not who writes the spec, but that you *can* read it when you need to, and that a tool more reliable than the code enforces it. Keep contracts terse enough to audit at a glance; review the contract lines in the diff, not the regenerated body.
@@ -208,7 +208,7 @@ tests are generated from it, and it reads as documentation. One short,
208
208
  auditable text instead of four long ones. You don't have to buy this today —
209
209
  catch one bug first, then reread this paragraph.
210
210
 
211
- ## Integrated to python type-system, and more
211
+ ## Integrated to python type-system, and more
212
212
 
213
213
  Supports annotations and [PEP-593](https://peps.python.org/pep-0593/)
214
214
  using the [annotated-types](https://pypi.org/project/annotated-types/) library.
@@ -227,9 +227,9 @@ See the practical guide: [docs/types.md](docs/types.md).
227
227
  **Note 2:** Following an open-world reasoning, any unknown annotation is considered
228
228
  to be correct, so it won't cause a check failure.
229
229
 
230
- **Note 3:** Type checking follows Python's `isinstance` semantics, which means subclass
231
- relationships are respected. Since `bool` is a subclass of `int` in Python, boolean values
232
- will pass `int` type checks. Currently there's no built-in way to specify "exactly int, not bool"
230
+ **Note 3:** Type checking follows Python's `isinstance` semantics, which means subclass
231
+ relationships are respected. Since `bool` is a subclass of `int` in Python, boolean values
232
+ will pass `int` type checks. Currently there's no built-in way to specify "exactly int, not bool"
233
233
  in type annotations.
234
234
 
235
235
  ```python
@@ -286,6 +286,38 @@ signatures and other records, validated recursively. Its construction check is a
286
286
  precondition (a bad field is a *caller* bug), so it obeys the usual switches:
287
287
  compiled out under `python -O`, suspended by `set_policy("off")`.
288
288
 
289
+ ## Probing any type — and the check as one function call
290
+
291
+ Probes are not limited to records: `probes(T)` builds `accepts`/`rejects` for
292
+ **any type annotation** — the same engine as `@annotated`, the same guarantees
293
+ (a plain `bool`, never raises, survives `python -O`):
294
+
295
+ ```python
296
+ from contractme import probes
297
+ from contractme.types import Natural
298
+
299
+ probes(list[Natural]).accepts([1, 2, 3]) # True
300
+ probes(list[Natural]).rejects([1, -2]) # True
301
+ ```
302
+
303
+ One accessor, one vocabulary: `probes(f)` on a contracted function hands back
304
+ its call probes (`probes(f) is f`), a bare function is probed through its type
305
+ annotations (exactly what `@annotated` would enforce, without wrapping it — and
306
+ down to its bare signature when it has no hints: does the call bind?), and
307
+ a `@record` class keeps its constructor probes. Probing a bare function is how
308
+ you interface safely with *uncontracted* code — third-party, legacy, not yours
309
+ to decorate: screen the call, then make it, no wrapper. And if the accessor syntax is
310
+ one indirection too many, the same check is a plain function call —
311
+ `type_error(value, T)` returns the error message, or `None` when the value
312
+ parses, so anything can plug into the engine:
313
+
314
+ ```python
315
+ from contractme import type_error
316
+
317
+ if err := type_error(payload, list[Natural]):
318
+ return bad_request(err) # "structure ok, but value does not match constraints: [1]: …"
319
+ ```
320
+
289
321
  ## Writing tests and having test generation
290
322
 
291
323
  The hypothesis plugin can be used easily through the `contractme.testing.autotest`
@@ -429,7 +461,10 @@ cost nothing where it matters.
429
461
 
430
462
  # Test
431
463
 
432
- `uv run pytest`
464
+ `just test`
465
+
466
+ Dev commands are `just` recipes — bare `just` lists them; `just check` runs the
467
+ full local gate (tests + coverage, the `-O` differential run, lint, types).
433
468
 
434
469
  # Deploy new version
435
470
 
@@ -441,7 +476,7 @@ You only prepare the commit and the tag:
441
476
  * Run the pre-release script to version the tree and check everything lines up:
442
477
 
443
478
  ```bash
444
- uv run python release/prerelease.py 1.9.0 # or omit the arg to reuse pyproject's version
479
+ just prerelease 1.9.0 # or omit the arg to reuse pyproject's version
445
480
  ```
446
481
 
447
482
  It sets the version in `pyproject.toml`, refreshes `uv.lock`, verifies the `## v1.9.0`
@@ -458,5 +493,5 @@ You only prepare the commit and the tag:
458
493
  See [CHANGELOG.md](CHANGELOG.md)
459
494
 
460
495
  ---
461
-
462
- *Python design by contract · runtime verification · preconditions, postconditions, `old` state · executable specifications for AI-generated code*
496
+
497
+ *Python design by contract · runtime verification · preconditions, postconditions, `old` state · executable specifications for AI-generated code*