contractme 2.2.0__tar.gz → 2.3.0__tar.gz

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

@@ -7,6 +7,49 @@ section whose heading matches the tag via
 and GitLab release description — so every `## vX.Y.Z` heading must match its
 tag exactly.
 
+## v2.3.0
+
+* Contracts now work on `async def`. `@precondition`, `@postcondition` and
+  `@annotated` check across the await: postconditions and the return type check
+  see the **awaited value**, never the coroutine, and `old` captures before the
+  await. `inspect.iscoroutinefunction()` holds on the decorated form, so
+  pytest-asyncio, anyio and FastAPI route it correctly. This was silently
+  broken, not merely missing: `@annotated` used to raise on every *valid* call
+  while never awaiting the coroutine — so the body never ran — and the same
+  code worked under `CONTRACTME_OPTIMIZED`. Predicates must stay synchronous;
+  an `async def` predicate is refused at decoration time.
+* `autotest` / `property_test` drive an async target: each drawn example runs
+  under `asyncio.run`, no new dependency. What is out of reach now refuses
+  loudly instead of passing empty — an already-running event loop is rejected
+  before any coroutine exists, and an async generator raises. `accepts` /
+  `rejects` stay synchronous and argument-only on async targets: they answer
+  "is this call legal?", which never requires running a body or an event loop.
+* `typing.Literal` is now checked, as a sum of singletons: `Literal[1]` rejects
+  `True` and `Literal[True]` rejects `1`, since membership tests the type
+  before the value. It used to raise `NotImplementedError` *even for a valid
+  member*, so the annotation was unusable rather than merely unchecked;
+  `autotest` covers it for free, Hypothesis already samples `Literal`.
+  `dataclasses.Field[T]` is checked as an `isinstance` leaf (`T` is
+  static-only and is not claimed to be verified), which unblocks a `Protocol`
+  declaring `__dataclass_fields__`.
+* `int` is accepted where `float` is declared, and `int`/`float` where
+  `complex` is (PEP 484 numeric tower, matching pyright). An alias such as
+  `Seconds = Annotated[float, Gt(0)]` used to reject `60`, making duration
+  annotations unusable — a function could be refused by its own integer
+  default. The reverse stays an error, constraints still apply to the promoted
+  value, and no value is ever converted.
+* `is_signal_number` no longer raises `TypeError` on an unhashable value: it
+  answers `False`, as every predicate in the module promises to.
+* Tighter string predicates: `is_semver`, `is_e164`, `is_byte_size` and
+  `is_duration` matched Unicode digits and case-folded outside ASCII, accepting
+  `"+١٢٣٤٥٦٧٨"` as a phone number and `"10KB"` (KELVIN SIGN) as a byte size.
+* `is_iana_timezone` caches the tzdata scan instead of redoing it (~9 ms) on
+  every check; `property_test` builds its Hypothesis strategies once at
+  construction rather than inside the draw path.
+* Internal: violation construction deduplicated, a stale `sys.version_info`
+  assert dropped, value-walker signatures annotated, constraint tests
+  parametrized.
+
 ## v2.2.0
 
 * `ClassVar[T]` and `Final[T]` now check everywhere a type does: the marker is

