crosshair-tool 0.0.99__cp312-cp312-macosx_10_13_x86_64.whl

crosshair/examples/PEP316/correct_code/chess.py

@@ -0,0 +1,77 @@
+import dataclasses
+
+
+@dataclasses.dataclass(init=False)
+class ChessPiece:
+    """
+    A base class for chess pieces.
+
+    inv: 0 <= self.x < 8
+    inv: 0 <= self.y < 8
+    """
+
+    x: int
+    y: int
+
+    def __init__(self, x: int, y: int):
+        """
+        :raises: ValueError
+        """
+        if not (0 <= x < 8):
+            raise ValueError(f'x position "{x}" is invalid')
+        if not (0 <= y < 8):
+            raise ValueError(f'y position "{y}" is invalid')
+        self.x = x
+        self.y = y
+
+    def can_move_to(self, x: int, y: int) -> bool:
+        """
+        Determine whether this piece can move to the given position (in a single turn).
+
+        pre: (0 <= x < 8) and (0 <= y < 8)
+
+        #  It's never valid to "move" to your present location:
+        post: implies((x, y) == (self.x, self.y), not __return__)
+        """
+        raise NotImplementedError
+
+
+class FreeChessPiece(ChessPiece):
+    def can_move_to(self, x: int, y: int) -> bool:
+        """
+        Most pieces (except the pawn) can move back to their
+        starting position after moving.
+        post: implies(_, type(self)(x, y).can_move_to(self.x, self.y))
+        """
+        raise NotImplementedError
+
+
+def _board_is_symmetric(piece: ChessPiece, x: int, y: int):
+    """
+    A method just for testing. (put this is a test file if you like)
+
+    If the given piece can move to (x,y), then the equivalent
+    opponent's piece should be able to move to the mirrored position.
+
+    pre: piece.can_move_to(x, y)
+    post: piece.can_move_to(7 - x, 7 - y)
+    """
+    piece.x = 7 - piece.x
+    piece.y = 7 - piece.y
+
+
+class Pawn(ChessPiece):
+    def can_move_to(self, x: int, y: int) -> bool:
+        return (x == self.x) and (y == 3) and (x, y) != (self.x, self.y)
+
+
+class Rook(FreeChessPiece):
+    def can_move_to(self, x: int, y: int) -> bool:
+        return (x == self.x) ^ (y == self.y)
+
+
+class King(FreeChessPiece):
+    def can_move_to(self, x: int, y: int) -> bool:
+        return (
+            abs(x - self.x) <= 1 and abs(y - self.y) <= 1 and (x, y) != (self.x, self.y)
+        )

crosshair/examples/PEP316/correct_code/nesting_inference.py

@@ -0,0 +1,17 @@
+from typing import Optional, Tuple
+
+
+def mydiv(x: int, y: int) -> Optional[float]:
+    """
+    pre: y != 0
+    post: isinstance(_, float)
+    """
+    return None if y == 0 else x / y
+
+
+def myavg(t: Tuple[int, ...]) -> Optional[float]:
+    """
+    pre: len(t) > 0
+    post: isinstance(_, float)
+    """
+    return mydiv(sum(t), len(t))

crosshair/examples/PEP316/correct_code/numpy_examples.py

