Genbadge - Generate Badges for Python Tools

1.1.3 · active · verified Mon Apr 13

Genbadge (version 1.1.3) is a Python library that provides command-line utilities to generate badges for various development tools that may not offer them natively. It currently supports generating badges for test results (e.g., from `junit.xml`), code coverage (e.g., from `coverage.xml`), and flake8 reports. The project has an active development status with several releases per year, addressing bug fixes and adding new features.

Warnings

breaking As of version 1.1.2, genbadge officially dropped support for Python versions 2.7, 3.5, 3.6, and 3.7. This version and subsequent releases may not function correctly on these older Python environments.
Fix: Upgrade your Python environment to 3.8 or newer, or use an older version of genbadge that explicitly supports your Python version.
gotcha Older versions of genbadge (prior to 1.1.1) might experience issues when running with Pillow version 10 or greater due to API changes in Pillow. [from release notes]
Fix: Upgrade genbadge to version 1.1.1 or higher. If unable to upgrade genbadge, consider downgrading Pillow to a version below 10.
gotcha When using `genbadge coverage` on reports where no branches are present (e.g., when `--no-branch` option is set in coverage.py), older versions could raise a `ZeroDivisionError`. [from release notes]
Fix: Upgrade genbadge to version 1.0.4 or higher to correctly handle coverage reports with zero branches.
gotcha Users running Python 3.12 with older genbadge versions might encounter problems related to a missing `setuptools` dependency, as it was explicitly added for 3.12 support. [from release notes]
Fix: Upgrade genbadge to version 1.1.1 or higher. Alternatively, ensure `setuptools` is explicitly installed in your environment (`pip install setuptools`).
deprecated Versions prior to 1.1.3 used `pkg_resources` which is a deprecated dependency and could lead to `UserWarning` messages. [from release notes]
Fix: Upgrade genbadge to version 1.1.3 or higher, which migrates to `importlib.resources`.

Install

pip install genbadge Minimal installation (core features)
pip install genbadge[all] Full installation (including test, coverage, and flake8 support)

Quickstart

This quickstart demonstrates how to generate a coverage badge using `genbadge` from a `coverage.xml` report. First, ensure `genbadge` is installed with `coverage` extra. Then, generate your `coverage.xml` report (e.g., using the `coverage.py` tool). Finally, run the `genbadge coverage` command, specifying the input XML file and desired output SVG file.

# 1. Install genbadge with coverage support
pip install genbadge[coverage]

# 2. Run your tests with coverage.py to generate a coverage.xml report
# (Example: assuming you have tests and source code in a 'src' directory)
# (Run from your project root where .coverage file will be generated)
# pip install coverage
# coverage run -m pytest
# coverage xml -o coverage.xml
# Create a dummy coverage.xml for demonstration if not available
import os
if not os.path.exists('coverage.xml'):
    with open('coverage.xml', 'w') as f:
        f.write('<coverage branch-rate="0.75" line-rate="0.80">\n')
        f.write('  <sources><source>src</source></sources>\n')
        f.write('  <packages><package name="src"><classes><class branch-rate="0.75" complexity="0" filename="src/my_module.py" line-rate="0.80" name="my_module.py">\n')
        f.write('    <methods/><lines><line branch="false" hits="1" number="1"/><line branch="false" hits="1" number="2"/><line branch="true" condition-coverage="100% (2/2)" hits="1" number="5"/><line branch="false" hits="1" number="6"/><line branch="false" hits="0" number="9"/></lines>\n')
        f.write('  </class></classes></package></packages>\n')
        f.write('</coverage>')

# 3. Generate the coverage badge from the XML report
# The badge will be saved as 'coverage-badge.svg' in the current directory
# You can specify the output file with -o flag, e.g., genbadge coverage -o ./reports/coverage-badge.svg
os.system('genbadge coverage -i coverage.xml -o coverage-badge.svg')

print("Coverage badge generated as coverage-badge.svg")
print("You can include it in your README with: ![Coverage](coverage-badge.svg)")

view raw JSON →