contractme 2.2.0__tar.gz → 2.4.1__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.2.0 → contractme-2.4.1}/.flake8 +1 -1
- {contractme-2.2.0 → contractme-2.4.1}/.gitignore +1 -0
- {contractme-2.2.0 → contractme-2.4.1}/.gitlab-ci.yml +54 -13
- {contractme-2.2.0 → contractme-2.4.1}/CHANGELOG.md +85 -0
- {contractme-2.2.0 → contractme-2.4.1}/PKG-INFO +21 -9
- {contractme-2.2.0 → contractme-2.4.1}/README.md +19 -7
- contractme-2.4.1/docs/comparison-facts.yaml +73 -0
- {contractme-2.2.0 → contractme-2.4.1}/pyproject.toml +1 -1
- contractme-2.4.1/release_notes.md +12 -0
- {contractme-2.2.0 → contractme-2.4.1}/src/contractme/annotations.py +26 -14
- {contractme-2.2.0 → contractme-2.4.1}/src/contractme/config.py +15 -2
- {contractme-2.2.0 → contractme-2.4.1}/src/contractme/contracting.py +291 -90
- {contractme-2.2.0 → contractme-2.4.1}/src/contractme/probing.py +3 -3
- {contractme-2.2.0 → contractme-2.4.1}/src/contractme/records.py +11 -14
- {contractme-2.2.0 → contractme-2.4.1}/src/contractme/skills/contractme/SKILL.md +63 -13
- contractme-2.4.1/src/contractme/testing.py +141 -0
- contractme-2.4.1/src/contractme/typecheck.py +443 -0
- {contractme-2.2.0 → contractme-2.4.1}/src/contractme/types/predicates.py +17 -10
- {contractme-2.2.0 → contractme-2.4.1}/src/contractme/typeshape.py +53 -6
- {contractme-2.2.0 → contractme-2.4.1}/tests/conftest.py +2 -2
- {contractme-2.2.0 → contractme-2.4.1}/tests/test_annotations.py +65 -375
- contractme-2.4.1/tests/test_async.py +479 -0
- {contractme-2.2.0 → contractme-2.4.1}/tests/test_contracting.py +196 -0
- contractme-2.4.1/tests/test_evaluation_order.py +323 -0
- contractme-2.4.1/tests/test_hypothesis_async.py +200 -0
- contractme-2.4.1/tests/test_literal.py +73 -0
- {contractme-2.2.0 → contractme-2.4.1}/tests/test_optimized_policy.py +61 -0
- contractme-2.4.1/tests/test_predicate_source.py +408 -0
- {contractme-2.2.0 → contractme-2.4.1}/tests/test_typechecks.py +213 -2
- {contractme-2.2.0 → contractme-2.4.1}/tests/test_types_extra.py +76 -0
- {contractme-2.2.0 → contractme-2.4.1}/tests/test_typeshape.py +58 -1
- {contractme-2.2.0 → contractme-2.4.1}/uv.lock +1 -1
- contractme-2.2.0/release_notes.md +0 -7
- contractme-2.2.0/src/contractme/testing.py +0 -67
- contractme-2.2.0/src/contractme/typecheck.py +0 -244
- {contractme-2.2.0 → contractme-2.4.1}/.pre-commit-config.yaml +0 -0
- {contractme-2.2.0 → contractme-2.4.1}/.python-version +0 -0
- {contractme-2.2.0 → contractme-2.4.1}/.vscode/settings.json +0 -0
- {contractme-2.2.0 → contractme-2.4.1}/CLAUDE.md +0 -0
- {contractme-2.2.0 → contractme-2.4.1}/LICENSE +0 -0
- {contractme-2.2.0 → contractme-2.4.1}/context7.json +0 -0
- {contractme-2.2.0 → contractme-2.4.1}/docs/comparison.md +0 -0
- {contractme-2.2.0 → contractme-2.4.1}/docs/types.md +0 -0
- {contractme-2.2.0 → contractme-2.4.1}/justfile +0 -0
- {contractme-2.2.0 → contractme-2.4.1}/release/prerelease.py +0 -0
- {contractme-2.2.0 → contractme-2.4.1}/release/pypi_mint_token.py +0 -0
- {contractme-2.2.0 → contractme-2.4.1}/release/release_notes.py +0 -0
- {contractme-2.2.0 → contractme-2.4.1}/src/contractme/__init__.py +0 -0
- {contractme-2.2.0 → contractme-2.4.1}/src/contractme/policy.py +0 -0
- {contractme-2.2.0 → contractme-2.4.1}/src/contractme/py.typed +0 -0
- {contractme-2.2.0 → contractme-2.4.1}/src/contractme/result.py +0 -0
- {contractme-2.2.0 → contractme-2.4.1}/src/contractme/types/__init__.py +0 -0
- {contractme-2.2.0 → contractme-2.4.1}/src/contractme/types/containers.py +0 -0
- {contractme-2.2.0 → contractme-2.4.1}/src/contractme/types/data.py +0 -0
- {contractme-2.2.0 → contractme-2.4.1}/src/contractme/types/identifiers.py +0 -0
- {contractme-2.2.0 → contractme-2.4.1}/src/contractme/types/network.py +0 -0
- {contractme-2.2.0 → contractme-2.4.1}/src/contractme/types/numeric.py +0 -0
- {contractme-2.2.0 → contractme-2.4.1}/src/contractme/types/paths.py +0 -0
- {contractme-2.2.0 → contractme-2.4.1}/src/contractme/types/system.py +0 -0
- {contractme-2.2.0 → contractme-2.4.1}/src/contractme/types/temporal.py +0 -0
- {contractme-2.2.0 → contractme-2.4.1}/src/contractme/types/text.py +0 -0
- {contractme-2.2.0 → contractme-2.4.1}/tests/test_annotations_future.py +0 -0
- {contractme-2.2.0 → contractme-2.4.1}/tests/test_canaries.py +0 -0
- {contractme-2.2.0 → contractme-2.4.1}/tests/test_contracting_optimized_python.py +0 -0
- {contractme-2.2.0 → contractme-2.4.1}/tests/test_hypothesis.py +0 -0
- {contractme-2.2.0 → contractme-2.4.1}/tests/test_layering.py +0 -0
- {contractme-2.2.0 → contractme-2.4.1}/tests/test_policy.py +0 -0
- {contractme-2.2.0 → contractme-2.4.1}/tests/test_probing.py +0 -0
- {contractme-2.2.0 → contractme-2.4.1}/tests/test_records.py +0 -0
- {contractme-2.2.0 → contractme-2.4.1}/tests/test_reentrancy.py +0 -0
- {contractme-2.2.0 → contractme-2.4.1}/tests/test_show_source.py +0 -0
- {contractme-2.2.0 → contractme-2.4.1}/tests/test_types.py +0 -0
- {contractme-2.2.0 → contractme-2.4.1}/tests/test_types_advanced.py +0 -0
|
@@ -4,4 +4,4 @@ max-line-length = 100
|
|
|
4
4
|
# E741: `l` is used on purpose as the list parameter in the design-by-contract
|
|
5
5
|
# examples (e.g. append_count(l, n)), mirroring the README
|
|
6
6
|
extend-ignore = E203, E741
|
|
7
|
-
exclude = .venv, obj, build, dist, .git, __pycache__
|
|
7
|
+
exclude = .venv, .uv-cache, obj, build, dist, .git, __pycache__
|
|
@@ -1,10 +1,25 @@
|
|
|
1
1
|
variables:
|
|
2
2
|
UV_VERSION: 0.9
|
|
3
|
-
|
|
3
|
+
# Matches pyproject's requires-python (>=3.13): the image ships the interpreter,
|
|
4
|
+
# so uv no longer downloads one in every job (saves ~10s per job).
|
|
5
|
+
PYTHON_VERSION: 3.13
|
|
4
6
|
BASE_LAYER: bookworm-slim
|
|
5
7
|
# GitLab CI creates a separate mountpoint for the build directory,
|
|
6
8
|
# so we need to copy instead of using hard links.
|
|
7
9
|
UV_LINK_MODE: copy
|
|
10
|
+
# Project-local so the `cache:` of .uv below can store it between jobs.
|
|
11
|
+
UV_CACHE_DIR: .uv-cache
|
|
12
|
+
|
|
13
|
+
# Pipelines exist only for MR events, main pushes and release tags. A new commit
|
|
14
|
+
# cancels the still-running `interruptible` jobs of the older pipeline, so a burst
|
|
15
|
+
# of pushes bills one test run instead of one per push.
|
|
16
|
+
workflow:
|
|
17
|
+
auto_cancel:
|
|
18
|
+
on_new_commit: interruptible
|
|
19
|
+
rules:
|
|
20
|
+
- if: $CI_PIPELINE_SOURCE == "merge_request_event"
|
|
21
|
+
- if: $CI_COMMIT_BRANCH == "main"
|
|
22
|
+
- if: $CI_COMMIT_TAG =~ /^v/
|
|
8
23
|
|
|
9
24
|
stages:
|
|
10
25
|
- test
|
|
@@ -17,16 +32,49 @@ stages:
|
|
|
17
32
|
rules:
|
|
18
33
|
- if: $CI_COMMIT_TAG =~ /^v\d+\.\d+\.\d+/
|
|
19
34
|
|
|
35
|
+
# Skip the test jobs on pushes that touch nothing the tests read (docs, README,
|
|
36
|
+
# CHANGELOG...): no minutes spent. release/ is linted and type-checked, hence listed.
|
|
37
|
+
.on-code-change:
|
|
38
|
+
rules:
|
|
39
|
+
- if: $CI_PIPELINE_SOURCE == "merge_request_event"
|
|
40
|
+
changes: &code-paths
|
|
41
|
+
- src/**/*
|
|
42
|
+
- tests/**/*
|
|
43
|
+
- release/**/*
|
|
44
|
+
- pyproject.toml
|
|
45
|
+
- uv.lock
|
|
46
|
+
- justfile
|
|
47
|
+
- .flake8
|
|
48
|
+
- .gitlab-ci.yml
|
|
49
|
+
when: always
|
|
50
|
+
- if: $CI_COMMIT_BRANCH == "main"
|
|
51
|
+
changes: *code-paths
|
|
52
|
+
when: always
|
|
53
|
+
|
|
54
|
+
# The uv cache (wheels, hypothesis/pyright deps) is shared across jobs and
|
|
55
|
+
# pipelines, keyed on uv.lock: saves the re-download of every dependency each run.
|
|
56
|
+
# `uv cache prune --ci` drops what is cheap to rebuild so the cache stays small.
|
|
20
57
|
.uv:
|
|
21
58
|
image: ghcr.io/astral-sh/uv:$UV_VERSION-python$PYTHON_VERSION-$BASE_LAYER
|
|
59
|
+
cache:
|
|
60
|
+
key:
|
|
61
|
+
files:
|
|
62
|
+
- uv.lock
|
|
63
|
+
paths:
|
|
64
|
+
- .uv-cache
|
|
65
|
+
after_script:
|
|
66
|
+
- uv cache prune --ci
|
|
22
67
|
|
|
23
68
|
# The scripts are one-liner justfile recipe calls (`uv run just ...`, the just
|
|
24
69
|
# binary comes from the dev deps) so CI runs exactly what `just check` runs
|
|
25
70
|
# locally; only the report/artifact flags are CI extras, passed through the
|
|
26
71
|
# recipes' *args.
|
|
27
72
|
checks:
|
|
28
|
-
extends:
|
|
73
|
+
extends:
|
|
74
|
+
- .uv
|
|
75
|
+
- .on-code-change
|
|
29
76
|
stage: test
|
|
77
|
+
interruptible: true
|
|
30
78
|
before_script:
|
|
31
79
|
- |
|
|
32
80
|
if echo "$CI_MERGE_REQUEST_TITLE" | grep -iq "^draft:\|^wip:"; then
|
|
@@ -61,11 +109,6 @@ checks:
|
|
|
61
109
|
coverage_format: cobertura
|
|
62
110
|
path: obj/cov.xml
|
|
63
111
|
junit: obj/tests_report.xml
|
|
64
|
-
rules:
|
|
65
|
-
- if: $CI_PIPELINE_SOURCE == "merge_request_event"
|
|
66
|
-
when: always
|
|
67
|
-
- if: $CI_COMMIT_BRANCH == "main"
|
|
68
|
-
when: always
|
|
69
112
|
|
|
70
113
|
# Differential run: contracts are pure redundancy, so with them compiled out
|
|
71
114
|
# (python -O) the suite must still pass on valid inputs. Contract-violation
|
|
@@ -74,18 +117,16 @@ checks:
|
|
|
74
117
|
# The ignored warning is pytest noticing library asserts are off — which is
|
|
75
118
|
# exactly what this job is about.
|
|
76
119
|
checks-optimized:
|
|
77
|
-
extends:
|
|
120
|
+
extends:
|
|
121
|
+
- .uv
|
|
122
|
+
- .on-code-change
|
|
78
123
|
stage: test
|
|
124
|
+
interruptible: true
|
|
79
125
|
script:
|
|
80
126
|
- uv run just test-optimized --junitxml=obj/tests_report_optimized.xml
|
|
81
127
|
artifacts:
|
|
82
128
|
reports:
|
|
83
129
|
junit: obj/tests_report_optimized.xml
|
|
84
|
-
rules:
|
|
85
|
-
- if: $CI_PIPELINE_SOURCE == "merge_request_event"
|
|
86
|
-
when: always
|
|
87
|
-
- if: $CI_COMMIT_BRANCH == "main"
|
|
88
|
-
when: always
|
|
89
130
|
|
|
90
131
|
# Validate the tag against pyproject + CHANGELOG, extract the release notes,
|
|
91
132
|
# then build dists.
|
|
@@ -7,6 +7,91 @@ 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.4.1
|
|
11
|
+
|
|
12
|
+
* A failed `Predicate` constraint is named by its source when it is a lambda
|
|
13
|
+
(`Predicate(lambda s: s.islower())`), by its qualified name otherwise, in `type_error`,
|
|
14
|
+
`@record` and the `@annotated` header, where it used to print `<function <lambda> at 0x…>`;
|
|
15
|
+
a lambda with default arguments, or whose source cannot be proven to match, falls back to
|
|
16
|
+
its qualified name ([#80](https://gitlab.com/leogermond/contractme/-/issues/80)).
|
|
17
|
+
* A passing check and every `accepts`/`rejects` probe build no message, unions included:
|
|
18
|
+
the text is written only for the failure that gets reported
|
|
19
|
+
([#80](https://gitlab.com/leogermond/contractme/-/issues/80)).
|
|
20
|
+
* The `@annotated` header lists its constraints as `under constraints [...]`, where it used
|
|
21
|
+
to show a tuple ([#80](https://gitlab.com/leogermond/contractme/-/issues/80)).
|
|
22
|
+
* v2.4.0 never reached PyPI (its CI build failed on the in-project uv cache): v2.4.1 ships
|
|
23
|
+
its changes too, see below ([5739ee2](https://gitlab.com/leogermond/contractme/-/commit/5739ee2)).
|
|
24
|
+
|
|
25
|
+
## v2.4.0
|
|
26
|
+
|
|
27
|
+
* A decorator built with `functools.wraps` around a contracted function keeps its own
|
|
28
|
+
body: it used to be silently skipped, the contracted function running in its place
|
|
29
|
+
([#73](https://gitlab.com/leogermond/contractme/-/issues/73)).
|
|
30
|
+
* `@annotated` type checks now run before the explicit `@precondition`/`@postcondition`,
|
|
31
|
+
whatever the decorator order, so a wrong type is reported as such instead of a more
|
|
32
|
+
distant contract failing, or a precondition crashing on the ill-typed argument, or a
|
|
33
|
+
postcondition crashing on the ill-typed result under `observe`/`warn`
|
|
34
|
+
([#78](https://gitlab.com/leogermond/contractme/-/issues/78)).
|
|
35
|
+
* A callable `message=` receives the parameters it declares itself (`result` and
|
|
36
|
+
`old` included), independently of the predicate; it used to raise `KeyError` in
|
|
37
|
+
place of the violation
|
|
38
|
+
([#70](https://gitlab.com/leogermond/contractme/-/issues/70)).
|
|
39
|
+
* A callable `message=` naming a parameter the function lacks is refused with a
|
|
40
|
+
`TypeError` when the contract is declared, instead of a `KeyError` at its first
|
|
41
|
+
failure ([#70](https://gitlab.com/leogermond/contractme/-/issues/70)).
|
|
42
|
+
* A `functools.wraps` wrapper is told apart from the function it wraps by
|
|
43
|
+
`@no_contracts` and by the contract decorators: marking a wrapper of a contracted
|
|
44
|
+
function, or contracting a wrapper of a `@no_contracts` function, now works
|
|
45
|
+
([#74](https://gitlab.com/leogermond/contractme/-/issues/74)).
|
|
46
|
+
* A contracted function exposes `__name__`, `__qualname__` and `__doc__` to the type
|
|
47
|
+
checker, like a plain function: `step.__name__` passes pyright
|
|
48
|
+
([#77](https://gitlab.com/leogermond/contractme/-/issues/77)).
|
|
49
|
+
* CI spends fewer runner minutes (Python 3.13 image, uv cache, tests skipped on
|
|
50
|
+
doc-only pushes) ([5f70e0d](https://gitlab.com/leogermond/contractme/-/commit/5f70e0d)).
|
|
51
|
+
|
|
52
|
+
## v2.3.0
|
|
53
|
+
|
|
54
|
+
* Contracts now work on `async def`. `@precondition`, `@postcondition` and
|
|
55
|
+
`@annotated` check across the await: postconditions and the return type check
|
|
56
|
+
see the **awaited value**, never the coroutine, and `old` captures before the
|
|
57
|
+
await. `inspect.iscoroutinefunction()` holds on the decorated form, so
|
|
58
|
+
pytest-asyncio, anyio and FastAPI route it correctly. This was silently
|
|
59
|
+
broken, not merely missing: `@annotated` used to raise on every *valid* call
|
|
60
|
+
while never awaiting the coroutine — so the body never ran — and the same
|
|
61
|
+
code worked under `CONTRACTME_OPTIMIZED`. Predicates must stay synchronous;
|
|
62
|
+
an `async def` predicate is refused at decoration time.
|
|
63
|
+
* `autotest` / `property_test` drive an async target: each drawn example runs
|
|
64
|
+
under `asyncio.run`, no new dependency. What is out of reach now refuses
|
|
65
|
+
loudly instead of passing empty — an already-running event loop is rejected
|
|
66
|
+
before any coroutine exists, and an async generator raises. `accepts` /
|
|
67
|
+
`rejects` stay synchronous and argument-only on async targets: they answer
|
|
68
|
+
"is this call legal?", which never requires running a body or an event loop.
|
|
69
|
+
* `typing.Literal` is now checked, as a sum of singletons: `Literal[1]` rejects
|
|
70
|
+
`True` and `Literal[True]` rejects `1`, since membership tests the type
|
|
71
|
+
before the value. It used to raise `NotImplementedError` *even for a valid
|
|
72
|
+
member*, so the annotation was unusable rather than merely unchecked;
|
|
73
|
+
`autotest` covers it for free, Hypothesis already samples `Literal`.
|
|
74
|
+
`dataclasses.Field[T]` is checked as an `isinstance` leaf (`T` is
|
|
75
|
+
static-only and is not claimed to be verified), which unblocks a `Protocol`
|
|
76
|
+
declaring `__dataclass_fields__`.
|
|
77
|
+
* `int` is accepted where `float` is declared, and `int`/`float` where
|
|
78
|
+
`complex` is (PEP 484 numeric tower, matching pyright). An alias such as
|
|
79
|
+
`Seconds = Annotated[float, Gt(0)]` used to reject `60`, making duration
|
|
80
|
+
annotations unusable — a function could be refused by its own integer
|
|
81
|
+
default. The reverse stays an error, constraints still apply to the promoted
|
|
82
|
+
value, and no value is ever converted.
|
|
83
|
+
* `is_signal_number` no longer raises `TypeError` on an unhashable value: it
|
|
84
|
+
answers `False`, as every predicate in the module promises to.
|
|
85
|
+
* Tighter string predicates: `is_semver`, `is_e164`, `is_byte_size` and
|
|
86
|
+
`is_duration` matched Unicode digits and case-folded outside ASCII, accepting
|
|
87
|
+
`"+١٢٣٤٥٦٧٨"` as a phone number and `"10KB"` (KELVIN SIGN) as a byte size.
|
|
88
|
+
* `is_iana_timezone` caches the tzdata scan instead of redoing it (~9 ms) on
|
|
89
|
+
every check; `property_test` builds its Hypothesis strategies once at
|
|
90
|
+
construction rather than inside the draw path.
|
|
91
|
+
* Internal: violation construction deduplicated, a stale `sys.version_info`
|
|
92
|
+
assert dropped, value-walker signatures annotated, constraint tests
|
|
93
|
+
parametrized.
|
|
94
|
+
|
|
10
95
|
## v2.2.0
|
|
11
96
|
|
|
12
97
|
* `ClassVar[T]` and `Final[T]` now check everywhere a type does: the marker is
|
|
@@ -1,6 +1,6 @@
|
|
|
1
|
-
Metadata-Version: 2.
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
2
|
Name: contractme
|
|
3
|
-
Version: 2.
|
|
3
|
+
Version: 2.4.1
|
|
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>
|
|
@@ -69,11 +69,12 @@ ready-made types](docs/types.md) (`Port`, `EmailStr`, `Positive`, …).
|
|
|
69
69
|
|
|
70
70
|
```python
|
|
71
71
|
import math
|
|
72
|
-
from contractme import
|
|
72
|
+
from contractme import annotated, postcondition
|
|
73
|
+
from contractme.types import NonNegativeFloat
|
|
73
74
|
|
|
74
|
-
@
|
|
75
|
+
@annotated
|
|
75
76
|
@postcondition(lambda x, result: math.isclose(result * result, x, abs_tol=1e-12))
|
|
76
|
-
def square_root(x:
|
|
77
|
+
def square_root(x: NonNegativeFloat) -> NonNegativeFloat:
|
|
77
78
|
return x**0.5
|
|
78
79
|
```
|
|
79
80
|
|
|
@@ -84,13 +85,24 @@ it — this is the ground only contracts cover.
|
|
|
84
85
|
Rules can even compare the state before and after the call (`old`):
|
|
85
86
|
|
|
86
87
|
```python
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
88
|
+
from contractme import annotated, postcondition
|
|
89
|
+
from contractme.types import NonNegativeInt
|
|
90
|
+
|
|
91
|
+
@annotated
|
|
92
|
+
@postcondition(lambda l, n: l[-1] == n) # element appended
|
|
93
|
+
@postcondition(lambda l, old: l[:-1] == old.l) # nothing lost
|
|
94
|
+
def append_count(l: list[NonNegativeInt], n: NonNegativeInt):
|
|
91
95
|
l.append(n)
|
|
92
96
|
```
|
|
93
97
|
|
|
98
|
+
Stack `@annotated` and the explicit rules in any order: the type checks run
|
|
99
|
+
first — parameter types, in signature order, before the preconditions; the return
|
|
100
|
+
type before the postconditions — so a violation names its most immediate cause.
|
|
101
|
+
The types guard the relational rules of their side: when a parameter type fails,
|
|
102
|
+
it is reported and the preconditions stay unevaluated; when the return type fails,
|
|
103
|
+
it is reported and the postconditions stay unevaluated. Write the relational rules
|
|
104
|
+
for well-typed values only.
|
|
105
|
+
|
|
94
106
|
## When the generated code is wrong, you hear about it
|
|
95
107
|
|
|
96
108
|
Say your agent "implements" `square_root` as `return x / 2` — plausible at a
|
|
@@ -50,11 +50,12 @@ ready-made types](docs/types.md) (`Port`, `EmailStr`, `Positive`, …).
|
|
|
50
50
|
|
|
51
51
|
```python
|
|
52
52
|
import math
|
|
53
|
-
from contractme import
|
|
53
|
+
from contractme import annotated, postcondition
|
|
54
|
+
from contractme.types import NonNegativeFloat
|
|
54
55
|
|
|
55
|
-
@
|
|
56
|
+
@annotated
|
|
56
57
|
@postcondition(lambda x, result: math.isclose(result * result, x, abs_tol=1e-12))
|
|
57
|
-
def square_root(x:
|
|
58
|
+
def square_root(x: NonNegativeFloat) -> NonNegativeFloat:
|
|
58
59
|
return x**0.5
|
|
59
60
|
```
|
|
60
61
|
|
|
@@ -65,13 +66,24 @@ it — this is the ground only contracts cover.
|
|
|
65
66
|
Rules can even compare the state before and after the call (`old`):
|
|
66
67
|
|
|
67
68
|
```python
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
69
|
+
from contractme import annotated, postcondition
|
|
70
|
+
from contractme.types import NonNegativeInt
|
|
71
|
+
|
|
72
|
+
@annotated
|
|
73
|
+
@postcondition(lambda l, n: l[-1] == n) # element appended
|
|
74
|
+
@postcondition(lambda l, old: l[:-1] == old.l) # nothing lost
|
|
75
|
+
def append_count(l: list[NonNegativeInt], n: NonNegativeInt):
|
|
72
76
|
l.append(n)
|
|
73
77
|
```
|
|
74
78
|
|
|
79
|
+
Stack `@annotated` and the explicit rules in any order: the type checks run
|
|
80
|
+
first — parameter types, in signature order, before the preconditions; the return
|
|
81
|
+
type before the postconditions — so a violation names its most immediate cause.
|
|
82
|
+
The types guard the relational rules of their side: when a parameter type fails,
|
|
83
|
+
it is reported and the preconditions stay unevaluated; when the return type fails,
|
|
84
|
+
it is reported and the postconditions stay unevaluated. Write the relational rules
|
|
85
|
+
for well-typed values only.
|
|
86
|
+
|
|
75
87
|
## When the generated code is wrong, you hear about it
|
|
76
88
|
|
|
77
89
|
Say your agent "implements" `square_root` as `return x / 2` — plausible at a
|
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
# Cached upstream facts for docs/comparison.md.
|
|
2
|
+
#
|
|
3
|
+
# Verifying competitors is the expensive half of a comparison pass, and it is
|
|
4
|
+
# also the half that barely moves between passes. So it is cached here instead
|
|
5
|
+
# of being re-derived every time: each entry carries its source and the date it
|
|
6
|
+
# was last checked. Refresh an entry when it ages out or when upstream ships a
|
|
7
|
+
# release — never re-verify the whole file by reflex.
|
|
8
|
+
#
|
|
9
|
+
# Facts about ContractMe itself are NOT cached: they are cheap to check by
|
|
10
|
+
# running them, and they must be re-checked every pass.
|
|
11
|
+
#
|
|
12
|
+
# Rule: nothing enters docs/comparison.md that is not backed by an entry here
|
|
13
|
+
# or by an execution done during that pass. "Not verified" is a publishable
|
|
14
|
+
# state; an unsourced claim is not.
|
|
15
|
+
|
|
16
|
+
beartype:
|
|
17
|
+
version: "0.22.9"
|
|
18
|
+
version_published: 2025-12-13
|
|
19
|
+
requires_python: ">=3.10"
|
|
20
|
+
checked: 2026-07-28
|
|
21
|
+
source: https://pypi.org/pypi/beartype/json
|
|
22
|
+
maintenance: |
|
|
23
|
+
Daily commits (latest 2026-07-27) but no PyPI release in over 7 months.
|
|
24
|
+
Development is active, the release cadence is not. Its readthedocs "latest"
|
|
25
|
+
documents a 0.23.0 that cannot be installed — the published docs run ahead
|
|
26
|
+
of the published package.
|
|
27
|
+
claims:
|
|
28
|
+
- claim: "beartype.claw installs an import hook that instruments a whole package or all dependencies"
|
|
29
|
+
verdict: confirmed
|
|
30
|
+
source: doc/src/api_claw.rst in the 0.22.9 sdist
|
|
31
|
+
- claim: "is_bearable(value, hint) is a boolean probe that never raises"
|
|
32
|
+
verdict: confirmed
|
|
33
|
+
note: |
|
|
34
|
+
Covers any PEP-compliant hint (generics, unions, Annotated), not just
|
|
35
|
+
bare classes — but it answers "does this match a type hint?", never an
|
|
36
|
+
arbitrary predicate.
|
|
37
|
+
source: README and doc/src/api_door.rst in the 0.22.9 sdist
|
|
38
|
+
- claim: "can warn instead of raise"
|
|
39
|
+
verdict: confirmed
|
|
40
|
+
detail: BeartypeConf(violation_type=UserWarning)
|
|
41
|
+
source: README in the 0.22.9 sdist
|
|
42
|
+
- claim: "claims O(1) checking by random sampling"
|
|
43
|
+
verdict: confirmed
|
|
44
|
+
note: This is beartype's own claim about itself, quoted as such.
|
|
45
|
+
source: doc/src/faq.rst in the 0.22.9 sdist
|
|
46
|
+
- claim: "silently ignores non-beartype Annotated metadata such as annotated-types Ge/Le"
|
|
47
|
+
verdict: confirmed_by_execution_only
|
|
48
|
+
note: |
|
|
49
|
+
True, but NOT documented by beartype. A grep for annotated_types across
|
|
50
|
+
the whole 0.22.9 sdist — code, tests and docs — returns nothing, and the
|
|
51
|
+
documented validators are only beartype.vale.Is/IsAttr/IsEqual. The
|
|
52
|
+
behaviour follows from PEP 593 (unrecognised metadata is ignored).
|
|
53
|
+
The comparison must therefore say "verified by running it", never
|
|
54
|
+
"documented by beartype".
|
|
55
|
+
source: exhaustive grep of the 0.22.9 sdist (the finding is an absence)
|
|
56
|
+
|
|
57
|
+
typeguard:
|
|
58
|
+
version: "4.6.0"
|
|
59
|
+
version_published: 2026-07-26
|
|
60
|
+
requires_python: ">=3.10"
|
|
61
|
+
checked: 2026-07-28
|
|
62
|
+
source: https://pypi.org/pypi/typeguard/json
|
|
63
|
+
maintenance: |
|
|
64
|
+
Actively maintained; commits on the day of the release. Note that 4.5.2,
|
|
65
|
+
which docs/comparison.md still cites, went stale two days before this check
|
|
66
|
+
— a version number in a comparison ages faster than anything else in it.
|
|
67
|
+
claims:
|
|
68
|
+
- claim: "runtime checking via decorator, import hook, or pytest plugin"
|
|
69
|
+
verdict: confirmed
|
|
70
|
+
detail: |
|
|
71
|
+
_decorators.py (@typechecked), _importhook.py (install_import_hook),
|
|
72
|
+
and _pytest_plugin.py, registered under the pytest11 entry point.
|
|
73
|
+
source: pyproject.toml and src/typeguard/ in the 4.6.0 sdist
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
* A failed `Predicate` constraint is named by its source when it is a lambda
|
|
2
|
+
(`Predicate(lambda s: s.islower())`), by its qualified name otherwise, in `type_error`,
|
|
3
|
+
`@record` and the `@annotated` header, where it used to print `<function <lambda> at 0x…>`;
|
|
4
|
+
a lambda with default arguments, or whose source cannot be proven to match, falls back to
|
|
5
|
+
its qualified name ([#80](https://gitlab.com/leogermond/contractme/-/issues/80)).
|
|
6
|
+
* A passing check and every `accepts`/`rejects` probe build no message, unions included:
|
|
7
|
+
the text is written only for the failure that gets reported
|
|
8
|
+
([#80](https://gitlab.com/leogermond/contractme/-/issues/80)).
|
|
9
|
+
* The `@annotated` header lists its constraints as `under constraints [...]`, where it used
|
|
10
|
+
to show a tuple ([#80](https://gitlab.com/leogermond/contractme/-/issues/80)).
|
|
11
|
+
* v2.4.0 never reached PyPI (its CI build failed on the in-project uv cache): v2.4.1 ships
|
|
12
|
+
its changes too, see below ([5739ee2](https://gitlab.com/leogermond/contractme/-/commit/5739ee2)).
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
from typing import Callable, cast, get_type_hints
|
|
2
|
-
from contractme.contracting import
|
|
3
|
-
from contractme.typecheck import type_error
|
|
2
|
+
from contractme.contracting import PRE, POST, ContractedFunction, condition_decorator
|
|
3
|
+
from contractme.typecheck import conforms, constraint_text, type_error
|
|
4
4
|
from contractme.typeshape import (
|
|
5
5
|
CompositeTypeInfo,
|
|
6
6
|
resolve_type,
|
|
@@ -16,9 +16,12 @@ def annotated[**F_Params, F_Ret](
|
|
|
16
16
|
For each parameter and the return value, ``@annotated`` auto-generates a
|
|
17
17
|
``@precondition`` (parameters) or ``@postcondition`` (return) that validates
|
|
18
18
|
both the type structure and any ``annotated-types`` constraints (``Ge``,
|
|
19
|
-
``Lt``, ``MinLen``, ``Predicate``, ...).
|
|
20
|
-
|
|
21
|
-
|
|
19
|
+
``Lt``, ``MinLen``, ``Predicate``, ...). These type checks run before the
|
|
20
|
+
explicit ``@precondition``/``@postcondition`` of the same function, whatever
|
|
21
|
+
the decorator order: a violation names its most immediate cause. Every type
|
|
22
|
+
shape :mod:`typeshape` models is supported — scalars, containers, unions,
|
|
23
|
+
tuples, dataclasses (field-by-field), enums, ``Literal`` alternatives, ``Protocol`` duck typing,
|
|
24
|
+
and recursive types.
|
|
22
25
|
|
|
23
26
|
Validation is two-phase: structure first ("is this a list?"), then
|
|
24
27
|
constraints ("are all elements ≥ 0?"). On violation the raised
|
|
@@ -39,28 +42,35 @@ def annotated[**F_Params, F_Ret](
|
|
|
39
42
|
|
|
40
43
|
def check_annotated_arg(arg_name, arg_an: AnnotationForm):
|
|
41
44
|
info = CompositeTypeInfo(resolve_type(arg_an))
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
+
|
|
46
|
+
def header() -> str:
|
|
47
|
+
# built on failure only: naming a lambda by its source reads and
|
|
48
|
+
# compiles its module, a cost decoration (an import) never pays
|
|
49
|
+
msg = f"{arg_name} should be instance of {info.base}"
|
|
50
|
+
if info.constraints:
|
|
51
|
+
msg += f" under constraints [{', '.join(map(constraint_text, info.constraints))}]"
|
|
52
|
+
return msg
|
|
45
53
|
|
|
46
54
|
if arg_name == "return":
|
|
47
55
|
cond_arg_name = "result"
|
|
48
|
-
|
|
56
|
+
kind = POST
|
|
49
57
|
else:
|
|
50
58
|
cond_arg_name = arg_name
|
|
51
|
-
|
|
59
|
+
kind = PRE
|
|
52
60
|
|
|
53
61
|
def chk(**kw):
|
|
54
|
-
return
|
|
62
|
+
return conforms(kw[cond_arg_name], arg_an)
|
|
55
63
|
|
|
56
64
|
def describe_failure(**kw):
|
|
57
65
|
# only evaluated at failure time (by the raising path, never by the
|
|
58
66
|
# accepts/rejects probes), so re-running the check is affordable and
|
|
59
67
|
# the error is known to exist
|
|
60
68
|
err = type_error(kw[cond_arg_name], arg_an)
|
|
61
|
-
return f"{
|
|
69
|
+
return f"{header()}: {err}"
|
|
62
70
|
|
|
63
|
-
|
|
71
|
+
# a type check: it runs before the explicit pre/postconditions,
|
|
72
|
+
# whatever the decorator order (issue #78)
|
|
73
|
+
return condition_decorator(kind, chk, describe_failure, type_check=True)
|
|
64
74
|
|
|
65
75
|
# `include_extras=True` keeps the `Annotated[...]` metadata (plain
|
|
66
76
|
# `get_type_hints` strips it), and, crucially, `get_type_hints` *resolves*
|
|
@@ -69,7 +79,9 @@ def annotated[**F_Params, F_Ret](
|
|
|
69
79
|
# `f.__annotations__` would be strings and silently disable every check.
|
|
70
80
|
ans = get_type_hints(f, include_extras=True)
|
|
71
81
|
|
|
72
|
-
|
|
82
|
+
# each check prepends to the type checks: apply them last hint first, so the
|
|
83
|
+
# parameter types run in signature order
|
|
84
|
+
for n, an in reversed(ans.items()):
|
|
73
85
|
f = check_annotated_arg(n, an)(f)
|
|
74
86
|
|
|
75
87
|
# the loop is invisible statically: with any hint at all, `f` is now the
|
|
@@ -27,6 +27,7 @@ from __future__ import annotations
|
|
|
27
27
|
|
|
28
28
|
import os
|
|
29
29
|
from contextlib import contextmanager
|
|
30
|
+
from types import MethodType
|
|
30
31
|
from typing import Any, Callable
|
|
31
32
|
|
|
32
33
|
from contractme.policy import (
|
|
@@ -50,10 +51,22 @@ def no_contracts(f: Callable) -> Callable:
|
|
|
50
51
|
"""Mark ``f`` as never contractable: applying a contract to it raises at
|
|
51
52
|
decoration time. The engine's check-path helpers rely on it; also usable on
|
|
52
53
|
any function that must stay contract-free (hot paths, engine extensions).
|
|
54
|
+
|
|
55
|
+
Both ways are decided by *identity* (issue #74, as #73 for ``get_wrapped``):
|
|
56
|
+
``functools.wraps`` copies ``__dict__``, so a wrapper carries the wrapped
|
|
57
|
+
function's ``contractme_*`` attributes. "Already contracted" is the engine's
|
|
58
|
+
wrapper — its *class* carries ``contractme_engine_wrapper``, which ``wraps``
|
|
59
|
+
never copies — or, under ``optimized``, a function whose
|
|
60
|
+
``contractme_wrapped`` is itself. The mark stores the marked function, so it
|
|
61
|
+
designates that function alone. A bound method designates its function
|
|
62
|
+
(``__func__``, the very object, so identity still holds).
|
|
53
63
|
"""
|
|
54
|
-
if
|
|
64
|
+
target = f.__func__ if isinstance(f, MethodType) else f
|
|
65
|
+
if getattr(type(target), "contractme_engine_wrapper", False) or (
|
|
66
|
+
getattr(target, "contractme_wrapped", None) is target
|
|
67
|
+
):
|
|
55
68
|
raise RuntimeError(f"{f.__name__}() is already contracted")
|
|
56
|
-
setattr(f, "contractme_no_contracts",
|
|
69
|
+
setattr(f, "contractme_no_contracts", f)
|
|
57
70
|
return f
|
|
58
71
|
|
|
59
72
|
|