cot-assert 0.1.0__py2.py3-none-any.whl

cot_assert/__init__.py

@@ -0,0 +1,22 @@
+"""Assertion rewriting with a structured AssertionError."""
+
+from __future__ import absolute_import, division, print_function
+
+from ._entry import report_annotated
+from ._error import AnnotatedAssertion, AssertSite, annotated
+from ._hook import install, uninstall
+from ._rewrite import rewrite_asserts, rewrite_source
+
+# the public name, in tracebacks and pickles
+AnnotatedAssertion.__module__ = __name__
+
+__all__ = [
+    "AnnotatedAssertion",
+    "AssertSite",
+    "annotated",
+    "install",
+    "report_annotated",
+    "rewrite_asserts",
+    "rewrite_source",
+    "uninstall",
+]

cot_assert/_entry.py

@@ -0,0 +1,29 @@
+"""Making AnnotatedAssertion explanations visible from translated programs."""
+
+from __future__ import absolute_import, division, print_function
+
+import os
+
+from ._error import AnnotatedAssertion
+from ._rpy import we_are_translated
+
+
+def report_annotated(func):
+    """Wrap a translated entry point to print an escaping AnnotatedAssertion.
+
+    Uncaught, RPython aborts with just the class name. The wrapper writes
+    the explanation to stderr first and re-raises, so the abort still
+    happens. On the host the traceback already shows it; nothing is written.
+    """
+
+    def entry_point(*args):
+        try:
+            return func(*args)
+        # RPython rejects ``except`` on AssertionError or any subclass
+        except Exception as exc:
+            if we_are_translated() and isinstance(exc, AnnotatedAssertion):
+                os.write(2, exc.render_plain() + "\n")
+            raise
+
+    entry_point.__name__ = "report_annotated_" + func.__name__
+    return entry_point

cot_assert/_error.py

