[](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]) # => <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](https://github.com/google/pybadges/tree/master/server-example)
contains an example of serving badge images from a
[Flask server](https://flask.palletsprojects.com/).
### Caveats
- pybadges uses a pre-calculated table of text widths and
[kerning](https://en.wikipedia.org/wiki/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:
## Development
```sh
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.](CONTRIBUTING.md)
## Versioning
We use [SemVer](http://semver.org/) 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.
Raw data
{
"_id": null,
"home_page": "https://github.com/google/pybadges",
"name": "pybadges",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.4",
"maintainer_email": "",
"keywords": "github gh-badges badge shield status",
"author": "Brian Quinlan",
"author_email": "brian@sweetapp.com",
"download_url": "https://files.pythonhosted.org/packages/0e/6a/6296d49ba2b4b62e7ea97606c6c6b21c291784afd63c56b2390f658c8cb3/pybadges-3.0.1.tar.gz",
"platform": null,
"description": "[](https://circleci.com/gh/google/pybadges)\n\n\n \n# pybadges\n\npybadges is a Python library and command line tool that allows you to create\nGithub-style badges as SVG images. For example:\n\n\n\n\n\nThe aesthetics of the generated badges matches the visual design found in this\n[specification](https://github.com/badges/shields/blob/master/spec/SPECIFICATION.md).\n\nThe implementation of the library was heavily influenced by\n[Shields.io](https://github.com/badges/shields) and the JavaScript\n[badge-maker](https://github.com/badges/shields/tree/master/badge-maker#badge-maker) library.\n\n## Getting Started\n\n### Installing\n\npybadges can be installed using [pip](https://pypi.org/project/pip/):\n\n```sh\npip install pybadges\n```\n\nTo test that installation was successful, try:\n```sh\npython -m pybadges --left-text=build --right-text=failure --right-color='#c00' --browser\n```\n\nYou will see a badge like this in your browser:\n\n\n\n## Usage\n\npybadges can be used both from the command line and as a Python library.\n\nThe command line interface is a great way to experiment with the API before\nwriting Python code.\n\nYou could also look at the [example server](https://github.com/google/pybadges/tree/master/server-example).\n\n### Command line usage\n\nComplete documentation of pybadges command arguments can be found using the `--help`\nflag:\n\n```sh\npython -m pybadges --help\n```\n\nBut the following usage demonstrates every interesting option:\n```sh\npython -m pybadges \\\n --left-text=complete \\\n --right-text=example \\\n --left-color=green \\\n --right-color='#fb3' \\\n --left-link=http://www.complete.com/ \\\n --right-link=http://www.example.com \\\n --logo='data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAIAAAACCAIAAAD91JpzAAAAD0lEQVQI12P4zwAD/xkYAA/+Af8iHnLUAAAAAElFTkSuQmCC' \\\n --embed-logo \\\n --whole-title=\"Badge Title\" \\\n --left-title=\"Left Title\" \\\n --right-title=\"Right Title\" \\\n --browser\n```\n\n\n\n#### A note about `--logo` and `--embed-logo`\n\nNote that the `--logo` option can include a regular URL:\n\n```sh\npython -m pybadges \\\n --left-text=\"python\" \\\n --right-text=\"3.2, 3.3, 3.4, 3.5, 3.6\" \\\n --whole-link=\"https://www.python.org/\" \\\n --browser \\\n --logo='https://dev.w3.org/SVG/tools/svgweb/samples/svg-files/python.svg'\n```\n\n\n\nIf the `--logo` option is set, the `--embed-logo` option can also be set.\nThe `--embed-logo` option causes the content of the URL provided in `--logo`\nto be embedded in the badge rather than be referenced through a link.\n\nThe advantage of using this option is an extra HTTP request will not be required\nto render the badge and that some browsers will not load image references at all.\n\nYou can see the difference in your browser:\n\n \n\n#### A note about `--(whole|left|right)-title`\n\nThe `title` element is usually displayed as a\n[pop-up by browsers](https://developer.mozilla.org/en-US/docs/Web/SVG/Element/title)\nbut is currently\n[filtered by Github](https://github.com/github/markup/issues/1267).\n\n\n### Library usage\n\npybadges is primarily meant to be used as a Python library.\n\n```python\nfrom pybadges import badge\ns = badge(left_text='coverage', right_text='23%', right_color='red')\n# s is a string that contains the badge data as an svg image.\nprint(s[:40]) # => <svg height=\"20\" width=\"191.0\" xmlns=\"ht\n```\n\nThe keyword arguments to `badge()` are identical to the command flags names\ndescribed above except with keyword arguments using underscore instead of\nhyphen/minus (e.g. `--left-text` => `left_text=`)\n\n#### Server usage\n\npybadges can be used to serve badge images on the web. \n\n[server-example](https://github.com/google/pybadges/tree/master/server-example)\ncontains an example of serving badge images from a\n[Flask server](https://flask.palletsprojects.com/).\n\n### Caveats\n\n - pybadges uses a pre-calculated table of text widths and\n [kerning](https://en.wikipedia.org/wiki/Kerning) distances\n (for western glyphs) to determine the size of the badge.\n So Eastern European languages may be rendered less well than\n Western European ones:\n\n \n\n and glyphs not present in Deja Vu Sans (the default font) may\n be rendered very poorly:\n\n \n\n - pybadges does not have any explicit support for languages that\n are written right-to-left (e.g. Arabic, Hebrew) and the displayed\n text direction may be incorrect:\n\n \n\n## Development\n\n```sh\ngit clone https://github.com/google/pybadges.git\ncd pybadges\npython -m virtualenv venv\nsource venv/bin/activate\n# Installs in edit mode and with development dependencies.\npip install -e .[dev]\nnox\n```\n\nIf you'd like to contribute your changes back to pybadges, please read the\n[contributor guide.](CONTRIBUTING.md)\n\n## Versioning\n\nWe use [SemVer](http://semver.org/) for versioning.\n\n## License\n\nThis project is licensed under the Apache License - see the [LICENSE](LICENSE) file for details\n\nThis is not an officially supported Google product.\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "A library and command-line tool for generating Github-style badges",
"version": "3.0.1",
"project_urls": {
"Homepage": "https://github.com/google/pybadges"
},
"split_keywords": [
"github",
"gh-badges",
"badge",
"shield",
"status"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "dca478905bcfa9db1e6402721a2f4a66ac45c2251c7a842cd4aeaec77b37456c",
"md5": "441aa283d3d1f74388bcfef1fd799288",
"sha256": "6e37f3eacd503143c3110438cf69bc3f2cd988ce4514de23dd5de8cbfa162a05"
},
"downloads": -1,
"filename": "pybadges-3.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "441aa283d3d1f74388bcfef1fd799288",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.4",
"size": 57344,
"upload_time": "2023-10-11T21:44:19",
"upload_time_iso_8601": "2023-10-11T21:44:19.758103Z",
"url": "https://files.pythonhosted.org/packages/dc/a4/78905bcfa9db1e6402721a2f4a66ac45c2251c7a842cd4aeaec77b37456c/pybadges-3.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0e6a6296d49ba2b4b62e7ea97606c6c6b21c291784afd63c56b2390f658c8cb3",
"md5": "caa980831f43571672a964bbe5c99f72",
"sha256": "a29962d3435a5a1b5b775f3f2b89e2d519f39d947d5118c279e36bf890158faa"
},
"downloads": -1,
"filename": "pybadges-3.0.1.tar.gz",
"has_sig": false,
"md5_digest": "caa980831f43571672a964bbe5c99f72",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.4",
"size": 58600,
"upload_time": "2023-10-11T21:44:21",
"upload_time_iso_8601": "2023-10-11T21:44:21.921492Z",
"url": "https://files.pythonhosted.org/packages/0e/6a/6296d49ba2b4b62e7ea97606c6c6b21c291784afd63c56b2390f658c8cb3/pybadges-3.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-11 21:44:21",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "google",
"github_project": "pybadges",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"circle": true,
"lcname": "pybadges"
}
JSON
