coverage 7.13.1__cp313-cp313-musllinux_1_2_riscv64.whl

coverage/misc.py

@@ -0,0 +1,381 @@
+# Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
+# For details: https://github.com/coveragepy/coveragepy/blob/main/NOTICE.txt
+
+"""Miscellaneous stuff for coverage.py."""
+
+from __future__ import annotations
+
+import contextlib
+import datetime
+import errno
+import functools
+import hashlib
+import importlib
+import importlib.util
+import inspect
+import os
+import os.path
+import re
+import sys
+import types
+from collections.abc import Iterable, Iterator, Mapping, Sequence
+from types import ModuleType
+from typing import Any, NoReturn, TypeVar
+
+# In 6.0, the exceptions moved from misc.py to exceptions.py.  But a number of
+# other packages were importing the exceptions from misc, so import them here.
+# pylint: disable=unused-wildcard-import
+from coverage.exceptions import *  # pylint: disable=wildcard-import
+from coverage.exceptions import CoverageException
+from coverage.types import TArc
+
+ISOLATED_MODULES: dict[ModuleType, ModuleType] = {}
+
+
+def isolate_module(mod: ModuleType) -> ModuleType:
+    """Copy a module so that we are isolated from aggressive mocking.
+
+    If a test suite mocks os.path.exists (for example), and then we need to use
+    it during the test, everything will get tangled up if we use their mock.
+    Making a copy of the module when we import it will isolate coverage.py from
+    those complications.
+    """
+    if mod not in ISOLATED_MODULES:
+        new_mod = types.ModuleType(mod.__name__)
+        ISOLATED_MODULES[mod] = new_mod
+        for name in dir(mod):
+            value = getattr(mod, name)
+            if isinstance(value, types.ModuleType):
+                value = isolate_module(value)
+            setattr(new_mod, name, value)
+    return ISOLATED_MODULES[mod]
+
+
+os = isolate_module(os)
+
+
+class SysModuleSaver:
+    """Saves the contents of sys.modules, and removes new modules later."""
+
+    def __init__(self) -> None:
+        self.old_modules = set(sys.modules)
+
+    def restore(self) -> None:
+        """Remove any modules imported since this object started."""
+        new_modules = set(sys.modules) - self.old_modules
+        for m in new_modules:
+            del sys.modules[m]
+
+
+@contextlib.contextmanager
+def sys_modules_saved() -> Iterator[None]:
+    """A context manager to remove any modules imported during a block."""
+    saver = SysModuleSaver()
+    try:
+        yield
+    finally:
+        saver.restore()
+
+
+def import_third_party(modname: str) -> tuple[ModuleType, bool]:
+    """Import a third-party module we need, but might not be installed.
+
+    This also cleans out the module after the import, so that coverage won't
+    appear to have imported it.  This lets the third party use coverage for
+    their own tests.
+
+    Arguments:
+        modname (str): the name of the module to import.
+
+    Returns:
+        The imported module, and a boolean indicating if the module could be imported.
+
+    If the boolean is False, the module returned is not the one you want: don't use it.
+
+    """
+    with sys_modules_saved():
+        try:
+            return importlib.import_module(modname), True
+        except ImportError:
+            return sys, False
+
+
+def nice_pair(pair: TArc) -> str:
+    """Make a nice string representation of a pair of numbers.
+
+    If the numbers are equal, just return the number, otherwise return the pair
+    with a dash between them, indicating the range.
+
+    """
+    start, end = pair
+    if start == end:
+        return f"{start}"
+    else:
+        return f"{start}-{end}"
+
+
+def bool_or_none(b: Any) -> bool | None:
+    """Return bool(b), but preserve None."""
+    if b is None:
+        return None
+    else:
+        return bool(b)
+
+
+def join_regex(regexes: Iterable[str]) -> str:
+    """Combine a series of regex strings into one that matches any of them."""
+    regexes = list(regexes)
+    if len(regexes) == 1:
+        return regexes[0]
+    else:
+        return "|".join(f"(?:{r})" for r in regexes)
+
+
+def file_be_gone(path: str) -> None:
+    """Remove a file, and don't get annoyed if it doesn't exist."""
+    try:
+        os.remove(path)
+    except OSError as e:
+        if e.errno != errno.ENOENT:
+            raise
+
+
+def ensure_dir(directory: str) -> None:
+    """Make sure the directory exists.
+
+    If `directory` is None or empty, do nothing.
+    """
+    if directory:
+        os.makedirs(directory, exist_ok=True)
+
+
+def ensure_dir_for_file(path: str) -> None:
+    """Make sure the directory for the path exists."""
+    ensure_dir(os.path.dirname(path))
+
+
+class Hasher:
+    """Hashes Python data for fingerprinting."""
+
+    def __init__(self) -> None:
+        self.hash = hashlib.new("sha3_256", usedforsecurity=False)
+
+    def update(self, v: Any) -> None:
+        """Add `v` to the hash, recursively if needed."""
+        self.hash.update(str(type(v)).encode("utf-8"))
+        match v:
+            case None:
+                pass
+            case str():
+                self.hash.update(f"{len(v)}:".encode("utf-8"))
+                self.hash.update(v.encode("utf-8"))
+            case bytes():
+                self.hash.update(f"{len(v)}:".encode("utf-8"))
+                self.hash.update(v)
+            case int() | float():
+                self.hash.update(str(v).encode("utf-8"))
+            case tuple() | list():
+                for e in v:
+                    self.update(e)
+            case dict():
+                for k, kv in sorted(v.items()):
+                    self.update(k)
+                    self.update(kv)
+            case set():
+                for e in sorted(v):
+                    self.update(e)
+            case _:
+                for k in dir(v):
+                    if k.startswith("__"):
+                        continue
+                    a = getattr(v, k)
+                    if inspect.isroutine(a):
+                        continue
+                    self.update(k)
+                    self.update(a)
+        self.hash.update(b".")
+
+    def digest(self) -> bytes:
+        """Get the full binary digest of the hash."""
+        return self.hash.digest()
+
+    def hexdigest(self) -> str:
+        """Retrieve a 32-char hex digest of the hash."""
+        return self.hash.hexdigest()[:32]
+
+
+def _needs_to_implement(that: Any, func_name: str) -> NoReturn:
+    """Helper to raise NotImplementedError in interface stubs."""
+    if hasattr(that, "_coverage_plugin_name"):
+        thing = "Plugin"
+        name = that._coverage_plugin_name
+    else:
+        thing = "Class"
+        klass = that.__class__
+        name = f"{klass.__module__}.{klass.__name__}"
+
+    raise NotImplementedError(
+        f"{thing} {name!r} needs to implement {func_name}()",
+    )
+
+
+class DefaultValue:
+    """A sentinel object to use for unusual default-value needs.
+
+    Construct with a string that will be used as the repr, for display in help
+    and Sphinx output.
+
+    """
+
+    def __init__(self, display_as: str) -> None:
+        self.display_as = display_as
+
+    def __repr__(self) -> str:
+        return self.display_as
+
+
+def substitute_variables(text: str, variables: Mapping[str, str]) -> str:
+    """Substitute ``${VAR}`` variables in `text` with their values.
+
+    Variables in the text can take a number of shell-inspired forms::
+
+        $VAR
+        ${VAR}
+        ${VAR?}             strict: an error if VAR isn't defined.
+        ${VAR-missing}      defaulted: "missing" if VAR isn't defined.
+        $$                  just a dollar sign.
+
+    `variables` is a dictionary of variable values.
+
+    Returns the resulting text with values substituted.
+
+    """
+    dollar_pattern = r"""(?x)   # Use extended regex syntax
+        \$                      # A dollar sign,
+        (?:                     # then
+            (?P<dollar> \$ ) |      # a dollar sign, or
+            (?P<word1> \w+ ) |      # a plain word, or
+            \{                      # a {-wrapped
+                (?P<word2> \w+ )        # word,
+                (?:                         # either
+                    (?P<strict> \? ) |      # with a strict marker
+                    -(?P<defval> [^}]* )    # or a default value
+                )?                      # maybe.
+            }
+        )
+        """
+
+    dollar_groups = ("dollar", "word1", "word2")
+
+    def dollar_replace(match: re.Match[str]) -> str:
+        """Called for each $replacement."""
+        # Only one of the dollar_groups will have matched, just get its text.
+        word = next(g for g in match.group(*dollar_groups) if g)  # pragma: always breaks
+        if word == "$":
+            return "$"
+        elif word in variables:
+            return variables[word]
+        elif match["strict"]:
+            msg = f"Variable {word} is undefined: {text!r}"
+            raise CoverageException(msg)
+        else:
+            return match["defval"]
+
+    text = re.sub(dollar_pattern, dollar_replace, text)
+    return text
+
+
+def format_local_datetime(dt: datetime.datetime) -> str:
+    """Return a string with local timezone representing the date."""
+    return dt.astimezone().strftime("%Y-%m-%d %H:%M %z")
+
+
+def import_local_file(modname: str, modfile: str | None = None) -> ModuleType:
+    """Import a local file as a module.
+
+    Opens a file in the current directory named `modname`.py, imports it
+    as `modname`, and returns the module object.  `modfile` is the file to
+    import if it isn't in the current directory.
+
+    """
+    if modfile is None:
+        modfile = modname + ".py"
+    spec = importlib.util.spec_from_file_location(modname, modfile)
+    assert spec is not None
+    mod = importlib.util.module_from_spec(spec)
+    sys.modules[modname] = mod
+    assert spec.loader is not None
+    spec.loader.exec_module(mod)
+
+    return mod
+
+
+@functools.cache
+def _human_key(s: str) -> tuple[list[str | int], str]:
+    """Turn a string into a list of string and number chunks.
+
+    "z23a" -> (["z", 23, "a"], "z23a")
+
+    The original string is appended as a last value to ensure the
+    key is unique enough so that "x1y" and "x001y" can be distinguished.
+    """
+
+    def tryint(s: str) -> str | int:
+        """If `s` is a number, return an int, else `s` unchanged."""
+        try:
+            return int(s)
+        except ValueError:
+            return s
+
+    return ([tryint(c) for c in re.split(r"(\d+)", s)], s)
+
+
+def human_sorted(strings: Iterable[str]) -> list[str]:
+    """Sort the given iterable of strings the way that humans expect.
+
+    Numeric components in the strings are sorted as numbers.
+
+    Returns the sorted list.
+
+    """
+    return sorted(strings, key=_human_key)
+
+
+SortableItem = TypeVar("SortableItem", bound=Sequence[Any])
+
+
+def human_sorted_items(
+    items: Iterable[SortableItem],
+    reverse: bool = False,
+) -> list[SortableItem]:
+    """Sort (string, ...) items the way humans expect.
+
+    The elements of `items` can be any tuple/list. They'll be sorted by the
+    first element (a string), with ties broken by the remaining elements.
+
+    Returns the sorted list of items.
+    """
+    return sorted(items, key=lambda item: (_human_key(item[0]), *item[1:]), reverse=reverse)
+
+
+def plural(n: int, thing: str = "", things: str = "") -> str:
+    """Pluralize a word.
+
+    If n is 1, return thing.  Otherwise return things, or thing+s.
+    """
+    if n == 1:
+        return thing
+    else:
+        return things or (thing + "s")
+
+
+def stdout_link(text: str, url: str) -> str:
+    """Format text+url as a clickable link for stdout.
+
+    If attached to a terminal, use escape sequences. Otherwise, just return
+    the text.
+    """
+    if hasattr(sys.stdout, "isatty") and sys.stdout.isatty():
+        return f"\033]8;;{url}\a{text}\033]8;;\a"
+    else:
+        return text