@@ -0,0 +1,155 @@
+"""The assertion error raised by rewritten asserts.
+
+Everything in this module that is not marked host-only is in the RPython
+subset: fields keep one type per attribute, and host-only paths sit behind
+``we_are_translated()``, which the flow space folds to True.
+"""
+
+from __future__ import absolute_import, division, print_function
+
+from ._rpy import specialize, we_are_translated
+from ._values import value
+
+
+class AssertSite(object):
+    """Static description of one assert statement, prebuilt by the rewriter."""
+
+    def __init__(self, source, path_labels, shape=None, paths=None):
+        self.source = source
+        # One label list per failure path: a path that skipped a short-circuit
+        # operand has no value for it. Lists, not tuples: prebuilt tuples of
+        # different lengths do not unify in RPython, lists of str do.
+        self.path_labels = path_labels
+        # Host only, never read by translated code, so never annotated:
+        # the expression tree and per-path records the renderer walks.
+        # See _rewrite.AssertRewriter.
+        self.shape = shape
+        self.paths = paths
+
+
+class AnnotatedAssertion(AssertionError):
+    """An AssertionError that carries the values its explanation is built from.
+
+    Translated, ``values`` holds str; on the host it holds the objects
+    themselves until ``finalize`` renders them and drops them.
+    """
+
+    # Unpatched RPython takes every AssertionError subclass for a built-in
+    # exception: it skips __init__ and allows no attributes but the ones
+    # listed here. Code that has to translate there builds instances with
+    # ``annotated()``; see docs/design/rpython.md.
+    _attrs_ = ["msg", "site", "path", "values", "labels", "rendered"]
+
+    def __init__(self, msg=None, site=None, path=0, values=None):
+        if not we_are_translated():
+            AssertionError.__init__(self)
+        self.init_fields(msg, site, path, values)
+
+    def init_fields(self, msg, site, path, values):
+        self.msg = msg
+        self.site = site
+        self.path = path
+        if values is None:
+            values = []
+        self.values = values
+        self.labels = []
+        self.rendered = None
+
+    @specialize.argtype(2)
+    def annotate(self, label, obj):
+        """Attach a labelled value; the label follows the site's labels."""
+        self.labels.append(label)
+        self.values.append(value(obj))
+        return self
+
+    def all_labels(self):
+        if self.site is None:
+            return self.labels
+        return self.site.path_labels[self.path] + self.labels
+
+    def render_plain(self):
+        """The explanation from str values, as translated code can build it."""
+        lines = []
+        if self.msg is not None:
+            lines.append(self.msg)
+        if self.site is not None:
+            lines.append("assert " + self.site.source)
+        labels = self.all_labels()
+        i = 0
+        while i < len(labels) and i < len(self.values):
+            lines.append(" where " + labels[i] + " = " + self.values[i])
+            i += 1
+        return "\n".join(lines)
+
+    def render(self):
+        """Host only: the explanation text."""
+        if self.rendered is not None:
+            return self.rendered
+        from ._render import render
+
+        return render(self)
+
+    def finalize(self, mode="notes"):
+        """Host only: render once and drop the tracked values.
+
+        ``mode="notes"`` adds the explanation as a PEP 678 note,
+        ``mode="message"`` puts it into ``args`` for hosts that do not show
+        notes (pytest 4.6, Python < 3.11 tracebacks).
+        """
+        if mode not in ("notes", "message"):
+            raise ValueError("unknown finalize mode: %r" % (mode,))
+        if self.values is None:
+            return self
+        text = self.render()
+        # keep only text: nothing that holds on to the tested objects or
+        # needs this package's classes to unpickle into a meaningful state
+        self.rendered = text
+        self.values = None
+        self.site = None
+        if self.msg is not None:
+            self.msg = str(self.msg)
+        if mode == "notes":
+            _add_note(self, text)
+        else:
+            self.args = (text,)
+        return self
+
+    def __reduce__(self):
+        # BaseException's reduce passes args to __init__, which reads them
+        # as msg/site/...; restore args and state directly instead
+        return _unpickle, (type(self), self.args, self.__dict__)
+
+    def __str__(self):
+        if we_are_translated():
+            return self.render_plain()
+        if self.args:
+            return str(self.args[0])
+        if self.values is None:
+            # finalized into notes: the note carries the explanation
+            return self.msg if self.msg is not None else ""
+        return self.render()
+
+
+def annotated(msg=None, site=None, path=0, values=None):
+    """Build an AnnotatedAssertion; the constructor for RPython code."""
+    exc = AnnotatedAssertion()
+    exc.init_fields(msg, site, path, values)
+    return exc
+
+
+def _unpickle(cls, args, state):
+    exc = cls.__new__(cls)
+    exc.args = args
+    exc.__dict__.update(state)
+    return exc
+
+
+def _add_note(exc, text):
+    add_note = getattr(exc, "add_note", None)
+    if add_note is not None:
+        add_note(text)
+    else:
+        notes = getattr(exc, "__notes__", None)
+        if notes is None:
+            notes = exc.__notes__ = []
+        notes.append(text)

cot_assert/_hook.py

