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.
- {contractme-2.0.0 → contractme-2.2.0}/.gitlab-ci.yml +17 -12
- contractme-2.2.0/.pre-commit-config.yaml +27 -0
- {contractme-2.0.0 → contractme-2.2.0}/.vscode/settings.json +1 -1
- {contractme-2.0.0 → contractme-2.2.0}/CHANGELOG.md +22 -0
- {contractme-2.0.0 → contractme-2.2.0}/CLAUDE.md +76 -42
- {contractme-2.0.0 → contractme-2.2.0}/PKG-INFO +57 -22
- {contractme-2.0.0 → contractme-2.2.0}/README.md +56 -21
- contractme-2.2.0/context7.json +4 -0
- contractme-2.2.0/docs/comparison.md +265 -0
- contractme-2.2.0/justfile +70 -0
- {contractme-2.0.0 → contractme-2.2.0}/pyproject.toml +4 -2
- contractme-2.2.0/release_notes.md +7 -0
- {contractme-2.0.0 → contractme-2.2.0}/src/contractme/__init__.py +9 -2
- {contractme-2.0.0 → contractme-2.2.0}/src/contractme/annotations.py +3 -3
- {contractme-2.0.0 → contractme-2.2.0}/src/contractme/contracting.py +10 -0
- contractme-2.2.0/src/contractme/probing.py +119 -0
- {contractme-2.0.0 → contractme-2.2.0}/src/contractme/records.py +7 -31
- {contractme-2.0.0 → contractme-2.2.0}/src/contractme/skills/contractme/SKILL.md +78 -12
- {contractme-2.0.0 → contractme-2.2.0}/src/contractme/typecheck.py +21 -6
- {contractme-2.0.0 → contractme-2.2.0}/src/contractme/typeshape.py +17 -4
- {contractme-2.0.0 → contractme-2.2.0}/tests/test_annotations.py +28 -1
- contractme-2.2.0/tests/test_layering.py +107 -0
- contractme-2.2.0/tests/test_probing.py +101 -0
- {contractme-2.0.0 → contractme-2.2.0}/tests/test_records.py +18 -14
- {contractme-2.0.0 → contractme-2.2.0}/tests/test_typechecks.py +12 -1
- {contractme-2.0.0 → contractme-2.2.0}/tests/test_typeshape.py +25 -1
- {contractme-2.0.0 → contractme-2.2.0}/uv.lock +27 -1
- contractme-2.0.0/.pre-commit-config.yaml +0 -31
- contractme-2.0.0/docs/comparison.md +0 -190
- contractme-2.0.0/release_notes.md +0 -87
- {contractme-2.0.0 → contractme-2.2.0}/.flake8 +0 -0
- {contractme-2.0.0 → contractme-2.2.0}/.gitignore +0 -0
- {contractme-2.0.0 → contractme-2.2.0}/.python-version +0 -0
- {contractme-2.0.0 → contractme-2.2.0}/LICENSE +0 -0
- {contractme-2.0.0 → contractme-2.2.0}/docs/types.md +0 -0
- {contractme-2.0.0 → contractme-2.2.0}/release/prerelease.py +0 -0
- {contractme-2.0.0 → contractme-2.2.0}/release/pypi_mint_token.py +0 -0
- {contractme-2.0.0 → contractme-2.2.0}/release/release_notes.py +0 -0
- {contractme-2.0.0 → contractme-2.2.0}/src/contractme/config.py +0 -0
- {contractme-2.0.0 → contractme-2.2.0}/src/contractme/policy.py +0 -0
- {contractme-2.0.0 → contractme-2.2.0}/src/contractme/py.typed +0 -0
- {contractme-2.0.0 → contractme-2.2.0}/src/contractme/result.py +0 -0
- {contractme-2.0.0 → contractme-2.2.0}/src/contractme/testing.py +0 -0
- {contractme-2.0.0 → contractme-2.2.0}/src/contractme/types/__init__.py +0 -0
- {contractme-2.0.0 → contractme-2.2.0}/src/contractme/types/containers.py +0 -0
- {contractme-2.0.0 → contractme-2.2.0}/src/contractme/types/data.py +0 -0
- {contractme-2.0.0 → contractme-2.2.0}/src/contractme/types/identifiers.py +0 -0
- {contractme-2.0.0 → contractme-2.2.0}/src/contractme/types/network.py +0 -0
- {contractme-2.0.0 → contractme-2.2.0}/src/contractme/types/numeric.py +0 -0
- {contractme-2.0.0 → contractme-2.2.0}/src/contractme/types/paths.py +0 -0
- {contractme-2.0.0 → contractme-2.2.0}/src/contractme/types/predicates.py +0 -0
- {contractme-2.0.0 → contractme-2.2.0}/src/contractme/types/system.py +0 -0
- {contractme-2.0.0 → contractme-2.2.0}/src/contractme/types/temporal.py +0 -0
- {contractme-2.0.0 → contractme-2.2.0}/src/contractme/types/text.py +0 -0
- {contractme-2.0.0 → contractme-2.2.0}/tests/conftest.py +0 -0
- {contractme-2.0.0 → contractme-2.2.0}/tests/test_annotations_future.py +0 -0
- {contractme-2.0.0 → contractme-2.2.0}/tests/test_canaries.py +0 -0
- {contractme-2.0.0 → contractme-2.2.0}/tests/test_contracting.py +0 -0
- {contractme-2.0.0 → contractme-2.2.0}/tests/test_contracting_optimized_python.py +0 -0
- {contractme-2.0.0 → contractme-2.2.0}/tests/test_hypothesis.py +0 -0
- {contractme-2.0.0 → contractme-2.2.0}/tests/test_optimized_policy.py +0 -0
- {contractme-2.0.0 → contractme-2.2.0}/tests/test_policy.py +0 -0
- {contractme-2.0.0 → contractme-2.2.0}/tests/test_reentrancy.py +0 -0
- {contractme-2.0.0 → contractme-2.2.0}/tests/test_show_source.py +0 -0
- {contractme-2.0.0 → contractme-2.2.0}/tests/test_types.py +0 -0
- {contractme-2.0.0 → contractme-2.2.0}/tests/test_types_advanced.py +0 -0
- {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
|
-
|
|
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
|
|
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
|
-
|
|
46
|
-
-
|
|
47
|
-
- is_exit_code_allowed
|
|
48
|
-
- uv run
|
|
49
|
-
- uv run
|
|
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
|
|
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
|
-
#
|
|
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
|
|
98
|
-
- uv
|
|
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
|
|
@@ -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
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
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
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
#
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
#
|
|
35
|
-
#
|
|
36
|
-
#
|
|
37
|
-
#
|
|
38
|
-
#
|
|
39
|
-
|
|
40
|
-
#
|
|
41
|
-
|
|
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.
|
|
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 `
|
|
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 (`
|
|
86
|
-
|
|
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 `
|
|
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.
|
|
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
|
-
[](https://gitlab.com/leogermond/contractme/-/commits/main)
|
|
24
|
+
[](https://gitlab.com/leogermond/contractme/-/commits/main)
|
|
25
25
|

|
|
26
26
|
[](https://microsoft.github.io/pyright/)
|
|
27
27
|
[](https://github.com/psf/black)
|
|
28
28
|
[](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
|
-
`
|
|
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
|
-
|
|
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
|
-
[](https://gitlab.com/leogermond/contractme/-/commits/main)
|
|
5
|
+
[](https://gitlab.com/leogermond/contractme/-/commits/main)
|
|
6
6
|

|
|
7
7
|
[](https://microsoft.github.io/pyright/)
|
|
8
8
|
[](https://github.com/psf/black)
|
|
9
9
|
[](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
|
-
`
|
|
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
|
-
|
|
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*
|