Skip to main content

A library and command-line tool for generating Github-style badges

Project description

CircleCI pypi versions

pybadges

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

pip installation pip installation pip installation

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:

pip installation

Usage

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 --help flag:

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

pip installation

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

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'

pip installation

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 can see the difference in your browser:

--embed-logo=yes --embed-logo=no

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 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 hyphen/minus (e.g. --left-text => left_text=)

Server usage

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

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

Caveats

  • 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:

    pip installation

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

    pip installation

  • 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:

    pip installation

Development

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.

Versioning

We use SemVer for versioning.

License

This project is licensed under the Apache License - see the LICENSE file for details

This is not an officially supported Google product.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pybadges-3.0.1.tar.gz (58.6 kB view details)

Uploaded Source

Built Distribution

pybadges-3.0.1-py3-none-any.whl (57.3 kB view details)

Uploaded Python 3

File details

Details for the file pybadges-3.0.1.tar.gz.

File metadata

  • Download URL: pybadges-3.0.1.tar.gz
  • Upload date:
  • Size: 58.6 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.2 CPython/3.11.5

File hashes

Hashes for pybadges-3.0.1.tar.gz
Algorithm Hash digest
SHA256 a29962d3435a5a1b5b775f3f2b89e2d519f39d947d5118c279e36bf890158faa
MD5 caa980831f43571672a964bbe5c99f72
BLAKE2b-256 0e6a6296d49ba2b4b62e7ea97606c6c6b21c291784afd63c56b2390f658c8cb3

See more details on using hashes here.

File details

Details for the file pybadges-3.0.1-py3-none-any.whl.

File metadata

  • Download URL: pybadges-3.0.1-py3-none-any.whl
  • Upload date:
  • Size: 57.3 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.2 CPython/3.11.5

File hashes

Hashes for pybadges-3.0.1-py3-none-any.whl
Algorithm Hash digest
SHA256 6e37f3eacd503143c3110438cf69bc3f2cd988ce4514de23dd5de8cbfa162a05
MD5 441aa283d3d1f74388bcfef1fd799288
BLAKE2b-256 dca478905bcfa9db1e6402721a2f4a66ac45c2251c7a842cd4aeaec77b37456c

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page