@@ -0,0 +1,224 @@
+"""Import hook that rewrites the asserts of selected modules."""
+
+from __future__ import absolute_import, division, print_function
+
+import fnmatch
+import hashlib
+import os
+import sys
+
+from ._rewrite import rewrite_source
+
+PY2 = sys.version_info[0] == 2
+
+
+def _rewriter_digest():
+    """Changes whenever the code that shapes rewritten modules changes.
+
+    Cached bytecode is only valid for the rewriter that produced it; hashing
+    the sources avoids having to remember a version bump.
+    """
+    here = os.path.dirname(os.path.abspath(__file__))
+    digest = hashlib.sha1()
+    for name in ("_rewrite.py", "_unparse.py"):
+        try:
+            with open(os.path.join(here, name), "rb") as f:
+                digest.update(f.read())
+        except (IOError, OSError):
+            return "unknown"
+    return digest.hexdigest()[:10]
+
+
+CACHE_TAG = "cot_assert-" + _rewriter_digest()
+
+
+class _Matcher(object):
+    def __init__(self, patterns):
+        self.patterns = list(patterns)
+
+    def __call__(self, fullname):
+        if fullname == "cot_assert" or fullname.startswith("cot_assert."):
+            return False
+        for pattern in self.patterns:
+            if fnmatch.fnmatchcase(fullname, pattern):
+                return True
+            # a package name selects its submodules too
+            if fullname.startswith(pattern + "."):
+                return True
+            # a wildcard pattern like "test_*" matches the last dotted component
+            last = fullname.rpartition(".")[2]
+            if _is_glob(pattern) and "." not in pattern:
+                if fnmatch.fnmatchcase(last, pattern):
+                    return True
+        return False
+
+
+def _is_glob(pattern):
+    return any(char in pattern for char in "*?[")
+
+
+def install(match):
+    """Rewrite asserts in modules imported from now on whose name matches.
+
+    ``match`` is a list of module names (selecting their submodules too) or
+    fnmatch patterns; a wildcard pattern without dots also matches the last
+    component of a dotted name. Returns the hook; ``uninstall(hook)`` removes it.
+    """
+    hook = RewriteHook(match)
+    sys.meta_path.insert(0, hook)
+    return hook
+
+
+def uninstall(hook):
+    try:
+        sys.meta_path.remove(hook)
+    except ValueError:
+        pass
+
+
+if not PY2:
+    import importlib.machinery
+    import importlib.util
+    import marshal
+
+    class RewriteHook(object):
+        def __init__(self, match):
+            self.matches = _Matcher(match)
+
+        def find_spec(self, fullname, path=None, target=None):
+            if not self.matches(fullname):
+                return None
+            spec = importlib.machinery.PathFinder.find_spec(fullname, path)
+            if spec is None or not isinstance(
+                spec.loader, importlib.machinery.SourceFileLoader
+            ):
+                return None
+            spec.loader = RewritingLoader(fullname, spec.origin)
+            return spec
+
+        def invalidate_caches(self):
+            pass
+
+    class RewritingLoader(importlib.machinery.SourceFileLoader):
+        """A source loader whose code has its asserts rewritten.
+
+        It keeps its own bytecode cache next to the regular one; the regular
+        ``__pycache__`` entry holds unrewritten code and must not be used.
+        """
+
+        def get_code(self, fullname):
+            path = self.get_filename(fullname)
+            st = os.stat(path)
+            cache = cache_path(path)
+            code = _read_cache(cache, st)
+            if code is None:
+                code = rewrite_source(self.get_data(path), path)
+                if not sys.dont_write_bytecode:
+                    _write_cache(cache, st, code)
+            return code
+
+    def cache_path(source_path):
+        directory, filename = os.path.split(source_path)
+        stem = filename.rpartition(".")[0]
+        tag = sys.implementation.cache_tag
+        return os.path.join(
+            directory, "__pycache__", "%s.%s-%s.pyc" % (stem, tag, CACHE_TAG)
+        )
+
+    def _header(st):
+        return (
+            importlib.util.MAGIC_NUMBER
+            + (0).to_bytes(4, "little")
+            + (int(st.st_mtime) & 0xFFFFFFFF).to_bytes(4, "little")
+            + (st.st_size & 0xFFFFFFFF).to_bytes(4, "little")
+        )
+
+    def _read_cache(cache, st):
+        try:
+            with open(cache, "rb") as f:
+                data = f.read()
+        except OSError:
+            return None
+        header = _header(st)
+        if data[: len(header)] != header:
+            return None
+        try:
+            return marshal.loads(data[len(header) :])
+        except (EOFError, ValueError, TypeError):
+            return None
+
+    def _write_cache(cache, st, code):
+        data = _header(st) + marshal.dumps(code)
+        tmp = "%s.%d" % (cache, os.getpid())
+        try:
+            os.makedirs(os.path.dirname(cache), exist_ok=True)
+            with open(tmp, "wb") as f:
+                f.write(data)
+            os.replace(tmp, cache)
+        except OSError:
+            # read-only trees just go without a cache
+            try:
+                os.unlink(tmp)
+            except OSError:
+                pass
+
+else:
+    import imp
+
+    class RewriteHook(object):
+        """PEP 302 finder and loader; Python 2 goes without a disk cache."""
+
+        def __init__(self, match):
+            self.matches = _Matcher(match)
+            self._found = {}
+            self._sources = {}
+
+        def find_module(self, fullname, path=None):
+            if not self.matches(fullname):
+                return None
+            name = fullname.rpartition(".")[2]
+            try:
+                fd, pathname, (_, _, kind) = imp.find_module(name, path)
+            except ImportError:
+                return None
+            if fd is not None:
+                fd.close()
+            is_package = kind == imp.PKG_DIRECTORY
+            if is_package:
+                pathname = os.path.join(pathname, "__init__.py")
+                if not os.path.isfile(pathname):
+                    return None
+            elif kind != imp.PY_SOURCE:
+                return None
+            self._found[fullname] = (pathname, is_package)
+            return self
+
+        def load_module(self, fullname):
+            if fullname in sys.modules:
+                return sys.modules[fullname]
+            pathname, is_package = self._found.pop(fullname)
+            with open(pathname, "rb") as f:
+                code = rewrite_source(f.read(), pathname)
+            module = imp.new_module(fullname)
+            module.__file__ = pathname
+            module.__loader__ = self
+            if is_package:
+                module.__path__ = [os.path.dirname(pathname)]
+                module.__package__ = fullname
+            else:
+                module.__package__ = fullname.rpartition(".")[0]
+            self._sources[fullname] = pathname
+            sys.modules[fullname] = module
+            try:
+                exec(code, module.__dict__)
+            except BaseException:
+                sys.modules.pop(fullname, None)
+                raise
+            return sys.modules[fullname]
+
+        def is_package(self, fullname):
+            return os.path.basename(self._sources[fullname]) == "__init__.py"
+
+        def get_source(self, fullname):
+            with open(self._sources[fullname], "rb") as f:
+                return f.read()

