Metadata-Version: 2.1
Name: pytest-local-badge
Version: 1.3.0
Summary: Pytest plugin that writes self-hosted SVG badges (tests, coverage, skipped, xfailed, warnings, duration) to your repo — no third-party shield service required.
Keywords: pytest,pytest-plugin,badge,badges,shield,shields,svg,coverage,pytest-cov,ci,readme,self-hosted,offline,private-repo
Author-Email: Ilja Orlovs <vrghost@gmail.com>
License: MIT License
         
         Copyright (c) 2023 Ilya Orlov
         
         Permission is hereby granted, free of charge, to any person obtaining a copy
         of this software and associated documentation files (the "Software"), to deal
         in the Software without restriction, including without limitation the rights
         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
         copies of the Software, and to permit persons to whom the Software is
         furnished to do so, subject to the following conditions:
         
         The above copyright notice and this permission notice shall be included in all
         copies or substantial portions of the Software.
         
         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
         SOFTWARE.
         
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Plugins
Classifier: Framework :: Pytest
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Software Development :: Testing :: BDD
Classifier: Topic :: Software Development :: Documentation
Classifier: Typing :: Typed
Project-URL: Homepage, https://github.com/IljaOrlovs/pytest-local-badge
Project-URL: Source, https://github.com/IljaOrlovs/pytest-local-badge
Project-URL: Issues, https://github.com/IljaOrlovs/pytest-local-badge/issues
Project-URL: Changelog, https://github.com/IljaOrlovs/pytest-local-badge/blob/main/CHANGELOG.md
Project-URL: Release notes, https://github.com/IljaOrlovs/pytest-local-badge/releases
Project-URL: CI, https://github.com/IljaOrlovs/pytest-local-badge/actions
Requires-Python: >=3.10
Requires-Dist: pytest>=8.4
Provides-Extra: cov
Requires-Dist: pytest-cov>=5.0; extra == "cov"
Description-Content-Type: text/markdown

# pytest-local-badge

