crosshair-tool 0.0.99__cp312-cp312-macosx_10_13_x86_64.whl

crosshair/enforce.py

@@ -0,0 +1,282 @@
+import contextlib
+import copy
+import functools
+import os
+from types import FrameType
+from typing import Callable, Dict, Mapping, Optional, Set, Tuple
+
+from crosshair.condition_parser import (
+    ConditionParser,
+    Conditions,
+    NoEnforce,
+    fn_globals,
+    get_current_parser,
+)
+from crosshair.fnutil import FunctionInfo
+from crosshair.statespace import prefer_true
+from crosshair.tracers import COMPOSITE_TRACER, NoTracing, ResumedTracing, TracingModule
+from crosshair.util import AttributeHolder
+
+# [Pre|Post]conditionFailed exceptions extend BaseException just to reduce the
+# possibility that end-user code accidentally handles them.
+
+
+class PreconditionFailed(BaseException):
+    pass
+
+
+class PostconditionFailed(BaseException):
+    pass
+
+
+def WithEnforcement(fn: Callable) -> Callable:
+    """
+    Ensure conditions are enforced on the given callable.
+
+    Enforcement is normally disabled when calling from some internal files, for
+    performance reasons. Use WithEnforcement to ensure it is enabled anywhere.
+    """
+
+    # This local function has a special name that we look for while tracing
+    # (see the wants_codeobj method below):
+    def _crosshair_with_enforcement(*a, **kw):
+        return fn(*a, **kw)
+
+    return _crosshair_with_enforcement
+
+
+def manual_constructor(typ: type):
+    def manually_construct(*a, **kw):
+        obj = WithEnforcement(typ.__new__)(typ, *a, **kw)  # object.__new__(typ)
+        with NoTracing():
+            # Python does not invoke __init__ if __new__ returns an object of another type
+            # https://docs.python.org/3/reference/datamodel.html#object.__new__
+            if isinstance(obj, typ):
+                with ResumedTracing():
+                    WithEnforcement(obj.__init__)(*a, **kw)  # type: ignore
+        return obj
+
+    return manually_construct
+
+
+_MISSING = object()
+
+
+def EnforcementWrapper(
+    fn: Callable,
+    conditions: Conditions,
+    enforced: "EnforcedConditions",
+    first_arg: object,
+) -> Callable:
+    signature = conditions.sig
+
+    def _crosshair_wrapper(*a, **kw):
+        with NoTracing():
+            fns_enforcing = enforced.fns_enforcing
+            if fns_enforcing is None or fn in fns_enforcing:
+                with ResumedTracing():
+                    return fn(*a, **kw)
+            with enforced.currently_enforcing(fn):
+                # debug("Calling enforcement wrapper ", fn.__name__, signature)
+                bound_args = signature.bind(*a, **kw)
+                bound_args.apply_defaults()
+                old = {}
+                mutable_args = conditions.mutable_args
+                mutable_args_remaining = (
+                    set(mutable_args) if mutable_args is not None else set()
+                )
+                for argname, argval in bound_args.arguments.items():
+                    try:
+                        # TODO: reduce the type realizations when argval is a SymbolicObject
+                        old[argname] = copy.copy(argval)
+                    except TypeError as exc:  # for uncopyables
+                        pass
+                    if argname in mutable_args_remaining:
+                        mutable_args_remaining.remove(argname)
+                if mutable_args_remaining:
+                    raise PostconditionFailed(
+                        'Unrecognized mutable argument(s) in postcondition: "{}"'.format(
+                            ",".join(mutable_args_remaining)
+                        )
+                    )
+                for precondition in conditions.pre:
+                    # debug(' precondition eval ', precondition.expr_source)
+                    # TODO: is fn_globals required here?
+                    with ResumedTracing():
+                        if not precondition.evaluate(bound_args.arguments):
+                            raise PreconditionFailed(
+                                f'Precondition "{precondition.expr_source}" was not satisfied '
+                                f'before calling "{fn.__name__}"'
+                            )
+            with ResumedTracing():
+                ret = fn(*a, **kw)
+            with enforced.currently_enforcing(fn):
+                if fn.__name__ in ("__init__", "__new__"):
+                    old["self"] = a[0]
+                lcls = {
+                    **bound_args.arguments,
+                    "__return__": ret,
+                    "_": ret,
+                    "__old__": AttributeHolder(old),
+                }
+                args = {**fn_globals(fn), **lcls}
+                for postcondition in conditions.post:
+                    # debug('Checking postcondition ', postcondition.expr_source, ' on ', fn)
+                    if not postcondition.evaluate:
+                        continue
+                    with ResumedTracing():
+                        postcondition_ok = postcondition.evaluate(args)
+                    if not prefer_true(postcondition_ok):
+                        raise PostconditionFailed(
+                            "Postcondition failed at {}:{}".format(
+                                postcondition.filename, postcondition.line
+                            )
+                        )
+            # debug("Completed enforcement wrapper ", fn)
+            return ret
+
+    functools.update_wrapper(_crosshair_wrapper, fn)
+    return _crosshair_wrapper
+
+
+_MISSING = object()
+
+
+_FILE_SUFFIXES_WITHOUT_ENFORCEMENT: Tuple[str, ...] = (
+    "/ast.py",
+    "/crosshair/libimpl/builtinslib.py",
+    "/crosshair/core.py",
+    "/crosshair/condition_parser.py",
+    "/crosshair/enforce.py",
+    "/crosshair/util.py",
+    "/crosshair/fnutil.py",
+    "/crosshair/statespace.py",
+    "/crosshair/tracers.py",
+    "/z3.py",
+    "/z3core.py",
+    "/z3printer.py",
+    "/z3types.py",
+    "/copy.py",
+    "/inspect.py",
+    "/re.py",
+    "/copyreg.py",
+    "/sre_parse.py",
+    "/sre_compile.py",
+    "/traceback.py",
+    "/contextlib.py",
+    "/linecache.py",
+    "/collections/__init__.py",
+    "/enum.py",
+    "/typing.py",
+)
+
+if os.name == "nt":
+    # Hacky platform-independence for performance reasons.
+    # (not sure whether there are landmines here?)
+    _FILE_SUFFIXES_WITHOUT_ENFORCEMENT = tuple(
+        p.replace("/", "\\") for p in _FILE_SUFFIXES_WITHOUT_ENFORCEMENT
+    )
+
+
+class EnforcedConditions(TracingModule):
+    def __init__(
+        self,
+        condition_parser: Optional[ConditionParser] = None,
+        interceptor=lambda x: x,
+    ):
+        super().__init__()
+        self.condition_parser = (
+            get_current_parser() if condition_parser is None else condition_parser
+        )
+        self.interceptor = interceptor
+        self.fns_enforcing: Optional[Set[Callable]] = None
+        self.codeobj_cache: Dict[object, bool] = {}
+
+    @contextlib.contextmanager
+    def currently_enforcing(self, fn: Callable):
+        if self.fns_enforcing is None:
+            yield None
+        else:
+            self.fns_enforcing.add(fn)
+            try:
+                yield None
+            finally:
+                self.fns_enforcing.remove(fn)
+
+    # TODO: replace this with PushedModule(EnforcedConditions)?
+    @contextlib.contextmanager
+    def enabled_enforcement(self):
+        prev = self.fns_enforcing
+        assert prev is None
+        self.fns_enforcing = set()
+        COMPOSITE_TRACER.push_module(self)
+
+        try:
+            yield None
+        finally:
+            self.fns_enforcing = prev
+            COMPOSITE_TRACER.pop_config(self)
+
+    def wants_codeobj(self, codeobj) -> bool:
+        name = codeobj.co_name
+        if name == "_crosshair_with_enforcement":
+            return True
+        fname = codeobj.co_filename
+        if fname.endswith(_FILE_SUFFIXES_WITHOUT_ENFORCEMENT):
+            return False
+        if name == "_crosshair_wrapper":
+            return False
+        return True
+
+    def cached_wants_codeobj(self, codeobj) -> bool:
+        cache = self.codeobj_cache
+        cachedval = cache.get(codeobj)
+        if cachedval is None:
+            cachedval = self.wants_codeobj(codeobj)
+            cache[codeobj] = cachedval
+        return cachedval
+
+    def trace_call(
+        self,
+        frame: FrameType,
+        fn: Callable,
+        binding_target: object,
+    ) -> Optional[Callable]:
+        caller_code = frame.f_code
+        if not self.cached_wants_codeobj(caller_code):
+            return None
+        try:
+            target_name = object.__getattribute__(fn, "__name__")
+        except AttributeError:
+            target_name = ""
+        if target_name.endswith((">", "_crosshair_wrapper")):
+            return None
+        if isinstance(fn, NoEnforce):
+            return fn.fn
+        if isinstance(fn, type) and fn not in (super, type):
+            return manual_constructor(fn)
+
+        parser = self.condition_parser
+        conditions = None
+        if binding_target is None:
+            conditions = parser.get_fn_conditions(FunctionInfo(None, "", fn))  # type: ignore
+        else:
+            # Method call.
+            # We normally expect to look up contracts on `type(binding_target)`, but
+            # if it's a `@classmethod`, we'll find it directly on `binding_target`.
+            # TODO: test contracts on metaclass methods
+            if isinstance(binding_target, type):
+                instance_methods = parser.get_class_conditions(binding_target).methods
+                conditions = instance_methods.get(target_name)
+            if conditions is None or not conditions.has_any():
+                type_methods = parser.get_class_conditions(type(binding_target)).methods
+                conditions = type_methods.get(target_name)
+
+        if conditions is not None and not conditions.has_any():
+            conditions = None
+        if conditions is None:
+            return None
+        # debug("Enforcing conditions on", fn, " type(binding)=", type(binding_target))
+        fn = self.interceptor(fn)  # conditions.fn)  # type: ignore
+        wrapper = EnforcementWrapper(fn, conditions, self, binding_target)  # type: ignore
+        return wrapper

