coverage 7.11.3__cp314-cp314-musllinux_1_2_x86_64.whl

coverage/plugin_support.py

@@ -0,0 +1,299 @@
+# Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
+# For details: https://github.com/coveragepy/coveragepy/blob/main/NOTICE.txt
+
+"""Support for plugins."""
+
+from __future__ import annotations
+
+import os
+import os.path
+import sys
+from collections.abc import Iterable, Iterator
+from types import FrameType
+from typing import Any, Callable
+
+from coverage.exceptions import PluginError
+from coverage.misc import isolate_module
+from coverage.plugin import CoveragePlugin, FileReporter, FileTracer
+from coverage.types import TArc, TConfigurable, TDebugCtl, TLineNo, TPluginConfig, TSourceTokenLines
+
+os = isolate_module(os)
+
+
+class Plugins:
+    """The currently loaded collection of coverage.py plugins."""
+
+    def __init__(self, debug: TDebugCtl | None = None) -> None:
+        self.order: list[CoveragePlugin] = []
+        self.names: dict[str, CoveragePlugin] = {}
+        self.file_tracers: list[CoveragePlugin] = []
+        self.configurers: list[CoveragePlugin] = []
+        self.context_switchers: list[CoveragePlugin] = []
+
+        self.current_module: str | None = None
+        self.debug = debug
+
+    def load_from_config(
+        self,
+        modules: Iterable[str],
+        config: TPluginConfig,
+    ) -> None:
+        """Load plugin modules, and read their settings from configuration."""
+
+        for module in modules:
+            self.current_module = module
+            __import__(module)
+            mod = sys.modules[module]
+
+            coverage_init = getattr(mod, "coverage_init", None)
+            if not coverage_init:
+                raise PluginError(
+                    f"Plugin module {module!r} didn't define a coverage_init function",
+                )
+
+            options = config.get_plugin_options(module)
+            coverage_init(self, options)
+
+        self.current_module = None
+
+    def load_from_callables(
+        self,
+        plugin_inits: Iterable[TCoverageInit],
+    ) -> None:
+        """Load plugins from callables provided."""
+        for fn in plugin_inits:
+            fn(self)
+
+    def add_file_tracer(self, plugin: CoveragePlugin) -> None:
+        """Add a file tracer plugin.
+
+        `plugin` is an instance of a third-party plugin class.  It must
+        implement the :meth:`CoveragePlugin.file_tracer` method.
+
+        """
+        self._add_plugin(plugin, self.file_tracers)
+
+    def add_configurer(self, plugin: CoveragePlugin) -> None:
+        """Add a configuring plugin.
+
+        `plugin` is an instance of a third-party plugin class. It must
+        implement the :meth:`CoveragePlugin.configure` method.
+
+        """
+        self._add_plugin(plugin, self.configurers)
+
+    def add_dynamic_context(self, plugin: CoveragePlugin) -> None:
+        """Add a dynamic context plugin.
+
+        `plugin` is an instance of a third-party plugin class.  It must
+        implement the :meth:`CoveragePlugin.dynamic_context` method.
+
+        """
+        self._add_plugin(plugin, self.context_switchers)
+
+    def add_noop(self, plugin: CoveragePlugin) -> None:
+        """Add a plugin that does nothing.
+
+        This is only useful for testing the plugin support.
+
+        """
+        self._add_plugin(plugin, None)
+
+    def _add_plugin(
+        self,
+        plugin: CoveragePlugin,
+        specialized: list[CoveragePlugin] | None,
+    ) -> None:
+        """Add a plugin object.
+
+        `plugin` is a :class:`CoveragePlugin` instance to add.  `specialized`
+        is a list to append the plugin to.
+
+        """
+        plugin_name = f"{self.current_module}.{plugin.__class__.__name__}"
+        if self.debug and self.debug.should("plugin"):
+            self.debug.write(f"Loaded plugin {self.current_module!r}: {plugin!r}")
+            labelled = LabelledDebug(f"plugin {self.current_module!r}", self.debug)
+            plugin = DebugPluginWrapper(plugin, labelled)
+
+        plugin._coverage_plugin_name = plugin_name
+        plugin._coverage_enabled = True
+        self.order.append(plugin)
+        self.names[plugin_name] = plugin
+        if specialized is not None:
+            specialized.append(plugin)
+
+    def __bool__(self) -> bool:
+        return bool(self.order)
+
+    def __iter__(self) -> Iterator[CoveragePlugin]:
+        return iter(self.order)
+
+    def get(self, plugin_name: str) -> CoveragePlugin:
+        """Return a plugin by name."""
+        return self.names[plugin_name]
+
+
+TCoverageInit = Callable[[Plugins], None]
+
+
+class LabelledDebug:
+    """A Debug writer, but with labels for prepending to the messages."""
+
+    def __init__(self, label: str, debug: TDebugCtl, prev_labels: Iterable[str] = ()):
+        self.labels = list(prev_labels) + [label]
+        self.debug = debug
+
+    def add_label(self, label: str) -> LabelledDebug:
+        """Add a label to the writer, and return a new `LabelledDebug`."""
+        return LabelledDebug(label, self.debug, self.labels)
+
+    def message_prefix(self) -> str:
+        """The prefix to use on messages, combining the labels."""
+        prefixes = self.labels + [""]
+        return ":\n".join("  " * i + label for i, label in enumerate(prefixes))
+
+    def write(self, message: str) -> None:
+        """Write `message`, but with the labels prepended."""
+        self.debug.write(f"{self.message_prefix()}{message}")
+
+
+class DebugPluginWrapper(CoveragePlugin):
+    """Wrap a plugin, and use debug to report on what it's doing."""
+
+    def __init__(self, plugin: CoveragePlugin, debug: LabelledDebug) -> None:
+        super().__init__()
+        self.plugin = plugin
+        self.debug = debug
+
+    def file_tracer(self, filename: str) -> FileTracer | None:
+        tracer = self.plugin.file_tracer(filename)
+        self.debug.write(f"file_tracer({filename!r}) --> {tracer!r}")
+        if tracer:
+            debug = self.debug.add_label(f"file {filename!r}")
+            tracer = DebugFileTracerWrapper(tracer, debug)
+        return tracer
+
+    def file_reporter(self, filename: str) -> FileReporter | str:
+        reporter = self.plugin.file_reporter(filename)
+        assert isinstance(reporter, FileReporter)
+        self.debug.write(f"file_reporter({filename!r}) --> {reporter!r}")
+        if reporter:
+            debug = self.debug.add_label(f"file {filename!r}")
+            reporter = DebugFileReporterWrapper(filename, reporter, debug)
+        return reporter
+
+    def dynamic_context(self, frame: FrameType) -> str | None:
+        context = self.plugin.dynamic_context(frame)
+        self.debug.write(f"dynamic_context({frame!r}) --> {context!r}")
+        return context
+
+    def find_executable_files(self, src_dir: str) -> Iterable[str]:
+        executable_files = self.plugin.find_executable_files(src_dir)
+        self.debug.write(f"find_executable_files({src_dir!r}) --> {executable_files!r}")
+        return executable_files
+
+    def configure(self, config: TConfigurable) -> None:
+        self.debug.write(f"configure({config!r})")
+        self.plugin.configure(config)
+
+    def sys_info(self) -> Iterable[tuple[str, Any]]:
+        return self.plugin.sys_info()
+
+
+class DebugFileTracerWrapper(FileTracer):
+    """A debugging `FileTracer`."""
+
+    def __init__(self, tracer: FileTracer, debug: LabelledDebug) -> None:
+        self.tracer = tracer
+        self.debug = debug
+
+    def _show_frame(self, frame: FrameType) -> str:
+        """A short string identifying a frame, for debug messages."""
+        filename = os.path.basename(frame.f_code.co_filename)
+        return f"{filename}@{frame.f_lineno}"
+
+    def source_filename(self) -> str:
+        sfilename = self.tracer.source_filename()
+        self.debug.write(f"source_filename() --> {sfilename!r}")
+        return sfilename
+
+    def has_dynamic_source_filename(self) -> bool:
+        has = self.tracer.has_dynamic_source_filename()
+        self.debug.write(f"has_dynamic_source_filename() --> {has!r}")
+        return has
+
+    def dynamic_source_filename(self, filename: str, frame: FrameType) -> str | None:
+        dyn = self.tracer.dynamic_source_filename(filename, frame)
+        self.debug.write(
+            "dynamic_source_filename({!r}, {}) --> {!r}".format(
+                filename,
+                self._show_frame(frame),
+                dyn,
+            )
+        )
+        return dyn
+
+    def line_number_range(self, frame: FrameType) -> tuple[TLineNo, TLineNo]:
+        pair = self.tracer.line_number_range(frame)
+        self.debug.write(f"line_number_range({self._show_frame(frame)}) --> {pair!r}")
+        return pair
+
+
+class DebugFileReporterWrapper(FileReporter):
+    """A debugging `FileReporter`."""
+
+    def __init__(self, filename: str, reporter: FileReporter, debug: LabelledDebug) -> None:
+        super().__init__(filename)
+        self.reporter = reporter
+        self.debug = debug
+
+    def relative_filename(self) -> str:
+        ret = self.reporter.relative_filename()
+        self.debug.write(f"relative_filename() --> {ret!r}")
+        return ret
+
+    def lines(self) -> set[TLineNo]:
+        ret = self.reporter.lines()
+        self.debug.write(f"lines() --> {ret!r}")
+        return ret
+
+    def excluded_lines(self) -> set[TLineNo]:
+        ret = self.reporter.excluded_lines()
+        self.debug.write(f"excluded_lines() --> {ret!r}")
+        return ret
+
+    def translate_lines(self, lines: Iterable[TLineNo]) -> set[TLineNo]:
+        ret = self.reporter.translate_lines(lines)
+        self.debug.write(f"translate_lines({lines!r}) --> {ret!r}")
+        return ret
+
+    def translate_arcs(self, arcs: Iterable[TArc]) -> set[TArc]:
+        ret = self.reporter.translate_arcs(arcs)
+        self.debug.write(f"translate_arcs({arcs!r}) --> {ret!r}")
+        return ret
+
+    def no_branch_lines(self) -> set[TLineNo]:
+        ret = self.reporter.no_branch_lines()
+        self.debug.write(f"no_branch_lines() --> {ret!r}")
+        return ret
+
+    def exit_counts(self) -> dict[TLineNo, int]:
+        ret = self.reporter.exit_counts()
+        self.debug.write(f"exit_counts() --> {ret!r}")
+        return ret
+
+    def arcs(self) -> set[TArc]:
+        ret = self.reporter.arcs()
+        self.debug.write(f"arcs() --> {ret!r}")
+        return ret
+
+    def source(self) -> str:
+        ret = self.reporter.source()
+        self.debug.write(f"source() --> {len(ret)} chars")
+        return ret
+
+    def source_token_lines(self) -> TSourceTokenLines:
+        ret = list(self.reporter.source_token_lines())
+        self.debug.write(f"source_token_lines() --> {len(ret)} tokens")
+        return ret

