A library and command-line tool for generating Github-style badges
pybadges 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.
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:
pybadges 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 pybadges command arguments can be found using the
python -m pybadges --help
But the following usage demonstrates every interesting option:
python -m pybadges \ --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
Note that the
--logo option can include a regular URL:
python -m pybadges \ --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'
--logo option is set, the
--embed-logo option can also be set.
--embed-logo option causes the content of the URL provided in
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 can see the difference in your browser:
A note about
pybadges is primarily meant to be used as a Python library.
from pybadges 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
pybadges can be used to serve badge images on the web.
pybadges uses a pre-calculated table of text widths and kerning distances (for western glyphs) to determine the size of the badge. So 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:
pybadges 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:
git clone https://github.com/google/pybadges.git cd pybadges python -m virtualenv venv source venv/bin/activate # Installs in edit mode and with development dependencies. pip install -e .[dev] nox
If you'd like to contribute your changes back to pybadges, please read the contributor guide.
We use SemVer for versioning.
This project is licensed under the Apache License - see the LICENSE file for details
This is not an officially supported Google product.
Release history Release notifications | RSS feed
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.