@@ -0,0 +1,132 @@
+from typing import Tuple, Type
+
+import numpy as np
+from numpy.lib.mixins import NDArrayOperatorsMixin
+
+from crosshair import (
+    IgnoreAttempt,
+    SymbolicFactory,
+    deep_realize,
+    realize,
+    register_type,
+)
+from crosshair.util import CrosshairUnsupported
+
+#
+# Classes implemented in C generally cannot be simulated symbolically by
+# CrossHair.
+# However, you can install hooks to produce custom symbolic values.
+# Here, we provide a lazy version of the numpy's array class: this has
+# a symbolic shape and data type.
+# When an actual operation needs to be performed, we'll construct the
+# actual array.
+#
+
+
+class SymbolicNdarray(NDArrayOperatorsMixin):
+    def __init__(self, creator: SymbolicFactory):
+        # Our callback gets a SymbolicFactory instance which can produce more
+        # symbolic values when called with a type.
+        self.shape = creator(Tuple[int, ...], "_shape")
+        # Note that we avoid the builtin len() - symbolic creation hooks do not run
+        # under the monkeypatched environment, and calling the real len() would
+        # realize the shape's length.
+        self.ndim = self.shape.__len__()
+        self.dtype = np.dtype(realize(creator(Type[np.number], "_dtype")))
+
+    @property
+    def size(self):
+        totalsize = 1
+        for size in self.shape:
+            if size < 0:
+                raise IgnoreAttempt("ndarray disallows negative dimensions")
+            totalsize *= size
+        return totalsize
+
+    def __repr__(self):
+        return repr(self.__array__())
+
+    def __array_function__(self, func, types, args, kwargs):
+        return func(*deep_realize(args), **kwargs)
+
+    def __array_ufunc__(self, ufunc, method, *args, **kwargs):
+        if method == "__call__":
+            return ufunc(*deep_realize(args), **kwargs)
+        else:
+            return NotImplemented
+
+    def __ch_realize__(self):
+        # CrossHair looks for this magic method when it needs to make a value concrete:
+        return self.__array__()
+
+    def __array__(self):
+        # numpy looks for this magic method when it needs a real numpy array:
+        if any(size < 0 for size in self.shape):
+            raise IgnoreAttempt("ndarray disallows negative dimensions")
+        self.dtype = realize(self.dtype)
+        self.shape = deep_realize(self.shape)
+        if self.size * self.dtype.itemsize > 10 * 1024 * 1024:
+            raise CrosshairUnsupported("Will not realize numpy arrays over 10MB")
+        # For the contents, we just construct it with ones. This makes it much
+        # less complete in terms of finding counterexamples, but is sufficient
+        # for array dimension and type reasoning. If we were more ambitious,
+        # we would rewrite a (slow) implementation of numpy in terms of native
+        # Python types.
+        return np.ones(self.shape, self.dtype)
+
+
+# Make crosshair use our custom class whenever it needs a symbolic
+# ndarray instance:
+register_type(np.ndarray, SymbolicNdarray)
+
+
+def matrix_multiply(image1: np.ndarray, image2: np.ndarray) -> np.ndarray:
+    """
+    pre: image1.dtype == image2.dtype == np.float64
+    pre: len(image1.shape) == len(image2.shape) == 2
+    pre: image1.shape[1] == image2.shape[0]
+    post: __return__.shape == (image1.shape[0], image2.shape[1])
+    """
+    return image1 @ image2
+
+
+def unit_normalize(a: np.ndarray) -> np.ndarray:
+    """
+    Normalize the given array values into the [0,1] range.
+
+    >>> unit_normalize(np.arange(-1, 2))
+    array([0. , 0.5, 1. ])
+
+    pre: a.size > 0
+    pre: a.dtype == np.float64
+    pre: np.ptp(a) > 0
+    post: np.max(_) <= 1.0
+    post: np.min(_) >= 0.0
+    """
+    return (a - np.min(a)) / np.ptp(a)
+
+
+def threshold_image(image: np.ndarray, threshold: float) -> np.ndarray:
+    """
+    >>> threshold_image(np.array([[0.0, 0.3], [0.6, 1.0]], dtype=np.float64), 0.5)
+    array([[0.5, 0.5],
+           [0.6, 1. ]])
+
+    pre: len(image.shape) == 2
+    pre: image.dtype == np.float64
+    pre: image.size > 0
+    pre: threshold > 0
+    post: _.shape == image.shape
+    post: image.dtype == _.dtype
+    post: np.min(_) >= threshold
+    """
+    return np.where(image > threshold, image, threshold)
+
+
+def repeat_array(src: np.ndarray, count: int) -> np.ndarray:
+    """
+    pre: src.shape[0] > 0
+    pre: count > 0
+    post: _.shape == (src.shape[0] * count, *src.shape[1:])
+    """
+    return np.concatenate([src] * count)

