coverage 7.6.7__cp311-cp311-win_amd64.whl → 7.11.1__cp311-cp311-win_amd64.whl

coverage/control.py

@@ -8,6 +8,7 @@ from __future__ import annotations
 import atexit
 import collections
 import contextlib
+import datetime
 import functools
 import os
 import os.path
@@ -17,20 +18,23 @@ import sys
 import threading
 import time
 import warnings
-
-from types import FrameType
-from typing import cast, Any, Callable, IO
 from collections.abc import Iterable, Iterator
+from types import FrameType
+from typing import IO, Any, Callable, cast
 
 from coverage import env
 from coverage.annotate import AnnotateReporter
 from coverage.collector import Collector
 from coverage.config import CoverageConfig, read_coverage_config
-from coverage.context import should_start_context_test_function, combine_context_switchers
-from coverage.core import Core, HAS_CTRACER
+from coverage.context import combine_context_switchers, should_start_context_test_function
+from coverage.core import CTRACER_FILE, Core
 from coverage.data import CoverageData, combine_parallel_data
 from coverage.debug import (
-    DebugControl, NoDebugging, short_stack, write_formatted_info, relevant_environment_display,
+    DebugControl,
+    NoDebugging,
+    relevant_environment_display,
+    short_stack,
+    write_formatted_info,
 )
 from coverage.disposition import disposition_debug_msg
 from coverage.exceptions import ConfigError, CoverageException, CoverageWarning, PluginError
@@ -39,23 +43,37 @@ from coverage.html import HtmlReporter
 from coverage.inorout import InOrOut
 from coverage.jsonreport import JsonReporter
 from coverage.lcovreport import LcovReporter
-from coverage.misc import bool_or_none, join_regex
-from coverage.misc import DefaultValue, ensure_dir_for_file, isolate_module
+from coverage.misc import (
+    DefaultValue,
+    bool_or_none,
+    ensure_dir_for_file,
+    isolate_module,
+    join_regex,
+)
 from coverage.multiproc import patch_multiprocessing
+from coverage.patch import apply_patches
 from coverage.plugin import FileReporter
-from coverage.plugin_support import Plugins
+from coverage.plugin_support import Plugins, TCoverageInit
 from coverage.python import PythonFileReporter
 from coverage.report import SummaryReporter
 from coverage.report_core import render_report
 from coverage.results import Analysis, analysis_from_file_reporter
 from coverage.types import (
-    FilePath, TConfigurable, TConfigSectionIn, TConfigValueIn, TConfigValueOut,
-    TFileDisposition, TLineNo, TMorf,
+    FilePath,
+    TConfigSectionIn,
+    TConfigurable,
+    TConfigValueIn,
+    TConfigValueOut,
+    TFileDisposition,
+    TLineNo,
+    TMorf,
 )
+from coverage.version import __url__
 from coverage.xmlreport import XmlReporter
 
 os = isolate_module(os)
 
+
 @contextlib.contextmanager
 def override_config(cov: Coverage, **kwargs: TConfigValueIn) -> Iterator[None]:
     """Temporarily tweak the configuration of `cov`.
@@ -74,6 +92,8 @@ def override_config(cov: Coverage, **kwargs: TConfigValueIn) -> Iterator[None]:
 
 DEFAULT_DATAFILE = DefaultValue("MISSING")
 _DEFAULT_DATAFILE = DEFAULT_DATAFILE  # Just in case, for backwards compatibility
+CONFIG_DATA_PREFIX = ":data:"
+
 
 class Coverage(TConfigurable):
     """Programmatic access to coverage.py.
@@ -120,7 +140,7 @@ class Coverage(TConfigurable):
         else:
             return None
 