coverage/multiproc.py

@@ -0,0 +1,120 @@
+# Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
+# For details: https://github.com/coveragepy/coveragepy/blob/main/NOTICE.txt
+
+"""Monkey-patching to add multiprocessing support for coverage.py"""
+
+from __future__ import annotations
+
+import multiprocessing
+import multiprocessing.process
+import os
+import os.path
+import sys
+import traceback
+from typing import Any
+
+from coverage.debug import DebugControl
+
+# An attribute that will be set on the module to indicate that it has been
+# monkey-patched.
+PATCHED_MARKER = "_coverage$patched"
+
+
+OriginalProcess = multiprocessing.process.BaseProcess
+original_bootstrap = OriginalProcess._bootstrap  # type: ignore[attr-defined]
+
+
+class ProcessWithCoverage(OriginalProcess):  # pylint: disable=abstract-method
+    """A replacement for multiprocess.Process that starts coverage."""
+
+    def _bootstrap(self, *args, **kwargs):  # type: ignore[no-untyped-def]
+        """Wrapper around _bootstrap to start coverage."""
+        debug: DebugControl | None = None
+        try:
+            from coverage import Coverage  # avoid circular import
+
+            cov = Coverage(data_suffix=True, auto_data=True)
+            cov._warn_preimported_source = False
+            cov.start()
+            _debug = cov._debug
+            assert _debug is not None
+            if _debug.should("multiproc"):
+                debug = _debug
+            if debug:
+                debug.write("Calling multiprocessing bootstrap")
+        except Exception:
+            print("Exception during multiprocessing bootstrap init:", file=sys.stderr)
+            traceback.print_exc(file=sys.stderr)
+            sys.stderr.flush()
+            raise
+        try:
+            return original_bootstrap(self, *args, **kwargs)
+        finally:
+            if debug:
+                debug.write("Finished multiprocessing bootstrap")
+            try:
+                cov.stop()
+                cov.save()
+            except Exception as exc:
+                if debug:
+                    debug.write("Exception during multiprocessing bootstrap cleanup", exc=exc)
+                raise
+            if debug:
+                debug.write("Saved multiprocessing data")
+
+
+class Stowaway:
+    """An object to pickle, so when it is unpickled, it can apply the monkey-patch."""
+
+    def __init__(self, rcfile: str) -> None:
+        self.rcfile = rcfile
+
+    def __getstate__(self) -> dict[str, str]:
+        return {"rcfile": self.rcfile}
+
+    def __setstate__(self, state: dict[str, str]) -> None:
+        patch_multiprocessing(state["rcfile"])
+
+
+def patch_multiprocessing(rcfile: str) -> None:
+    """Monkey-patch the multiprocessing module.
+
+    This enables coverage measurement of processes started by multiprocessing.
+    This involves aggressive monkey-patching.
+
+    `rcfile` is the path to the rcfile being used.
+
+    """
+
+    if hasattr(multiprocessing, PATCHED_MARKER):
+        return
+
+    OriginalProcess._bootstrap = ProcessWithCoverage._bootstrap  # type: ignore[attr-defined]
+
+    # Set the value in ProcessWithCoverage that will be pickled into the child
+    # process.
+    os.environ["COVERAGE_RCFILE"] = os.path.abspath(rcfile)
+
+    # When spawning processes rather than forking them, we have no state in the
+    # new process.  We sneak in there with a Stowaway: we stuff one of our own
+    # objects into the data that gets pickled and sent to the subprocess. When
+    # the Stowaway is unpickled, its __setstate__ method is called, which
+    # re-applies the monkey-patch.
+    # Windows only spawns, so this is needed to keep Windows working.
+    try:
+        from multiprocessing import spawn
+
+        original_get_preparation_data = spawn.get_preparation_data
+    except (ImportError, AttributeError):
+        pass
+    else:
+
+        def get_preparation_data_with_stowaway(name: str) -> dict[str, Any]:
+            """Get the original preparation data, and also insert our stowaway."""
+            d = original_get_preparation_data(name)
+            d["stowaway"] = Stowaway(rcfile)
+            return d
+
+        spawn.get_preparation_data = get_preparation_data_with_stowaway
+
+    setattr(multiprocessing, PATCHED_MARKER, True)