coverage/py.typed

@@ -0,0 +1 @@
+# Marker file for PEP 561 to indicate that this package has type hints.

coverage/python.py

@@ -0,0 +1,269 @@
+# Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
+# For details: https://github.com/coveragepy/coveragepy/blob/main/NOTICE.txt
+
+"""Python source expertise for coverage.py"""
+
+from __future__ import annotations
+
+import os.path
+import types
+import zipimport
+from collections.abc import Iterable
+from typing import TYPE_CHECKING
+
+from coverage import env
+from coverage.exceptions import CoverageException, NoSource
+from coverage.files import canonical_filename, relative_filename, zip_location
+from coverage.misc import isolate_module, join_regex
+from coverage.parser import PythonParser
+from coverage.phystokens import source_encoding, source_token_lines
+from coverage.plugin import CodeRegion, FileReporter
+from coverage.regions import code_regions
+from coverage.types import TArc, TLineNo, TMorf, TSourceTokenLines
+
+if TYPE_CHECKING:
+    from coverage import Coverage
+
+os = isolate_module(os)
+
+
+def read_python_source(filename: str) -> bytes:
+    """Read the Python source text from `filename`.
+
+    Returns bytes.
+
+    """
+    with open(filename, "rb") as f:
+        source = f.read()
+
+    return source.replace(b"\r\n", b"\n").replace(b"\r", b"\n")
+
+
+def get_python_source(filename: str) -> str:
+    """Return the source code, as unicode."""
+    base, ext = os.path.splitext(filename)
+    if ext == ".py" and env.WINDOWS:
+        exts = [".py", ".pyw"]
+    else:
+        exts = [ext]
+
+    source_bytes: bytes | None
+    for ext in exts:
+        try_filename = base + ext
+        if os.path.exists(try_filename):
+            # A regular text file: open it.
+            source_bytes = read_python_source(try_filename)
+            break
+
+        # Maybe it's in a zip file?
+        source_bytes = get_zip_bytes(try_filename)
+        if source_bytes is not None:
+            break
+    else:
+        # Couldn't find source.
+        raise NoSource(f"No source for code: '{filename}'.", slug="no-source")
+
+    # Replace \f because of http://bugs.python.org/issue19035
+    source_bytes = source_bytes.replace(b"\f", b" ")
+    source = source_bytes.decode(source_encoding(source_bytes), "replace")
+
+    # Python code should always end with a line with a newline.
+    if source and source[-1] != "\n":
+        source += "\n"
+
+    return source
+
+
+def get_zip_bytes(filename: str) -> bytes | None:
+    """Get data from `filename` if it is a zip file path.
+
+    Returns the bytestring data read from the zip file, or None if no zip file
+    could be found or `filename` isn't in it.  The data returned will be
+    an empty string if the file is empty.
+
+    """
+    zipfile_inner = zip_location(filename)
+    if zipfile_inner is not None:
+        zipfile, inner = zipfile_inner
+        try:
+            zi = zipimport.zipimporter(zipfile)
+        except zipimport.ZipImportError:
+            return None
+        try:
+            data = zi.get_data(inner)
+        except OSError:
+            return None
+        return data
+    return None
+
+
+def source_for_file(filename: str) -> str:
+    """Return the source filename for `filename`.
+
+    Given a file name being traced, return the best guess as to the source
+    file to attribute it to.
+
+    """
+    if filename.endswith(".py"):
+        # .py files are themselves source files.
+        return filename
+
+    elif filename.endswith((".pyc", ".pyo")):
+        # Bytecode files probably have source files near them.
+        py_filename = filename[:-1]
+        if os.path.exists(py_filename):
+            # Found a .py file, use that.
+            return py_filename
+        if env.WINDOWS:
+            # On Windows, it could be a .pyw file.
+            pyw_filename = py_filename + "w"
+            if os.path.exists(pyw_filename):
+                return pyw_filename
+        # Didn't find source, but it's probably the .py file we want.
+        return py_filename
+
+    # No idea, just use the file name as-is.
+    return filename
+
+
+def source_for_morf(morf: TMorf) -> str:
+    """Get the source filename for the module-or-file `morf`."""
+    if hasattr(morf, "__file__") and morf.__file__:
+        filename = morf.__file__
+    elif isinstance(morf, types.ModuleType):
+        # A module should have had .__file__, otherwise we can't use it.
+        # This could be a PEP-420 namespace package.
+        raise CoverageException(f"Module {morf} has no file")
+    else:
+        filename = morf
+
+    filename = source_for_file(filename)
+    return filename
+
+
+class PythonFileReporter(FileReporter):
+    """Report support for a Python file."""
+
+    def __init__(self, morf: TMorf, coverage: Coverage | None = None) -> None:
+        self.coverage = coverage
+
+        filename = source_for_morf(morf)
+
+        fname = filename
+        canonicalize = True
+        if self.coverage is not None:
+            if self.coverage.config.relative_files:
+                canonicalize = False
+        if canonicalize:
+            fname = canonical_filename(filename)
+        super().__init__(fname)
+
+        if hasattr(morf, "__name__"):
+            name = morf.__name__.replace(".", os.sep)
+            if os.path.basename(filename).startswith("__init__."):
+                name += os.sep + "__init__"
+            name += ".py"
+        else:
+            name = relative_filename(filename)
+        self.relname = name
+
+        self._source: str | None = None
+        self._parser: PythonParser | None = None
+        self._excluded = None
+
+    def __repr__(self) -> str:
+        return f"<PythonFileReporter {self.filename!r}>"
+
+    def relative_filename(self) -> str:
+        return self.relname
+
+    @property
+    def parser(self) -> PythonParser:
+        """Lazily create a :class:`PythonParser`."""
+        assert self.coverage is not None
+        if self._parser is None:
+            self._parser = PythonParser(
+                filename=self.filename,
+                exclude=self.coverage._exclude_regex("exclude"),
+            )
+            self._parser.parse_source()
+        return self._parser
+
+    def lines(self) -> set[TLineNo]:
+        """Return the line numbers of statements in the file."""
+        return self.parser.statements
+
+    def multiline_map(self) -> dict[TLineNo, TLineNo]:
+        """A map of line numbers to first-line in a multi-line statement."""
+        return self.parser.multiline_map
+
+    def excluded_lines(self) -> set[TLineNo]:
+        """Return the line numbers of statements in the file."""
+        return self.parser.excluded
+
+    def translate_lines(self, lines: Iterable[TLineNo]) -> set[TLineNo]:
+        return self.parser.translate_lines(lines)
+
+    def translate_arcs(self, arcs: Iterable[TArc]) -> set[TArc]:
+        return self.parser.translate_arcs(arcs)
+
+    def no_branch_lines(self) -> set[TLineNo]:
+        assert self.coverage is not None
+        no_branch = self.parser.lines_matching(
+            join_regex(self.coverage.config.partial_list + self.coverage.config.partial_always_list)
+        )
+        return no_branch
+
+    def arcs(self) -> set[TArc]:
+        return self.parser.arcs()
+
+    def exit_counts(self) -> dict[TLineNo, int]:
+        return self.parser.exit_counts()
+
+    def missing_arc_description(
+        self,
+        start: TLineNo,
+        end: TLineNo,
+        executed_arcs: Iterable[TArc] | None = None,
+    ) -> str:
+        return self.parser.missing_arc_description(start, end)
+
+    def arc_description(self, start: TLineNo, end: TLineNo) -> str:
+        return self.parser.arc_description(start, end)
+
+    def source(self) -> str:
+        if self._source is None:
+            self._source = get_python_source(self.filename)
+        return self._source
+
+    def should_be_python(self) -> bool:
+        """Does it seem like this file should contain Python?
+
+        This is used to decide if a file reported as part of the execution of
+        a program was really likely to have contained Python in the first
+        place.
+
+        """
+        # Get the file extension.
+        _, ext = os.path.splitext(self.filename)
+
+        # Anything named *.py* should be Python.
+        if ext.startswith(".py"):
+            return True
+        # A file with no extension should be Python.
+        if not ext:
+            return True
+        # Everything else is probably not Python.
+        return False
+
+    def source_token_lines(self) -> TSourceTokenLines:
+        return source_token_lines(self.source())
+
+    def code_regions(self) -> Iterable[CodeRegion]:
+        return code_regions(self.source())
+
+    def code_region_kinds(self) -> Iterable[tuple[str, str]]:
+        return [
+            ("function", "functions"),
+            ("class", "classes"),
+        ]