-    def __init__(                       # pylint: disable=too-many-arguments
+    def __init__(  # pylint: disable=too-many-arguments
         self,
         data_file: FilePath | DefaultValue | None = DEFAULT_DATAFILE,
         data_suffix: str | bool | None = None,
@@ -131,6 +151,7 @@ class Coverage(TConfigurable):
         config_file: FilePath | bool = True,
         source: Iterable[str] | None = None,
         source_pkgs: Iterable[str] | None = None,
+        source_dirs: Iterable[str] | None = None,
         omit: str | Iterable[str] | None = None,
         include: str | Iterable[str] | None = None,
         debug: Iterable[str] | None = None,
@@ -138,6 +159,7 @@ class Coverage(TConfigurable):
         check_preimported: bool = False,
         context: str | None = None,
         messages: bool = False,
+        plugins: Iterable[Callable[..., None]] | None = None,
     ) -> None:
         """
         Many of these arguments duplicate and override values that can be
@@ -187,6 +209,10 @@ class Coverage(TConfigurable):
         `source`, but can be used to name packages where the name can also be
         interpreted as a file path.
 
+        `source_dirs` is a list of file paths. It works the same as
+        `source`, but raises an error if the path doesn't exist, rather
+        than being treated as a package name.
+
         `include` and `omit` are lists of file name patterns. Files that match
         `include` will be measured, files that match `omit` will not.  Each
         will also accept a single string argument.
@@ -211,6 +237,11 @@ class Coverage(TConfigurable):
         If `messages` is true, some messages will be printed to stdout
         indicating what is happening.
 
+        If `plugins` are passed, they are an iterable of function objects
+        accepting a `reg` object to register plugins, as described in
+        :ref:`api_plugin`.  When they are provided, they will override the
+        plugins found in the coverage configuration file.
+
         .. versionadded:: 4.0
             The `concurrency` parameter.
 
@@ -226,6 +257,11 @@ class Coverage(TConfigurable):
         .. versionadded:: 6.0
             The `messages` parameter.
 
+        .. versionadded:: 7.7
+            The `plugins` parameter.
+
+        .. versionadded:: 7.8
+            The `source_dirs` parameter.
         """
         # Start self.config as a usable default configuration. It will soon be
         # replaced with the real configuration.
@@ -249,9 +285,12 @@ class Coverage(TConfigurable):
         self._warn_no_data = True
         self._warn_unimported_source = True
         self._warn_preimported_source = check_preimported
-        self._no_warn_slugs: list[str] = []
+        self._no_warn_slugs: set[str] = set()
         self._messages = messages
 
+        # If we're invoked from a .pth file, we shouldn't try to make another one.
+        self._make_pth_file = True
+
         # A record of all the warnings that have been issued.
         self._warnings: list[str] = []
 
@@ -260,7 +299,9 @@ class Coverage(TConfigurable):
         self._debug: DebugControl = NoDebugging()
         self._inorout: InOrOut | None = None
         self._plugins: Plugins = Plugins()
+        self._plugin_override = cast(Iterable[TCoverageInit] | None, plugins)
         self._data: CoverageData | None = None
+        self._data_to_close: list[CoverageData] = []
         self._core: Core | None = None
         self._collector: Collector | None = None
         self._metacov = False
@@ -280,28 +321,32 @@ class Coverage(TConfigurable):
         self._should_write_debug = True
 
         # Build our configuration from a number of sources.
-        if not isinstance(config_file, bool):
-            config_file = os.fspath(config_file)
-        self.config = read_coverage_config(
-            config_file=config_file,
-            warn=self._warn,
-            data_file=data_file,
-            cover_pylib=cover_pylib,
-            timid=timid,
-            branch=branch,
-            parallel=bool_or_none(data_suffix),
-            source=source,
-            source_pkgs=source_pkgs,
-            run_omit=omit,
-            run_include=include,
-            debug=debug,
-            report_omit=omit,
-            report_include=include,
-            concurrency=concurrency,
-            context=context,
-        )
+        if isinstance(config_file, str) and config_file.startswith(CONFIG_DATA_PREFIX):
+            self.config = CoverageConfig.deserialize(config_file[len(CONFIG_DATA_PREFIX) :])
+        else:
+            if not isinstance(config_file, bool):
+                config_file = os.fspath(config_file)
+            self.config = read_coverage_config(
+                config_file=config_file,
+                warn=self._warn,
+                data_file=data_file,
+                cover_pylib=cover_pylib,
+                timid=timid,
+                branch=branch,
+                parallel=bool_or_none(data_suffix),
+                source=source,
+                source_pkgs=source_pkgs,
+                source_dirs=source_dirs,
+                run_omit=omit,
+                run_include=include,
+                debug=debug,
+                report_omit=omit,
+                report_include=include,
+                concurrency=concurrency,
+                context=context,
+            )
 
-        # If we have sub-process measurement happening automatically, then we
+        # If we have subprocess measurement happening automatically, then we
         # want any explicit creation of a Coverage object to mean, this process
         # is already coverage-aware, so don't auto-measure it.  By now, the
         # auto-creation of a Coverage object has already happened.  But we can
@@ -340,7 +385,11 @@ class Coverage(TConfigurable):
             self._file_mapper = relative_filename
 
         # Load plugins
-        self._plugins = Plugins.load_plugins(self.config.plugins, self.config, self._debug)
+        self._plugins = Plugins(self._debug)
+        if self._plugin_override:
+            self._plugins.load_from_callables(self._plugin_override)
+        else:
+            self._plugins.load_from_config(self.config.plugins, self.config)
 
         # Run configuring plugins.
         for plugin in self._plugins.configurers:
@@ -366,22 +415,24 @@ class Coverage(TConfigurable):
         wrote_any = False
         with self._debug.without_callers():
             if self._debug.should("config"):
-                config_info = self.config.debug_info()
-                write_formatted_info(self._debug.write, "config", config_info)
+                write_formatted_info(self._debug.write, "config", self.config.debug_info())
                 wrote_any = True
 
             if self._debug.should("sys"):
                 write_formatted_info(self._debug.write, "sys", self.sys_info())
                 for plugin in self._plugins:
                     header = "sys: " + plugin._coverage_plugin_name
-                    info = plugin.sys_info()
-                    write_formatted_info(self._debug.write, header, info)
+                    write_formatted_info(self._debug.write, header, plugin.sys_info())
                 wrote_any = True
 
             if self._debug.should("pybehave"):
                 write_formatted_info(self._debug.write, "pybehave", env.debug_info())
                 wrote_any = True
 
+            if self._debug.should("sqlite"):
+                write_formatted_info(self._debug.write, "sqlite", CoverageData.sys_info())
+                wrote_any = True
+
         if wrote_any:
             write_formatted_info(self._debug.write, "end", ())
 
@@ -424,7 +475,7 @@ class Coverage(TConfigurable):
 
         """
         if not self._no_warn_slugs:
-            self._no_warn_slugs = list(self.config.disable_warnings)
+            self._no_warn_slugs = set(self.config.disable_warnings)
 
         if slug in self._no_warn_slugs:
             # Don't issue the warning
@@ -432,14 +483,14 @@ class Coverage(TConfigurable):
 
         self._warnings.append(msg)
         if slug:
-            msg = f"{msg} ({slug})"
+            msg = f"{msg} ({slug}); see {__url__}/messages.html#warning-{slug}"
         if self._debug.should("pid"):
             msg = f"[{os.getpid()}] {msg}"
         warnings.warn(msg, category=CoverageWarning, stacklevel=2)
 
         if once:
             assert slug is not None
-            self._no_warn_slugs.append(slug)
+            self._no_warn_slugs.add(slug)
 
     def _message(self, msg: str) -> None:
         """Write a message to the user, if configured to do so."""
@@ -512,7 +563,7 @@ class Coverage(TConfigurable):
     def _init_for_start(self) -> None:
         """Initialization for start()"""
         # Construct the collector.
-        concurrency: list[str] = self.config.concurrency or []
+        concurrency: list[str] = self.config.concurrency
         if "multiprocessing" in concurrency:
             if self.config.config_file is None:
                 raise ConfigError("multiprocessing requires a configuration file")
@@ -534,7 +585,9 @@ class Coverage(TConfigurable):
 
         self._core = Core(
             warn=self._warn,
-            timid=self.config.timid,
+            debug=(self._debug if self._debug.should("core") else None),
+            config=self.config,
+            dynamic_contexts=(should_start_context is not None),
             metacov=self._metacov,
         )
         self._collector = Collector(
@@ -571,8 +624,7 @@ class Coverage(TConfigurable):
             self._warn(
                 "Plugin file tracers ({}) aren't supported with {}".format(
                     ", ".join(
-                        plugin._coverage_plugin_name
-                            for plugin in self._plugins.file_tracers
+                        plugin._coverage_plugin_name for plugin in self._plugins.file_tracers
                     ),
                     self._collector.tracer_name(),
                 ),
@@ -596,13 +648,14 @@ class Coverage(TConfigurable):
         # Register our clean-up handlers.
         atexit.register(self._atexit)
         if self.config.sigterm:
-            is_main = (threading.current_thread() == threading.main_thread())
+            is_main = (threading.current_thread() == threading.main_thread())  # fmt: skip
             if is_main and not env.WINDOWS:
                 # The Python docs seem to imply that SIGTERM works uniformly even
                 # on Windows, but that's not my experience, and this agrees:
                 # https://stackoverflow.com/questions/35772001/x/35792192#35792192
-                self._old_sigterm = signal.signal(      # type: ignore[assignment]
-                    signal.SIGTERM, self._on_sigterm,
+                self._old_sigterm = signal.signal(  # type: ignore[assignment]
+                    signal.SIGTERM,
+                    self._on_sigterm,
                 )
 
     def _init_data(self, suffix: str | bool | None) -> None:
@@ -619,6 +672,7 @@ class Coverage(TConfigurable):
                 debug=self._debug,
                 no_disk=self._no_disk,
             )
+            self._data_to_close.append(self._data)
 
     def start(self) -> None:
         """Start measuring code coverage.
@@ -654,6 +708,8 @@ class Coverage(TConfigurable):
         if self._auto_load:
             self.load()
 
+        apply_patches(self, self.config, self._debug, make_pth_file=self._make_pth_file)
+
         self._collector.start()
         self._started = True
         self._instances.append(self)
@@ -679,7 +735,7 @@ class Coverage(TConfigurable):
         try:
             yield
         finally:
-            self.stop()     # pragma: nested
+            self.stop()  # pragma: nested
 
     def _atexit(self, event: str = "atexit") -> None:
         """Clean up on process shutdown."""
@@ -689,14 +745,16 @@ class Coverage(TConfigurable):
             self.stop()
         if self._auto_save or event == "sigterm":
             self.save()
+        for d in self._data_to_close:
+            d.close(force=True)
 
     def _on_sigterm(self, signum_unused: int, frame_unused: FrameType | None) -> None:
         """A handler for signal.SIGTERM."""
         self._atexit("sigterm")
         # Statements after here won't be seen by metacov because we just wrote
         # the data, and are about to kill the process.
-        signal.signal(signal.SIGTERM, self._old_sigterm)    # pragma: not covered
-        os.kill(os.getpid(), signal.SIGTERM)                # pragma: not covered
+        signal.signal(signal.SIGTERM, self._old_sigterm)  # pragma: not covered
+        os.kill(os.getpid(), signal.SIGTERM)  # pragma: not covered
 
     def erase(self) -> None:
         """Erase previously collected coverage data.
@@ -728,7 +786,7 @@ class Coverage(TConfigurable):
         .. versionadded:: 5.0
 
         """
-        if not self._started:                           # pragma: part started
+        if not self._started:  # pragma: part started
             raise CoverageException("Cannot switch context, coverage is not started")
 
         assert self._collector is not None
@@ -740,7 +798,7 @@ class Coverage(TConfigurable):
     def clear_exclude(self, which: str = "exclude") -> None:
         """Clear the exclude list."""
         self._init()
-        setattr(self.config, which + "_list", [])
+        setattr(self.config, f"{which}_list", [])
         self._exclude_regex_stale()
 
     def exclude(self, regex: str, which: str = "exclude") -> None:
@@ -759,7 +817,7 @@ class Coverage(TConfigurable):
 
         """
         self._init()
-        excl_list = getattr(self.config, which + "_list")
+        excl_list = getattr(self.config, f"{which}_list")
         excl_list.append(regex)
         self._exclude_regex_stale()
 
@@ -770,7 +828,7 @@ class Coverage(TConfigurable):
     def _exclude_regex(self, which: str) -> str:
         """Return a regex string for the given exclusion list."""
         if which not in self._exclude_re:
-            excl_list = getattr(self.config, which + "_list")
+            excl_list = getattr(self.config, f"{which}_list")
             self._exclude_re[which] = join_regex(excl_list)
         return self._exclude_re[which]
 
@@ -782,7 +840,7 @@ class Coverage(TConfigurable):
 
         """
         self._init()
-        return cast(list[str], getattr(self.config, which + "_list"))
+        return cast(list[str], getattr(self.config, f"{which}_list"))
 
     def save(self) -> None:
         """Save the collected coverage data to the data file."""
@@ -935,6 +993,7 @@ class Coverage(TConfigurable):
             analysis.missing_formatted(),
         )
 