coverage/numbits.py

@@ -0,0 +1,146 @@
+# Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
+# For details: https://github.com/coveragepy/coveragepy/blob/main/NOTICE.txt
+
+"""
+Functions to manipulate packed binary representations of number sets.
+
+To save space, coverage stores sets of line numbers in SQLite using a packed
+binary representation called a numbits.  A numbits is a set of positive
+integers.
+
+A numbits is stored as a blob in the database.  The exact meaning of the bytes
+in the blobs should be considered an implementation detail that might change in
+the future.  Use these functions to work with those binary blobs of data.
+
+"""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+from collections.abc import Iterable
+from itertools import zip_longest
+
+
+def nums_to_numbits(nums: Iterable[int]) -> bytes:
+    """Convert `nums` into a numbits.
+
+    Arguments:
+        nums: a reusable iterable of integers, the line numbers to store.
+
+    Returns:
+        A binary blob.
+    """
+    try:
+        nbytes = max(nums) // 8 + 1
+    except ValueError:
+        # nums was empty.
+        return b""
+    b = bytearray(nbytes)
+    for num in nums:
+        b[num // 8] |= 1 << num % 8
+    return bytes(b)
+
+
+def numbits_to_nums(numbits: bytes) -> list[int]:
+    """Convert a numbits into a list of numbers.
+
+    Arguments:
+        numbits: a binary blob, the packed number set.
+
+    Returns:
+        A list of ints.
+
+    When registered as a SQLite function by :func:`register_sqlite_functions`,
+    this returns a string, a JSON-encoded list of ints.
+
+    """
+    nums = []
+    for byte_i, byte in enumerate(numbits):
+        for bit_i in range(8):
+            if byte & (1 << bit_i):
+                nums.append(byte_i * 8 + bit_i)
+    return nums
+
+
+def numbits_union(numbits1: bytes, numbits2: bytes) -> bytes:
+    """Compute the union of two numbits.
+
+    Returns:
+        A new numbits, the union of `numbits1` and `numbits2`.
+    """
+    byte_pairs = zip_longest(numbits1, numbits2, fillvalue=0)
+    return bytes(b1 | b2 for b1, b2 in byte_pairs)
+
+
+def numbits_intersection(numbits1: bytes, numbits2: bytes) -> bytes:
+    """Compute the intersection of two numbits.
+
+    Returns:
+        A new numbits, the intersection `numbits1` and `numbits2`.
+    """
+    byte_pairs = zip_longest(numbits1, numbits2, fillvalue=0)
+    intersection_bytes = bytes(b1 & b2 for b1, b2 in byte_pairs)
+    return intersection_bytes.rstrip(b"\0")
+
+
+def numbits_any_intersection(numbits1: bytes, numbits2: bytes) -> bool:
+    """Is there any number that appears in both numbits?
+
+    Determine whether two number sets have a non-empty intersection. This is
+    faster than computing the intersection.
+
+    Returns:
+        A bool, True if there is any number in both `numbits1` and `numbits2`.
+    """
+    byte_pairs = zip_longest(numbits1, numbits2, fillvalue=0)
+    return any(b1 & b2 for b1, b2 in byte_pairs)
+
+
+def num_in_numbits(num: int, numbits: bytes) -> bool:
+    """Does the integer `num` appear in `numbits`?
+
+    Returns:
+        A bool, True if `num` is a member of `numbits`.
+    """
+    nbyte, nbit = divmod(num, 8)
+    if nbyte >= len(numbits):
+        return False
+    return bool(numbits[nbyte] & (1 << nbit))
+
+
+def register_sqlite_functions(connection: sqlite3.Connection) -> None:
+    """
+    Define numbits functions in a SQLite connection.
+
+    This defines these functions for use in SQLite statements:
+
+    * :func:`numbits_union`
+    * :func:`numbits_intersection`
+    * :func:`numbits_any_intersection`
+    * :func:`num_in_numbits`
+    * :func:`numbits_to_nums`
+
+    `connection` is a :class:`sqlite3.Connection <python:sqlite3.Connection>`
+    object.  After creating the connection, pass it to this function to
+    register the numbits functions.  Then you can use numbits functions in your
+    queries::
+
+        import sqlite3
+        from coverage.numbits import register_sqlite_functions
+
+        conn = sqlite3.connect("example.db")
+        register_sqlite_functions(conn)
+        c = conn.cursor()
+        # Kind of a nonsense query:
+        # Find all the files and contexts that executed line 47 in any file:
+        c.execute(
+            "select file_id, context_id from line_bits where num_in_numbits(?, numbits)",
+            (47,)
+        )
+    """
+    connection.create_function("numbits_union", 2, numbits_union)
+    connection.create_function("numbits_intersection", 2, numbits_intersection)
+    connection.create_function("numbits_any_intersection", 2, numbits_any_intersection)
+    connection.create_function("num_in_numbits", 2, num_in_numbits)
+    connection.create_function("numbits_to_nums", 1, lambda b: json.dumps(numbits_to_nums(b)))