crosshair/examples/PEP316/correct_code/rolling_average.py

@@ -0,0 +1,35 @@
+import dataclasses
+from typing import List
+
+
+@dataclasses.dataclass
+class AverageableStack:
+    """
+    A stack of numbers with a O(1) average() operation.
+
+    inv: self._total == sum(self._values)
+    """
+
+    _values: List[int]
+    _total: int
+
+    def __init__(self):
+        self._values = []
+        self._total = 0
+
+    def push(self, val: int):
+        """post: True"""
+        self._values.append(val)
+        self._total += val
+
+    def pop(self) -> int:
+        """
+        pre: self._values
+        """
+        val = self._values.pop()
+        self._total -= val
+        return val
+
+    def average(self) -> float:
+        """pre: self._values"""
+        return self._total / len(self._values)

crosshair/examples/PEP316/correct_code/showcase.py

@@ -0,0 +1,104 @@
+import statistics
+from typing import Iterable, List, Sequence, Tuple, TypeVar
+
+T = TypeVar("T")
+U = TypeVar("U")
+
+
+def average(numbers: List[float]) -> float:
+    """
+    pre: len(numbers) > 0
+    post: min(numbers) <= __return__ <= max(numbers)
+    """
+    return sum(numbers) / len(numbers)
+
+
+def duplicate_list(a: List[T]) -> List[T]:
+    """
+    post: len(__return__) == 2 * len(a)
+    post: __return__[:len(a)] == a
+    post: __return__[-len(a):] == a
+    """
+    return a + a
+
+
+def compute_grade(homework_scores: List[float], exam_scores: List[float]) -> float:
+    """
+    pre: homework_scores or exam_scores
+    pre: all(0 <= s <= 1.0 for s in homework_scores + exam_scores)
+    post: 0 <= __return__ <= 1.0
+    """
+    # make exams matter more by counting them twice:
+    all_scores = homework_scores + exam_scores + exam_scores
+    return sum(all_scores) / len(all_scores)
+
+
+def make_csv_line(objects: Sequence) -> str:
+    """
+    pre: len(objects) > 0
+    pre: all(',' not in str(o) for o in objects)
+    post: __return__.split(',') == list(map(str, objects))
+    """
+    return ",".join(map(str, objects))
+
+
+def csv_first_column(lines: List[str]) -> List[str]:
+    """
+    pre: all(',' in line for line in lines)
+    post: __return__ == [line.split(',')[0] for line in lines]
+    """
+    return [line[: line.index(",")] for line in lines]
+
+
+def zip_exact(a: Iterable[T], b: Iterable[U]) -> List[Tuple[T, U]]:
+    """
+    pre: len(a) == len(b)
+    post: len(__return__) == len(a) == len(b)
+    """
+    return list(zip(a, b))
+
+
+def zipped_pairs(x: List[T]) -> List[Tuple[T, T]]:
+    """
+    post: len(__return__) == max(0, len(x) - 1)
+    """
+    return zip_exact(x[:-1], x[1:])
+
+
+def even_fibb(n: int) -> List[int]:
+    """
+    Return a list of the first N even fibbonacci numbers.
+
+    >>> even_fibb(2)
+    [2, 8]
+
+    pre: n >= 0
+    post: len(__return__) == n
+    """
+    prev = 1
+    cur = 1
+    result = []
+    while n > 0:
+        prev, cur = cur, prev + cur
+        if cur % 2 == 0:
+            result.append(cur)
+            n -= 1
+    return result
+
+
+def remove_outliers(numbers: List[float], num_deviations: float = 3):
+    """
+    >>> remove_outliers([0, 1, 2, 3, 4, 5, 50, 6, 7, 8, 9], num_deviations=1)
+    [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
+
+    post: len(_) <= len(numbers)
+    post: not numbers or max(_) <= max(numbers)
+    post: not numbers or min(_) >= min(numbers)
+    post: all(x in numbers for x in _)
+    """
+    if len(numbers) < 2:
+        return numbers
+    avg = statistics.mean(numbers)
+    allowed_range = statistics.stdev(numbers) * num_deviations
+    min_val, max_val = avg - allowed_range, avg + allowed_range
+    return [num for num in numbers if min_val <= num <= max_val]