+    @functools.lru_cache(maxsize=1)
     def _analyze(self, morf: TMorf) -> Analysis:
         """Analyze a module or file.  Private for now."""
         self._init()
@@ -945,6 +1004,20 @@ class Coverage(TConfigurable):
         filename = self._file_mapper(file_reporter.filename)
         return analysis_from_file_reporter(data, self.config.precision, file_reporter, filename)
 
+    def branch_stats(self, morf: TMorf) -> dict[TLineNo, tuple[int, int]]:
+        """Get branch statistics about a module.
+
+        `morf` is a module or a file name.
+
+        Returns a dict mapping line numbers to a tuple:
+        (total_exits, taken_exits).
+
+        .. versionadded:: 7.7
+
+        """
+        analysis = self._analyze(morf)
+        return analysis.branch_stats()
+
     @functools.lru_cache(maxsize=1)
     def _get_file_reporter(self, morf: TMorf) -> FileReporter:
         """Get a FileReporter for a module or file name."""
@@ -963,7 +1036,8 @@ class Coverage(TConfigurable):
                     if file_reporter is None:
                         raise PluginError(
                             "Plugin {!r} did not provide a file reporter for {!r}.".format(
-                                plugin._coverage_plugin_name, morf,
+                                plugin._coverage_plugin_name,
+                                morf,
                             ),
                         )
 
