Skip to main content

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

Project description

# pybadges

pybadges is a Python library and command line tools that allows you to create
Git-hub styles badges as SVG images. For example:

![pip installation](tests/golden-images/pip.svg)
![pip installation](tests/golden-images/license.svg)
![pip installation](tests/golden-images/build-passing.svg)

The aesthetics of the generated badges matches the visual design of Shields badges

The implementation of the library was heavily influenced by
[]( and the JavaScript
[gh-badges]( library.

## Getting Started

These instructions will get you a copy of the project up and running on your
local machine for development and testing purposes. See deployment for notes on
how to deploy the project on a live system.

### 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 or other image viewer:

![pip installation](tests/golden-images/build-failure.svg)

## 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.

### Command line usage

Complete documentation of pybadges command arguments can be found using the help

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= \
--right-link= \

![pip installation](tests/golden-images/complete.svg)

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="" \
--browser \

![pip installation](tests/golden-images/python.svg)

### 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-width` => `left_width=`)

### 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](tests/golden-images/saying-russian.svg)

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

![pip installation](tests/golden-images/saying-chinese.svg)

- 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](tests/golden-images/saying-arabic.svg)

## Development

git clone TODO
python -m virtualenv py
source py/bin/activate
# Installs in edit mode and with development dependencies.
pip install -e .[dev]

If you'd like to contribute your changes back to pybadges, please read the
[contributer guide.](

## Versioning

We use [SemVer]( for versioning.

## License

This project is licensed under the Apache License - see the [LICENSE](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-0.0.2.tar.gz (10.4 kB view hashes)

Uploaded Source

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