cot_assert/_llexc.py

@@ -0,0 +1,75 @@
+"""Host view of an AnnotatedAssertion raised under RPython's llinterpreter."""
+
+from __future__ import absolute_import, division, print_function
+
+from ._error import AnnotatedAssertion, AssertSite
+
+
+def from_llexception(interp, exc):
+    """The AnnotatedAssertion inside an ``LLException``, or None.
+
+    ``interp`` is the ``LLInterpreter`` that raised it; its rtyper knows the
+    low-level layout of the class.
+    """
+    from rpython.rtyper.annlowlevel import hlstr
+    from rpython.rtyper.lltypesystem import lltype
+    from rpython.rtyper.rclass import getinstancerepr
+
+    klass, inst = exc.args[0], exc.args[1]
+    rtyper = interp.typer
+    bookkeeper = rtyper.annotator.bookkeeper
+    try:
+        classdef = bookkeeper.getuniqueclassdef(AnnotatedAssertion)
+    except Exception:
+        return None
+    r_inst = getinstancerepr(rtyper, classdef)
+    vtable = r_inst.rclass.getvtable()
+    if not _is_subclass(klass, vtable):
+        return None
+    inst = lltype.cast_pointer(r_inst.lowleveltype, inst)
+
+    def text(ll):
+        # a field that only ever holds one constant is Void, and reads back
+        # as that host constant
+        if ll is None or isinstance(ll, str):
+            return ll
+        return hlstr(ll) if ll else None
+
+    def strlist(ll):
+        if not ll:
+            return []
+        return [text(ll.ll_getitem_fast(i)) for i in range(ll.ll_length())]
+
+    result = AnnotatedAssertion(
+        text(inst.inst_msg),
+        _host_site(rtyper, inst.inst_site),
+        inst.inst_path,
+        strlist(inst.inst_values),
+    )
+    result.labels = strlist(inst.inst_labels)
+    return result
+
+
+def _is_subclass(klass, vtable):
+    # RPython vtables carry a [min, max] id range for subclass checks
+    low, high = vtable.subclassrange_min, vtable.subclassrange_max
+    return low <= klass.subclassrange_min < high
+
+
+def _host_site(rtyper, ll_site):
+    """The prebuilt host AssertSite behind a low-level one.
+
+    Sites are prebuilt constants, so the host object exists; its fields that
+    translated code never reads are not in the low-level struct at all.
+    """
+    from rpython.rtyper.lltypesystem import lltype
+    from rpython.rtyper.rclass import getinstancerepr
+
+    if not ll_site:
+        return None
+    classdef = rtyper.annotator.bookkeeper.getuniqueclassdef(AssertSite)
+    r_site = getinstancerepr(rtyper, classdef)
+    for host, ll in r_site.iprebuiltinstances.items():
+        if lltype.cast_pointer(lltype.typeOf(ll_site), ll) == ll_site:
+            return host
+    raise LookupError("no prebuilt AssertSite for %r" % (ll_site,))