crosshair/enforce_test.py

@@ -0,0 +1,182 @@
+import abc
+import sys
+from contextlib import ExitStack
+
+import pytest
+
+from crosshair.condition_parser import Pep316Parser
+from crosshair.enforce import (
+    EnforcedConditions,
+    PostconditionFailed,
+    PreconditionFailed,
+    manual_constructor,
+)
+from crosshair.tracers import COMPOSITE_TRACER
+from crosshair.util import set_debug
+
+
+def foo(x: int) -> int:
+    """
+    pre: 0 <= x <= 100
+    post: _ > x
+    """
+    return x * 2
+
+
+class Pokeable:
+    """
+    inv: self.x >= 0
+    """
+
+    x: int = 1
+
+    def poke(self) -> None:
+        self.x += 1
+
+    def pokeby(self, amount: int) -> None:
+        """
+        pre: amount >= 0
+        """
+        self.x += amount
+
+
+def same_thing(thing: object) -> object:
+    """post: __old__.thing == _"""
+    # If `thing` isn't copyable, it won't be available in `__old__`.
+    # In this case, enforcement will fail with an AttributeError.
+    return thing
+
+
+class Enforcement(ExitStack):
+    def __enter__(self):
+        super().__enter__()
+        enforced_conditions = EnforcedConditions(Pep316Parser())
+        self.enter_context(COMPOSITE_TRACER)
+        self.enter_context(enforced_conditions.enabled_enforcement())
+        COMPOSITE_TRACER.trace_caller()
+
+
+class TestCore:
+    def test_enforce_conditions(self) -> None:
+        assert foo(-1) == -2  # unchecked
+        with Enforcement():
+            assert foo(50) == 100
+            with pytest.raises(PreconditionFailed):
+                foo(-1)
+            with pytest.raises(PostconditionFailed):
+                foo(0)
+
+    def test_class_enforce(self) -> None:
+        Pokeable().pokeby(-1)  # no exception (yet!)
+        with Enforcement():
+            Pokeable().poke()
+            with pytest.raises(PreconditionFailed):
+                Pokeable().pokeby(-1)
+
+    def test_enforce_on_uncopyable_value(self) -> None:
+        class NotCopyable:
+            def __copy__(self):
+                raise TypeError("not copyable")
+
+        not_copyable = NotCopyable()
+        with Enforcement():
+            with pytest.raises(AttributeError):
+                same_thing(not_copyable)
+
+
+class BaseFooable:
+    def foo(self, x: int):
+        """pre: x > 100"""
+
+    def foo_only_in_super(self, x: int):
+        """pre: x > 100"""
+
+    @classmethod
+    def class_foo(cls, x: int):
+        """pre: x > 100"""
+
+    @staticmethod
+    def static_foo(x: int):
+        """pre: x > 100"""
+
+
+class DerivedFooable(BaseFooable):
+    def foo(self, x: int):
+        """pre: x > 0"""
+
+    @classmethod
+    def class_foo(cls, x: int):
+        """pre: x > 0"""
+
+    @staticmethod
+    def static_foo(x: int):
+        """pre: x > 0"""
+
+
+class TestTrickyCases:
+    def test_attrs_restored_properly(self) -> None:
+        orig_class_dict = DerivedFooable.__dict__.copy()
+        with Enforcement():
+            pass
+        for k, v in orig_class_dict.items():
+            assert (
+                DerivedFooable.__dict__[k] is v
+            ), f'member "{k}" changed afer encforcement'
+
+    def test_enforcement_of_class_methods(self) -> None:
+        with Enforcement():
+            with pytest.raises(PreconditionFailed):
+                BaseFooable.class_foo(50)
+        with Enforcement():
+            DerivedFooable.class_foo(50)
+
+    def test_enforcement_of_static_methods(self) -> None:
+        with Enforcement():
+            DerivedFooable.static_foo(50)
+            with pytest.raises(PreconditionFailed):
+                BaseFooable.static_foo(50)
+
+    def test_super_method_enforced(self) -> None:
+        with Enforcement():
+            with pytest.raises(PreconditionFailed):
+                DerivedFooable().foo_only_in_super(50)
+            with pytest.raises(PreconditionFailed):
+                DerivedFooable().foo(-1)
+            # Derived class has a weaker precondition, so this is OK:
+            DerivedFooable().foo(50)
+
+
+class WithMetaclass(metaclass=abc.ABCMeta):
+    """inv: x != 55"""
+
+    def __init__(self, x):
+        """pre: x != 22"""
+        self.x = x
+
+
+def test_skip_init_when_new_returns_different_type():
+    COUNTER = [0]
+
+    class ClassWithInit:
+        def __init__(self):
+            COUNTER[0] += 1
+
+    objwithinit = ClassWithInit()
+    assert COUNTER[0] == 1
+
+    class ClassWithNew:
+        def __new__(self):
+            return objwithinit
+
+    assert manual_constructor(ClassWithNew)() is objwithinit
+
+    assert COUNTER[0] == 1  # ensure we did not call __init__ again
+
+
+def test_enforcement_init_on_abcmeta() -> None:
+    with Enforcement():
+        with pytest.raises(PreconditionFailed):
+            WithMetaclass(22)
+        with pytest.raises(PostconditionFailed):
+            WithMetaclass(55)
+        WithMetaclass(99)

