| Name | pybadges2 JSON |
| Version |
2024.11.23
JSON |
| download |
| home_page | None |
| Summary | Library and command-line tool for generating GitHub-style badges |
| upload_time | 2024-11-24 03:21:24 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.9 |
| license | None |
| keywords |
badge
gh-badges
github
shield
status
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
[](https://pypi.python.org/pypi/pybadges2)
[](https://pypi.python.org/pypi/pybadges2)
[](https://github.com/jdknight/pybadges2/actions/workflows/build.yml)
# pybadges2
> [!IMPORTANT]
> The pybadges2 is a new release (end of 2024) based on the original
> [pybadges][pybadges] repository. The primary goal is to support the
> maintenace of this library/utility (since upstream maintenance appears
> to have paused).
pybadges2 is a Python library and command line tool that allows you to create
Github-style badges as SVG images. For example:
<p align="center">
<img src="https://raw.githubusercontent.com/jdknight/pybadges2/refs/heads/main/tests/assets/golden-images/pip.svg" />
<img src="https://raw.githubusercontent.com/jdknight/pybadges2/refs/heads/main/tests/assets/golden-images/license.svg" />
<img src="https://raw.githubusercontent.com/jdknight/pybadges2/refs/heads/main/tests/assets/golden-images/build-passing.svg" />
</p>
The aesthetics of the generated badges matches the visual design found in this
[specification][badges-shields-spec].
The implementation of the library was heavily influenced by
[Shields.io][shields-io] and the JavaScript [badge-maker][badge-maker] library.
## Getting Started
### Installing
pybadges2 can be installed using [pip][pip]:
```sh
pip install pybadges2
```
To test that installation was successful, try:
```sh
python -m pybadges2 --left-text=build --right-text=failure --right-color='#c00' --browser
```
You will see a badge like this in your browser:
<p align="center">
<img src="https://raw.githubusercontent.com/jdknight/pybadges2/refs/heads/main/tests/assets/golden-images/build-failure.svg" />
</p>
## Usage
pybadges2 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][example-server].
### Command line usage
Complete documentation of pybadges2 command arguments can be found using
the `--help` flag:
```sh
pybadges2 --help
(or)
python -m pybadges2 --help
```
But the following usage demonstrates every interesting option:
```sh
pybadges2 \
--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
```
<p align="center">
<img src="https://raw.githubusercontent.com/jdknight/pybadges2/refs/heads/main/tests/assets/golden-images/complete.svg" />
</p>
#### A note about `--logo` and `--embed-logo`
> [!NOTE]
> Logos that are not embedded may experience issues on sites where the
> Content Security Policy (CSP) blocks the logo requests.
Note that the `--logo` option can attempt include a regular URL:
```sh
pybadges2 \
--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'
```
<p align="center">
<img src="https://raw.githubusercontent.com/jdknight/pybadges2/refs/heads/main/tests/assets/golden-images/python.svg" />
</p>
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 may see the difference in your browser:
<p align="center">
<img src="https://raw.githubusercontent.com/jdknight/pybadges2/refs/heads/main/tests/assets/golden-images/embedded-logo.svg" />
<img src="https://raw.githubusercontent.com/jdknight/pybadges2/refs/heads/main/tests/assets/golden-images/no-embedded-logo.svg" />
</p>
#### A note about `--(whole|left|right)-title`
The `title` element is usually displayed as a [pop-up by browsers][svg-title]
but is currently [filtered by Github][github-markup-issue-1267].
### Library usage
pybadges is primarily meant to be used as a Python library.
```python
from pybadges2 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
pybadges2 can be used to serve badge images on the web.
[server-example][example-server] contains an example of serving badge
images from a [Flask server][flask].
### Caveats
- pybadges2 uses a pre-calculated table of text widths and [kerning][kerning]
distances (for Western glyphs) to determine the size of the badge. 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:
- pybadges2 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
Testing can be performed using [tox][tox]:
```sh
git clone https://github.com/jdknight/pybadges2.git
cd pybadges2
tox
```
Users wishing to contribute, please read the [contributor guide][contributing].
[badge-maker]: https://github.com/badges/shields/tree/master/badge-maker#badge-maker
[badges-shields-spec]: https://github.com/badges/shields/blob/master/spec/SPECIFICATION.md
[contributing]: https://github.com/jdknight/pybadges2/blob/main/CONTRIBUTING.md
[example-server]: https://github.com/jdknight/pybadges2/tree/main/server-example
[flask]: https://flask.palletsprojects.com/
[github-markup-issue-1267]: https://github.com/github/markup/issues/1267
[kerning]: https://wikipedia.org/wiki/Kerning
[pip]: https://pypi.org/project/pip/
[pybadges]: https://github.com/google/pybadges
[shields-io]: https://github.com/badges/shields
[svg-title]: https://developer.mozilla.org/en-US/docs/Web/SVG/Element/title
[tox]: https://tox.wiki/
Raw data
{
"_id": null,
"home_page": null,
"name": "pybadges2",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "James Knight <git@jdknight.me>",
"keywords": "badge, gh-badges, github, shield, status",
"author": null,
"author_email": "Brian Quinlan <brian@sweetapp.com>",
"download_url": "https://files.pythonhosted.org/packages/67/85/701ce82567fb449906d4f1e8edca8daf51c5987746f3b076f7d809c0e3cd/pybadges2-2024.11.23.tar.gz",
"platform": null,
"description": "[](https://pypi.python.org/pypi/pybadges2)\n[](https://pypi.python.org/pypi/pybadges2)\n[](https://github.com/jdknight/pybadges2/actions/workflows/build.yml)\n\n# pybadges2\n\n> [!IMPORTANT]\n> The pybadges2 is a new release (end of 2024) based on the original\n> [pybadges][pybadges] repository. The primary goal is to support the\n> maintenace of this library/utility (since upstream maintenance appears\n> to have paused).\n\npybadges2 is a Python library and command line tool that allows you to create\nGithub-style badges as SVG images. For example:\n\n<p align=\"center\">\n <img src=\"https://raw.githubusercontent.com/jdknight/pybadges2/refs/heads/main/tests/assets/golden-images/pip.svg\" />\n <img src=\"https://raw.githubusercontent.com/jdknight/pybadges2/refs/heads/main/tests/assets/golden-images/license.svg\" />\n <img src=\"https://raw.githubusercontent.com/jdknight/pybadges2/refs/heads/main/tests/assets/golden-images/build-passing.svg\" />\n</p>\n\nThe aesthetics of the generated badges matches the visual design found in this\n[specification][badges-shields-spec].\n\nThe implementation of the library was heavily influenced by\n[Shields.io][shields-io] and the JavaScript [badge-maker][badge-maker] library.\n\n## Getting Started\n\n### Installing\n\npybadges2 can be installed using [pip][pip]:\n\n```sh\npip install pybadges2\n```\n\nTo test that installation was successful, try:\n\n```sh\npython -m pybadges2 --left-text=build --right-text=failure --right-color='#c00' --browser\n```\n\nYou will see a badge like this in your browser:\n\n<p align=\"center\">\n <img src=\"https://raw.githubusercontent.com/jdknight/pybadges2/refs/heads/main/tests/assets/golden-images/build-failure.svg\" />\n</p>\n\n## Usage\n\npybadges2 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][example-server].\n\n### Command line usage\n\nComplete documentation of pybadges2 command arguments can be found using\nthe `--help` flag:\n\n```sh\npybadges2 --help\n (or)\npython -m pybadges2 --help\n```\n\nBut the following usage demonstrates every interesting option:\n\n```sh\npybadges2 \\\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<p align=\"center\">\n <img src=\"https://raw.githubusercontent.com/jdknight/pybadges2/refs/heads/main/tests/assets/golden-images/complete.svg\" />\n</p>\n\n#### A note about `--logo` and `--embed-logo`\n\n> [!NOTE]\n> Logos that are not embedded may experience issues on sites where the\n> Content Security Policy (CSP) blocks the logo requests.\n\nNote that the `--logo` option can attempt include a regular URL:\n\n```sh\npybadges2 \\\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<p align=\"center\">\n <img src=\"https://raw.githubusercontent.com/jdknight/pybadges2/refs/heads/main/tests/assets/golden-images/python.svg\" />\n</p>\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\nrequired to render the badge and that some browsers will not load image\nreferences at all.\n\nYou may see the difference in your browser:\n\n<p align=\"center\">\n <img src=\"https://raw.githubusercontent.com/jdknight/pybadges2/refs/heads/main/tests/assets/golden-images/embedded-logo.svg\" />\n <img src=\"https://raw.githubusercontent.com/jdknight/pybadges2/refs/heads/main/tests/assets/golden-images/no-embedded-logo.svg\" />\n</p>\n\n#### A note about `--(whole|left|right)-title`\n\nThe `title` element is usually displayed as a [pop-up by browsers][svg-title]\nbut is currently [filtered by Github][github-markup-issue-1267].\n\n### Library usage\n\npybadges is primarily meant to be used as a Python library.\n\n```python\nfrom pybadges2 import badge\n\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\npybadges2 can be used to serve badge images on the web.\n\n[server-example][example-server] contains an example of serving badge\nimages from a [Flask server][flask].\n\n### Caveats\n\n- pybadges2 uses a pre-calculated table of text widths and [kerning][kerning]\n distances (for Western glyphs) to determine the size of the badge. Eastern\n European languages may be rendered less well than Western European ones:\n\n \n\n And glyphs not present in Deja Vu Sans (the default font) may be rendered\n very poorly:\n\n \n\n- pybadges2 does not have any explicit support for languages that are\n written right-to-left (e.g. Arabic, Hebrew) and the displayed text\n direction may be incorrect:\n\n \n\n## Development\n\nTesting can be performed using [tox][tox]:\n\n```sh\ngit clone https://github.com/jdknight/pybadges2.git\ncd pybadges2\ntox\n```\n\nUsers wishing to contribute, please read the [contributor guide][contributing].\n\n\n[badge-maker]: https://github.com/badges/shields/tree/master/badge-maker#badge-maker\n[badges-shields-spec]: https://github.com/badges/shields/blob/master/spec/SPECIFICATION.md\n[contributing]: https://github.com/jdknight/pybadges2/blob/main/CONTRIBUTING.md\n[example-server]: https://github.com/jdknight/pybadges2/tree/main/server-example\n[flask]: https://flask.palletsprojects.com/\n[github-markup-issue-1267]: https://github.com/github/markup/issues/1267\n[kerning]: https://wikipedia.org/wiki/Kerning\n[pip]: https://pypi.org/project/pip/\n[pybadges]: https://github.com/google/pybadges\n[shields-io]: https://github.com/badges/shields\n[svg-title]: https://developer.mozilla.org/en-US/docs/Web/SVG/Element/title\n[tox]: https://tox.wiki/\n\n",
"bugtrack_url": null,
"license": null,
"summary": "Library and command-line tool for generating GitHub-style badges",
"version": "2024.11.23",
"project_urls": {
"Download": "https://pypi.python.org/pypi/pybadges2",
"Source": "https://github.com/jdknight/pybadges2"
},
"split_keywords": [
"badge",
" gh-badges",
" github",
" shield",
" status"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "bf569770b6605a85bc8abc5953a6e39678a1ccdeb65eddde8ca18ac95afe24c2",
"md5": "d5909d135f72fe63503022c08fe5260e",
"sha256": "278c25f5b8ffc59b631f5c6531a34ff1f4c6e7d3322aa593f018893526a55f05"
},
"downloads": -1,
"filename": "pybadges2-2024.11.23-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d5909d135f72fe63503022c08fe5260e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 54256,
"upload_time": "2024-11-24T03:21:23",
"upload_time_iso_8601": "2024-11-24T03:21:23.162896Z",
"url": "https://files.pythonhosted.org/packages/bf/56/9770b6605a85bc8abc5953a6e39678a1ccdeb65eddde8ca18ac95afe24c2/pybadges2-2024.11.23-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "6785701ce82567fb449906d4f1e8edca8daf51c5987746f3b076f7d809c0e3cd",
"md5": "9a8c6bb561e932955a8a2e67e41a2b07",
"sha256": "cf31f0cdbf5554044b10aaacf178a729c5d23f028113ded5c3d61ac2a8c73336"
},
"downloads": -1,
"filename": "pybadges2-2024.11.23.tar.gz",
"has_sig": false,
"md5_digest": "9a8c6bb561e932955a8a2e67e41a2b07",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 72268,
"upload_time": "2024-11-24T03:21:24",
"upload_time_iso_8601": "2024-11-24T03:21:24.765010Z",
"url": "https://files.pythonhosted.org/packages/67/85/701ce82567fb449906d4f1e8edca8daf51c5987746f3b076f7d809c0e3cd/pybadges2-2024.11.23.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-24 03:21:24",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jdknight",
"github_project": "pybadges2",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "pybadges2"
}
