contractme 2.3.0__tar.gz → 2.4.2__tar.gz

{contractme-2.3.0 → contractme-2.4.2}/.flake8

@@ -4,4 +4,4 @@ max-line-length = 100
 # E741: `l` is used on purpose as the list parameter in the design-by-contract
 #       examples (e.g. append_count(l, n)), mirroring the README
 extend-ignore = E203, E741
-exclude = .venv, obj, build, dist, .git, __pycache__
+exclude = .venv, .uv-cache, obj, build, dist, .git, __pycache__

{contractme-2.3.0 → contractme-2.4.2}/.gitignore

@@ -14,3 +14,4 @@ obj
 
 # tooling
 .claude/
+.uv-cache/

{contractme-2.3.0 → contractme-2.4.2}/.gitlab-ci.yml

@@ -1,10 +1,25 @@
 variables:
   UV_VERSION: 0.9
-  PYTHON_VERSION: 3.12
+  # Matches pyproject's requires-python (>=3.13): the image ships the interpreter,
+  # so uv no longer downloads one in every job (saves ~10s per job).
+  PYTHON_VERSION: 3.13
   BASE_LAYER: bookworm-slim
   # GitLab CI creates a separate mountpoint for the build directory,
   # so we need to copy instead of using hard links.
   UV_LINK_MODE: copy
+  # Project-local so the `cache:` of .uv below can store it between jobs.
+  UV_CACHE_DIR: .uv-cache
+
+# Pipelines exist only for MR events, main pushes and release tags. A new commit
+# cancels the still-running `interruptible` jobs of the older pipeline, so a burst
+# of pushes bills one test run instead of one per push.
+workflow:
+  auto_cancel:
+    on_new_commit: interruptible
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+    - if: $CI_COMMIT_BRANCH == "main"
+    - if: $CI_COMMIT_TAG =~ /^v/
 
 stages:
   - test
@@ -17,16 +32,50 @@ stages:
   rules:
     - if: $CI_COMMIT_TAG =~ /^v\d+\.\d+\.\d+/
 
+# Skip the test jobs on pushes that touch nothing the tests read (docs, README,
+# CHANGELOG...): no minutes spent. release/ is linted and type-checked, hence listed.
+.on-code-change:
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+      changes: &code-paths
+        - src/**/*
+        - tests/**/*
+        - release/**/*
+        - pyproject.toml
+        - uv.lock
+        - justfile
+        - tox.ini
+        - .flake8
+        - .gitlab-ci.yml
+      when: always
+    - if: $CI_COMMIT_BRANCH == "main"
+      changes: *code-paths
+      when: always
+
+# The uv cache (wheels, hypothesis/pyright deps) is shared across jobs and
+# pipelines, keyed on uv.lock: saves the re-download of every dependency each run.
+# `uv cache prune --ci` drops what is cheap to rebuild so the cache stays small.
 .uv:
   image: ghcr.io/astral-sh/uv:$UV_VERSION-python$PYTHON_VERSION-$BASE_LAYER
+  cache:
+    key:
+      files:
+        - uv.lock
+    paths:
+      - .uv-cache
+  after_script:
+    - uv cache prune --ci
 
 # The scripts are one-liner justfile recipe calls (`uv run just ...`, the just
 # binary comes from the dev deps) so CI runs exactly what `just check` runs
 # locally; only the report/artifact flags are CI extras, passed through the
 # recipes' *args.
 checks:
-  extends: .uv
+  extends:
+    - .uv
+    - .on-code-change
   stage: test
+  interruptible: true
   before_script:
     - |
       if echo "$CI_MERGE_REQUEST_TITLE" | grep -iq "^draft:\|^wip:"; then
@@ -61,11 +110,6 @@ checks:
         coverage_format: cobertura
         path: obj/cov.xml
       junit: obj/tests_report.xml
-  rules:
-    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
-      when: always
-    - if: $CI_COMMIT_BRANCH == "main"
-      when: always
 
 # Differential run: contracts are pure redundancy, so with them compiled out
 # (python -O) the suite must still pass on valid inputs. Contract-violation
@@ -74,18 +118,41 @@ checks:
 # The ignored warning is pytest noticing library asserts are off — which is
 # exactly what this job is about.
 checks-optimized:
