coverage 7.11.3__cp314-cp314-macosx_11_0_arm64.whl

coverage/__init__.py

@@ -0,0 +1,40 @@
+# Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
+# For details: https://github.com/coveragepy/coveragepy/blob/main/NOTICE.txt
+
+"""
+Code coverage measurement for Python.
+
+Ned Batchelder
+https://coverage.readthedocs.io
+
+"""
+
+from __future__ import annotations
+
+# isort: skip_file
+
+# mypy's convention is that "import as" names are public from the module.
+# We import names as themselves to indicate that. Pylint sees it as pointless,
+# so disable its warning.
+# pylint: disable=useless-import-alias
+
+from coverage.version import (
+    __version__ as __version__,
+    version_info as version_info,
+)
+
+from coverage.control import (
+    Coverage as Coverage,
+    process_startup as process_startup,
+)
+from coverage.data import CoverageData as CoverageData
+from coverage.exceptions import CoverageException as CoverageException
+from coverage.plugin import (
+    CodeRegion as CodeRegion,
+    CoveragePlugin as CoveragePlugin,
+    FileReporter as FileReporter,
+    FileTracer as FileTracer,
+)
+
+# Backward compatibility.
+coverage = Coverage

coverage/__main__.py

@@ -0,0 +1,12 @@
+# Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
+# For details: https://github.com/coveragepy/coveragepy/blob/main/NOTICE.txt
+
+"""Coverage.py's main entry point."""
+
+from __future__ import annotations
+
+import sys
+
+from coverage.cmdline import main
+
+sys.exit(main())

coverage/annotate.py

@@ -0,0 +1,114 @@
+# Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
+# For details: https://github.com/coveragepy/coveragepy/blob/main/NOTICE.txt
+
+"""Source file annotation for coverage.py."""
+
+from __future__ import annotations
+
+import os
+import re
+from collections.abc import Iterable
+from typing import TYPE_CHECKING
+
+from coverage.files import flat_rootname
+from coverage.misc import ensure_dir, isolate_module
+from coverage.plugin import FileReporter
+from coverage.report_core import get_analysis_to_report
+from coverage.results import Analysis
+from coverage.types import TMorf
+
+if TYPE_CHECKING:
+    from coverage import Coverage
+
+os = isolate_module(os)
+
+
+class AnnotateReporter:
+    """Generate annotated source files showing line coverage.
+
+    This reporter creates annotated copies of the measured source files. Each
+    .py file is copied as a .py,cover file, with a left-hand margin annotating
+    each line::
+
+        > def h(x):
+        -     if 0:   #pragma: no cover
+        -         pass
+        >     if x == 1:
+        !         a = 1
+        >     else:
+        >         a = 2
+
+        > h(2)
+
+    Executed lines use ">", lines not executed use "!", lines excluded from
+    consideration use "-".
+
+    """
+
+    def __init__(self, coverage: Coverage) -> None:
+        self.coverage = coverage
+        self.config = self.coverage.config
+        self.directory: str | None = None
+
+    blank_re = re.compile(r"\s*(#|$)")
+    else_re = re.compile(r"\s*else\s*:\s*(#|$)")
+
+    def report(self, morfs: Iterable[TMorf] | None, directory: str | None = None) -> None:
+        """Run the report.
+
+        See `coverage.report()` for arguments.
+
+        """
+        self.directory = directory
+        self.coverage.get_data()
+        for fr, analysis in get_analysis_to_report(self.coverage, morfs):
+            self.annotate_file(fr, analysis)
+
+    def annotate_file(self, fr: FileReporter, analysis: Analysis) -> None:
+        """Annotate a single file.
+
+        `fr` is the FileReporter for the file to annotate.
+
+        """
+        statements = sorted(analysis.statements)
+        missing = sorted(analysis.missing)
+        excluded = sorted(analysis.excluded)
+
+        if self.directory:
+            ensure_dir(self.directory)
+            dest_file = os.path.join(self.directory, flat_rootname(fr.relative_filename()))
+            assert dest_file.endswith("_py")
+            dest_file = dest_file[:-3] + ".py"
+        else:
+            dest_file = fr.filename
+        dest_file += ",cover"
+
+        with open(dest_file, "w", encoding="utf-8") as dest:
+            i = j = 0
+            covered = True
+            source = fr.source()
+            for lineno, line in enumerate(source.splitlines(True), start=1):
+                while i < len(statements) and statements[i] < lineno:
+                    i += 1
+                while j < len(missing) and missing[j] < lineno:
+                    j += 1
+                if i < len(statements) and statements[i] == lineno:
+                    covered = j >= len(missing) or missing[j] > lineno
+                if self.blank_re.match(line):
+                    dest.write("  ")
+                elif self.else_re.match(line):
+                    # Special logic for lines containing only "else:".
+                    if j >= len(missing):
+                        dest.write("> ")
+                    elif statements[i] == missing[j]:
+                        dest.write("! ")
+                    else:
+                        dest.write("> ")
+                elif lineno in excluded:
+                    dest.write("- ")
+                elif covered:
+                    dest.write("> ")
+                else:
+                    dest.write("! ")
+
+                dest.write(line)