crosshair/examples/PEP316/__init__.py

@@ -0,0 +1 @@
+# crosshair: analysis_kind=PEP316

crosshair/examples/PEP316/bugs_detected/getattr_magic.py

@@ -0,0 +1,16 @@
+class Farm:
+    def visit_chickens(self) -> str:
+        return "cluck"
+
+    def visit_cows(self) -> str:
+        return "moo"
+
+
+def visit_animals(animal: str) -> str:
+    """
+    post: __return__ != "moo"
+    """
+    try:
+        return getattr(Farm(), "visit_" + animal)()
+    except BaseException:
+        return ""

crosshair/examples/PEP316/bugs_detected/hash_consistent_with_equals.py

@@ -0,0 +1,31 @@
+import dataclasses
+
+
+class HasConsistentHash:
+    """
+    A mixin to enforce that classes have hash methods that are consistent
+    with their equality checks.
+    """
+
+    def __eq__(self, other: object) -> bool:
+        """
+        post: implies(__return__, hash(self) == hash(other))
+        """
+        raise NotImplementedError
+
+
+@dataclasses.dataclass
+class Apples(HasConsistentHash):
+    """
+    Uses HasConsistentHash to discover that the __eq__ method is
+    missing a test for the `count` attribute.
+    """
+
+    count: int
+    kind: str
+
+    def __hash__(self):
+        return self.count + hash(self.kind)
+
+    def __eq__(self, other: object) -> bool:
+        return isinstance(other, Apples) and self.kind == other.kind

