crosshair-tool 0.0.99__cp312-cp312-macosx_10_13_x86_64.whl

crosshair/test_util.py

@@ -0,0 +1,329 @@
+import pathlib
+import sys
+from copy import deepcopy
+from dataclasses import dataclass, replace
+from decimal import Decimal
+from math import isnan
+from numbers import Real
+from typing import (
+    Callable,
+    Collection,
+    Iterable,
+    List,
+    Mapping,
+    Optional,
+    Sequence,
+    Set,
+    Tuple,
+)
+
+from crosshair.core import (
+    AnalysisMessage,
+    Checkable,
+    MessageType,
+    analyze_function,
+    deep_realize,
+    run_checkables,
+)
+from crosshair.options import AnalysisOptionSet
+from crosshair.statespace import context_statespace
+from crosshair.tracers import NoTracing, ResumedTracing
+from crosshair.util import (
+    assert_tracing,
+    ch_stack,
+    debug,
+    in_debug,
+    is_iterable,
+    is_pure_python,
+    name_of_type,
+)
+
+ComparableLists = Tuple[List, List]
+
+
+class _Missing:
+    pass
+
+
+_MISSING = _Missing()
+
+
+def simplefs(path: pathlib.Path, files: dict) -> None:
+    for name, contents in files.items():
+        subpath = path / name
+        if isinstance(contents, str):
+            with open(subpath, "w") as fh:
+                fh.write(contents)
+        elif isinstance(contents, dict):
+            subpath.mkdir()
+            simplefs(subpath, contents)
+        else:
+            raise Exception("bad input to simplefs")
+
+
+def check_states(
+    fn: Callable,
+    expected: MessageType,
+    optionset: AnalysisOptionSet = AnalysisOptionSet(),
+) -> None:
+    if expected == MessageType.POST_FAIL:
+        local_opts = AnalysisOptionSet(
+            per_condition_timeout=16,
+            max_uninteresting_iterations=sys.maxsize,
+        )
+    elif expected == MessageType.CONFIRMED:
+        local_opts = AnalysisOptionSet(
+            per_condition_timeout=60,
+            per_path_timeout=20,
+            max_uninteresting_iterations=sys.maxsize,
+        )
+    elif expected == MessageType.POST_ERR:
+        local_opts = AnalysisOptionSet(max_iterations=20)
+    elif expected == MessageType.CANNOT_CONFIRM:
+        local_opts = AnalysisOptionSet(
+            max_uninteresting_iterations=40,
+            per_condition_timeout=3,
+        )
+    else:
+        local_opts = AnalysisOptionSet(
+            max_uninteresting_iterations=40,
+            per_condition_timeout=5,
+        )
+    options = local_opts.overlay(optionset)
+    found = set([m.state for m in run_checkables(analyze_function(fn, options))])
+    assertmsg = f"Got {','.join(map(str, found))} instead of {expected}"
+    if not in_debug():
+        assertmsg += " (use `pytest -v` to show trace)"
+    assert found == {expected}, assertmsg
+
+
+def check_exec_err(
+    fn: Callable, message_prefix="", optionset: AnalysisOptionSet = AnalysisOptionSet()
+) -> ComparableLists:
+    local_opts = AnalysisOptionSet(max_iterations=20)
+    options = local_opts.overlay(optionset)
+    messages = run_checkables(analyze_function(fn, options))
+    if all(m.message.startswith(message_prefix) for m in messages):
+        return ([m.state for m in messages], [MessageType.EXEC_ERR])
+    else:
+        return (
+            [(m.state, m.message) for m in messages],
+            [(MessageType.EXEC_ERR, message_prefix)],
+        )
+
+
+def check_messages(checkables: Iterable[Checkable], **kw) -> ComparableLists:
+    msgs = run_checkables(checkables)
+    if kw.get("state") != MessageType.CONFIRMED:
+        # Normally, ignore confirmation messages:
+        msgs = [m for m in msgs if m.state != MessageType.CONFIRMED]
+    else:
+        # When we want CONFIRMED, take the message with the worst status:
+        msgs = [max(msgs, key=lambda m: m.state)]
+    default_msg = AnalysisMessage(MessageType.CANNOT_CONFIRM, "", "", 0, 0, "")
+    msg = msgs[0] if msgs else replace(default_msg)
+    fields = (
+        "state",
+        "message",
+        "filename",
+        "line",
+        "column",
+        "traceback",
+        "test_fn",
+        "condition_src",
+    )
+    for k in fields:
+        if k not in kw:
+            default_val = getattr(default_msg, k)
+            msg = replace(msg, **{k: default_val})
+            kw[k] = default_val
+    if msgs:
+        msgs[0] = msg
+    return (msgs, [AnalysisMessage(**kw)])
+
+
+_NAN_ABLE = (Decimal, Real)
+
+
+def flexible_equal(a: object, b: object) -> bool:
+    if a is b:
+        return True
+    if type(a) is type(b) and type(a).__eq__ is object.__eq__:
+        # If types match and it uses identity-equals, we can't do much. Assume equal.
+        return True
+    if isinstance(a, _NAN_ABLE) and isinstance(b, _NAN_ABLE) and isnan(a) and isnan(b):
+        return True
+    if (
+        is_iterable(a)
+        and not isinstance(a, Collection)
+        and is_iterable(b)
+        and not isinstance(b, Collection)
+    ):  # unsized iterables compare by contents
+        a, b = list(a), list(b)  # type: ignore
+    if (
+        type(a) == type(b)
+        and isinstance(a, Collection)
+        and not isinstance(a, (str, bytes, Set))
+    ):
+        # Recursively apply flexible_equal for most containers:
+        if len(a) != len(b):  # type: ignore
+            return False
+        if isinstance(a, Mapping):
+            for k, v in a.items():
+                if not flexible_equal(v, b.get(k, _MISSING)):  # type: ignore
+                    return False
+            return True
+        else:
+            return all(flexible_equal(ai, bi) for ai, bi in zip(a, b))  # type: ignore
+
+    return a == b
+
+
+@dataclass(eq=False)
+class ExecutionResult:
+    ret: object  # return value
+    exc: Optional[BaseException]  # exception raised, if any
+    tb: Optional[str]
+    # args after the function terminates:
+    post_args: Sequence
+    post_kwargs: Mapping[str, object]
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, ExecutionResult):
+            return False
+        return (
+            flexible_equal(self.ret, other.ret)
+            and type(self.exc) == type(other.exc)
+            and self.post_args == other.post_args
+            and self.post_kwargs == other.post_kwargs
+        )
+
+    def describe(self, include_postexec=False) -> str:
+        ret = ""
+        if self.exc:
+            exc = self.exc
+            exc_type = name_of_type(type(exc))
+            tb = self.tb or "(missing traceback)"
+            ret = f"exc={exc_type}: {str(exc)} {tb}"
+        else:
+            ret = f"ret={self.ret!r}"
+        if include_postexec:
+            a = [repr(a) for a in self.post_args]
+            a += [f"{k}={v!r}" for k, v in self.post_kwargs.items()]
+            ret += f'  post=({", ".join(a)})'
+        return ret
+
+
+@dataclass
+class IterableResult:
+    values: tuple
+    typ: type
+
+
+def summarize_execution(
+    fn: Callable,
+    args: Sequence[object] = (),
+    kwargs: Optional[Mapping[str, object]] = None,
+    detach_path: bool = True,
+) -> ExecutionResult:
+    if not kwargs:
+        kwargs = {}
+    ret: object = None
+    exc: Optional[Exception] = None
+    tbstr: Optional[str] = None
+    try:
+        possibly_symbolic_ret = fn(*args, **kwargs)
+        if detach_path:
+            context_statespace().detach_path()
+            detach_path = False
+        ret_type = type(possibly_symbolic_ret)
+        _ret = deep_realize(possibly_symbolic_ret)
+        if hasattr(_ret, "__next__"):
+            # Summarize any iterator as the values it produces, plus its type:
+            ret = IterableResult(tuple(_ret), ret_type)
+        elif callable(_ret) and not is_pure_python(_ret):
+            # Summarize C-based callables just based on their type:
+            ret = f"C-based callable {type(_ret).__name__}"
+        else:
+            ret = _ret
+        args = deep_realize(args)
+        kwargs = deep_realize(kwargs)
+    except Exception as e:
+        exc = e
+        if detach_path:
+            context_statespace().detach_path(e)
+        exc = deep_realize(exc)
+        # NOTE: deep_realize somehow empties the __traceback__ member; re-assign it:
+        exc.__traceback__ = e.__traceback__
+        tbstr = ch_stack(currently_handling=exc)
+        if in_debug():
+            debug("hit exception:", type(exc), exc, tbstr)
+    return ExecutionResult(ret, exc, tbstr, args, kwargs)
+
+
+@dataclass
+class ResultComparison:
+    left: ExecutionResult
+    right: ExecutionResult
+
+    def __bool__(self):
+        return self.left == self.right and type(self.left) == type(self.right)
+
+    def __repr__(self):
+        left, right = self.left, self.right
+        include_postexec = left.ret == right.ret and type(left.exc) == type(right.exc)
+        return (
+            left.describe(include_postexec)
+            + "  <--symbolic-vs-concrete-->  "
+            + right.describe(include_postexec)
+        )
+
+
+def compare_returns(fn: Callable, *a: object, **kw: object) -> ResultComparison:
+    comparison = compare_results(fn, *a, **kw)
+    comparison.left.post_args = ()
+    comparison.left.post_kwargs = {}
+    comparison.right.post_args = ()
+    comparison.right.post_kwargs = {}
+    return comparison
+
+
+@assert_tracing(True)
+def compare_results(fn: Callable, *a: object, **kw: object) -> ResultComparison:
+    original_a = deepcopy(a)
+    original_kw = deepcopy(kw)
+    symbolic_result = summarize_execution(fn, a, kw)
+
+    concrete_a = deep_realize(original_a)
+    concrete_kw = deep_realize(original_kw)
+
+    # Check that realization worked, too:
+    with NoTracing():
+        labels_and_args = [
+            *(
+                (f"Argument {idx + 1}", a[idx], arg)
+                for idx, arg in enumerate(concrete_a)
+            ),
+            *((f"Keyword argument '{k}'", kw[k], v) for k, v in concrete_kw.items()),
+        ]
+        for label, symbolic_arg, concrete_arg in labels_and_args:
+            with ResumedTracing():
+                symbolic_type = type(symbolic_arg)
+                concrete_type = type(concrete_arg)
+            true_concrete_type = type(concrete_arg)
+            assert (
+                true_concrete_type == concrete_type
+            ), f"{label} did not realize. It is {true_concrete_type} instead of {concrete_type}."
+            assert (
+                true_concrete_type == symbolic_type
+            ), f"{label} should realize to {symbolic_type}; it is {true_concrete_type} instead."
+
+    with NoTracing():
+        concrete_result = summarize_execution(
+            fn, concrete_a, concrete_kw, detach_path=False
+        )
+        debug("concrete_result:", concrete_result)
+
+    ret = ResultComparison(symbolic_result, concrete_result)
+    bool(ret)
+    return ret