coverage/bytecode.py

@@ -0,0 +1,196 @@
+# Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
+# For details: https://github.com/coveragepy/coveragepy/blob/main/NOTICE.txt
+
+"""Bytecode analysis for coverage.py"""
+
+from __future__ import annotations
+
+import collections
+import dis
+from types import CodeType
+from typing import Iterable, Mapping, Optional
+
+from coverage.types import TArc, TLineNo, TOffset
+
+
+def code_objects(code: CodeType) -> Iterable[CodeType]:
+    """Iterate over all the code objects in `code`."""
+    stack = [code]
+    while stack:
+        # We're going to return the code object on the stack, but first
+        # push its children for later returning.
+        code = stack.pop()
+        for c in code.co_consts:
+            if isinstance(c, CodeType):
+                stack.append(c)
+        yield code
+
+
+def op_set(*op_names: str) -> set[int]:
+    """Make a set of opcodes from instruction names.
+
+    The names might not exist in this version of Python, skip those if not.
+    """
+    ops = {op for name in op_names if (op := dis.opmap.get(name))}
+    assert ops, f"At least one opcode must exist: {op_names}"
+    return ops
+
+
+# Opcodes that are unconditional jumps elsewhere.
+ALWAYS_JUMPS = op_set(
+    "JUMP_BACKWARD",
+    "JUMP_BACKWARD_NO_INTERRUPT",
+    "JUMP_FORWARD",
+)
+
+# Opcodes that exit from a function.
+RETURNS = op_set(
+    "RETURN_VALUE",
+    "RETURN_GENERATOR",
+)
+
+# Opcodes that do nothing.
+NOPS = op_set(
+    "NOP",
+    "NOT_TAKEN",
+)
+
+
+class InstructionWalker:
+    """Utility to step through trails of instructions.
+
+    We have two reasons to need sequences of instructions from a code object:
+    First, in strict sequence to visit all the instructions in the object.
+    This is `walk(follow_jumps=False)`.  Second, we want to follow jumps to
+    understand how execution will flow: `walk(follow_jumps=True)`.
+    """
+
+    def __init__(self, code: CodeType) -> None:
+        self.code = code
+        self.insts: dict[TOffset, dis.Instruction] = {}
+
+        inst = None
+        for inst in dis.get_instructions(code):
+            self.insts[inst.offset] = inst
+
+        assert inst is not None
+        self.max_offset = inst.offset
+
+    def walk(
+        self, *, start_at: TOffset = 0, follow_jumps: bool = True
+    ) -> Iterable[dis.Instruction]:
+        """
+        Yield instructions starting from `start_at`.  Follow unconditional
+        jumps if `follow_jumps` is true.
+        """
+        seen = set()
+        offset = start_at
+        while offset < self.max_offset + 1:
+            if offset in seen:
+                break
+            seen.add(offset)
+            if inst := self.insts.get(offset):
+                yield inst
+                if follow_jumps and inst.opcode in ALWAYS_JUMPS:
+                    offset = inst.jump_target
+                    continue
+            offset += 2
+
+
+TBranchTrailsOneSource = dict[Optional[TArc], set[TOffset]]
+TBranchTrails = dict[TOffset, TBranchTrailsOneSource]
+
+
+def branch_trails(
+    code: CodeType,
+    multiline_map: Mapping[TLineNo, TLineNo],
+) -> TBranchTrails:
+    """
+    Calculate branch trails for `code`.
+
+    `multiline_map` maps line numbers to the first line number of a
+    multi-line statement.
+
+    Instructions can have a jump_target, where they might jump to next.  Some
+    instructions with a jump_target are unconditional jumps (ALWAYS_JUMPS), so
+    they aren't interesting to us, since they aren't the start of a branch
+    possibility.
+
+    Instructions that might or might not jump somewhere else are branch
+    possibilities.  For each of those, we track a trail of instructions.  These
+    are lists of instruction offsets, the next instructions that can execute.
+    We follow the trail until we get to a new source line.  That gives us the
+    arc from the original instruction's line to the new source line.
+
+    """
+    the_trails: TBranchTrails = collections.defaultdict(lambda: collections.defaultdict(set))
+    iwalker = InstructionWalker(code)
+    for inst in iwalker.walk(follow_jumps=False):
+        if not inst.jump_target:
+            # We only care about instructions with jump targets.
+            continue
+        if inst.opcode in ALWAYS_JUMPS:
+            # We don't care about unconditional jumps.
+            continue
+
+        from_line = inst.line_number
+        if from_line is None:
+            continue
+        from_line = multiline_map.get(from_line, from_line)
+
+        def add_one_branch_trail(
+            trails: TBranchTrailsOneSource,
+            start_at: TOffset,
+        ) -> None:
+            # pylint: disable=cell-var-from-loop
+            inst_offsets: set[TOffset] = set()
+            to_line = None
+            for inst2 in iwalker.walk(start_at=start_at, follow_jumps=True):
+                inst_offsets.add(inst2.offset)
+                l2 = inst2.line_number
+                if l2 is not None:
+                    l2 = multiline_map.get(l2, l2)
+                if l2 and l2 != from_line:
+                    to_line = l2
+                    break
+                elif inst2.jump_target and (inst2.opcode not in ALWAYS_JUMPS):
+                    break
+                elif inst2.opcode in RETURNS:
+                    to_line = -code.co_firstlineno
+                    break
+            if to_line is not None:
+                trails[(from_line, to_line)].update(inst_offsets)
+            else:
+                trails[None] = set()
+
+        # Calculate two trails: one from the next instruction, and one from the
+        # jump_target instruction.
+        trails: TBranchTrailsOneSource = collections.defaultdict(set)
+        add_one_branch_trail(trails, start_at=inst.offset + 2)
+        add_one_branch_trail(trails, start_at=inst.jump_target)
+        the_trails[inst.offset] = trails
+
+        # Sometimes we get BRANCH_RIGHT or BRANCH_LEFT events from instructions
+        # other than the original jump possibility instruction.  Register each
+        # trail under all of their offsets so we can pick up in the middle of a
+        # trail if need be.
+        for arc, offsets in trails.items():
+            for offset in offsets:
+                the_trails[offset][arc].update(offsets)
+
+    return the_trails
+
+
+def always_jumps(code: CodeType) -> dict[TOffset, TOffset]:
+    """Make a map of unconditional bytecodes jumping to others.
+
+    Only include bytecodes that do no work and go to another bytecode.
+    """
+    jumps = {}
+    iwalker = InstructionWalker(code)
+    for inst in iwalker.walk(follow_jumps=False):
+        if inst.opcode in ALWAYS_JUMPS:
+            jumps[inst.offset] = inst.jump_target
+        elif inst.opcode in NOPS:
+            jumps[inst.offset] = inst.offset + 2
+    return jumps