crosshair/examples/check_examples_test.py

@@ -0,0 +1,146 @@
+"""Run functional tests of the tool on all the examples."""
+
+import argparse
+import os
+import pathlib
+import re
+import shlex
+import subprocess
+import sys
+from pathlib import Path
+from typing import Iterable, List
+
+import pytest
+
+
+def extract_linenums(text: str) -> List[int]:
+    r"""
+    Pull ordered line numbers out of crosshair output.
+
+    >>> extract_linenums("foo:34:bar\nfoo:64:bar\n")
+    [34, 64]
+    """
+    return list(map(int, re.compile(r":(\d+)\:").findall(text)))
+
+
+def find_examples() -> Iterable[Path]:
+    examples_dir = pathlib.Path(os.path.realpath(__file__)).parent
+    for path in sorted(examples_dir.glob("*/**/*.py")):
+        if path.stem != "__init__":
+            yield path
+
+
+def main(argv: List[str]) -> int:
+    """Execute the main routine."""
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--overwrite", help="If set, overwrite the golden files", action="store_true"
+    )
+    args = parser.parse_args(argv)
+
+    overwrite = bool(args.overwrite)
+
+    success = True
+
+    for pth in find_examples():
+        success &= run_on_file(pth, overwrite)
+
+    if not success:
+        print("One or more functional tests failed. Please see above.")
+        return 1
+
+    print("The functional tests passed.")
+    return 0
+
+
+def run_on_file(pth: Path, overwrite: bool) -> bool:
+    cmd = [
+        sys.executable,
+        "-m",
+        "crosshair",
+        "check",
+        str(pth),
+    ]
+
+    cmd_as_string = " ".join(shlex.quote(part) for part in cmd)
+
+    print(f"Running: {cmd_as_string}")
+
+    proc = subprocess.Popen(
+        cmd,
+        stdin=subprocess.DEVNULL,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        encoding="utf-8",
+    )
+
+    stdout, stderr = proc.communicate()
+
+    assert isinstance(stdout, str)
+    assert isinstance(stderr, str)
+
+    # We see empty output if, and only if, the process succeeds:
+    if (proc.returncode == 0) != (stdout == "" and stderr == ""):
+        print(
+            f"The return code does not correspond to the output.\n\n"
+            f"The command was:\n"
+            f"{cmd_as_string}\n\n"
+            f"The return code was: {proc.returncode}\n"
+            f"The captured stdout was:\n"
+            f"{stdout}\n\n"
+            f"The captured stderr:\n"
+            f"{stderr}\n\n"
+        )
+        return False
+
+    expected_stdout_pth = pth.parent / (pth.stem + ".out")
+
+    ##
+    # Replace the absolute path to the examples directory
+    # with a place holder to make these tests machine agnostic.
+    ##
+
+    path_re = re.compile(r"^.*[/\\]([_\w]+\.py):", re.MULTILINE)
+    stdout, _ = path_re.subn(r"\1:", stdout)
+
+    if overwrite:
+        if expected_stdout_pth.exists():
+            expected_stdout_pth.unlink()
+        if stdout:
+            expected_stdout_pth.write_text(stdout)
+    else:
+        if expected_stdout_pth.exists():
+            expected_stdout = expected_stdout_pth.read_text()
+        else:
+            expected_stdout = ""
+
+        # We only check line numbers, as error messages aren't stable.
+        if extract_linenums(expected_stdout) != extract_linenums(stdout):
+            print(
+                f"The output was different than expected.\n\n"
+                f"The command was:\n"
+                f"{cmd_as_string}\n\n"
+                f"The captured stdout was:\n"
+                f"{stdout}\n\n"
+                f"The expected stdout:\n"
+                f"{expected_stdout}\n\n"
+            )
+            if stderr:
+                print(f"The captured stderr was:\n" f"{stderr}\n\n")
+            return False
+    return True
+
+
+@pytest.mark.skipif(
+    sys.version_info < (3, 8),
+    reason="only test 3rd party libs under new python versions",
+)
+@pytest.mark.parametrize("path", find_examples(), ids=lambda p: "_".join(p.parts[-3:]))
+def test_examples(path: Path):
+    # TODO: "unable to meet precondition" and non-deterministic problems aren't
+    # surfaced. Reconsider.
+    assert run_on_file(path, overwrite=False)
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

