Metadata-Version: 2.4
Name: coverage-treemap
Version: 0.2.0
Summary: Render a treemap visualization from a coverage.py JSON report.
Author-email: Martin Mahner <martin@mahner.org>
License-Expression: MIT
License-File: LICENSE
Keywords: coverage,pytest,treemap,visualization
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: Pytest
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.13
Requires-Dist: click>=8.1
Requires-Dist: coverage>=7.0
Requires-Dist: squarify>=0.4
Description-Content-Type: text/markdown

# coverage-treemap

A small tool that turns a [coverage.py](https://coverage.readthedocs.io/) 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.

<img src="https://github.com/bartTC/coverage-treemap/blob/main/screenshot.png?raw=true" alt="coverage-treemap example output: an SVG treemap where each rectangle is a source file, sized by statement count and colored by coverage percentage" width="300">

Inspired by [go-cover-treemap](https://github.com/nikolaydubina/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

```bash
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:

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

2. Render the treemap:

   ```bash
   # 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:

```bash
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:

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