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.
Files changed (73) hide show
  1. {contractme-2.2.0 → contractme-2.4.1}/.flake8 +1 -1
  2. {contractme-2.2.0 → contractme-2.4.1}/.gitignore +1 -0
  3. {contractme-2.2.0 → contractme-2.4.1}/.gitlab-ci.yml +54 -13
  4. {contractme-2.2.0 → contractme-2.4.1}/CHANGELOG.md +85 -0
  5. {contractme-2.2.0 → contractme-2.4.1}/PKG-INFO +21 -9
  6. {contractme-2.2.0 → contractme-2.4.1}/README.md +19 -7
  7. contractme-2.4.1/docs/comparison-facts.yaml +73 -0
  8. {contractme-2.2.0 → contractme-2.4.1}/pyproject.toml +1 -1
  9. contractme-2.4.1/release_notes.md +12 -0
  10. {contractme-2.2.0 → contractme-2.4.1}/src/contractme/annotations.py +26 -14
  11. {contractme-2.2.0 → contractme-2.4.1}/src/contractme/config.py +15 -2
  12. {contractme-2.2.0 → contractme-2.4.1}/src/contractme/contracting.py +291 -90
  13. {contractme-2.2.0 → contractme-2.4.1}/src/contractme/probing.py +3 -3
  14. {contractme-2.2.0 → contractme-2.4.1}/src/contractme/records.py +11 -14
  15. {contractme-2.2.0 → contractme-2.4.1}/src/contractme/skills/contractme/SKILL.md +63 -13
  16. contractme-2.4.1/src/contractme/testing.py +141 -0
  17. contractme-2.4.1/src/contractme/typecheck.py +443 -0
  18. {contractme-2.2.0 → contractme-2.4.1}/src/contractme/types/predicates.py +17 -10
  19. {contractme-2.2.0 → contractme-2.4.1}/src/contractme/typeshape.py +53 -6
  20. {contractme-2.2.0 → contractme-2.4.1}/tests/conftest.py +2 -2
  21. {contractme-2.2.0 → contractme-2.4.1}/tests/test_annotations.py +65 -375
  22. contractme-2.4.1/tests/test_async.py +479 -0
  23. {contractme-2.2.0 → contractme-2.4.1}/tests/test_contracting.py +196 -0
  24. contractme-2.4.1/tests/test_evaluation_order.py +323 -0
  25. contractme-2.4.1/tests/test_hypothesis_async.py +200 -0
  26. contractme-2.4.1/tests/test_literal.py +73 -0
  27. {contractme-2.2.0 → contractme-2.4.1}/tests/test_optimized_policy.py +61 -0
  28. contractme-2.4.1/tests/test_predicate_source.py +408 -0
  29. {contractme-2.2.0 → contractme-2.4.1}/tests/test_typechecks.py +213 -2
  30. {contractme-2.2.0 → contractme-2.4.1}/tests/test_types_extra.py +76 -0
  31. {contractme-2.2.0 → contractme-2.4.1}/tests/test_typeshape.py +58 -1
  32. {contractme-2.2.0 → contractme-2.4.1}/uv.lock +1 -1
  33. contractme-2.2.0/release_notes.md +0 -7
  34. contractme-2.2.0/src/contractme/testing.py +0 -67
  35. contractme-2.2.0/src/contractme/typecheck.py +0 -244
  36. {contractme-2.2.0 → contractme-2.4.1}/.pre-commit-config.yaml +0 -0
  37. {contractme-2.2.0 → contractme-2.4.1}/.python-version +0 -0
  38. {contractme-2.2.0 → contractme-2.4.1}/.vscode/settings.json +0 -0
  39. {contractme-2.2.0 → contractme-2.4.1}/CLAUDE.md +0 -0
  40. {contractme-2.2.0 → contractme-2.4.1}/LICENSE +0 -0
  41. {contractme-2.2.0 → contractme-2.4.1}/context7.json +0 -0
  42. {contractme-2.2.0 → contractme-2.4.1}/docs/comparison.md +0 -0
  43. {contractme-2.2.0 → contractme-2.4.1}/docs/types.md +0 -0
  44. {contractme-2.2.0 → contractme-2.4.1}/justfile +0 -0
  45. {contractme-2.2.0 → contractme-2.4.1}/release/prerelease.py +0 -0
  46. {contractme-2.2.0 → contractme-2.4.1}/release/pypi_mint_token.py +0 -0
  47. {contractme-2.2.0 → contractme-2.4.1}/release/release_notes.py +0 -0
  48. {contractme-2.2.0 → contractme-2.4.1}/src/contractme/__init__.py +0 -0
  49. {contractme-2.2.0 → contractme-2.4.1}/src/contractme/policy.py +0 -0
  50. {contractme-2.2.0 → contractme-2.4.1}/src/contractme/py.typed +0 -0
  51. {contractme-2.2.0 → contractme-2.4.1}/src/contractme/result.py +0 -0
  52. {contractme-2.2.0 → contractme-2.4.1}/src/contractme/types/__init__.py +0 -0
  53. {contractme-2.2.0 → contractme-2.4.1}/src/contractme/types/containers.py +0 -0
  54. {contractme-2.2.0 → contractme-2.4.1}/src/contractme/types/data.py +0 -0
  55. {contractme-2.2.0 → contractme-2.4.1}/src/contractme/types/identifiers.py +0 -0
  56. {contractme-2.2.0 → contractme-2.4.1}/src/contractme/types/network.py +0 -0
  57. {contractme-2.2.0 → contractme-2.4.1}/src/contractme/types/numeric.py +0 -0
  58. {contractme-2.2.0 → contractme-2.4.1}/src/contractme/types/paths.py +0 -0
  59. {contractme-2.2.0 → contractme-2.4.1}/src/contractme/types/system.py +0 -0
  60. {contractme-2.2.0 → contractme-2.4.1}/src/contractme/types/temporal.py +0 -0
  61. {contractme-2.2.0 → contractme-2.4.1}/src/contractme/types/text.py +0 -0
  62. {contractme-2.2.0 → contractme-2.4.1}/tests/test_annotations_future.py +0 -0
  63. {contractme-2.2.0 → contractme-2.4.1}/tests/test_canaries.py +0 -0
  64. {contractme-2.2.0 → contractme-2.4.1}/tests/test_contracting_optimized_python.py +0 -0
  65. {contractme-2.2.0 → contractme-2.4.1}/tests/test_hypothesis.py +0 -0
  66. {contractme-2.2.0 → contractme-2.4.1}/tests/test_layering.py +0 -0
  67. {contractme-2.2.0 → contractme-2.4.1}/tests/test_policy.py +0 -0
  68. {contractme-2.2.0 → contractme-2.4.1}/tests/test_probing.py +0 -0
  69. {contractme-2.2.0 → contractme-2.4.1}/tests/test_records.py +0 -0
  70. {contractme-2.2.0 → contractme-2.4.1}/tests/test_reentrancy.py +0 -0
  71. {contractme-2.2.0 → contractme-2.4.1}/tests/test_show_source.py +0 -0
  72. {contractme-2.2.0 → contractme-2.4.1}/tests/test_types.py +0 -0
  73. {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__
@@ -14,3 +14,4 @@ obj
14
14
 
15
15
  # tooling
16
16
  .claude/
17
+ .uv-cache/
@@ -1,10 +1,25 @@
1
1
  variables:
2
2
  UV_VERSION: 0.9
3
- PYTHON_VERSION: 3.12
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: .uv
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: .uv
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.4
1
+ Metadata-Version: 2.5
2
2
  Name: contractme
3
- Version: 2.2.0
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 precondition, postcondition
72
+ from contractme import annotated, postcondition
73
+ from contractme.types import NonNegativeFloat
73
74
 
74
- @precondition(lambda x: x >= 0)
75
+ @annotated
75
76
  @postcondition(lambda x, result: math.isclose(result * result, x, abs_tol=1e-12))
76
- def square_root(x: float) -> float:
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
- @precondition(lambda l, n: n >= 0)
88
- @postcondition(lambda l, n: l[-1] == n) # element appended
89
- @postcondition(lambda l, n, old: l[:-1] == old.l) # nothing lost
90
- def append_count(l: list[int], n: int):
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 precondition, postcondition
53
+ from contractme import annotated, postcondition
54
+ from contractme.types import NonNegativeFloat
54
55
 
55
- @precondition(lambda x: x >= 0)
56
+ @annotated
56
57
  @postcondition(lambda x, result: math.isclose(result * result, x, abs_tol=1e-12))
57
- def square_root(x: float) -> float:
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
- @precondition(lambda l, n: n >= 0)
69
- @postcondition(lambda l, n: l[-1] == n) # element appended
70
- @postcondition(lambda l, n, old: l[:-1] == old.l) # nothing lost
71
- def append_count(l: list[int], n: int):
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
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "contractme"
3
- version = "2.2.0"
3
+ version = "2.4.1"
4
4
  description = "Executable specifications for python. Keep control of the code AI writes for you."
5
5
  readme = "README.md"
6
6
  license = "Apache-2.0"
@@ -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 ContractedFunction, precondition, postcondition
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``, ...). Every type shape :mod:`typeshape`
20
- models is supported — scalars, containers, unions, tuples, dataclasses
21
- (field-by-field), enums, ``Protocol`` duck typing, and recursive types.
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
- msg = f"{arg_name} should be instance of {info.base}"
43
- if info.constraints:
44
- msg += f" under constraints {tuple(info.constraints)}"
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
- cond_f = postcondition
56
+ kind = POST
49
57
  else:
50
58
  cond_arg_name = arg_name
51
- cond_f = precondition
59
+ kind = PRE
52
60
 
53
61
  def chk(**kw):
54
- return type_error(kw[cond_arg_name], arg_an) is None
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"{msg}: {err}"
69
+ return f"{header()}: {err}"
62
70
 
63
- return cond_f(chk, describe_failure)
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
- for n, an in ans.items():
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 hasattr(f, "contractme_wrapped"):
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", True)
69
+ setattr(f, "contractme_no_contracts", f)
57
70
  return f
58
71
 
59
72