crosshair/examples/deal/__init__.py

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

crosshair/examples/icontract/__init__.py

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

crosshair/examples/icontract/bugs_detected/showcase.py

@@ -0,0 +1,41 @@
+from typing import Callable, Dict, List, Sequence, Tuple, TypeVar
+
+from icontract import ensure, require, snapshot
+
+T = TypeVar("T")
+
+
+@require(lambda x: x > 0)
+@ensure(lambda result: result > 0)
+def some_func(x: int) -> int:
+    # Bug when the constant makes the result negative.
+    return x - 1000
+
+
+@ensure(lambda s, result: len(result) == len(s))
+def list_to_dict(s: Sequence[T]) -> Dict[T, T]:
+    # CrossHair finds a counterexample with duplicate values in the input.
+    return dict(zip(s, s))
+
+
+@ensure(lambda x, result: len(result) == len(x) - 1)
+def consecutive_pairs(x: List[T]) -> List[Tuple[T, T]]:
+    # Bug on an empty input list
+    return [(x[i], x[i + 1]) for i in range(len(x) - 1)]
+
+
+@ensure(lambda result: result != 42)
+def higher_order(fn: Callable[[int], int]) -> int:
+    # Crosshair can find models for pure callables over atomic types.
+    # Bug when given something like lambda a: 42 if (a == 0) else 0.
+    return fn(fn(100))
+
+
+@snapshot(lambda lists: lists[:])
+@ensure(
+    lambda lists, OLD: all(len(x) == len(OLD.lists[i]) + 1 for i, x in enumerate(lists))
+)
+def append_fourtytwo_to_each(lists: List[List[int]]):
+    # Bug when two elements of the input are the SAME list!
+    for ls in lists:
+        ls.append(42)

crosshair/examples/icontract/bugs_detected/wrong_sign.py

@@ -0,0 +1,8 @@
+import icontract
+
+
+@icontract.require(lambda x: x > 0)
+@icontract.ensure(lambda result: result > 0)
+def some_func(x: int) -> int:
+    # The constant makes the result negative.
+    return x - 1000

crosshair/examples/icontract/correct_code/arith.py

@@ -0,0 +1,51 @@
+from typing import List, Optional, Tuple
+
+import icontract
+
+
+@icontract.require(lambda ln, w: ln > 0 and w > 0)
+@icontract.ensure(
+    lambda ln, w, result: result > ln and result > w,
+    "The perimeter of a rectangle is longer than any single side.",
+)
+def perimiter_length(length: int, width: int) -> int:
+    return 2 * length + 2 * width
+
+
+@icontract.ensure(lambda things, result: result[0] == things[1])
+@icontract.ensure(lambda things, result: result[1] == things[0])
+def swap(things: Tuple[int, int]) -> Tuple[int, int]:
+    """
+    Swap the arguments.
+    """
+    return (things[1], things[0])
+
+
+@icontract.ensure(lambda items, result: len(result) == len(items) * 2)
+def double(items: List[str]) -> List[str]:
+    """
+    Return a new list that is the input list, repeated twice.
+    """
+    return items + items
+
+
+# NOTE: This is an example of contracts on recursive functions.
+
+
+@icontract.require(lambda numbers: len(numbers) > 0)
+@icontract.ensure(
+    lambda numbers, result: result[0] == min(numbers),
+    "The left return value is always the smallest.",
+)
+def smallest_two(numbers: Tuple[int, ...]) -> Tuple[Optional[int], Optional[int]]:
+    """Find the two smallest 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)