-  extends: .uv
+  extends:
+    - .uv
+    - .on-code-change
   stage: test
+  interruptible: true
   script:
     - uv run just test-optimized --junitxml=obj/tests_report_optimized.xml
   artifacts:
     reports:
       junit: obj/tests_report_optimized.xml
+
+# Python 3.14: one extra job runs both version-sensitive gates
+# (coverage + the -O run) through tox; lint and types stay on 3.13 in `checks`.
+# UV_PYTHON makes the outer `uv run` use the image's interpreter instead of
+# downloading .python-version's 3.13. A draft MR tolerates failures here, like
+# the lax mode of `checks`.
+checks-py314:
+  extends: .uv
+  stage: test
+  interruptible: true
+  variables:
+    PYTHON_VERSION: "3.14"
+    UV_PYTHON: "3.14"
   rules:
-    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
-      when: always
-    - if: $CI_COMMIT_BRANCH == "main"
-      when: always
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event" && $CI_MERGE_REQUEST_TITLE =~ /^(draft|wip):/i
+      changes: *code-paths
+      allow_failure: true
+    - !reference [.on-code-change, rules]
+  script:
+    - uv run just tox -e py314
+  artifacts:
+    reports:
+      junit:
+        - obj/py314/tests_report.xml
+        - obj/py314/tests_report_optimized.xml
 
 # Validate the tag against pyproject + CHANGELOG, extract the release notes,
 # then build dists.

{contractme-2.3.0 → contractme-2.4.2}/CHANGELOG.md

@@ -7,6 +7,59 @@ section whose heading matches the tag via
 and GitLab release description — so every `## vX.Y.Z` heading must match its
 tag exactly.
 