@@ -993,8 +1067,9 @@ class Coverage(TConfigurable):
 
         # Be sure we have a collection.
         if not isinstance(morfs, (list, tuple, set)):
-            morfs = [morfs]     # type: ignore[list-item]
+            morfs = [morfs]  # type: ignore[list-item]
 
+        morfs = sorted(morfs, key=lambda m: m if isinstance(m, str) else m.__name__)
         return [(self._get_file_reporter(morf), morf) for morf in morfs]
 
     def _prepare_data_for_reporting(self) -> None:
@@ -1004,6 +1079,7 @@ class Coverage(TConfigurable):
             if self._data is not None:
                 mapped_data.update(self._data, map_path=self._make_aliases().map)
             self._data = mapped_data
+            self._data_to_close.append(mapped_data)
 
     def report(
         self,
@@ -1172,8 +1248,7 @@ class Coverage(TConfigurable):
             precision=precision,
         ):
             reporter = HtmlReporter(self)
-            ret = reporter.report(morfs)
-            return ret
+            return reporter.report(morfs)
 
     def xml_report(
         self,
@@ -1298,21 +1373,23 @@ class Coverage(TConfigurable):
             ("coverage_version", covmod.__version__),
             ("coverage_module", covmod.__file__),
             ("core", self._collector.tracer_name() if self._collector is not None else "-none-"),
-            ("CTracer", "available" if HAS_CTRACER else "unavailable"),
+            ("CTracer", f"available from {CTRACER_FILE}" if CTRACER_FILE else "unavailable"),
             ("plugins.file_tracers", plugin_info(self._plugins.file_tracers)),
             ("plugins.configurers", plugin_info(self._plugins.configurers)),
             ("plugins.context_switchers", plugin_info(self._plugins.context_switchers)),
             ("configs_attempted", self.config.config_files_attempted),
             ("configs_read", self.config.config_files_read),
             ("config_file", self.config.config_file),
-            ("config_contents",
+            (
+                "config_contents",
                 repr(self.config._config_contents) if self.config._config_contents else "-none-",
             ),
             ("data_file", self._data.data_filename() if self._data is not None else "-none-"),
             ("python", sys.version.replace("\n", "")),
             ("platform", platform.platform()),
             ("implementation", platform.python_implementation()),
-            ("gil_enabled", getattr(sys, '_is_gil_enabled', lambda: True)()),
+            ("build", platform.python_build()),
+            ("gil_enabled", getattr(sys, "_is_gil_enabled", lambda: True)()),
             ("executable", sys.executable),
             ("def_encoding", sys.getdefaultencoding()),
             ("fs_encoding", sys.getfilesystemencoding()),
@@ -1321,52 +1398,46 @@ class Coverage(TConfigurable):
             ("path", sys.path),
             ("environment", [f"{k} = {v}" for k, v in relevant_environment_display(os.environ)]),
             ("command_line", " ".join(getattr(sys, "argv", ["-none-"]))),
+            ("time", f"{datetime.datetime.now():%Y-%m-%d %H:%M:%S}"),
         ]
 
         if self._inorout is not None:
             info.extend(self._inorout.sys_info())
 
-        info.extend(CoverageData.sys_info())
-
         return info
 
 
 # Mega debugging...
 # $set_env.py: COVERAGE_DEBUG_CALLS - Lots and lots of output about calls to Coverage.
-if int(os.getenv("COVERAGE_DEBUG_CALLS", 0)):               # pragma: debugging
+if int(os.getenv("COVERAGE_DEBUG_CALLS", 0)):  # pragma: debugging
     from coverage.debug import decorate_methods, show_calls
 
-    Coverage = decorate_methods(        # type: ignore[misc]
+    Coverage = decorate_methods(  # type: ignore[misc]
         show_calls(show_args=True),
         butnot=["get_data"],
     )(Coverage)
 
 
-def process_startup() -> Coverage | None:
+def process_startup(*, force: bool = False) -> Coverage | None:
     """Call this at Python start-up to perhaps measure coverage.
 
     If the environment variable COVERAGE_PROCESS_START is defined, coverage
     measurement is started.  The value of the variable is the config file
     to use.
 
-    There are two ways to configure your Python installation to invoke this
-    function when Python starts:
-
-    #. Create or append to sitecustomize.py to add these lines::
-
-        import coverage
-        coverage.process_startup()
-
-    #. Create a .pth file in your Python installation containing::
-
-        import coverage; coverage.process_startup()
+    For details, see https://coverage.readthedocs.io/en/latest/subprocess.html.
 
     Returns the :class:`Coverage` instance that was started, or None if it was
     not started by this call.
 
     """
+    config_data = os.getenv("COVERAGE_PROCESS_CONFIG")
     cps = os.getenv("COVERAGE_PROCESS_START")
-    if not cps:
+    if config_data is not None:
+        config_file = CONFIG_DATA_PREFIX + config_data
+    elif cps is not None:
+        config_file = cps
+    else:
         # No request for coverage, nothing to do.
         return None
 
@@ -1379,22 +1450,30 @@ def process_startup() -> Coverage | None:
     #
     # https://github.com/nedbat/coveragepy/issues/340 has more details.
 
-    if hasattr(process_startup, "coverage"):
+    if not force and hasattr(process_startup, "coverage"):
         # We've annotated this function before, so we must have already
-        # started coverage.py in this process.  Nothing to do.
+        # auto-started coverage.py in this process.  Nothing to do.
         return None
 
-    cov = Coverage(config_file=cps)
-    process_startup.coverage = cov      # type: ignore[attr-defined]
+    cov = Coverage(config_file=config_file)
+    process_startup.coverage = cov  # type: ignore[attr-defined]
     cov._warn_no_data = False
     cov._warn_unimported_source = False
     cov._warn_preimported_source = False
     cov._auto_save = True
+    cov._make_pth_file = False
     cov.start()
 
     return cov
 
 
+def _after_fork_in_child() -> None:
+    """Used by patch=fork in the child process to restart coverage."""
+    if cov := Coverage.current():
+        cov.stop()
+    process_startup(force=True)
+
+
 def _prevent_sub_process_measurement() -> None:
     """Stop any subprocess auto-measurement from writing data."""
     auto_created_coverage = getattr(process_startup, "coverage", None)