crosshair/examples/PEP316/bugs_detected/shopping_cart.py

@@ -0,0 +1,24 @@
+from typing import Dict, List, Optional, Tuple
+
+
+class ShoppingCart:
+    """
+    inv: all(quantity > 0 for (_, quantity) in self.items)
+    """
+
+    def __init__(self, items: Optional[List[Tuple[str, int]]] = None):
+        self.items = items or []
+
+
+def compute_total(cart: ShoppingCart, prices: Dict[str, float]) -> float:
+    """
+    pre: len(cart.items) > 0
+    pre: all(pid in prices for (pid, _) in cart.items)
+
+    We try to ensure that you can't check out with a zero (or less) total.
+    However, we forgot a precondition; namely that the `prices` dictionary only has
+    prices that are greater than zero.
+
+    post: __return__ > 0
+    """
+    return sum(prices[pid] * quantity for (pid, quantity) in cart.items)

crosshair/examples/PEP316/bugs_detected/showcase.py

@@ -0,0 +1,39 @@
+from typing import Callable, Dict, List, Sequence, Tuple, TypeVar
+
+T = TypeVar("T")
+
+
+def list_to_dict(s: Sequence[T]) -> Dict[T, T]:
+    """
+    post: len(__return__) == len(s)
+    # False; CrossHair finds a counterexample with duplicate values in the input.
+    """
+    return dict(zip(s, s))
+
+
+def consecutive_pairs(x: List[T]) -> List[Tuple[T, T]]:
+    """
+    post: len(__return__) == len(x) - 1
+    # False (on an empty input list)
+    """
+    return [(x[i], x[i + 1]) for i in range(len(x) - 1)]
+
+
+def higher_order(fn: Callable[[int], int]) -> int:
+    """
+    Crosshair can find models for pure callables over atomic types.
+
+    post: _ != 42
+    # False (when given something like lambda a: 42 if (a == 0) else 0)
+    """
+    return fn(fn(100))
+
+
+def append_fourtytwo_to_each(lists: List[List[int]]):
+    """
+    pre: len(lists) >= 2
+    post: all(len(x) == len(__old__.lists[i]) + 1 for i, x in enumerate(lists))
+    # False when two elements of the input are the SAME list!
+    """
+    for ls in lists:
+        ls.append(42)

