Merge branch 'main' of https://github.com/plasma-umass/slipcover

Author: emeryberger

.github/workflows/codeql.yml

@@ -3,10 +3,17 @@ name: "CodeQL"
 on:
   push:
     branches: [ "main" ]
+    paths:
+      - src/**
+      - tests/**
   pull_request:
     branches: [ "main" ]
+    paths:
+      - src/**
+      - tests/**
   schedule:
     - cron: "42 19 * * 1"
+  workflow_dispatch:
 
 jobs:
   analyze:
@@ -20,23 +27,23 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        language: [ cpp, python ]
+        language: [ python ]
 
     steps:
       - name: Checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@v2
+        uses: github/codeql-action/init@v3
         with:
           languages: ${{ matrix.language }}
           queries: +security-and-quality
 
       - name: Autobuild
-        uses: github/codeql-action/autobuild@v2
+        uses: github/codeql-action/autobuild@v3
         if: ${{ matrix.language == 'cpp' || matrix.language == 'python' }}
 
       - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@v2
+        uses: github/codeql-action/analyze@v3
         with:
           category: "/language:${{ matrix.language }}"

.github/workflows/tests.yml

@@ -17,20 +17,10 @@ jobs:
   run-tests:
     runs-on: ${{ matrix.os }}
     strategy:
+      fail-fast: false
       matrix:
         os: [ ubuntu-latest, macos-latest, windows-latest ]
-        python: [ '3.8', '3.9', 'pypy-3.9', '3.10', '3.11', '3.12', '3.13' ]
-        include:
-          - os: macos-13
-            python: '3.8'
-          - os: macos-13
-            python: '3.9'
-          - os: macos-13
-            python: 'pypy-3.9'
-          - os: macos-13
-            python: '3.10'
-          - os: macos-13
-            python: '3.11'
+        python: [ '3.8', '3.9', 'pypy-3.9', '3.10', 'pypy-3.10', '3.11', '3.12', '3.13', '3.14' ]
         exclude:
           - os: macos-latest  # Python 3.8 unavailable on macos-14
             python: '3.8'
@@ -54,16 +44,19 @@ jobs:
         python-version: ${{ matrix.python }}
         allow-prereleases: true
 
-    - name: install SlipCover and pytest
+    - name: install prereqs
       run: |
-        python3 -m pip install --upgrade pip  # to avoid warnings
-        python3 -m pip install .
+        python3 -m pip install -U pip  # to avoid warnings
         python3 -m pip install pytest
 
     - name: install Unix dependencies
       if: matrix.os != 'windows-latest'
       run: python3 -m pip install pytest-forked
 
+    - name: install SlipCover
+      run: |
+        python3 -m pip install .
+
     - name: run tests
       run: python3 -m pytest
 
@@ -73,7 +66,7 @@ jobs:
     container: ${{ matrix.container }}
     strategy:
       matrix:
-        python_tag: ['cp311', 'pp39']
+        python_tag: ['cp311']  # PyPy not available in manylinux container; tested via run-tests job
         include:
           - os: ubuntu-latest
             container: quay.io/pypa/manylinux_2_28_x86_64 # https://github.com/pypa/manylinux
@@ -86,16 +79,17 @@ jobs:
             cat $GITHUB_PATH
       - name: install dependencies
         run: |
-            python3 -m pip install --upgrade pip  # to avoid warnings
-            python3 -m pip install wheel
+            python3 -m pip install -U pip # avoids warnings
+            python3 -m pip install wheel build
+
       - name: build sdist
-        run: |
-            python3 setup.py sdist
+        run: python3 -m build --sdist
+
       - name: try to use it
         run: |
             tar xzf dist/slipcover*.tar.gz
             cd slipcover*
-            python3 setup.py build
+            python3 -m build --wheel
 
   # Run a manylinux wheel build to verify build configuration
   test-build-wheel-manylinux:
@@ -114,13 +108,15 @@ jobs:
         run: |
           PYV=`echo "${{ matrix.python_version }}" | tr -d "."`; ls -d -1 /opt/python/cp$PYV*/bin | head -n 1 >> $GITHUB_PATH
           cat $GITHUB_PATH
+
       - name: install dependencies
         run: |
-          python3 -m pip install --upgrade pip  # otherwise building 'cryptography' may fail
-          python3 -m pip install setuptools wheel twine
+          python3 -m pip install -U pip # avoids GitHub warnings
+          python3 -m pip install twine build
+
       - name: build wheel