+## v2.4.2
+
+* On Python 3.14, `@annotated` stacked over `@precondition` (or any contracted function
+  passed to `typing.get_type_hints`) works again: it raised
+  `NameError: name 'ClassVar' is not defined` at decoration since v2.4.0
+  ([#104](https://gitlab.com/leogermond/contractme/-/issues/104)).
+* The test suite runs on Python 3.13 and 3.14, locally (`just tox`) and in CI
+  ([9b69657](https://gitlab.com/leogermond/contractme/-/commit/9b69657)).
+* `just types` installs pyright with its bundled node, so a broken nodeenv no longer fails CI
+  ([51e80c6](https://gitlab.com/leogermond/contractme/-/commit/51e80c6)).
+
+## v2.4.1
+
+* A failed `Predicate` constraint is named by its source when it is a lambda
+  (`Predicate(lambda s: s.islower())`), by its qualified name otherwise, in `type_error`,
+  `@record` and the `@annotated` header, where it used to print `<function <lambda> at 0x…>`;
+  a lambda with default arguments, or whose source cannot be proven to match, falls back to
+  its qualified name ([#80](https://gitlab.com/leogermond/contractme/-/issues/80)).
+* A passing check and every `accepts`/`rejects` probe build no message, unions included:
+  the text is written only for the failure that gets reported
+  ([#80](https://gitlab.com/leogermond/contractme/-/issues/80)).
+* The `@annotated` header lists its constraints as `under constraints [...]`, where it used
+  to show a tuple ([#80](https://gitlab.com/leogermond/contractme/-/issues/80)).
+* v2.4.0 never reached PyPI (its CI build failed on the in-project uv cache): v2.4.1 ships
+  its changes too, see below ([5739ee2](https://gitlab.com/leogermond/contractme/-/commit/5739ee2)).
+
+## v2.4.0
+
+* A decorator built with `functools.wraps` around a contracted function keeps its own
+  body: it used to be silently skipped, the contracted function running in its place
+  ([#73](https://gitlab.com/leogermond/contractme/-/issues/73)).
+* `@annotated` type checks now run before the explicit `@precondition`/`@postcondition`,
+  whatever the decorator order, so a wrong type is reported as such instead of a more
+  distant contract failing, or a precondition crashing on the ill-typed argument, or a
+  postcondition crashing on the ill-typed result under `observe`/`warn`
+  ([#78](https://gitlab.com/leogermond/contractme/-/issues/78)).
+* A callable `message=` receives the parameters it declares itself (`result` and
+  `old` included), independently of the predicate; it used to raise `KeyError` in
+  place of the violation
+  ([#70](https://gitlab.com/leogermond/contractme/-/issues/70)).
+* A callable `message=` naming a parameter the function lacks is refused with a
+  `TypeError` when the contract is declared, instead of a `KeyError` at its first
+  failure ([#70](https://gitlab.com/leogermond/contractme/-/issues/70)).
+* A `functools.wraps` wrapper is told apart from the function it wraps by
+  `@no_contracts` and by the contract decorators: marking a wrapper of a contracted
+  function, or contracting a wrapper of a `@no_contracts` function, now works
+  ([#74](https://gitlab.com/leogermond/contractme/-/issues/74)).
+* A contracted function exposes `__name__`, `__qualname__` and `__doc__` to the type
+  checker, like a plain function: `step.__name__` passes pyright
+  ([#77](https://gitlab.com/leogermond/contractme/-/issues/77)).
+* CI spends fewer runner minutes (Python 3.13 image, uv cache, tests skipped on
+  doc-only pushes) ([5f70e0d](https://gitlab.com/leogermond/contractme/-/commit/5f70e0d)).
+
 ## v2.3.0
 
 * Contracts now work on `async def`. `@precondition`, `@postcondition` and

{contractme-2.3.0 → contractme-2.4.2}/CLAUDE.md

@@ -24,6 +24,10 @@ just test-optimized   # differential run: contracts compiled out via -O, valid-p
                       # behavior must be identical (mirrors the checks-optimized CI
                       # job). Contract-violation tests skip themselves via
                       # tests/conftest.py:contract_violation().
+just tox [args...]    # cov + test-optimized on Python 3.13 and 3.14 (tox.ini, tox-uv:
+                      # each env synced from uv.lock's dev group); mirrors the
+                      # checks-py314 CI job:
+                      #   just tox -e py314 -- -x
 just fmt              # format code (black)
 just lint             # black --check + flake8
 just types            # type checking (pinned pyright from the dev deps — matches CI)

contractme-2.3.0/README.md → contractme-2.4.2/PKG-INFO

@@ -1,3 +1,22 @@
+Metadata-Version: 2.5
+Name: contractme
+Version: 2.4.2
+Summary: Executable specifications for python. Keep control of the code AI writes for you.
+Project-URL: Repository, https://gitlab.com/leogermond/contractme
+Author-email: Leo Germond <leo.germond@gmail.com>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Requires-Python: >=3.13
+Requires-Dist: annotated-types>=0.7.0
+Requires-Dist: hypothesis>=6.131.9
+Provides-Extra: cron
+Requires-Dist: croniter>=2.0.0; extra == 'cron'
+Provides-Extra: iso
+Requires-Dist: pycountry>=23.12.11; extra == 'iso'
+Provides-Extra: yaml
+Requires-Dist: pyyaml>=6.0; extra == 'yaml'
+Description-Content-Type: text/markdown
+
 # ContractMe — executable specifications for Python
 
 ## Code is free. Bugs are not. Write the spec instead.
@@ -50,11 +69,12 @@ ready-made types](docs/types.md) (`Port`, `EmailStr`, `Positive`, …).
 
 ```python
 import math
-from contractme import precondition, postcondition
+from contractme import annotated, postcondition
+from contractme.types import NonNegativeFloat
 
-@precondition(lambda x: x >= 0)
+@annotated
 @postcondition(lambda x, result: math.isclose(result * result, x, abs_tol=1e-12))
-def square_root(x: float) -> float:
+def square_root(x: NonNegativeFloat) -> NonNegativeFloat:
     return x**0.5
 ```
 
@@ -65,13 +85,24 @@ it — this is the ground only contracts cover.
 Rules can even compare the state before and after the call (`old`):
 
 ```python
-@precondition(lambda l, n: n >= 0)
-@postcondition(lambda l, n: l[-1] == n)            # element appended
-@postcondition(lambda l, n, old: l[:-1] == old.l)  # nothing lost
-def append_count(l: list[int], n: int):
+from contractme import annotated, postcondition
+from contractme.types import NonNegativeInt
+
+@annotated
+@postcondition(lambda l, n: l[-1] == n)         # element appended
+@postcondition(lambda l, old: l[:-1] == old.l)  # nothing lost
+def append_count(l: list[NonNegativeInt], n: NonNegativeInt):
     l.append(n)
 ```
 
+Stack `@annotated` and the explicit rules in any order: the type checks run
+first — parameter types, in signature order, before the preconditions; the return
+type before the postconditions — so a violation names its most immediate cause.
+The types guard the relational rules of their side: when a parameter type fails,
+it is reported and the preconditions stay unevaluated; when the return type fails,
+it is reported and the postconditions stay unevaluated. Write the relational rules
+for well-typed values only.
+
 ## When the generated code is wrong, you hear about it
 
 Say your agent "implements" `square_root` as `return x / 2` — plausible at a
@@ -464,7 +495,9 @@ cost nothing where it matters.
 `just test`
 
 Dev commands are `just` recipes — bare `just` lists them; `just check` runs the
-full local gate (tests + coverage, the `-O` differential run, lint, types).
+full local gate (tests + coverage, the `-O` differential run, lint, types); `just tox`
+runs the version-sensitive gates (coverage, the `-O` run) on every supported Python
+(3.13, 3.14).
 
 # Deploy new version
 

contractme-2.3.0/PKG-INFO → contractme-2.4.2/README.md

@@ -1,22 +1,3 @@
-Metadata-Version: 2.4
-Name: contractme
-Version: 2.3.0
-Summary: Executable specifications for python. Keep control of the code AI writes for you.
-Project-URL: Repository, https://gitlab.com/leogermond/contractme
-Author-email: Leo Germond <leo.germond@gmail.com>
-License-Expression: Apache-2.0
-License-File: LICENSE
-Requires-Python: >=3.13
-Requires-Dist: annotated-types>=0.7.0
-Requires-Dist: hypothesis>=6.131.9
-Provides-Extra: cron
-Requires-Dist: croniter>=2.0.0; extra == 'cron'
-Provides-Extra: iso
-Requires-Dist: pycountry>=23.12.11; extra == 'iso'
-Provides-Extra: yaml
-Requires-Dist: pyyaml>=6.0; extra == 'yaml'
-Description-Content-Type: text/markdown
-
 # ContractMe — executable specifications for Python
 
 ## Code is free. Bugs are not. Write the spec instead.
@@ -69,11 +50,12 @@ ready-made types](docs/types.md) (`Port`, `EmailStr`, `Positive`, …).
 
 ```python
 import math
-from contractme import precondition, postcondition
+from contractme import annotated, postcondition
+from contractme.types import NonNegativeFloat
 
-@precondition(lambda x: x >= 0)
+@annotated
 @postcondition(lambda x, result: math.isclose(result * result, x, abs_tol=1e-12))
-def square_root(x: float) -> float:
+def square_root(x: NonNegativeFloat) -> NonNegativeFloat:
     return x**0.5
 ```
 
@@ -84,13 +66,24 @@ it — this is the ground only contracts cover.
 Rules can even compare the state before and after the call (`old`):
 
 ```python
-@precondition(lambda l, n: n >= 0)
-@postcondition(lambda l, n: l[-1] == n)            # element appended
-@postcondition(lambda l, n, old: l[:-1] == old.l)  # nothing lost
-def append_count(l: list[int], n: int):
+from contractme import annotated, postcondition
+from contractme.types import NonNegativeInt
+
+@annotated
+@postcondition(lambda l, n: l[-1] == n)         # element appended
+@postcondition(lambda l, old: l[:-1] == old.l)  # nothing lost
+def append_count(l: list[NonNegativeInt], n: NonNegativeInt):
     l.append(n)
 ```
 
+Stack `@annotated` and the explicit rules in any order: the type checks run
+first — parameter types, in signature order, before the preconditions; the return
+type before the postconditions — so a violation names its most immediate cause.
+The types guard the relational rules of their side: when a parameter type fails,
+it is reported and the preconditions stay unevaluated; when the return type fails,
+it is reported and the postconditions stay unevaluated. Write the relational rules
+for well-typed values only.
+
 ## When the generated code is wrong, you hear about it
 
 Say your agent "implements" `square_root` as `return x / 2` — plausible at a
@@ -483,7 +476,9 @@ cost nothing where it matters.
 `just test`
 
 Dev commands are `just` recipes — bare `just` lists them; `just check` runs the
-full local gate (tests + coverage, the `-O` differential run, lint, types).
+full local gate (tests + coverage, the `-O` differential run, lint, types); `just tox`
+runs the version-sensitive gates (coverage, the `-O` run) on every supported Python
+(3.13, 3.14).
 
 # Deploy new version
 

{contractme-2.3.0 → contractme-2.4.2}/justfile

@@ -24,6 +24,11 @@ cov *args:
 test-optimized *args:
     uv run python -O -m pytest -W ignore::pytest.PytestConfigWarning "$@"
 
+# Envs and args pass through to tox (e.g. `just tox -e py314 -- -x`); see tox.ini.
+[doc('Coverage gate + -O differential run on every supported Python (3.13, 3.14)')]
+tox *args:
+    uv run tox "$@"
+
 # Format the code (black, line length 100)
 fmt:
     uv run black .

{contractme-2.3.0 → contractme-2.4.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "contractme"
-version = "2.3.0"
+version = "2.4.2"
 description = "Executable specifications for python. Keep control of the code AI writes for you."
 readme = "README.md"
 license = "Apache-2.0"
@@ -30,7 +30,9 @@ build-backend = "hatchling.build"
 [dependency-groups]
 dev = [
     "epycs>=1.4.0",
-    "pyright==1.1.407",
+    # [nodejs] ships node as a wheel: pyright's nodeenv fallback crashes on
+    # some node release listings (CI image has no node of its own)
+    "pyright[nodejs]==1.1.407",
     "pytest>=8.3.5",
     "pytest-cov>=6.0.0",
     "black>=25.9.0",
@@ -42,6 +44,8 @@ dev = [
     "croniter>=2.0.0",
     "pycountry>=23.12.11",
     "pyyaml>=6.0",
+    "tox>=4.67.12",
+    "tox-uv>=1.37.5",
 ]
 
 [tool.pytest.ini_options]

contractme-2.4.2/release_notes.md

@@ -0,0 +1,8 @@
+* On Python 3.14, `@annotated` stacked over `@precondition` (or any contracted function
+  passed to `typing.get_type_hints`) works again: it raised
+  `NameError: name 'ClassVar' is not defined` at decoration since v2.4.0
+  ([#104](https://gitlab.com/leogermond/contractme/-/issues/104)).
+* The test suite runs on Python 3.13 and 3.14, locally (`just tox`) and in CI
+  ([9b69657](https://gitlab.com/leogermond/contractme/-/commit/9b69657)).
+* `just types` installs pyright with its bundled node, so a broken nodeenv no longer fails CI
+  ([51e80c6](https://gitlab.com/leogermond/contractme/-/commit/51e80c6)).

{contractme-2.3.0 → contractme-2.4.2}/src/contractme/annotations.py

@@ -1,6 +1,6 @@
 from typing import Callable, cast, get_type_hints
-from contractme.contracting import ContractedFunction, precondition, postcondition
-from contractme.typecheck import type_error
+from contractme.contracting import PRE, POST, ContractedFunction, condition_decorator
+from contractme.typecheck import conforms, constraint_text, type_error
 from contractme.typeshape import (
     CompositeTypeInfo,
     resolve_type,
@@ -16,9 +16,11 @@ def annotated[**F_Params, F_Ret](
     For each parameter and the return value, ``@annotated`` auto-generates a
     ``@precondition`` (parameters) or ``@postcondition`` (return) that validates
     both the type structure and any ``annotated-types`` constraints (``Ge``,
-    ``Lt``, ``MinLen``, ``Predicate``, ...). Every type shape :mod:`typeshape`
-    models is supported — scalars, containers, unions, tuples, dataclasses
-    (field-by-field), enums, ``Literal`` alternatives, ``Protocol`` duck typing,
+    ``Lt``, ``MinLen``, ``Predicate``, ...). These type checks run before the
+    explicit ``@precondition``/``@postcondition`` of the same function, whatever
+    the decorator order: a violation names its most immediate cause. Every type
+    shape :mod:`typeshape` models is supported — scalars, containers, unions,
+    tuples, dataclasses (field-by-field), enums, ``Literal`` alternatives, ``Protocol`` duck typing,
     and recursive types.
 
     Validation is two-phase: structure first ("is this a list?"), then
@@ -40,28 +42,35 @@ def annotated[**F_Params, F_Ret](
 
     def check_annotated_arg(arg_name, arg_an: AnnotationForm):
         info = CompositeTypeInfo(resolve_type(arg_an))
-        msg = f"{arg_name} should be instance of {info.base}"
-        if info.constraints:
-            msg += f" under constraints {tuple(info.constraints)}"
+
+        def header() -> str:
+            # built on failure only: naming a lambda by its source reads and
+            # compiles its module, a cost decoration (an import) never pays
+            msg = f"{arg_name} should be instance of {info.base}"
+            if info.constraints:
+                msg += f" under constraints [{', '.join(map(constraint_text, info.constraints))}]"
+            return msg
 
         if arg_name == "return":
             cond_arg_name = "result"
-            cond_f = postcondition
+            kind = POST
         else:
             cond_arg_name = arg_name
-            cond_f = precondition
+            kind = PRE
 
         def chk(**kw):
-            return type_error(kw[cond_arg_name], arg_an) is None
+            return conforms(kw[cond_arg_name], arg_an)
 
         def describe_failure(**kw):
             # only evaluated at failure time (by the raising path, never by the
             # accepts/rejects probes), so re-running the check is affordable and
             # the error is known to exist
             err = type_error(kw[cond_arg_name], arg_an)
-            return f"{msg}: {err}"
+            return f"{header()}: {err}"
 
-        return cond_f(chk, describe_failure)
+        # a type check: it runs before the explicit pre/postconditions,
+        # whatever the decorator order (issue #78)
+        return condition_decorator(kind, chk, describe_failure, type_check=True)
 
     # `include_extras=True` keeps the `Annotated[...]` metadata (plain
     # `get_type_hints` strips it), and, crucially, `get_type_hints` *resolves*
@@ -70,7 +79,9 @@ def annotated[**F_Params, F_Ret](
     # `f.__annotations__` would be strings and silently disable every check.
     ans = get_type_hints(f, include_extras=True)
 
-    for n, an in ans.items():
+    # each check prepends to the type checks: apply them last hint first, so the
+    # parameter types run in signature order
+    for n, an in reversed(ans.items()):
         f = check_annotated_arg(n, an)(f)
 
     # the loop is invisible statically: with any hint at all, `f` is now the

{contractme-2.3.0 → contractme-2.4.2}/src/contractme/config.py

@@ -27,6 +27,7 @@ from __future__ import annotations
 
 import os
 from contextlib import contextmanager
+from types import MethodType
 from typing import Any, Callable
 
 from contractme.policy import (
@@ -50,10 +51,22 @@ def no_contracts(f: Callable) -> Callable:
     """Mark ``f`` as never contractable: applying a contract to it raises at
     decoration time. The engine's check-path helpers rely on it; also usable on
     any function that must stay contract-free (hot paths, engine extensions).
+
+    Both ways are decided by *identity* (issue #74, as #73 for ``get_wrapped``):
+    ``functools.wraps`` copies ``__dict__``, so a wrapper carries the wrapped
+    function's ``contractme_*`` attributes. "Already contracted" is the engine's
+    wrapper — its *class* carries ``contractme_engine_wrapper``, which ``wraps``
+    never copies — or, under ``optimized``, a function whose
+    ``contractme_wrapped`` is itself. The mark stores the marked function, so it
+    designates that function alone. A bound method designates its function
+    (``__func__``, the very object, so identity still holds).
     """
-    if hasattr(f, "contractme_wrapped"):
+    target = f.__func__ if isinstance(f, MethodType) else f
+    if getattr(type(target), "contractme_engine_wrapper", False) or (
+        getattr(target, "contractme_wrapped", None) is target
+    ):
         raise RuntimeError(f"{f.__name__}() is already contracted")
-    setattr(f, "contractme_no_contracts", True)
+    setattr(f, "contractme_no_contracts", f)
     return f