Install & Compatibility
Where this runs
tested against v0.6.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.000s · 18.1MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 1.6s · import 0.000s · 19MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
check_all
✓ from coverage_threshold import check_all
✗ from coverage_threshold.lib import check_all_thresholds
This quickstart demonstrates how to use `coverage-threshold` programmatically with mock coverage data. In a real application, the `CoverageReport` object would be generated by parsing an actual `.coverage` file after `coverage.py` has run. The `check_all_thresholds` function raises an exception if any thresholds are not met.
from coverage_threshold.lib import check_all_thresholds
from coverage_threshold.model import Config, CoverageReport
# Simulate a coverage report object
# In a real scenario, this data would be parsed from a .coverage file
mock_report = CoverageReport(
line_coverage=95.0,
branch_coverage=85.0,
file_line_coverage={
"app.py": 95.0,
"another_module.py": 90.0
},
file_branch_coverage={
"app.py": 85.0,
"another_module.py": 80.0
}
)
# Define the desired thresholds (mimicking pyproject.toml configuration)
config = Config(
line_threshold=90.0,
branch_threshold=80.0,
exclude=[] # No file exclusions for this example
)
print(f"Checking report: Global Line={mock_report.line_coverage:.1f}%, Global Branch={mock_report.branch_coverage:.1f}%")
print(f"Against thresholds: Line={config.line_threshold:.1f}%, Branch={config.branch_threshold:.1f}%")
try:
# This function will raise an exception if thresholds are not met
check_all_thresholds(config, mock_report)
print("\nSUCCESS: All coverage thresholds met!")
except Exception as e:
print(f"\nFAILURE: Coverage thresholds not met: {e}")
print("\n--- Testing a failure scenario ---")
failing_report = CoverageReport(
line_coverage=80.0, # This is below the 90% threshold
branch_coverage=85.0,
file_line_coverage={
"app.py": 80.0,
"another_module.py": 90.0
},
file_branch_coverage={
"app.py": 85.0,
"another_module.py": 80.0
}
)
print(f"Checking failing report: Global Line={failing_report.line_coverage:.1f}%, Global Branch={failing_report.branch_coverage:.1f}%")
print(f"Against thresholds: Line={config.line_threshold:.1f}%, Branch={config.branch_threshold:.1f}%")
try:
check_all_thresholds(config, failing_report)
print("\nSUCCESS: All coverage thresholds met!")
except Exception as e:
print(f"\nFAILURE: Coverage thresholds not met: {e}")
coverage-threshold --version
Debug
Known issues
gotchaThe `coverage-threshold` tool does not run coverage itself; it requires a `.coverage` data file to already exist. Running `coverage-threshold` directly without prior coverage generation will fail.fixAlways ensure you run `coverage run` (or a similar command via your test runner) to generate the `.coverage` data file before invoking `coverage-threshold`.
affects: All
gotchaUsing an incompatible `coverage.py` version (older than 5.0.0) can lead to errors when `coverage-threshold` attempts to parse the `.coverage` data file.fixEnsure your `coverage.py` installation is version `5.0.0` or higher. Upgrade with `pip install --upgrade coverage`.
affects: All (especially with `coverage.py < 5.0.0`)
gotchaIncorrectly formatted or missing configuration in `pyproject.toml` or `.coverage.rc` can lead to errors or unexpected threshold checks.fixRefer to the official documentation for the correct `[tool.coverage-threshold]` section in `pyproject.toml` or the specific keys if using `.coverage.rc`.
affects: All
Upgrade
Version history
0.6.2latest on PyPI · released May 25, 2025
Audit
Dependencies
coveragerequiredRequires coverage.py to generate and parse coverage data files.