Metadata-Version: 2.1
Name: pybadges
Version: 1.0.2
Summary: A library and command-line tool for generating Github-style badges
Home-page: https://github.com/brianquinlan/cloud-opensource-python/pybadges
Author: Brian Quinlan
Author-email: brian@sweetapp.com
License: Apache-2.0
Keywords: github gh-badges badge shield status
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Operating System :: OS Independent
Requires-Python: >=3
Description-Content-Type: text/markdown
Provides-Extra: pil-measurement
Provides-Extra: dev
Requires-Dist: Jinja2 (>=2)
Provides-Extra: dev
Requires-Dist: fonttools (>=3.26); extra == 'dev'
Requires-Dist: nox-automation (>=0.19); extra == 'dev'
Requires-Dist: Pillow (>=5); extra == 'dev'
Requires-Dist: pytest (>=3.6); extra == 'dev'
Provides-Extra: pil-measurement
Requires-Dist: Pillow (>=5); extra == 'pil-measurement'

# 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](https://github.com/google/pybadges/raw/master/tests/golden-images/pip.svg?sanitize=true)
![pip installation](https://github.com/google/pybadges/raw/master/tests/golden-images/license.svg?sanitize=true)
![pip installation](https://github.com/google/pybadges/raw/master/tests/golden-images/build-passing.svg?sanitize=true)

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
[gh-badges](https://github.com/badges/shields#using-the-badge-library) 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:

![pip installation](https://github.com/google/pybadges/raw/master/tests/golden-images/build-failure.svg?sanitize=true)

## 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`
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' \
    --browser
```

![pip installation](https://github.com/google/pybadges/raw/master/tests/golden-images/complete.svg?sanitize=true)

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'
```

![pip installation](https://github.com/google/pybadges/raw/master/tests/golden-images/python.svg?sanitize=true)

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

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

   ![pip installation](https://github.com/google/pybadges/raw/master/tests/golden-images/saying-russian.svg?sanitize=true)

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

    ![pip installation](https://github.com/google/pybadges/raw/master/tests/golden-images/saying-chinese.svg?sanitize=true)

 - 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](https://github.com/google/pybadges/raw/master/tests/golden-images/saying-arabic.svg?sanitize=true)

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