crosshair/test_util_test.py

@@ -0,0 +1,26 @@
+from crosshair.test_util import flexible_equal
+
+
+def test_flexible_equal():
+    assert float("nan") != float("nan")
+    assert flexible_equal(float("nan"), float("nan"))
+    assert flexible_equal((42, float("nan")), (42, float("nan")))
+    assert not flexible_equal([float("nan"), 11], [float("nan"), 22])
+
+    def gen():
+        yield 11
+        yield 22
+
+    assert flexible_equal(gen(), iter([11, 22]))
+    assert not flexible_equal(gen(), iter([11, 22, 33]))
+    assert not flexible_equal(gen(), iter([11]))
+
+    ordered_set_1 = {10_000, 20_000} | {30_000}
+    ordered_set_2 = {30_000, 20_000} | {10_000}
+    assert list(ordered_set_1) != list(ordered_set_2)  # (different orderings)
+    assert flexible_equal(ordered_set_1, ordered_set_2)
+
+    ordered_dict_1 = {1: 2, 3: 4}
+    ordered_dict_2 = {3: 4, 1: 2}
+    assert list(ordered_dict_1.items()) != list(ordered_dict_2.items())
+    assert flexible_equal(ordered_dict_1, ordered_dict_2)

crosshair/tools/check_help_in_doc.py