[![PyPI version](https://badge.fury.io/py/pytest-local-badge.svg)](https://pypi.org/project/pytest-local-badge/)
[![CI](https://github.com/IljaOrlovs/pytest-local-badge/actions/workflows/main.yml/badge.svg)](https://github.com/IljaOrlovs/pytest-local-badge/actions/workflows/main.yml)

### Our badges:

Session badges (regenerated every pytest run):

![Tests](https://raw.githubusercontent.com/IljaOrlovs/pytest-local-badge/main/badges/tests.svg)
![Coverage](https://raw.githubusercontent.com/IljaOrlovs/pytest-local-badge/main/badges/coverage.svg)
![Skipped](https://raw.githubusercontent.com/IljaOrlovs/pytest-local-badge/main/badges/skipped.svg)
![XFailed](https://raw.githubusercontent.com/IljaOrlovs/pytest-local-badge/main/badges/xfailed.svg)
![Warnings](https://raw.githubusercontent.com/IljaOrlovs/pytest-local-badge/main/badges/warnings.svg)
![Duration](https://raw.githubusercontent.com/IljaOrlovs/pytest-local-badge/main/badges/duration.svg)
![Last run](https://raw.githubusercontent.com/IljaOrlovs/pytest-local-badge/main/badges/last-run.svg)

### Package-metadata badges (rendered from the installed dist's classifiers / `METADATA`)

![Version](https://raw.githubusercontent.com/IljaOrlovs/pytest-local-badge/main/badges/pytest-local-badge-version.svg)
![Python](https://raw.githubusercontent.com/IljaOrlovs/pytest-local-badge/main/badges/pytest-local-badge-python.svg)
![Requires-Python](https://raw.githubusercontent.com/IljaOrlovs/pytest-local-badge/main/badges/pytest-local-badge-requires-python.svg)
![Implementation](https://raw.githubusercontent.com/IljaOrlovs/pytest-local-badge/main/badges/pytest-local-badge-implementation.svg)
![License](https://raw.githubusercontent.com/IljaOrlovs/pytest-local-badge/main/badges/pytest-local-badge-license.svg)
![Maturity](https://raw.githubusercontent.com/IljaOrlovs/pytest-local-badge/main/badges/pytest-local-badge-maturity.svg)
![Framework](https://raw.githubusercontent.com/IljaOrlovs/pytest-local-badge/main/badges/pytest-local-badge-framework.svg)
![OS](https://raw.githubusercontent.com/IljaOrlovs/pytest-local-badge/main/badges/pytest-local-badge-os.svg)
![Typed](https://raw.githubusercontent.com/IljaOrlovs/pytest-local-badge/main/badges/pytest-local-badge-typed.svg)

### Custom

![Hello](https://raw.githubusercontent.com/IljaOrlovs/pytest-local-badge/main/badges/hello.svg)
![This](https://raw.githubusercontent.com/IljaOrlovs/pytest-local-badge/main/badges/this.svg)

> **Self-hosted pytest & package badges** — tests, coverage, skipped, xfailed, warnings, duration, last-run, plus version/python/license/maturity/os and more pulled straight from your installed dist's metadata. No shields.io, no Codecov, no third-party uptime to depend on — just SVG files committed alongside your code.

## Why?

Shiny badges in your README are great. But the usual recipe — a hosted shield service reading numbers from a hosted CI provider — falls apart the moment you:

- Work on a **private repo** the badge service can't see.
- Run on **internal CI** behind a VPN.
- Don't want a **third-party SVG endpoint** loading every time someone opens your README.
- Want badges that **work offline** (think air-gapped environments, local docs builds, PDFs).

`pytest-local-badge` skips the round-trip. Every test run regenerates plain SVG files next to your source. Commit them. Reference them with a normal relative path. Done.

## Install

Just the test-count badge:

```bash
pip install pytest-local-badge
```

With the coverage badge ([`pytest-cov`](https://pypi.org/project/pytest-cov/) pulled in automatically):

```bash
pip install "pytest-local-badge[cov]"
```

## Quick start

Tell pytest where to drop the SVGs:

```bash
pytest --cov=my_package --local-badge-output-dir badges/
```

You'll get:

```
badges/
├── tests.svg       # e.g. "tests | 142"  (or "139/142" if some fail)
├── coverage.svg    # e.g. "coverage | 87%"
├── skipped.svg     # e.g. "skipped | 3"
├── xfailed.svg     # e.g. "xfailed | 1"
├── warnings.svg    # e.g. "warnings | 0"
├── duration.svg    # e.g. "duration | 4.2s"
└── last-run.svg    # e.g. "last run | 2026-03-14 09:26 UTC"
```

All seven session badges are generated by default; narrow the set with `--local-badge-generate` (see below).

### Package metadata badges

Pass `--local-badge-package=YOUR_DIST` to also render badges sourced from the installed distribution's metadata (`importlib.metadata`):

```bash
pytest --local-badge-output-dir badges/ --local-badge-package=my_package
```

That adds (when the corresponding classifier / metadata field is present):

```
badges/
├── my-package-version.svg           # e.g. "version | 1.2.3"        (md["Version"])
├── my-package-python.svg            # e.g. "python | 3.10 | 3.11"   (Programming Language :: Python :: X.Y classifiers)
├── my-package-requires-python.svg   # e.g. "python | >=3.10"        (md["Requires-Python"])
├── my-package-implementation.svg    # e.g. "implementation | CPython | PyPy"
├── my-package-license.svg           # e.g. "License | MIT"          (License :: ... classifier)
├── my-package-maturity.svg          # e.g. "status | beta"          (Development Status :: N - ...)
├── my-package-framework.svg         # e.g. "framework | Pytest"     (Framework :: X)
├── my-package-os.svg                # e.g. "OS | Linux | MacOS"     (Operating System :: ... classifiers; "OS Independent" wins if set)
├── my-package-typed.svg             # only if `Typing :: Typed` is set
└── my-package-private.svg           # only if `Private :: Do Not Upload` is set
```

Repeat the flag for more than one distribution — each gets its own set of files, prefixed with the PEP 503-canonical name:

```bash
pytest --local-badge-output-dir badges/ \
       --local-badge-package=my_lib \
       --local-badge-package=my_cli
```

Disable any of them by listing only the ones you want via `--local-badge-generate`:

```bash
# Get version + license, skip the python-versions enumeration in favour of Requires-Python:
pytest --local-badge-output-dir badges/ \
       --local-badge-package=my_package \
       --local-badge-generate status cov version license requires-python
```

Then in your `README.md`:

```markdown
![Tests](badges/tests.svg)
![Coverage](badges/coverage.svg)
![Skipped](badges/skipped.svg)
![XFailed](badges/xfailed.svg)
![Warnings](badges/warnings.svg)
![Duration](badges/duration.svg)
![Last run](badges/last-run.svg)

<!-- if you used --local-badge-package=my_package -->
![Version](badges/my-package-version.svg)
![Python](badges/my-package-python.svg)
![License](badges/my-package-license.svg)
![OS](badges/my-package-os.svg)
```

### Custom badges (`--local-badge-custom`)

Sometimes you want a badge for a value that isn't a pytest stat or a classifier — a git commit, a deploy timestamp, an arbitrary number computed by a CI step. Three input channels feed the same `LABEL | MESSAGE` shape, designed to be glued together in shell scripts:

```bash
# 1. CLI — repeatable, simplest for one-offs and loops:
pytest --local-badge-output-dir badges/ \
       --local-badge-custom "commit=$(git rev-parse --short HEAD)" \
       --local-badge-custom "branch=$(git rev-parse --abbrev-ref HEAD):lightgrey" \
       --local-badge-custom "deployed=2026-06-08T14:32 UTC"
```

The syntax is `LABEL=MESSAGE[:COLOR]`. The trailing `:COLOR` is parsed only when COLOR is a known palette name (`brightgreen`, `green`, `yellowgreen`, `yellow`, `orange`, `red`, `lightgrey`, `blue`) or a `#hex` literal — otherwise it's part of the message. So `deployed=2026-06-08T14:32:00Z` keeps the timestamp intact; the colour defaults to `blue`.

```bash
# 2. File — JSON list or JSONL (auto-detected). Best for CI scripts
#    that generate many badges:
pytest --local-badge-output-dir badges/ --local-badge-custom-file badges/custom.json
```

```json
[
  {"label": "commit", "message": "abc1234"},
  {"label": "deploy", "message": "2026-06-08T14:32 UTC", "color": "yellow"},
  {"label": "build SHA", "message": "abc1234", "color": "#ff8800", "slug": "sha"}
]
```

…or the JSONL form, which is friendlier to append-driven CI scripts (`jq -nc ... >> file.jsonl` in a loop):

```jsonl
# comments and blank lines are skipped
{"label": "commit", "message": "abc1234"}
{"label": "deploy", "message": "2026-06-08T14:32 UTC", "color": "yellow"}
```

The parser tries `json.loads` over the whole file first; on `JSONDecodeError` it falls back to line-by-line.

```bash
# 3. Environment variables — drop into a GitHub Actions `env:` block
#    with zero CLI changes:
PYTEST_LOCAL_BADGE_CUSTOM_COMMIT=abc1234 \
PYTEST_LOCAL_BADGE_CUSTOM_BUILD_SHA="def5678:#ff8800" \
   pytest --local-badge-output-dir badges/
```

The `PYTEST_LOCAL_BADGE_CUSTOM_<LABEL>` prefix is stripped, the rest is lowercased and `_` → `-`, so `..._BUILD_SHA` becomes label `build-sha` (and file `build-sha.svg`).

**Merge order**: env → file → CLI. The same slug from a later source overrides the earlier one — handy when a file holds your defaults and you want one CLI override per-run.

**Empty messages are skipped silently** by default — lets `--local-badge-custom "commit=$(git rev-parse --short HEAD 2>/dev/null)"` work in tarball checkouts where the subshell returns empty. Pass `--local-badge-custom-strict` to flip that to a hard error in CI.

**Reserved labels** (`tests`, `coverage`, `skipped`, `xfailed`, `warnings`, `duration`, `last-run`) can't be used — they would silently overwrite the built-in session badges. Use the file form's `slug` field if you need to rename around a collision.

### Make it permanent

Add it to your `pyproject.toml` so every `pytest` run keeps the badges in sync:

```toml
[tool.pytest.ini_options]
addopts = "--cov=my_package --local-badge-output-dir badges/"
```

…and commit the badge directory. The diff is tiny (an SVG only changes when the numbers change) and lives forever in your repo's history.

## Command-line options

```
--no-local-badge                 Disable the plugin for this run.
--local-badge-output-dir DIR     Where to write the SVGs. (Required to activate.)
--local-badge-generate {cov,duration,framework,implementation,last-run,
                        license,maturity,os,private,python,requires-python,
                        skipped,status,typed,version,warnings,xfailed} [...]
                                 Which badges to generate. Defaults to all of them.
                                 Package-metadata badges (version, python, license,
                                 maturity, framework, implementation, typed, private,
                                 requires-python, os) only fire when --local-badge-package
                                 is also set.
--local-badge-package PACKAGE    Installed distribution name to read metadata from.
                                 Repeat the flag for more than one package.
--local-badge-custom 'LABEL=MESSAGE[:COLOR]'
                                 Render an arbitrary 'LABEL | MESSAGE' badge.
                                 Repeatable. Trailing ':COLOR' must be a palette
                                 name or `#hex`; otherwise the whole value is the
                                 message and colour defaults to blue.
--local-badge-custom-file PATH   Read custom badges from a JSON list or JSONL file
                                 (auto-detected). Repeatable.
--local-badge-custom-strict      Treat empty MESSAGE values as errors rather than
                                 silently skipping them.
--local-badge-duration-max SECONDS
                                 Duration "budget" for the `duration` badge. When
                                 set, colour thresholds scale proportionally — e.g.
                                 `--local-badge-duration-max=60` gives brightgreen
                                 ≤ 6 s, orange ≤ 60 s, red > 60 s. Without it, the
                                 default absolute scale applies.
```

## Badge colour scale

Most badges colour-grade by ratio (pass rate, coverage, or skipped/xfailed fraction of the suite). `warnings` and `duration` use absolute thresholds instead — see the [Supported badges](#supported-badges) table. The ratio scale:

| Range | Colour |
|------:|--------|
| ≥ 99% | brightgreen |
| ≥ 87% | green |
| ≥ 75% | yellowgreen |
| ≥ 50% | yellow |
| ≥ 30% | orange |
| < 30% | red |
| no data | lightgrey |

"No data" is reserved for genuinely missing input (no tests collected, `pytest-cov` produced no report) — a real 0% renders **red**, not grey.

## Supported badges

### Session badges (always on)

These read from the live pytest session, no extra flags required.

| Name | File | Shows |
|------|------|-------|
| `status` | `tests.svg` | Total tests collected, or `passed/total` when some failed. |
| `cov` | `coverage.svg` | `pytest-cov` line coverage as a percentage. Requires `pytest-cov`. |
| `skipped` | `skipped.svg` | Count of `@pytest.mark.skip` / `pytest.skip(...)` tests. Colours by the fraction of the suite that actually ran. |
| `xfailed` | `xfailed.svg` | Count of expected-failure (`@pytest.mark.xfail`) tests. |
| `warnings` | `warnings.svg` | Number of warnings raised during the run. Colour-graded by absolute count (0 → green, anything else escalates fast). |
| `duration` | `duration.svg` | Total test session wall-clock time (`4.2s`, `1m 23s`, `1h 30m`). Colours by absolute thresholds by default, or by `--local-badge-duration-max=SECONDS` when you set a budget. |

### Package-metadata badges (opt in with `--local-badge-package`)

Read from the installed distribution's `METADATA` via `importlib.metadata`. Each file is prefixed with the package's canonical name, e.g. `my-package-version.svg`. Badges only render when the underlying classifier / field is actually present — no empty placeholders.

| Name | File suffix | Source | Shows |
|------|-------------|--------|-------|
| `version` | `-version.svg` | `md["Version"]` | The distribution version, e.g. `version \| 1.2.3`. |
| `python` | `-python.svg` | `Programming Language :: Python :: X.Y` classifiers | Pipe-joined Python versions, e.g. `python \| 3.10 \| 3.11 \| 3.12`. |
| `requires-python` | `-requires-python.svg` | `md["Requires-Python"]` | The declared constraint as-is, e.g. `python \| >=3.10`. Often a cleaner alternative to `python` when you don't list every version in classifiers. |
| `implementation` | `-implementation.svg` | `Programming Language :: Python :: Implementation :: X` classifiers | `implementation \| CPython \| PyPy`. |
| `license` | `-license.svg` | `License :: ...` classifier | The final trove segment with a trailing " License" trimmed, e.g. `License \| MIT`. |
| `maturity` | `-maturity.svg` | `Development Status :: N - ...` classifier | Project status — `planning`, `pre-alpha`, `alpha`, `beta`, `production/stable`, `mature`, `inactive`. Colour-graded by the trove digit (1–2 red, 3 orange, 4 yellow, 5 brightgreen, 6 green, 7 grey). |
| `framework` | `-framework.svg` | `Framework :: X` classifiers | Top-level framework names, deduplicated (`Framework :: Django :: 4.2` collapses to `Django`). |
| `typed` | `-typed.svg` | `Typing :: Typed` classifier | Renders `typed \| py.typed` if the classifier is set; nothing otherwise. |
| `private` | `-private.svg` | `Private :: Do Not Upload` classifier | Renders `package \| private` if the marker is set; nothing otherwise. Useful for in-house dists you don't want anyone to twine-upload. |

Pick which ones to render with `--local-badge-generate`, e.g.:

```bash
# Just the basics, no package badges:
pytest --local-badge-output-dir badges/ --local-badge-generate status cov warnings

# Session badges plus version + license for the installed dist:
pytest --local-badge-output-dir badges/ \
       --local-badge-package=my_package \
       --local-badge-generate status cov version license
```

By default *all* badges are listed under `--local-badge-generate`. Session badges always run when the plugin is active; package badges additionally require `--local-badge-package` to be set.

## How it compares

| | shields.io / Codecov / Coveralls | **pytest-local-badge** |
|---|---|---|
| Needs an external HTTP service | yes | no |
| Works on private repos out of the box | depends on plan | yes |
| Survives going offline | no | yes |
| Adds extra commits to history | no | yes (one per badge change) |
| Cost | free → paid tiers | free, forever |

If you're already happy with a hosted service, keep using it. If "another SaaS dependency for a handful of SVGs" feels excessive — this plugin is for you.

## Contributing

Issues and PRs welcome: <https://github.com/IljaOrlovs/pytest-local-badge>

```bash
git clone https://github.com/IljaOrlovs/pytest-local-badge
cd pytest-local-badge
pdm install

# Measure coverage of the plugin itself, then regenerate the committed
# badges with that data. We need `coverage run` (not just `pytest --cov`)
# because the plugin is imported by pytest *before* pytest-cov starts
# measuring, which would otherwise leave module-level code uncounted.
# CI enforces 100% via `--fail-under=100`.
pdm run coverage erase
pdm run coverage run -m pytest
pdm run coverage combine
pdm run coverage report -m --fail-under=100
# Pipe the same data into pytest-cov so the coverage badge reflects the
# real 100%, not the partial number you'd get from `pytest --cov` alone.
pdm run pytest --cov=pytest_local_badge --cov-append

pdm run ruff check ./src ./test
pdm run pyright
```

## Acknowledgements

The bundled `verdana_11px_normal.json` character-width table comes from
[anafanafo](https://github.com/metabolize/anafanafo) (MIT). It's the same
table [shields.io](https://shields.io) uses to size their badges, so locally
generated badges line up visually with their hosted siblings. See
[NOTICE](NOTICE) for attribution details.

## License

MIT — see [LICENSE](LICENSE).
