coverage-flashlight 1.0.0__py3-none-any.whl

coverage_flashlight/trace.py

@@ -0,0 +1,353 @@
+"""Record ordered Python execution for isolated pytest cases, including workers.
+
+No tracing is installed by importing this module. The runner adds an opt-in
+sitecustomize to its children's PYTHONPATH; the installed environment is untouched.
+
+PYTEST_DONT_REWRITE: this module is also loaded before pytest in child processes.
+"""
+
+from __future__ import annotations
+
+import atexit
+import json
+import os
+import sys
+import threading
+import time
+import uuid
+from pathlib import Path
+
+from coverage_flashlight.config import Sources
+
+KINDS = ("call", "line", "return", "exception")
+_recorder = None
+
+
+class Recorder:
+    def __init__(
+        self,
+        root: Path,
+        directory: Path,
+        limit: int,
+        *,
+        active: bool,
+        sources: Sources | None = None,
+        role: str | None = None,
+    ):
+        self.root = root.resolve()
+        self.selection = sources or Sources(self.root, ["."])
+        self.limit = limit
+        self.active = active
+        self.closed = False
+        self.count = 0
+        self.truncated = False
+        self.capture_error = None
+        self.lock = threading.RLock()
+        self.paths = {}
+        self.locations = {}
+        self.threads = {}
+        self.sources = set()
+        self.buffer = []
+        directory.mkdir(parents=True, exist_ok=True)
+        self.file = (directory / f"{os.getpid()}-{uuid.uuid4().hex[:8]}.jsonl").open(
+            "x", encoding="utf-8"
+        )
+        self.write(
+            {
+                "type": "process",
+                "pid": os.getpid(),
+                "parent": os.getppid(),
+                "role": role or ("child" if active else "test"),
+            }
+        )
+
+    def write(self, value):
+        try:
+            self.file.write(json.dumps(value, separators=(",", ":")) + "\n")
+        except OSError as error:
+            self.capture_error = str(error)
+            self.active = False
+
+    def start(self):
+        if sys.gettrace() is not None or threading.gettrace() is not None:
+            raise RuntimeError(
+                "Execution recording cannot share a tracer with coverage or a debugger"
+            )
+        threading.settrace(self.trace)
+        sys.settrace(self.trace)
+
+    def trace(self, frame, event, _arg):
+        try:
+            return self._trace(frame, event)
+        except (OSError, UnicodeError) as error:
+            # A diagnostic capture must not turn a source/logging I/O failure
+            # into an exception in the application's currently executing line.
+            self.capture_error = str(error)
+            self.active = False
+            return None
+
+    def _trace(self, frame, event):
+        if self.closed or not self.active or self.truncated or self.capture_error:
+            return None
+        filename = frame.f_code.co_filename
+        if filename not in self.paths:
+            self.paths[filename] = self.selection.name(filename)
+        path = self.paths[filename]
+        if path is None:
+            return None
+        if event not in KINDS:
+            return self.trace
+        timestamp = time.perf_counter_ns()
+        with self.lock:
+            if self.closed:
+                return None
+            if self.count >= self.limit:
+                self.truncated = True
+                self.flush()
+                self.write({"type": "truncated", "limit": self.limit})
+                self.file.flush()
+                return None
+            if path not in self.sources:
+                self.sources.add(path)
+                self.write(
+                    {
+                        "type": "source",
+                        "path": path,
+                        # Keep the actual platform's path type when tests mock os.name.
+                        "text": type(self.root)(filename).read_text(encoding="utf-8"),
+                    }
+                )
+            key = (path, frame.f_lineno, frame.f_code.co_qualname)
+            if key not in self.locations:
+                self.locations[key] = len(self.locations)
+                self.write(
+                    {"type": "location", "id": self.locations[key], "value": key}
+                )
+            # Thread objects, rather than OS IDs, distinguish reused thread IDs.
+            thread = threading.current_thread()
+            if thread not in self.threads:
+                self.threads[thread] = len(self.threads)
+                self.write(
+                    {"type": "thread", "id": self.threads[thread], "name": thread.name}
+                )
+            self.buffer.append(
+                [
+                    timestamp,
+                    self.threads[thread],
+                    KINDS.index(event),
+                    self.locations[key],
+                ]
+            )
+            self.count += 1
+            if len(self.buffer) >= 256:
+                self.flush()
+        return self.trace
+
+    def flush(self):
+        if self.buffer:
+            self.write({"type": "events", "values": self.buffer})
+            self.buffer = []
+        try:
+            self.file.flush()
+        except OSError as error:
+            self.capture_error = str(error)
+            self.active = False
+
+    def mark(self, phase, outcome=None):
+        with self.lock:
+            if not self.closed and not self.capture_error:
+                self.flush()
+                self.write(
+                    {
+                        "type": "phase",
+                        "time": time.perf_counter_ns(),
+                        "name": phase,
+                        "outcome": outcome,
+                    }
+                )
+                self.flush()
+
+    def close(self):
+        with self.lock:
+            if self.closed:
+                return
+            interrupted = sys.gettrace() != self.trace
+            self.closed = True
+            if not interrupted:
+                sys.settrace(None)
+            if threading.gettrace() == self.trace:
+                threading.settrace(None)
+            self.flush()
+            self.write(
+                {
+                    "type": "end",
+                    "events": self.count,
+                    "interrupted": interrupted,
+                    "error": self.capture_error,
+                }
+            )
+            try:
+                self.file.close()
+            except OSError:
+                pass  # A missing end marker still flags incomplete capture.
+
+
+def install():
+    global _recorder
+    if _recorder is not None:
+        return
+    is_child = "COVERAGE_FLASHLIGHT_PARENT" in os.environ
+    os.environ.setdefault("COVERAGE_FLASHLIGHT_PARENT", str(os.getpid()))
+    _recorder = Recorder(
+        Path(os.environ["COVERAGE_FLASHLIGHT_ROOT"]),
+        Path(os.environ["COVERAGE_FLASHLIGHT_DIR"]),
+        int(os.environ["COVERAGE_FLASHLIGHT_LIMIT"]),
+        active=is_child or os.environ.get("COVERAGE_FLASHLIGHT_MODE") == "run",
+        role="child"
+        if is_child
+        else os.environ.get("COVERAGE_FLASHLIGHT_MODE", "test"),
+        sources=Sources(
+            Path(os.environ["COVERAGE_FLASHLIGHT_ROOT"]),
+            json.loads(os.environ.get("COVERAGE_FLASHLIGHT_SOURCE", '["."]')),
+            json.loads(os.environ.get("COVERAGE_FLASHLIGHT_OMIT", "[]")),
+        ),
+    )
+    _recorder.start()
+    atexit.register(_recorder.close)
+    real_exit = os._exit
+
+    def recorded_exit(status):
+        _recorder.close()
+        real_exit(status)
+
+    os._exit = recorded_exit
+
+
+def pytest_runtest_logstart(nodeid, location):
+    del nodeid, location
+    if _recorder:
+        _recorder.active = True
+        _recorder.mark("setup")
+
+
+def pytest_runtest_call(item):
+    del item
+    if _recorder:
+        _recorder.mark("call")
+
+
+def pytest_runtest_teardown(item):
+    del item
+    if _recorder:
+        _recorder.mark("teardown")
+
+
+def pytest_runtest_logreport(report):
+    if _recorder:
+        _recorder.mark(report.when, report.outcome)
+
+
+def pytest_runtest_logfinish(nodeid, location):
+    del nodeid, location
+    if _recorder:
+        _recorder.close()
+
+
+def read_recording(directory: Path, sources: dict) -> dict:
+    """Merge by a shared monotonic clock, preserving each thread's event order.
+
+    This is observation order, not a causal ordering of concurrent processes.
+    A killed process may leave a partial final JSON line or no end marker.
+    """
+    events, lanes, locations, phases, warnings = [], [], [], [], []
+    process_count = 0
+    for path in sorted(directory.glob("*.jsonl")):
+        local_locations, local_threads = {}, {}
+        ended = False
+        process = None
+        with path.open(encoding="utf-8") as stream:
+            for line in stream:
+                try:
+                    record = json.loads(line)
+                except json.JSONDecodeError:
+                    warnings.append(f"{path.name}: incomplete final record")
+                    break
+                kind = record["type"]
+                if kind == "process":
+                    process = record
+                    process_count += 1
+                elif kind == "source":
+                    name, source = record["path"], record["text"].splitlines()
+                    if name in sources and sources[name] != source:
+                        raise ValueError(f"Source changed between recordings: {name}")
+                    sources[name] = source
+                elif kind == "location":
+                    local_locations[record["id"]] = len(locations)
+                    locations.append(record["value"])
+                elif kind == "thread":
+                    local_threads[record["id"]] = len(lanes)
+                    lanes.append(
+                        {
+                            "pid": process["pid"],
+                            "parent": process["parent"],
+                            "role": process["role"],
+                            "name": record["name"],
+                        }
+                    )
+                elif kind == "events":
+                    events.extend(
+                        [ns, local_threads[thread], event, local_locations[location]]
+                        for ns, thread, event, location in record["values"]
+                    )
+                elif kind == "phase":
+                    phases.append(record)
+                elif kind == "truncated":
+                    warnings.append(
+                        f"PID {process['pid']}: stopped at {record['limit']:,} events"
+                    )
+                elif kind == "end":
+                    ended = True
+                    if record.get("error"):
+                        warnings.append(
+                            f"PID {process['pid']}: capture stopped: {record['error']}"
+                        )
+                    if record["interrupted"]:
+                        warnings.append(
+                            f"PID {process['pid']}: another tracer interrupted capture"
+                        )
+        if not ended:
+            warnings.append(
+                f"{path.name}: process did not finish capture; buffered events may be missing"
+            )
+    if not events:
+        warnings.append("No execution events captured")
+    events.sort(key=lambda event: event[0])
+    origin = events[0][0] if events else 0
+    for event in events:
+        event[0] = round((event[0] - origin) / 1_000_000, 3)
+    for phase in phases:
+        phase["time"] = round((phase["time"] - origin) / 1_000_000, 3)
+    return {
+        "events": events,
+        "lanes": lanes,
+        "locations": locations,
+        "phases": phases,
+        "warnings": warnings,
+        "processes": process_count,
+    }
+
+
+def render(payload):
+    template = (
+        Path(__file__)
+        .with_name("execution_flashlight.html")
+        .read_text(encoding="utf-8")
+    )
+    encoded = json.dumps(payload, ensure_ascii=True, separators=(",", ":")).replace(
+        "<", "\\u003c"
+    )
+    template = template.replace(
+        "__FLASHLIGHT_STYLE__",
+        Path(__file__).with_name("flashlight.css").read_text(encoding="utf-8"),
+    )
+    return template.replace("__TRACE_DATA__", encoded)

