Registry / testing / coverage-enable-subprocess

coverage-enable-subprocess

JSON →
library1.0pypypiunverified

This package installs a .pth file that enables the coverage.py process_startup feature in the Python prefix/virtualenv in subsequent runs, facilitating automatic coverage measurement for subprocesses. It is currently stable and actively maintained, with version 1.0 being the latest. The release cadence is as-needed for stability and compatibility with coverage.py.

pip install coverage-enable-subprocess
INSTALL
IMPORT
SIG · COVERAGE-ENABLE-SU
C
coverage-enable-subprocess
testingpythonv1.0
Install
Import
Disk
Pass rate
0/ 10
Env Coverage0 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v? · pip install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.920 runs
build_error
glibc
py 3.103.920 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

No direct Python imports
This package works by installing a .pth file that automatically invokes `coverage.process_startup()` when Python starts, rather than providing symbols for direct import into user code. Its primary interaction is via environment variables and a `.coveragerc` file.
The library itself does not expose Python symbols for direct programmatic interaction. Its effect is through Python's startup mechanism.

This quickstart demonstrates how to enable coverage for a Python subprocess. It involves installing `coverage-enable-subprocess`, creating a `.coveragerc` file, setting the `COVERAGE_PROCESS_START` environment variable, and then running a Python script as a subprocess. The installed `.pth` file ensures that `coverage.py`'s `process_startup()` function is called, initiating coverage collection in the subprocess.

import os import subprocess import sys # 1. Create a dummy .coveragerc for demonstration with open('.coveragerc', 'w') as f: f.write('[run]\n') f.write('parallel = True\n') f.write('data_file = .coverage.subprocess\n') # 2. Set the environment variable to point coverage.py to the config file os.environ['COVERAGE_PROCESS_START'] = os.path.abspath('.coveragerc') # 3. Create a simple script to run as a subprocess script_content = """ import os import sys # This line should be covered by the subprocess def my_subprocess_func(): print("Hello from subprocess!") if __name__ == '__main__': my_subprocess_func() """ with open('subprocess_target.py', 'w') as f: f.write(script_content) print("Running subprocess...") # 4. Run the script as a subprocess # Ensure environment variables are passed correctly subprocess_env = os.environ.copy() process = subprocess.Popen([sys.executable, 'subprocess_target.py'], env=subprocess_env) process.wait() print("Subprocess finished. Check for .coverage.subprocess file.") # Clean up (optional for quickstart, but good practice) os.remove('.coveragerc') os.remove('subprocess_target.py') # To see the actual coverage report, you would then run: # coverage combine --data-file=.coverage.subprocess # coverage report --data-file=.coverage.subprocess
Debug
Known issues
gotchaCoverage data may not be collected from subprocesses if `COV_*` environment variables are not correctly passed to them. When using `subprocess.Popen`, ensure the `env` argument includes all relevant `os.environ` variables, especially those starting with `COV_`.
fix
When creating subprocesses with `subprocess.Popen`, explicitly pass `env=os.environ.copy()` or carefully merge environment variables, e.g., `subprocess_env = os.environ.copy(); subprocess_env.update({'MY_VAR': 'value'}); subprocess.Popen(..., env=subprocess_env)`.
affects: 1.0
gotchaUsing `process.kill()` to terminate subprocesses will prevent `coverage.py` from writing out its collected data, resulting in missing or incomplete coverage reports for those processes. Coverage.py relies on a clean shutdown (via `atexit` or `SIGTERM`) to write its data file.
fix
Always use `process.terminate()` (sends SIGTERM) and then `process.wait()` with a timeout. Only resort to `process.kill()` if `terminate` and `wait` fail. Example: `process.terminate(); try: process.wait(timeout=1.0) except subprocess.TimeoutExpired: process.kill()`.
affects: 1.0
gotchaWhen measuring coverage across multiple subprocesses, `coverage.py` requires `parallel = True` in the `[run]` section of your `.coveragerc` file. Without this, subprocesses might overwrite each other's data files, or data might not be collected correctly.
fix
Add `parallel = True` under the `[run]` section in your `.coveragerc` file. After all processes complete, use `coverage combine` to merge the individual data files.
affects: 1.0
gotchaThe `COVERAGE_PROCESS_START` environment variable *must* point to an existing and accessible `coverage.py` configuration file (e.g., `.coveragerc`). If the file is missing or the path is incorrect, coverage will not be enabled in subprocesses.
fix
Ensure that `COVERAGE_PROCESS_START` is set to the absolute path of your `.coveragerc` file before launching subprocesses. Verify the file exists and is readable.
affects: 1.0
Upgrade
Version history
1.0latest on PyPI · released May 11, 2016
Audit
Dependencies
coveragerequiredThis library enables a feature of coverage.py; coverage.py must be installed and configured separately for actual coverage measurement to occur.
Agent activity
11 hits · last 30 days
node
10
OpenAI (training)
1
Resources
coverage-enable-subprocess — pip install coverage-enable-subprocess · libregistry