BadgeShield

Get Started View on GitHub

0 Colors

0 Templates

0 Styles

Index

Why BadgeShield?¶

BadgeShield gives you pixel-perfect SVG badges — rectangular, pill, circle, framed, or banner — with accurate text sizing powered by real font metrics. Drop it into a CI pipeline, a Python script, or call it from the terminal.

🎨 5 Templates

Choose DEFAULT (two-part rectangular), PILL (fully rounded), CIRCLE, CIRCLE_FRAME with 11 PNG overlays, or BANNER (icon-zone + text).

✨ 4 Visual Styles

Apply FLAT, ROUNDED, GRADIENT, or SHADOWED to any template via --style or the BadgeStyle enum.

🌈 51 Built-in Colors

Use BadgeColor enum names like GREEN or DARK_PURPLE, or supply any #RRGGBB hex value.

📐 Accurate Text Sizing

Text widths are measured with Pillow font metrics (DejaVuSans), not guesswork — badges always fit.

🖼️ Logo Support

Embed any PNG/JPEG logo with optional color tinting to match your brand palette.

⚡ Concurrent Batch

Generate hundreds of badges in parallel from a single JSON config using BadgeBatchGenerator.

🖥️ Modern CLI

Typer-powered CLI with Rich progress bars, error panels, summary table, and an audit subcommand that detects external URL violations in SVG output.

Why badgeshield instead of shields.io?¶

shields.io is great — but it makes an HTTP call to an external server on every CI run. badgeshield generates badges entirely offline:

No network calls — works in air-gapped CI, behind corporate proxies, and offline laptops
No rate limits — generate thousands of badges in a single run
No data sent externally — version numbers, branch names, and repo stats stay local
Reproducible — same inputs always produce the same SVG, no caching surprises

Bash

# Generate every standard badge for your Python project in one command
badgeshield preset --all --output-path ./badges/ --format markdown

Badge Showcase¶

These badges are generated by badgeshield itself — no shields.io, no network calls.

Project badgesTemplatesStyles

Badge	Command
	`badgeshield preset version`
	`badgeshield preset python`
	`badgeshield preset ruff`
	`badgeshield preset mypy`
	`badgeshield preset maintained`
	`badgeshield preset library`
	`badgeshield preset cross-platform`

Template	Preview
`DEFAULT`
`PILL`
`CIRCLE`
`BANNER`

Style	Preview
`FLAT`
`ROUNDED`
`GRADIENT`
`SHADOWED`

Quick Look¶

Python APICLI — singleCLI — batchCLI — audit

Python

from badgeshield import BadgeGenerator, BadgeTemplate, BadgeStyle

generator = BadgeGenerator(template=BadgeTemplate.DEFAULT, style=BadgeStyle.GRADIENT)
generator.generate_badge(
    left_text="build",
    left_color="DARK_GREEN",
    right_text="passing",
    right_color="#44cc11",
    badge_name="build.svg",
)

Bash

badgeshield single \
  --left-text "coverage" \
  --left-color "#555555" \
  --right-text "94%" \
  --right-color "#44cc11" \
  --style gradient \
  --badge-name coverage.svg \
  --output-path ./badges

Bash

badgeshield batch badges.json --output-path ./badges --style rounded

badges.json:

JSON

[
  { "badge_name": "build.svg",    "left_text": "build",    "left_color": "GREEN" },
  { "badge_name": "coverage.svg", "left_text": "coverage", "left_color": "#555", "right_text": "94%", "right_color": "#44cc11", "style": "gradient" }
]

Bash

badgeshield audit build.svg        # exits 0 if clean
badgeshield audit build.svg --json # machine-readable JSON

📖 Continue to Installation or jump to the Python API guide.