coverage_flashlight-1.0.0.dist-info/METADATA

@@ -0,0 +1,150 @@
+Metadata-Version: 2.5
+Name: coverage-flashlight
+Version: 1.0.0
+Summary: Explore Python coverage and replay execution with a code flashlight.
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: coverage>=7.10.6
+Provides-Extra: pytest
+Requires-Dist: pytest>=8; extra == 'pytest'
+Description-Content-Type: text/markdown
+
+# Coverage flashlight
+
+See which Python code ran, then replay its execution as a flashlight revealing
+source through fog. Reports are standalone HTML with source snapshots, shared
+light/dark themes, and no server or external assets.
+
+## Install and run
+
+Install in the environment containing the program and its dependencies:
+
+```sh
+uv add --dev 'coverage-flashlight[pytest]'
+# Or: python -m pip install 'coverage-flashlight[pytest]'
+```
+
+## Usage
+
+```sh
+# Static per-test line/branch coverage; pytest arguments follow --.
+flashlight pytest -- tests/ -k database
+
+# Ordered playback, including threads and newly launched Python processes.
+flashlight pytest --trace -- tests/ -k database
+
+# A script, with its arguments, executed once.
+flashlight run -- scripts/example.py --input sample.bin
+flashlight run --trace -- scripts/example.py --input sample.bin
+
+# Python modules work too, including other test runners.
+flashlight run -m my_package --help
+flashlight run --trace -m unittest discover
+
+# Render existing coverage.py branch data without another run.
+flashlight report
+```
+
+Open **htmlcov/flashlight.html** for static coverage or
+**htmlcov/execution.html** for playback. Use `--output path/to/report.html`
+before `--` to choose another destination. `python -m coverage_flashlight`
+is equivalent to `flashlight`.
+
+Coverage and tracing are separate modes: a command never silently runs a script
+twice. `--trace` selects execution recording instead of coverage.py. To create
+both reports, run the two commands explicitly. The program's exit status is
+preserved and failed runs still produce a report. Pytest mode continues recording
+other cases after a failure and returns a nonzero status.
+
+Pytest is an optional adapter. Static measurement uses coverage.py; ordered
+playback uses Python trace events. Script/module execution requires no pytest
+installation. Each pytest case runs in its own interpreter with its own context,
+which also follows newly launched Python children. This includes fixture setup
+and teardown. Isolation is slower than a normal suite run and can expose fixture
+or order dependencies; continue running ordinary tests for correctness.
+
+## Source selection
+
+Run from the target project's root. By default, the tool includes Python files
+inside that root, excluding hidden directories, virtual environments, build
+outputs, and node_modules. Narrow this with `--source src --source tests` or:
+
+```toml
+[tool.coverage-flashlight]
+source = ["src/my_package"]
+trace-source = ["src/my_package", "tests"]
+omit = ["*/generated/*"]
+```
+
+Paths are project-relative files or directories, not import names. `trace-source`
+defaults to `source`; absent both, the project root is used. `--source` overrides
+the configured selection for the current command. Keep source files inside the
+project root. Selected but unexecuted files remain visible in the reports.
+
+Coverage mode writes fresh data to `.coverage` after collection, replacing its
+previous contents. Use `--data-file path` to keep a separate database. It enables
+branch measurement and subprocess/`os._exit()` coverage itself; no coverage.py
+configuration is required. Existing report exclusion rules are respected when
+rendering. `flashlight report` can also render a combined database collected by
+coverage.py or pytest-cov, preserving its context names.
+
+Raw recordings and manifests are kept beside the report under `runs/<run-id>/`.
+The default trace cap is 100,000 events per process; increase it with
+`--max-events 500000`. Capture caps, interrupted hooks, source I/O failures, and
+missing process completion markers are explicitly reported.
+
+## Reading the reports
+
+Static coverage distinguishes executed lines, branch gaps, execution in another
+scope, and unexecuted statements. Select a line to inspect its contexts and missing
+branch destinations. Coverage is evidence of execution, not proof of assertions.
+
+Playback offers Play/Pause, stepping, timeline scrubbing, Next new line, a pytest
+Test body shortcut, Whole run, and process/thread selection. Unrevealed ranges
+collapse to grey `…` rows; Reveal source context expands them without marking
+them visited. Selecting a module pauses playback; Follow execution restores
+automatic navigation. The module map and source scroll inside the window.
+
+The timeline records observed event order, not variable history or cross-thread
+causality. Speed is events per second, not original elapsed time. Generator
+suspension produces Python return/call events. Native code, generated code with
+synthetic filenames, pre-existing processes, and threads created outside Python's
+threading module are outside capture. A forcibly killed process can lose its
+buffered tail. A skipped test can have no events. The source snapshot must remain
+consistent across cases; changed source is rejected rather than misattributed.
+
+Tracing changes timing and cannot share a trace hook with coverage.py or a
+debugger. Pytest-xdist parallel execution is rejected: per-case subprocess
+isolation already supplies attribution. Python children using `-S` or `-I`
+can bypass the opt-in bootstrap. No startup hook is installed globally.
+
+## Development and releases
+
+```sh
+uv sync --all-extras
+uv run pytest
+uv run ruff check .
+uv run ruff format --check .
+uv build
+```
+
+Tests use disposable Python projects, real threads/subprocesses, failing and
+skipped cases, arbitrary pytest layouts, and actual script/module entry points.
+They require no IDA installation. HTML, CSS and the opt-in bootstrap ship in the
+wheel and source distribution.
+
+The manual `Release` GitHub Actions workflow supports `release-current`, `dev`,
+`release-patch`, and `release-minor`. It tests, builds and checks the wheel, commits
+an optional version bump, creates a tag, publishes with `uv publish`, and creates
+a GitHub release. Versioning uses `uv version`; there is only one package version.
+
+To enable publication, create the GitHub repository and configure a PyPI trusted
+publisher for project **coverage-flashlight**, your repository owner/name,
+workflow **release.yml**, and environment **pypi**. Create that GitHub environment
+and allow the workflow to push release commits/tags. No PyPI API token is needed.
+These setup steps do not publish anything until the workflow is dispatched.
+
+References: [uv publishing](https://docs.astral.sh/uv/guides/package/),
+[coverage.py subprocess measurement](https://coverage.readthedocs.io/en/latest/subprocess.html),
+[Python tracing](https://docs.python.org/3/library/sys.html#sys.settrace).

coverage_flashlight-1.0.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+coverage_flashlight/__init__.py,sha256=pNroUo3M1ka2f0wZ5or0nVaIaK5EEK6s5RgL8xn1Sxs,70
+coverage_flashlight/__main__.py,sha256=fHO_t_1Iuz93vFIYUBhGcJyekERd8vGNId6tmTe5QM4,67
+coverage_flashlight/cli.py,sha256=cKOPcGaTBNlcGXms4ttyEYVwVMXgA0RV2VWo3lIlYR0,3868
+coverage_flashlight/config.py,sha256=IBfVZ3bWmV0qMGmUJ5wEGpCqWcnWz8bg3N86iGb78ns,3517
+coverage_flashlight/coverage.py,sha256=J_yaufg22Pr5nB8w4Y4QGMWWDl3TVTJD1gENURppbFw,3125
+coverage_flashlight/coverage_flashlight.html,sha256=W2u_OMQDvKZ3-LpRbu13fEx6q4z5E8171aKu9jK-tw4,9939
+coverage_flashlight/execution_flashlight.html,sha256=MwtWt7IMxEnFT1VQmLcEkGvGWO4tUStiSBXNV9VtMbw,17486
+coverage_flashlight/flashlight.css,sha256=x0pXmZiM0seo8JAvLv2GdpqciwmR-fy_CaWlombUCN8,3472
+coverage_flashlight/pytest_plugin.py,sha256=bQUplZbOeQsI5kE-9kroC8PvdJtR0EXoBlTUOjqppGk,918
+coverage_flashlight/runner.py,sha256=ZqPYibrfHT7NjF9OyI4_A53NbCwkgmudKxPtZNqCHM8,7674
+coverage_flashlight/trace.py,sha256=5tmOFaublgk4o4F7XXRfUIPjH_cnhUOJ46tutgGYbrI,12051
+coverage_flashlight/bootstrap/sitecustomize.py,sha256=WYmg4f8aq4c5Zr192FedHF0-h2Q_NIcxqIVP4mfsudI,663
+coverage_flashlight-1.0.0.dist-info/METADATA,sha256=YWgyKsUcjp8G2uQTI84pz3RzjSgBT7eQEsi2tkA8l44,6865
+coverage_flashlight-1.0.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+coverage_flashlight-1.0.0.dist-info/entry_points.txt,sha256=J8X-ys63GVnf38C6lFZDMvyCkWRp7rW5icKKSSEuaV4,60
+coverage_flashlight-1.0.0.dist-info/licenses/LICENSE,sha256=NiZqj9BzVoOUy4HNsrEk9_2uLGTBp-0J2zS00i76KVE,1359
+coverage_flashlight-1.0.0.dist-info/RECORD,,

coverage_flashlight-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

coverage_flashlight-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+flashlight = coverage_flashlight.cli:main

coverage_flashlight-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,23 @@
+Boost Software License - Version 1.0 - August 17th, 2003
+
+Permission is hereby granted, free of charge, to any person or organization
+obtaining a copy of the software and accompanying documentation covered by
+this license (the "Software") to use, reproduce, display, distribute,
+execute, and transmit the Software, and to prepare derivative works of the
+Software, and to permit third-parties to whom the Software is furnished to
+do so, all subject to the following:
+
+The copyright notices in the Software and this entire statement, including
+the above license grant, this restriction and the following disclaimer,
+must be included in all copies of the Software, in whole or in part, and
+all derivative works of the Software, unless such copies or derivative
+works are solely in the form of machine-executable object code generated by
+a source language processor.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT
+SHALL THE COPYRIGHT HOLDERS OR ANYONE DISTRIBUTING THE SOFTWARE BE LIABLE
+FOR ANY DAMAGES OR OTHER LIABILITY, WHETHER IN CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.