Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/google/pybadges
A Python library for creating Github-style badges
https://github.com/google/pybadges
Last synced: about 2 months ago
JSON representation
A Python library for creating Github-style badges
- Host: GitHub
- URL: https://github.com/google/pybadges
- Owner: google
- License: apache-2.0
- Created: 2018-06-27T17:46:57.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2024-06-06T22:57:00.000Z (6 months ago)
- Last Synced: 2024-07-31T20:28:55.879Z (4 months ago)
- Language: Python
- Homepage:
- Size: 177 KB
- Stars: 466
- Watchers: 7
- Forks: 144
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
- badges-awesome-badges - pybadges
- awesome-starts - google/pybadges - A Python library for creating Github-style badges (Python)
- awesome-badges - pybadges
README
[](https://circleci.com/gh/google/pybadges)
# pybadges
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](https://github.com/badges/shields/blob/master/spec/SPECIFICATION.md).
The implementation of the library was heavily influenced by
[Shields.io](https://github.com/badges/shields) and the JavaScript
[badge-maker](https://github.com/badges/shields/tree/master/badge-maker#badge-maker) library.
## Getting Started
### Installing
pybadges can be installed using [pip](https://pypi.org/project/pip/):
```sh
pip install pybadges
```
To test that installation was successful, try:
```sh
python -m pybadges --left-text=build --right-text=failure --right-color='#c00' --browser
```
You will see a badge like this in your browser:
## 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](https://github.com/google/pybadges/tree/master/server-example).
### Command line usage
Complete documentation of pybadges command arguments can be found using the `--help`
flag:
```sh
python -m pybadges --help
```
But the following usage demonstrates every interesting option:
```sh
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 `--logo` and `--embed-logo`
Note that the `--logo` option can include a regular URL:
```sh
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'
```
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:
 
#### A note about `--(whole|left|right)-title`
The `title` element is usually displayed as a
[pop-up by browsers](https://developer.mozilla.org/en-US/docs/Web/SVG/Element/title)
but is currently
[filtered by Github](https://github.com/github/markup/issues/1267).
### Library usage
pybadges is primarily meant to be used as a Python library.
```python
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]) # =>