@@ -0,0 +1,264 @@
+#!/usr/bin/env python3
+
+"""Check that the help snippets in the doc coincide with the actual output."""
+import argparse
+import os
+import pathlib
+import re
+import subprocess
+import sys
+from typing import List, Optional, Tuple
+
+import icontract
+
+
+class Block:
+    """Represent a block in the readme that needs to be checked."""
+
+    @icontract.require(lambda command: command != "")
+    @icontract.require(
+        lambda start_line_idx, end_line_idx: start_line_idx <= end_line_idx
+    )
+    def __init__(self, command: str, start_line_idx: int, end_line_idx: int) -> None:
+        """
+        Initialize with the given values.
+
+        :param command: help command
+        :param start_line_idx: index of the first relevant line
+        :param end_line_idx: index of the first line excluded from the block
+        """
+        self.command = command
+        self.start_line_idx = start_line_idx
+        self.end_line_idx = end_line_idx
+
+
+HELP_STARTS_RE = re.compile(r"^.. Help starts: (?P<command>.*)$")
+
+
+def parse_rst(lines: List[str]) -> Tuple[List[Block], List[str]]:
+    """
+    Parse the code blocks that represent help commands in the RST file.
+
+    :param lines: lines of the readme file
+    :return: (help blocks, errors if any)
+    """
+    blocks = []  # type: List[Block]
+    errors = []  # type: List[str]
+
+    i = 0
+    while i < len(lines):
+        mtch = HELP_STARTS_RE.match(lines[i])
+        if mtch:
+            command = mtch.group("command")
+            help_ends = ".. Help ends: {}".format(command)
+            try:
+                end_index = lines.index(help_ends, i)
+            except ValueError:
+                end_index = -1
+
+            if end_index == -1:
+                return [], ["Could not find the end marker {!r}".format(help_ends)]
+
+            blocks.append(
+                Block(command=command, start_line_idx=i + 1, end_line_idx=end_index)
+            )
+
+            i = end_index + 1
+
+        else:
+            i += 1
+
+    return blocks, errors
+
+
+def capture_output_lines(command: str) -> List[str]:
+    """Capture the output of a help command."""
+    command_parts = command.split(" ")
+    if command_parts[0] in ["python", "python3"]:
+        # We need to replace "python" with "sys.executable" on Windows as the environment
+        # is not properly inherited.
+        command_parts[0] = sys.executable
+
+    proc = subprocess.Popen(
+        command_parts,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        encoding="utf-8",
+    )
+    output, err = proc.communicate()
+    if err:
+        raise RuntimeError(
+            f"The command {command!r} failed with exit code {proc.returncode} and "
+            f"stderr:\n{err}"
+        )
+    # Help text changed in 3.10 argparse; always use the newer text.
+    output = output.replace("optional arguments", "options")
+
+    return output.splitlines()
+
+
+def output_lines_to_code_block(output_lines: List[str]) -> List[str]:
+    """Translate the output of a help command to a RST code block."""
+    result = (
+        [".. code-block:: text", ""]
+        + ["    " + output_line for output_line in output_lines]
+        + [""]
+    )
+
+    result = [line.rstrip() for line in result]
+    return result
+
+
+def diff(got_lines: List[str], expected_lines: List[str]) -> Optional[str]:
+    """
+    Report a difference between the ``got`` and ``expected``.
+
+    Return None if no difference.
+    """
+    if got_lines == expected_lines:
+        return None
+
+    result = []
+
+    result.append("Expected:")
+    for i, line in enumerate(expected_lines):
+        if i >= len(got_lines) or line != got_lines[i]:
+            print("DIFF: {:2d}: {!r}".format(i, line))
+        else:
+            print("OK  : {:2d}: {!r}".format(i, line))
+
+    result.append("Got:")
+    for i, line in enumerate(got_lines):
+        if i >= len(expected_lines) or line != expected_lines[i]:
+            print("DIFF: {:2d}: {!r}".format(i, line))
+        else:
+            print("OK  : {:2d}: {!r}".format(i, line))
+
+    return "\n".join(result)
+
+
+def process_file(path: pathlib.Path, overwrite: bool) -> List[str]:
+    """
+    Check or overwrite the help blocks in the given file.
+
+    :param path: to the doc file
+    :param overwrite: if set, overwrite the help blocks
+    :return: list of errors, if any
+    """
+    text = path.read_text(encoding="utf-8")
+    lines = text.splitlines()
+
+    blocks, errors = parse_rst(lines=lines)
+    if errors:
+        return errors
+
+    if len(blocks) == 0:
+        return []
+
+    if overwrite:
+        result = []  # type: List[str]
+
+        previous_block = None  # type: Optional[Block]
+        for block in blocks:
+            output_lines = capture_output_lines(command=block.command)
+            code_block_lines = output_lines_to_code_block(output_lines=output_lines)
+
+            if previous_block is None:
+                result.extend(lines[: block.start_line_idx])
+            else:
+                result.extend(lines[previous_block.end_line_idx : block.start_line_idx])
+
+            result.extend(code_block_lines)
+            previous_block = block
+        assert previous_block is not None
+        result.extend(lines[previous_block.end_line_idx :])
+        result.append("")  # new line at the end of file
+
+        path.write_text("\n".join(result))
+    else:
+        for block in blocks:
+            output_lines = capture_output_lines(command=block.command)
+            code_block_lines = output_lines_to_code_block(output_lines=output_lines)
+
+            expected_lines = lines[block.start_line_idx : block.end_line_idx]
+            expected_lines = [line.rstrip() for line in expected_lines]
+
+            error = diff(got_lines=code_block_lines, expected_lines=expected_lines)
+            if error:
+                return [error]
+    return []
+
+
+def main() -> int:
+    """Execute the main routine."""
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--overwrite",
+        help="If set, overwrite the relevant part of the doc in-place.",
+        action="store_true",
+    )
+
+    args = parser.parse_args()
+    overwrite = bool(args.overwrite)
+
+    this_dir = pathlib.Path(os.path.realpath(__file__)).parent.parent.parent
+
+    pths = [
+        this_dir / "doc" / "source" / "contracts.rst",
+        this_dir / "doc" / "source" / "cover.rst",
+        this_dir / "doc" / "source" / "diff_behavior.rst",
+        this_dir / "doc" / "source" / "contributing.rst",
+    ]
+
+    success = True
+
+    for pth in pths:
+        errors = process_file(path=pth, overwrite=overwrite)
+        if errors:
+            print("One or more errors in {}:".format(pth), file=sys.stderr)
+            for error in errors:
+                print(error, file=sys.stderr)
+            success = False
+
+    # Also check that the TOC in the README matches the Sphinx TOC:
+    indexlines = open(
+        this_dir / "doc" / "source" / "index.rst", encoding="utf-8"
+    ).readlines()
+    rst_links = [
+        f"latest/{line.strip()}.html"
+        for line in indexlines
+        if re.fullmatch(r"\s*[a-z_]+\s*", line)
+    ]
+    readme_text = open(this_dir / "README.md", encoding="utf-8").read()
+    readme_idx = readme_text.index(
+        "## [Documentation]"
+    )  # find the Documentation section
+    readme_links = list(re.findall(r"latest/\w+.html", readme_text[readme_idx:]))
+    if rst_links != readme_links:
+        success = False
+        chapters_only_in_rst = set(rst_links) - set(readme_links)
+        chapters_only_in_readme = set(readme_links) - set(rst_links)
+        if chapters_only_in_rst:
+            print(
+                f"Error: chapters in index.rst, but missing from README.md: {list(chapters_only_in_rst)}",
+                file=sys.stderr,
+            )
+        elif chapters_only_in_readme:
+            print(
+                f"Error: chapters in README.md, but missing from index.rst: {list(chapters_only_in_readme)}",
+                file=sys.stderr,
+            )
+        else:
+            print(
+                f"Error: chapters in README.md and index.rst have different orderings. {rst_links} != {readme_links}",
+                file=sys.stderr,
+            )
+
+    if not success:
+        return -1
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())