coverage-treemap 0.2.0

Render a treemap visualization from a coverage.py JSON report.

coverage-treemap

A small tool that turns a coverage.py JSON report into an SVG (or standalone HTML) treemap — so you can see at a glance which parts of your codebase are well-tested and which aren't.

Inspired by go-cover-treemap.

Ships two entry points:

• a standalone CLI for rendering from an existing coverage.json,
• a pytest plugin that writes the treemap at the end of a test run.

Requirements

• Python 3.13+

Install

pip install coverage-treemap
# or, for one-off CLI use:
uvx coverage-treemap coverage.json -o coverage.html

CLI

1. Generate a coverage JSON report:

   pytest --cov=. --cov-report=json:coverage.json
   

2. Render the treemap:

   # HTML with interactive hover tooltips (recommended)
   coverage-treemap coverage.json -o coverage.html
   
   # Static SVG
   coverage-treemap coverage.json -o coverage.svg
   
   # Pipe to stdout
   coverage-treemap coverage.json > coverage.svg
   

Output format is auto-detected from the file extension; override with --format svg|html|auto.

Pytest plugin

Once installed, pytest picks up the plugin automatically. Pass --cov-treemap=PATH and a treemap is written at the end of the session:

pytest --cov-treemap=coverage.html

The plugin starts its own coverage.Coverage() under the hood, so you don't need --cov=. or pytest-cov installed. Source/omit rules come from your .coveragerc or [tool.coverage.run] section as usual. If pytest-cov is active, the plugin reuses its coverage instance instead of double-measuring.

Plugin options

Option	Default	Description
--cov-treemap	off	Output path. .html / .svg format inferred from extension.
--cov-treemap-group-by	package	package or directory.
--cov-treemap-depth	2	Depth for --cov-treemap-group-by package.

CLI options

Option	Default	Description
--group-by	package	package — group by first N path components. directory — full recursive tree.
--depth	2	For --group-by package: how many leading path components form the group key.
--width	1200	Canvas width in pixels.
--height	1800	Canvas height in pixels.
--format	auto	svg, html, or auto (infer from -o extension).
-o, --output	stdout	Output path.

--group-by package with --depth

For a repo laid out like mypkg/subpkg/file.py:

• --depth 1 groups by top-level package (mypkg).
• --depth 2 (default) groups by sub-package (mypkg/subpkg).
• --depth 3 goes one level deeper.

--group-by directory

Renders the full filesystem tree recursively — every directory becomes a nested rectangle. Useful for exploring deep hierarchies.

Filtering what shows up

The tool reports on whatever is in the coverage data. Exclude noise (migrations, vendored code, settings, tests) via coverage.py's own config, not via the treemap:

# pyproject.toml
[tool.coverage.run]
branch = true
omit = [
    "*/migrations/*",
    "*/tests/*",
    "*/settings/*",
    "vendored/*",
]