-        run: |
-            python3 setup.py bdist_wheel
+        run: python3 -m build --wheel
+
       - name: run auditwheel for manylinux
         run: |
           auditwheel repair dist/*.whl

CLAUDE.md

@@ -0,0 +1,89 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+SlipCover is a fast, near-zero-overhead Python code coverage tool. Unlike traditional coverage tools that use Python's tracing facilities, SlipCover uses just-in-time bytecode instrumentation (Python <3.12) or the `sys.monitoring` API (Python 3.12+) to track executed code with minimal overhead.
+
+## Build and Development Commands
+
+```bash
+# Install in development/editable mode
+pip install -e .
+
+# Run all tests
+pytest
+
+# Run a single test file
+pytest tests/test_coverage.py
+
+# Run a specific test
+pytest tests/test_coverage.py::test_function_name
+
+# Run with pytest-forked (Unix only, useful for isolation)
+pytest --forked
+
+# Clean build artifacts
+make clean
+
+# Run benchmarks
+make bench
+```
+
+## Running SlipCover
+
+```bash
+# Run a script with coverage
+python -m slipcover myscript.py
+
+# Run with a module (e.g., pytest)
+python -m slipcover -m pytest
+
+# Enable branch coverage
+python -m slipcover --branch myscript.py
+
+# Output JSON format
+python -m slipcover --json --out coverage.json myscript.py
+```
+
+## Architecture
+
+### Core Components
+
+- **`src/slipcover/slipcover.py`**: Main `Slipcover` class that manages instrumentation and coverage collection. Contains version-specific code paths for Python <3.12 (bytecode rewriting) vs 3.12+ (sys.monitoring).
+
+- **`src/slipcover/bytecode.py`**: Bytecode manipulation utilities (`Editor` class) for inserting probe calls into Python bytecode. Only used on Python <3.12.
+
+- **`src/slipcover/branch.py`**: AST-based pre-instrumentation for branch coverage. The `preinstrument()` function inserts branch markers before compilation.
+
+- **`src/slipcover/importer.py`**: Custom import machinery (`ImportManager`, `SlipcoverMetaPathFinder`, `SlipcoverLoader`) that intercepts module loading to instrument code. Also contains `FileMatcher` for source file filtering and `wrap_pytest()` for pytest integration.
+
+- **`src/probe.cxx`**: C++ extension module providing low-overhead probe signaling for Python <3.12. Not used on 3.12+ (pure Python there).
+
+### Python Version Handling
+
+The codebase has significant branching based on Python version:
+- **Python 3.12+**: Uses `sys.monitoring` API for coverage (no bytecode rewriting, no C++ extension)
+- **Python <3.12**: Uses bytecode instrumentation via the `probe` C++ extension
+
+Many functions have `if sys.version_info >= (3,12):` blocks with different implementations.
+
+### Coverage Flow
+
+1. **Script/module execution**: `__main__.py` parses args, creates `Slipcover` and `FileMatcher` instances
+2. **Import interception**: `ImportManager` installs a meta path finder that wraps module loaders
+3. **Instrumentation**: When matching modules load, their bytecode is instrumented via `Slipcover.instrument()`
+4. **Branch coverage** (optional): AST pre-instrumentation via `branch.preinstrument()` adds branch markers before compilation
+5. **Collection**: Probes signal line/branch execution to the `Slipcover` instance
+6. **De-instrumentation** (Python <3.12): Once coverage is recorded, probes can be disabled to reduce overhead
+7. **Reporting**: `get_coverage()` returns JSON-compatible coverage data; output can be text, JSON, or XML
+
+### Test Structure
+
+Tests are in `tests/` and use pytest:
+- `test_coverage.py`: End-to-end coverage functionality tests
+- `test_instrumentation.py`: Bytecode instrumentation tests
+- `test_bytecode.py`: Low-level bytecode editor tests
+- `test_branch.py`: Branch coverage and AST pre-instrumentation tests
+- `test_importer.py`: Import machinery tests

Makefile

@@ -2,11 +2,10 @@ all:
 	python3 -m pip install -e .
 
 # obtained with e.g. "brew install python@3.10"
-HOMEBREW_PYTHON=/opt/homebrew/opt/python@
 test:
 	- rm -f .coverage
-	@ for V in 3.8 3.9 3.10 3.11 3.12 3.13; do \
-	    P=$$(command -v ${HOMEBREW_PYTHON}$$V/bin/python3 || command -v python$$V); \
+	@ for V in python3.8 python3.9 pypy3.9 python3.10 pypy3.10 python3.11 python3.12 python3.13; do \
+	    P=$$(command -v $$V); \
 	    if ! [ -z $$P ]; then \
 	      $$P --version; \
 	      $$P -O -m pip uninstall -y slipcover; \

pyproject.toml

@@ -14,19 +14,23 @@ classifiers = [
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "License :: OSI Approved :: Apache Software License",
     "Operating System :: POSIX :: Linux",
     "Operating System :: MacOS :: MacOS X",
     "Operating System :: Microsoft :: Windows :: Windows 10"
 ]
-requires-python = ">=3.8,<3.14"
+requires-python = ">=3.8,<3.15"
 dependencies = [
     "tabulate"
 ]
 
 [project.scripts]
 slipcover = "slipcover.__main__:main"
 
+[project.entry-points.pytest11]
+slipcover = "slipcover.pytest_plugin"
+
 [project.urls]
 "Homepage" = "https://github.com/plasma-umass/slipcover"
 "Repository" = "https://github.com/plasma-umass/slipcover"
@@ -35,10 +39,19 @@ slipcover = "slipcover.__main__:main"
 # see https://peps.python.org/pep-0508/#environment-markers for conditional syntax
 requires = [
     "setuptools>61",
+    "setuptools<72.2; implementation_name == 'pypy'", # https://github.com/pypa/distutils/issues/283
     "wheel",
     "tomli; python_version < '3.11'" # tomllib alternative
 ]
 build-backend = "setuptools.build_meta"
 
 [tool.setuptools.package-dir]
 "" = "src"
+
+[project.optional-dependencies]
+test = [
+    'pytest',
+    'pytest-forked',
+    'pytest-xdist'
+]
+

src/slipcover/__init__.py

@@ -1,4 +1,4 @@
 from .version import __version__
-from .slipcover import Slipcover, merge_coverage, print_coverage
+from .slipcover import Slipcover, merge_coverage, print_coverage, print_xml
 from .importer import FileMatcher, ImportManager, wrap_pytest
 from .fuzz import wrap_function