{contractme-2.2.0 → contractme-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: contractme
-Version: 2.2.0
+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>

contractme-2.3.0/docs/comparison-facts.yaml

@@ -0,0 +1,73 @@
+# Cached upstream facts for docs/comparison.md.
+#
+# Verifying competitors is the expensive half of a comparison pass, and it is
+# also the half that barely moves between passes. So it is cached here instead
+# of being re-derived every time: each entry carries its source and the date it
+# was last checked. Refresh an entry when it ages out or when upstream ships a
+# release — never re-verify the whole file by reflex.
+#
+# Facts about ContractMe itself are NOT cached: they are cheap to check by
+# running them, and they must be re-checked every pass.
+#
+# Rule: nothing enters docs/comparison.md that is not backed by an entry here
+# or by an execution done during that pass. "Not verified" is a publishable
+# state; an unsourced claim is not.
+
+beartype:
+  version: "0.22.9"
+  version_published: 2025-12-13
+  requires_python: ">=3.10"
+  checked: 2026-07-28
+  source: https://pypi.org/pypi/beartype/json
+  maintenance: |
+    Daily commits (latest 2026-07-27) but no PyPI release in over 7 months.
+    Development is active, the release cadence is not. Its readthedocs "latest"
+    documents a 0.23.0 that cannot be installed — the published docs run ahead
+    of the published package.
+  claims:
+    - claim: "beartype.claw installs an import hook that instruments a whole package or all dependencies"
+      verdict: confirmed
+      source: doc/src/api_claw.rst in the 0.22.9 sdist
+    - claim: "is_bearable(value, hint) is a boolean probe that never raises"
+      verdict: confirmed
+      note: |
+        Covers any PEP-compliant hint (generics, unions, Annotated), not just
+        bare classes — but it answers "does this match a type hint?", never an
+        arbitrary predicate.
+      source: README and doc/src/api_door.rst in the 0.22.9 sdist
+    - claim: "can warn instead of raise"
+      verdict: confirmed
+      detail: BeartypeConf(violation_type=UserWarning)
+      source: README in the 0.22.9 sdist
+    - claim: "claims O(1) checking by random sampling"
+      verdict: confirmed
+      note: This is beartype's own claim about itself, quoted as such.
+      source: doc/src/faq.rst in the 0.22.9 sdist
+    - claim: "silently ignores non-beartype Annotated metadata such as annotated-types Ge/Le"
+      verdict: confirmed_by_execution_only
+      note: |
+        True, but NOT documented by beartype. A grep for annotated_types across
+        the whole 0.22.9 sdist — code, tests and docs — returns nothing, and the
+        documented validators are only beartype.vale.Is/IsAttr/IsEqual. The
+        behaviour follows from PEP 593 (unrecognised metadata is ignored).
+        The comparison must therefore say "verified by running it", never
+        "documented by beartype".
+      source: exhaustive grep of the 0.22.9 sdist (the finding is an absence)
+
+typeguard:
+  version: "4.6.0"
+  version_published: 2026-07-26
+  requires_python: ">=3.10"
+  checked: 2026-07-28
+  source: https://pypi.org/pypi/typeguard/json
+  maintenance: |
+    Actively maintained; commits on the day of the release. Note that 4.5.2,
+    which docs/comparison.md still cites, went stale two days before this check
+    — a version number in a comparison ages faster than anything else in it.
+  claims:
+    - claim: "runtime checking via decorator, import hook, or pytest plugin"
+      verdict: confirmed
+      detail: |
+        _decorators.py (@typechecked), _importhook.py (install_import_hook),
+        and _pytest_plugin.py, registered under the pytest11 entry point.
+      source: pyproject.toml and src/typeguard/ in the 4.6.0 sdist

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

@@ -1,6 +1,6 @@
 [project]
 name = "contractme"
-version = "2.2.0"
+version = "2.3.0"
 description = "Executable specifications for python. Keep control of the code AI writes for you."
 readme = "README.md"
 license = "Apache-2.0"

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

@@ -18,7 +18,8 @@ def annotated[**F_Params, F_Ret](
     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, ``Protocol`` duck typing, and recursive types.
+    (field-by-field), enums, ``Literal`` alternatives, ``Protocol`` duck typing,
+    and recursive types.
 
     Validation is two-phase: structure first ("is this a list?"), then
     constraints ("are all elements ≥ 0?"). On violation the raised

{contractme-2.2.0 → contractme-2.3.0}/src/contractme/contracting.py

@@ -6,6 +6,13 @@ freely call contracted functions — even self-referentially — without recursi
 or double-checking cost. Calls made by the wrapped function body are checked
 as usual.
 
+An ``async def`` gets the same treatment through a second, mirrored path (issue
+#58): the checks run *inside* the coroutine, around ``await``\\ ing the body, so
+a postcondition sees the awaited value and never the coroutine object. Only
+creating the coroutine stays eager, exactly as for an undecorated ``async def``.
+Predicates themselves are always synchronous — an ``async def`` predicate is
+refused at decoration time.
+
 The engine cannot verify itself: helpers that run while checking is *not*
 suspended are marked ``@no_contracts`` and carry plain asserts, backed by the
 canaries in tests/test_canaries.py.
@@ -340,6 +347,13 @@ def condition_decorator[**F_Params, F_Ret](
     message: FailureMessage | None = None,
     policy: PolicyLike | None = None,
 ) -> Callable[[Callable[F_Params, F_Ret]], ContractedFunction[F_Params, F_Ret]]:
+    if inspect.iscoroutinefunction(conditional):
+        raise RuntimeError(
+            f"{getattr(conditional, '__name__', conditional)!r} is an async predicate: "
+            "contract predicates must be synchronous. A probe (accepts/rejects) has to "
+            "stay total, cheap and loop-free — it answers without an event loop — and a "
+            "predicate awaiting external state is TOCTOU by construction (issue #57)"
+        )
     handler = resolve_handler(policy)
 
     def deco(f: Callable[F_Params, F_Ret]) -> ContractedFunction[F_Params, F_Ret]:
@@ -348,6 +362,9 @@ def condition_decorator[**F_Params, F_Ret](
         if kind is PRE and f.__name__ == "__init__":
             raise RuntimeError("__init__ cannot have precondition")
         original_call, preconditions, postconditions = get_wrapped(f)
+        # detection is on the *unwrapped* callable, so stacked decorators
+        # re-detect correctly at every level
+        is_coroutine = inspect.iscoroutinefunction(original_call)
 
         # decorators apply bottom-up: prepend, so conditions run in source order
         conditions = preconditions if kind is PRE else postconditions
@@ -389,23 +406,27 @@ def condition_decorator[**F_Params, F_Ret](
         def accepts(*a, **kw) -> bool:
             return not rejects(*a, **kw)
 
+        def report_failed(kind: ConditionKind, cond: Condition, cond_kw: dict) -> None:
+            """Build the ``ContractViolation`` for a failed condition and dispatch
+            it. An enforcing handler raises here, halting; advisory ones
+            (warn/observe) report and let execution proceed."""
+            blame = "**caller** of " if kind is PRE else ""
+            violation = ContractViolation(
+                f"{blame}{original_call.__name__}() bug: "
+                + format_failed_condition(kind, cond.predicate, cond.message, cond_kw),
+                kind=kind,
+                function=original_call.__qualname__,
+                condition_source=show_source(cond.predicate),
+                captured_values=cond_kw,
+                call_site=_definition_site(original_call),
+            )
+            report_violation(violation, cond.handler)
+
         def precondition_check(call_kw: dict) -> None:
             failures = failing_preconditions(call_kw, stop_at_first=False)
             with evaluating_contracts():
                 for cond, cond_kw in failures:
-                    violation = ContractViolation(
-                        f"**caller** of {original_call.__name__}() bug: "
-                        + format_failed_condition(PRE, cond.predicate, cond.message, cond_kw),
-                        kind=PRE,
-                        function=original_call.__qualname__,
-                        condition_source=show_source(cond.predicate),
-                        captured_values=cond_kw,
-                        call_site=_definition_site(original_call),
-                    )
-                    # an enforcing handler raises here, halting; advisory ones
-                    # (warn/observe) report and let the next failure — and the
-                    # body — proceed.
-                    report_violation(violation, cond.handler)
+                    report_failed(PRE, cond, cond_kw)
 
         def postcondition_prepare(call_kw: dict) -> list[dict]:
             # `old` capture deep-copies the arguments, which may run user code
@@ -421,16 +442,7 @@ def condition_decorator[**F_Params, F_Ret](
                 for cond, cond_kw in zip(postconditions, post_kw):
                     cond_kw.update(get_kw_for_postcondition_after(result, cond.predicate))
                     if not call_conditional(cond.predicate, cond_kw):
-                        violation = ContractViolation(
-                            f"{original_call.__name__}() bug: "
-                            + format_failed_condition(POST, cond.predicate, cond.message, cond_kw),
-                            kind=POST,
-                            function=original_call.__qualname__,
-                            condition_source=show_source(cond.predicate),
-                            captured_values=cond_kw,
-                            call_site=_definition_site(original_call),
-                        )
-                        report_violation(violation, cond.handler)
+                        report_failed(POST, cond, cond_kw)
 
         def call_and_run_contracts(wrapper: _ContractWrapper[F_Params, F_Ret], *a, **kw) -> F_Ret:
             if _evaluating_contracts.get():
@@ -456,6 +468,49 @@ def condition_decorator[**F_Params, F_Ret](
                     # Python's canonical TypeError (see get_kw_from_call)
                     return original_call(*a, **kw)
 
+        async def await_body_within_contracts(call_kw: dict, a: tuple, kw: dict):
+            """The awaited half of the async path: everything the sync
+            `call_and_run_contracts` does *around* the body, run inside the
+            coroutine. So the value postconditions judge is the awaited result,
+            never the coroutine object, `old` is captured at body entry (Eiffel),
+            and the ambient policy is the one live when the body actually runs."""
+            post_kw = None
+            if is_checked():
+                precondition_check(call_kw)
+                post_kw = postcondition_prepare(call_kw)
+
+            result = await original_call(*a, **kw)
+
+            if post_kw is not None:
+                postcondition_check(result, post_kw)
+
+            return result
+
+        def async_call_and_run_contracts(
+            wrapper: _ContractWrapper[F_Params, F_Ret], *a, **kw
+        ) -> F_Ret:
+            """Contract path of an `async def`, mirroring the sync one. It is a
+            *sync* entry returning the checking coroutine, so calling the
+            decorated function is exactly as eager as calling the bare one: a
+            malformed call raises Python's canonical `TypeError` right here, and
+            nothing else happens before the caller awaits."""
+            if _evaluating_contracts.get():
+                # assertion evaluation rule: a coroutine created while a
+                # predicate is being evaluated runs unchecked, like a sync call
+                return original_call(*a, **kw)
+
+            match get_kw_from_call(original_call, a, kw):
+                case Ok(call_kw):
+                    # this coroutine *is* the call's return value, but an
+                    # `async def` types as `Coroutine[...]` and the checker
+                    # cannot see that this is exactly the wrapped `F_Ret`
+                    return cast(F_Ret, await_body_within_contracts(call_kw, a, kw))
+                case _:
+                    # malformed call (`Err`): defer to the real function for
+                    # Python's canonical TypeError, raised *before* a coroutine
+                    # exists — so nothing is left un-awaited (see get_kw_from_call)
+                    return original_call(*a, **kw)
+
         if _OPTIMIZED:  # pragma: no cover
             # only reachable when CONTRACTME_OPTIMIZED is set at import — a
             # separate invocation, exercised by tests/test_optimized_policy.py
@@ -478,14 +533,21 @@ def condition_decorator[**F_Params, F_Ret](
             # the attach is invisible statically; the subprocess test asserts it
             return cast(ContractedFunction[F_Params, F_Ret], original_call)
 
-        return _ContractWrapper[F_Params, F_Ret](
-            call_and_run_contracts,
+        wrapper = _ContractWrapper[F_Params, F_Ret](
+            async_call_and_run_contracts if is_coroutine else call_and_run_contracts,
             original_call,
             preconditions,
             postconditions,
             accepts,
             rejects,
         )
+        if is_coroutine:
+            # the wrapper is a callable object, not an `async def`: without the
+            # mark, framework dispatch (pytest-asyncio, anyio, FastAPI) would
+            # misroute a contracted coroutine function as a sync one. Bound
+            # methods inherit the mark through `__func__`.
+            inspect.markcoroutinefunction(wrapper)
+        return wrapper
 
     return deco
 

{contractme-2.2.0 → contractme-2.3.0}/src/contractme/skills/contractme/SKILL.md

@@ -153,6 +153,36 @@ def square_root(x: float, y: str = "") -> float:
   diagnose the actual values.
 - `@annotated` and explicit contracts compose freely on the same function.
 
+## Async support
+
+`@precondition`, `@postcondition`, and `@annotated` all work on `async def`.
+Postconditions and return-type checks see the **awaited** value, never the coroutine
+object, and `old` deep-copies arguments before the coroutine body starts — same
+guarantee as a sync function, even if the mutation happens after an `await`:
+
+```python
+import asyncio
+
+@precondition(lambda x: x >= 0)
+@postcondition(lambda result, old: result == old.x * 2)
+async def double(x: int) -> int:
+    await asyncio.sleep(0)
+    return x * 2
+
+asyncio.run(double(-1))
+# ContractViolation: **caller** of double() bug: precondition 'x >= 0' failed: x = -1
+```
+
+The decorated function stays `inspect.iscoroutinefunction()`-true, so pytest-asyncio,
+anyio, and FastAPI route it correctly. Predicates themselves must stay synchronous: an
+`async def` predicate is refused at decoration time (`RuntimeError`) — a probe has to
+answer without an event loop, and an awaiting predicate is TOCTOU by construction.
+`autotest`/`property_test` drive an async target by running each Hypothesis-generated
+example under `asyncio.run` — no new dependency. `accepts()`/`rejects()` stay
+synchronous and argument-only even on an async target: they answer "is this call
+legal?" without ever running the body or requiring a loop. Async **generators** are out
+of scope — `property_test` raises `NotImplementedError` naming the target.
+
 ## Free property-based tests
 
 `autotest` builds a Hypothesis strategy from the type annotations, filters generated
@@ -268,8 +298,9 @@ Measured on a real placement search: ~5× end-to-end (46 s → 10 s).
 
 ## Ground rules
 
-- **Validate constructor inputs with `@annotated`, a `@record`, or a factory
-  function** — `@precondition` on `__init__` raises `RuntimeError` at decoration time.
+- **Validate constructor inputs with a `@record` or a factory function** —
+  `@precondition` *and* `@annotated` on `__init__` both raise
+  `RuntimeError('__init__ cannot have precondition')` at decoration time.
 - **Account for `old`'s deep copy** — it copies every argument before the call. On
   large arguments that cost is real; postconditions can be disabled in production
   (see below).
@@ -277,11 +308,8 @@ Measured on a real placement search: ~5× end-to-end (46 s → 10 s).
   guard) and are togglable at runtime: `set_policy("off")` globally, or
   `local_policy("off")` for a `with` block (see *Choosing what a violation
   does*). The `accepts()`/`rejects()` probes are the boundary tool that survives `-O`.
-- **Never call a contracted rule per-candidate in a search loop.** Wrap the loop in
-  `with local_policy("off")` and re-prove the output once with a postcondition on the
-  enclosing algorithm (pattern in *Choosing what a violation does*): the rule stays
-  the single source of truth for legality, at one check per result instead of one per
-  candidate.
+- **Never call a contracted rule per-candidate in a search loop** — see the
+  search-loop pattern in *Choosing what a violation does* above.
 - **Screen untrusted input with `f.accepts(...)`, `probes(T).accepts(value)` on the
   expected type, or parse it into a `@record` and
   check with `probes(Record).accepts(...)`.** The probes turn the rule into a question — a
@@ -298,8 +326,12 @@ Measured on a real placement search: ~5× end-to-end (46 s → 10 s).
   `@record` is `@dataclass_transform`, so pyright sees the real API. An ignore around
   contractme code signals a misuse (e.g. `Rec.accepts` instead of
   `probes(Rec).accepts`), not a framework gap.
-- **`isinstance` semantics**: `bool` passes an `int` check; exact-type matching is not
-  supported. Unknown annotations are ignored (open world), never a failure.
+- **Numeric tower**: `int` passes where `float` is declared (PEP 484 — `Annotated[float,
+  Gt(0)]` accepts `60`); the reverse never does — a `float` is always rejected where
+  `int` is declared. `bool` passes an `int` check via `isinstance`; beyond that,
+  exact-type matching is not supported. `typing.Literal` doesn't inherit this laxity —
+  membership checks type before value, so `Literal[1]` rejects `True` and `Literal[True]`
+  rejects `1`. Unknown annotations are ignored (open world), never a failure.
 - **`Protocol` parameters**: checked structurally by `@annotated` (duck typing, no
   `@runtime_checkable` needed), but `autotest` cannot generate values for them.
 

contractme-2.3.0/src/contractme/testing.py

@@ -0,0 +1,141 @@
+"""Hypothesis integration: property-based tests generated from the contracts.
+
+``property_test(f)`` builds the test — a ready-to-run callable whose Hypothesis
+strategy comes from ``f``'s type hints and which — when ``f`` is contracted —
+filters drawn inputs through its ``accepts`` probe, so only calls the
+preconditions allow are exercised. ``autotest(f)`` runs it.
+
+An ``async def`` target is driven with ``asyncio.run`` — a fresh event loop per
+drawn example, for isolation and deterministic shrinking, and no new dependency
+(issue #60). The dispatch reads ``inspect.iscoroutinefunction`` on the
+*decorated* form, dogfooding the mark the engine puts on its wrapper (#58).
+
+The one rule the async side answers to: **a test that runs nothing must not
+pass**. Merely *calling* a coroutine function builds a coroutine and runs no
+body, so a target this module cannot drive to completion is refused loudly, by
+name, at :func:`property_test` time — never turned into a green test that
+exercised nothing.
+"""
+
+import asyncio
+import inspect
+from typing import Callable, get_type_hints
+
+from hypothesis import assume, given, example, strategies as st
+
+from contractme.contracting import ContractedFunction, get_wrapped
+
+type TestableFunction = ContractedFunction | Callable
+type PropertyTest = Callable
+# how one drawn example is executed: ``(target, drawn arguments) -> anything``
+type ExampleRunner = Callable[[Callable, tuple | dict], object]
+
+
+def name_of(f: Callable) -> str:
+    """How a target is called out in a refusal message."""
+    return getattr(f, "__name__", repr(f))
+
+
+def call_with_composite(f: Callable, composite: tuple | dict):
+    if isinstance(composite, dict):
+        return f(**composite)
+    return f(*composite)
+
+
+def running_loop() -> asyncio.AbstractEventLoop | None:
+    """The event loop running in this thread, or ``None`` — the question
+    ``asyncio`` only answers by raising."""
+    try:
+        return asyncio.get_running_loop()
+    except RuntimeError:
+        return None
+
+
+def refuse_running_loop(f: Callable) -> None:
+    """Refuse to drive ``f`` from inside a running event loop.
+
+    ``asyncio.run`` cannot nest, so there is no test to build here — and the
+    check has to happen *before* the coroutine is created, or the refusal would
+    leave one un-awaited behind it."""
+    if running_loop() is not None:
+        raise RuntimeError(
+            f"cannot drive the coroutine function {name_of(f)}() while an event loop is "
+            "already running in this thread: each drawn example is run with asyncio.run(), "
+            "which refuses to nest. Call property_test/autotest/test_with_examples from "
+            "synchronous code — they need no async test runner of their own."
+        )
+
+
+def await_with_composite(f: Callable, composite: tuple | dict):
+    """Run one drawn example of a coroutine function to completion, on its own
+    event loop — so the body actually executes and the contracts see the awaited
+    value rather than a coroutine object."""
+    refuse_running_loop(f)
+    return asyncio.run(call_with_composite(f, composite))
+
+
+def example_runner(f: TestableFunction) -> ExampleRunner:
+    """How one drawn example of ``f`` gets executed — or a loud refusal.
+
+    The engine's wrapper is a callable *object*, which hides the code flags
+    ``inspect`` reads: shape questions go to the unwrapped body, except
+    ``iscoroutinefunction``, which the engine marks on the wrapper precisely so
+    that dispatch like this one works on the decorated form (#58)."""
+    body, _preconditions, _postconditions = get_wrapped(f)
+    if inspect.isasyncgenfunction(body):
+        raise NotImplementedError(
+            f"{name_of(f)}() is an async generator function, which property_test cannot "
+            "drive: calling it only builds an async generator, so the test would pass "
+            "without ever running the body. Async generators are out of scope (issue "
+            "#57) — property-test the coroutine that consumes one instead."
+        )
+    if inspect.iscoroutinefunction(f):
+        # fail at build time for the common case, where the test is built and
+        # run in the same breath; `await_with_composite` re-checks per example,
+        # for a test built outside a loop and later run inside one
+        refuse_running_loop(f)
+        return await_with_composite
+    return call_with_composite
+
+
+def property_test(f: TestableFunction) -> PropertyTest:
+    # `ContractedFunction` is a runtime-checkable Protocol, so this holds for both
+    # the wrapped and the `optimized` (bare function + attached probes) forms.
+    # Resolve the `accepts` probe and build the strategies once (not per drawn
+    # example — `get_type_hints` is costly); `accepts` is `None` for a plain
+    # callable, which then draws unfiltered.
+    accepts = f.accepts if isinstance(f, ContractedFunction) else None
+    hints = get_type_hints(f, include_extras=True)
+    strategies = [st.from_type(t) for name, t in hints.items() if name != "return"]
+    # sync targets keep the exact former path: `run_example` is `call_with_composite`
+    run_example = example_runner(f)
+
+    @st.composite
+    def correct_input(draw: Callable) -> tuple:
+        v = tuple(draw(s) for s in strategies)
+        if accepts is not None:
+            assume(accepts(*v))
+        return v
+
+    @given(correct_input())
+    def search(value):
+        run_example(f, value)
+
+    return search
+
+
+def autotest(f: TestableFunction):
+    property_test(f)()
+
+
+def test_with_examples(f: TestableFunction, *exs) -> PropertyTest:
+    gen = property_test(f)
+    for e in exs:
+        if isinstance(f, ContractedFunction):
+            # screening stays synchronous whatever the target: probes are
+            # precondition-only and argument-only, they never touch a loop
+            accepted = call_with_composite(f.accepts, e)
+            if not accepted:
+                raise RuntimeError(f"contracts rejected example {e}")
+        gen = example(e)(gen)
+    return gen

{contractme-2.2.0 → contractme-2.3.0}/src/contractme/typecheck.py

@@ -11,7 +11,7 @@ the engine into anything else (a CLI, a deserializer, another framework).
 import datetime
 import zoneinfo
 from enum import Enum
-from typing import cast
+from typing import Any, cast
 
 import annotated_types
 
@@ -24,6 +24,7 @@ from contractme.typeshape import (
     CompositeTypeInfo,
     Constraint,
     NormalizedConstraint,
+    accepted_classes,
     normalize_constraint,
     resolve_type,
 )
@@ -37,7 +38,9 @@ __all__ = [
 ]
 
 
-def get_all_constraint_errors(val, constraints: list[Constraint]) -> list[NormalizedConstraint]:
+def get_all_constraint_errors(
+    val: Any, constraints: list[Constraint]
+) -> list[NormalizedConstraint]:
     failing = []
     for constraint_denorm in constraints:
         constraint = normalize_constraint(constraint_denorm)
@@ -84,11 +87,11 @@ def get_all_constraint_errors(val, constraints: list[Constraint]) -> list[Normal
     return failing
 
 
-def _type_name(t) -> str:
+def _type_name(t: AnnotationForm) -> str:
     return getattr(t, "__name__", str(t))
 
 
-def get_first_structure_error(value, an) -> str | None:
+def get_first_structure_error(value: Any, an: AnnotationForm) -> str | None:
     """First structural mismatch between ``value`` and annotation ``an``, or
     ``None`` when the structure is sound.
 
@@ -110,6 +113,16 @@ def get_first_structure_error(value, an) -> str | None:
             return f"expect one of {list(cast(type[Enum], type_info.origin))} got {value!r}"
         return None
 
+    if type_info.child_mod == ChildMod.LITERAL:
+        # PEP 586: the value must *be* one of the spelled-out alternatives, which
+        # are the children here. Equality alone would not do it: `True == 1` and
+        # `False == 0` in Python, so `Literal[1]` would admit `True` (and
+        # `Literal[True]` a plain `1`). The exact type discriminates them — a
+        # literal denotes one value *of one type*, not an equivalence class.
+        if not any(type(value) is type(lit) and value == lit for lit in children):
+            return f"expect one of {list(children)!r} got {value!r}"
+        return None
+
     if type_info.child_mod == ChildMod.STRUCTURAL:
         # duck typing: every declared member must be present (hasattr), and a
         # member carrying a type (anything but `Any`) is checked against it
@@ -125,7 +138,11 @@ def get_first_structure_error(value, an) -> str | None:
         # `Any`, or a form isinstance cannot judge: open world
         return None
 
-    if not isinstance(value, type_info.origin):
+    # `accepted_classes` widens `float`/`complex` per PEP 484's numeric tower, so
+    # what pyright accepts statically the runtime accepts too. The promotion is
+    # acceptance only: the value is handed on untouched, never coerced. The
+    # message still names the *declared* type ("expect float got str").
+    if not isinstance(value, accepted_classes(type_info.origin)):
         return f"expect {_type_name(type_info.origin)} got {value.__class__.__name__}"
 
     match type_info.child_mod:
@@ -163,7 +180,7 @@ def get_first_structure_error(value, an) -> str | None:
     return None
 
 
-def get_constraints_errors(value, an) -> list[str]:
+def get_constraints_errors(value: Any, an: AnnotationForm) -> list[str]:
     """Every constraint violation between ``value`` and annotation ``an``
     (empty list = all constraints hold).
 
@@ -219,7 +236,7 @@ def get_constraints_errors(value, an) -> list[str]:
     return errors
 
 
-def type_error(value, an) -> str | None:
+def type_error(value: Any, an: AnnotationForm) -> str | None:
     """The full check of ``value`` against annotation ``an``: the error message,
     or ``None`` when the value parses.