crosshair/examples/PEP316/correct_code/arith.py

@@ -0,0 +1,60 @@
+from typing import List, Optional, Tuple
+
+
+def perimiter_length(length: int, width: int) -> int:
+    """
+    pre: l > 0 and w > 0
+
+    The perimeter of a rectangle is longer than any single side:
+    post: _ > l and _ > w
+    """
+    return 2 * length + 2 * width
+
+
+def swap(things: Tuple[int, int]) -> Tuple[int, int]:
+    """
+    Swap the arguments.
+
+    post: _[0] == things[1]
+    post: _[1] == things[0]
+    """
+    return (things[1], things[0])
+
+
+# NOTE: To perform additional testing, you can write extra private functions like this one:
+def _assert_double_swap_does_nothing(things: Tuple[int, int]) -> Tuple[int, int]:
+    """
+    post: _ == things
+    """
+    ret = swap(swap(things))
+    return ret
+
+
+def double(items: List[str]) -> List[str]:
+    """
+    Return a new list that is the input list, repeated twice.
+
+    post: len(_) == len(items) * 2
+    """
+    return items + items
+
+
+# NOTE: This is an example of contracts on recursive functions.
+def smallest_two(numbers: Tuple[int, ...]) -> Tuple[Optional[int], Optional[int]]:
+    """
+    Find the two smallest numbers.
+
+    pre: len(numbers) > 0
+    # The left return value is always the smallest
+    post: _[0] == min(numbers)
+    """
+    if len(numbers) == 1:
+        return (numbers[0], None)
+    (smallest, second) = smallest_two(numbers[1:])
+    n = numbers[0]
+    if smallest is None or n < smallest:
+        return (n, smallest)
+    elif second is None or n < second:
+        return (smallest, n)
+    else:
+        return (smallest, second)