pybadges2 2024.11.21

Library and command-line tool for generating GitHub-style badges

pybadges2

[!IMPORTANT] The pybadges2 is a new release (end of 2024) based on the original pybadges repository. The primary goal is to support the maintenace of this library/utility (since upstream maintenance appears to have paused).

pybadges2 is a Python library and command line tool that allows you to create Github-style badges as SVG images. For example:

The aesthetics of the generated badges matches the visual design found in this specification.

The implementation of the library was heavily influenced by Shields.io and the JavaScript badge-maker library.

Getting Started

Installing

pybadges can be installed using pip:

pip install pybadges

To test that installation was successful, try:

python -m pybadges --left-text=build --right-text=failure --right-color='#c00' --browser

You will see a badge like this in your browser:

Usage

pybadges2 can be used both from the command line and as a Python library.

The command line interface is a great way to experiment with the API before writing Python code.

You could also look at the example server.

Command line usage

Complete documentation of pybadges2 command arguments can be found using the --help flag:

pybadges2 --help
 (or)
python -m pybadges2 --help

But the following usage demonstrates every interesting option:

pybadges2 \
    --left-text=complete \
    --right-text=example \
    --left-color=green \
    --right-color='#fb3' \
    --left-link=http://www.complete.com/ \
    --right-link=http://www.example.com \
    --logo='data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAIAAAACCAIAAAD91JpzAAAAD0lEQVQI12P4zwAD/xkYAA/+Af8iHnLUAAAAAElFTkSuQmCC' \
    --embed-logo \
    --whole-title="Badge Title" \
    --left-title="Left Title" \
    --right-title="Right Title" \
    --browser

A note about --logo and --embed-logo

[!NOTE] Logos that are not embedded may experience issues on sites where the Content Security Policy (CSP) blocks the logo requests.

Note that the --logo option can attempt include a regular URL:

pybadges2 \
    --left-text="python" \
    --right-text="3.2, 3.3, 3.4, 3.5, 3.6" \
    --whole-link="https://www.python.org/" \
    --browser \
    --logo='https://dev.w3.org/SVG/tools/svgweb/samples/svg-files/python.svg'

If the --logo option is set, the --embed-logo option can also be set. The --embed-logo option causes the content of the URL provided in --logo to be embedded in the badge rather than be referenced through a link.

The advantage of using this option is an extra HTTP request will not be required to render the badge and that some browsers will not load image references at all.

You may see the difference in your browser:

A note about --(whole|left|right)-title

The title element is usually displayed as a pop-up by browsers but is currently filtered by Github.

Library usage

pybadges is primarily meant to be used as a Python library.

from pybadges2 import badge

s = badge(left_text='coverage', right_text='23%', right_color='red')
# s is a string that contains the badge data as an svg image.
print(s[:40]) # => <svg height="20" width="191.0" xmlns="ht

The keyword arguments to badge() are identical to the command flags names described above except with keyword arguments using underscore instead of hyphen/minus (e.g. --left-text => left_text=)

Server usage

pybadges2 can be used to serve badge images on the web.

server-example contains an example of serving badge images from a Flask server.

Caveats

• pybadges2 uses a pre-calculated table of text widths and kerning distances (for Western glyphs) to determine the size of the badge. Eastern European languages may be rendered less well than Western European ones:

  

  And glyphs not present in Deja Vu Sans (the default font) may be rendered very poorly:

  

• pybadges2 does not have any explicit support for languages that are written right-to-left (e.g. Arabic, Hebrew) and the displayed text direction may be incorrect:

  

Development

Testing can be performed using tox:

git clone https://github.com/jdknight/pybadges2.git
cd pybadges2
tox

Users wishing to contribute, please read the contributor guide.