Metadata-Version: 2.4
Name: anybadge
Version: 1.18.0
Summary: Simple, flexible badge generator for project badges.
Author-email: Jon Grace-Cox <30441316+jongracecox@users.noreply.github.com>
License: MIT
Project-URL: Homepage, https://github.com/jongracecox/anybadge
Classifier: License :: OSI Approved :: MIT License
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: AUTHORS.rst
Requires-Dist: packaging
Provides-Extra: emoji
Requires-Dist: emoji; extra == "emoji"
Dynamic: license-file

# anybadge

Python project for generating badges for your projects

[![pypi package](https://badge.fury.io/py/anybadge.svg)](https://pypi.org/project/anybadge)
[![build status](https://api.travis-ci.com/jongracecox/anybadge.svg?branch=master)](https://app.travis-ci.com/github/jongracecox/anybadge)
[![downloads](https://img.shields.io/pypi/dm/anybadge.svg)](https://pypistats.org/packages/anybadge)
[![GitHub last commit](https://img.shields.io/github/last-commit/jongracecox/anybadge.svg)](https://github.com/jongracecox/anybadge/commits/master)
[![GitHub](https://img.shields.io/github/license/jongracecox/anybadge.svg)](https://github.com/jongracecox/anybadge/blob/master/LICENSE)
[![GitHub stars](https://img.shields.io/github/stars/jongracecox/anybadge.svg?style=social)](https://github.com/jongracecox/anybadge/stargazers)
[![Snyk health](https://snyk.io/test/github/jongracecox/anybadge/badge.svg)](https://snyk.io/advisor/python/anybadge)
[![Downloads](https://pepy.tech/badge/anybadge)](https://pepy.tech/project/anybadge)

[![buymeacoffee](https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png)](https://www.buymeacoffee.com/jongracecox)

Supports: Python 3.7-3.15 (2.7-3.6 support has been dropped)

## Overview

`anybadge` can be used to add badge generation to your Python projects,
and also provides a command line interface.

This utility can be used to generate .svg badge images, using configurable
thresholds for coloring the badges based on the badge value.  Many badge
generation tools just provide the ability to specify the color of badge.
`anybadge` allows you to specify the label, badge value, and color, but
it also allows you to specify a set of thresholds that can be used to
select a color based on the badge value.

`anybadge` may be useful for companies developing internally, or any time
making calls to external badge services is not possible, or undesirable.
In this situation using `anybadge` will be easier than running your own
internal badge service.

The package can be imported into your python code, or run direct from the
command line.

## Demo

You can find a [repl.it demo here](https://repl.it/@JonGrace_Cox/anybadge-demo).
This will allow you to see what the package can do and play with it to test outputs.

## Basic usage

### Command line

As an example, if you want to produce a pylint badge, you may run `anybadge`
from the command line like this:

```bash
anybadge -l pylint -v 2.22 -f pylint.svg 2=red 4=orange 8=yellow 10=green
```

This would result in a badge like this:

![pylint](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/pylint.svg)

In this example the label is set to "pylint", the value "2.22", and an
output file called "pylint.svg".  The thresholds are provided in pairs
of `<value>=color`  Values can be integer or floats for ranges, and
string values are also supported.  See
[Thresholds](#thresholds) below for details of how the badge value is
compared against thresholds.

### Python

Here is the same example implemented in Python code:

```python
import anybadge

# Define thresholds: <2=red, <4=orange <8=yellow <10=green
thresholds = {2: 'red',
              4: 'orange',
              6: 'yellow',
              10: 'green'}

badge = anybadge.Badge('pylint', 2.22, thresholds=thresholds)

badge.write_badge('pylint.svg')
```

## Installation

`anybadge` is available in PyPi at https://pypi.org/project/anybadge

Release notes are published on the
[GitHub releases page](https://github.com/jongracecox/anybadge/releases).

You can install the latest release of `anybadge` using `pip`:

```bash
pip install anybadge
```

This will install the Python package, and also make `anybadge` available
as a command line utility.

Support for `:emoji:` shortcodes (see
[Emojis](#emojis) below) is an optional extra since it requires the
`emoji` package. Install it with:

```bash
pip install anybadge[emoji]
```

Without this extra, `:shortcode:` text is rendered exactly as it was passed.

## Getting help

To get help from the command line utility, just run:

```bash
anybadge --help
```

## Command line usage

### Output

Running the utility with the `--file` option will result in the .svg image being
written to file.  Without the `--file` option the `.svg` file content will be
written to stdout, so can be redirected to a file.

### Thresholds

Thresholds are provided as pairs of `<threshold>=<color>`. Each threshold
defines the upper bound of a range. The badge value is compared against
each threshold in turn, and the color used is that of the first threshold
whose value the badge value is strictly less than. With:

```bash
anybadge --label=pylint --value=2.22 --file=pylint.svg 2=red 4=orange 8=yellow 10=green
```

the thresholds can be read as "less than 2 = red, less than 4 = orange,
less than 8 = yellow, less than 10 = green", or shown as a decision flow:

```mermaid
flowchart LR
    A([badge value]) --> B{"value < 2?"}
    B -- "yes" --> R[red]
    B -- "no" --> C{"value < 4?"}
    C -- "yes" --> O[orange]
    C -- "no" --> D{"value < 8?"}
    D -- "yes" --> Y[yellow]
    D -- "no" --> E{"value < 10?"}
    E -- "yes" --> G[green]
    E -- "no" --> G

    classDef red fill:#e05d44,color:#fff
    classDef orange fill:#fe7d37,color:#fff
    classDef yellow fill:#dfb317,color:#000
    classDef green fill:#4c1,color:#000
    class R red
    class O orange
    class Y yellow
    class G green
```

Note that the comparison is exclusive (`<` rather than `<=`). A value
exactly equal to a threshold is not less than that threshold, so it
falls into the next range up. With the thresholds above:

| Badge value   | Badge color | Why                          |
| ------------- | ----------- | ---------------------------- |
| 1.99          | red         | 1.99 is < 2                  |
| 2.0           | orange      | 2.0 is not < 2, but is < 4   |
| 4.0           | yellow      | 4.0 is not < 4, but is < 8   |
| 9.0           | green       | 9.0 is not < 8, but is < 10  |
| 10 or greater | green       | see "Values above the top threshold" below |

**Values above the top threshold** default to the color of the largest
threshold.  On the command line this behavior is off by default; pass
`--use-max` to enable it, otherwise the `--color` value is used.
On the Python API the behavior is on by default; pass
`use_max_when_value_exceeds=False` to disable it and use `default_color`
instead.

**Lower is better, higher is worse.** The exclusive comparison matters
most when a badge shows a metric where lower values are good, such as
vulnerability or code-quality counts, because a value exactly equal to a
threshold has not reached the next level of "goodness". For example, with
0 vulnerabilities being good, and any value of 1 or more being bad:

```bash
anybadge --label=vulnerabilities --value=4 --file=vulnerabilities.svg --color=red 1=green
```

```mermaid
flowchart LR
    A([badge value]) --> B{"value < 1?"}
    B -- "yes (0)" --> G2[green]
    B -- "no (1+)" --> R2[red]

    classDef green fill:#4c1,color:#000
    classDef red fill:#e05d44,color:#fff
    class G2 green
    class R2 red
```

Here the fixed `--color=red` is used as the default color for values that
do not fall below the single threshold, so a badge value of 0 is green,
and any value of 1 or more is red. The same badge can be created in
Python with:

```python
badge = Badge(
    label='vulnerabilities',
    value=4,
    default_color='red',
    thresholds={1: 'green'},
    use_max_when_value_exceeds=False,
)
```

### Built-in templates

Some common badge types have been built in to save you from having to
specify thresholds, a label, and a value suffix each time. To use one of
these built-ins, specify the template name in place of threshold
value/color pairs:

```bash
anybadge --value=<VALUE> --file=<FILE> <TEMPLATE-NAME>
```

| Template | Label      | Value suffix | Thresholds                           | Colors produced                                                              |
| -------- | ---------- | ------------ | ------------------------------------ | ---------------------------------------------------------------------------- |
| pylint   | `pylint`   | (none)       | 2=red 4=orange 8=yellow 10=green     | less than 2 = red, less than 4 = orange, less than 8 = yellow, 10 and above = green |
| coverage | `coverage` | `%`          | 50=red 60=orange 80=yellow 100=green | less than 50 = red, less than 60 = orange, less than 80 = yellow, 100 and above = green |

For example:

```bash
anybadge --value=2.22 --file=pylint.svg pylint
```

Any badge can also be customized with a different style using
`--style=gitlab-scoped`, or with a custom SVG template file using
`--template <path>`.

### Colors

Anybadge comes with some pre-defined colors, which can be referred to by name.  It also
supports the use of custom colors by using the hex representation of the color.  Both color
types can be used in the `default_color`, `text_color` and `thresholds` attributes. Color names are
taken from the [Mozilla color keywords list](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/color_keywords).

Here is a Python example showing use of a named color and a custom color.

```python
import anybadge

badge = anybadge.Badge(label='custom color', value='teal', default_color='teal', num_padding_chars=1)
badge = anybadge.Badge(label='custom color', value='teal', default_color='#008080', num_padding_chars=1)
```

Available named colors are:

| Color Name    | Hex     | Example |
| ------------- | ------- | ------- |
| aliceblue     | #F0F8FF | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_aliceblue.svg)    |
| antiquewhite  | #FAEBD7 | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_antiquewhite.svg) |
| aqua          | #00FFFF | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_aqua.svg)         |
| aquamarine    | #7FFFD4 | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_aquamarine.svg)   |
| azure         | #F0FFFF | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_azure.svg)        |
| beige         | #F5F5DC | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_beige.svg)        |
| bisque        | #FFE4C4 | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_bisque.svg)       |
| black         | #000000 | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_black.svg)        |
| blanchedalmond | #FFEBCD | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_blanchedalmond.svg)|
| blue          | #0000FF | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_blue.svg)         |
| blueviolet    | #8A2BE2 | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_blueviolet.svg)   |
| bright_red    | #FF0000 | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_bright_red.svg)   |
| bright_yellow | #FFFF00 | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_bright_yellow.svg)|
| brown         | #A52A2A | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_brown.svg)        |
| burlywood     | #DEB887 | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_burlywood.svg)    |
| cadetblue     | #5F9EA0 | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_cadetblue.svg)    |
| chartreuse    | #7FFF00 | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_chartreuse.svg)   |
| chocolate     | #D2691E | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_chocolate.svg)    |
| coral         | #FF7F50 | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_coral.svg)        |
| cornflowerblue | #6495ED | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_cornflowerblue.svg)|
| cornsilk      | #FFF8DC | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_cornsilk.svg)     |
| crimson       | #DC143C | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_crimson.svg)      |
| darkblue      | #00008B | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_darkblue.svg)     |
| darkcyan      | #008B8B | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_darkcyan.svg)     |
| darkgoldenrod | #B8860B | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_darkgoldenrod.svg)|
| darkgray      | #A9A9A9 | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_darkgray.svg)     |
| darkgreen     | #006400 | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_darkgreen.svg)    |
| darkkhaki     | #BDB76B | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_darkkhaki.svg)    |
| darkmagenta   | #8B008B | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_darkmagenta.svg)  |
| darkolivegreen | #556B2F | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_darkolivegreen.svg)|
| darkorange    | #FF8C00 | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_darkorange.svg)   |
| darkorchid    | #9932CC | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_darkorchid.svg)   |
| darkred       | #8B0000 | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_darkred.svg)      |
| darksalmon    | #E9967A | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_darksalmon.svg)   |
| darkseagreen  | #8FBC8F | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_darkseagreen.svg) |
| darkslateblue | #483D8B | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_darkslateblue.svg)|
| darkslategray | #2F4F4F | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_darkslategray.svg)|
| darkturquoise | #00CED1 | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_darkturquoise.svg)|
| darkviolet    | #9400D3 | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_darkviolet.svg)   |
| deeppink      | #FF1493 | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_deeppink.svg)     |
| deepskyblue   | #00BFFF | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_deepskyblue.svg)  |
| dimgray       | #696969 | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_dimgray.svg)      |
| dodgerblue    | #1E90FF | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_dodgerblue.svg)   |
| firebrick     | #B22222 | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_firebrick.svg)    |
| floralwhite   | #FFFAF0 | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_floralwhite.svg)  |
| forestgreen   | #228B22 | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_forestgreen.svg)  |
| fuchsia       | #FF00FF | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_fuchsia.svg)      |
| gainsboro     | #DCDCDC | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_gainsboro.svg)    |
| ghostwhite    | #F8F8FF | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_ghostwhite.svg)   |
| gold          | #FFD700 | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_gold.svg)         |
| goldenrod     | #DAA520 | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_goldenrod.svg)    |
| gray          | #808080 | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_gray.svg)         |
| green         | #4C1    | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_green.svg)        |
| greenyellow   | #ADFF2F | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_greenyellow.svg)  |
| green_2       | #008000 | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_green_2.svg)      |
| honeydew      | #F0FFF0 | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_honeydew.svg)     |
| hotpink       | #FF69B4 | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_hotpink.svg)      |
| indianred     | #CD5C5C | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_indianred.svg)    |
| indigo        | #4B0082 | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_indigo.svg)       |
| ivory         | #FFFFF0 | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_ivory.svg)        |
| khaki         | #F0E68C | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_khaki.svg)        |
| lavender      | #E6E6FA | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_lavender.svg)     |
| lavenderblush | #FFF0F5 | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_lavenderblush.svg)|
| lawngreen     | #7CFC00 | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_lawngreen.svg)    |
| lemonchiffon  | #FFFACD | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_lemonchiffon.svg) |
| lightblue     | #ADD8E6 | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_lightblue.svg)    |
| lightcoral    | #F08080 | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_lightcoral.svg)   |
| lightcyan     | #E0FFFF | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_lightcyan.svg)    |
| lightgoldenrodyellow | #FAFAD2 | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_lightgoldenrodyellow.svg)|
| lightgray     | #D3D3D3 | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_lightgray.svg)    |
| lightgreen    | #90EE90 | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_lightgreen.svg)   |
| lightpink     | #FFB6C1 | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_lightpink.svg)    |
| lightsalmon   | #FFA07A | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_lightsalmon.svg)  |
| lightseagreen | #20B2AA | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_lightseagreen.svg)|
| lightskyblue  | #87CEFA | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_lightskyblue.svg) |
| lightslategray | #778899 | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_lightslategray.svg)|
| lightsteelblue | #B0C4DE | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_lightsteelblue.svg)|
| lightyellow   | #FFFFE0 | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_lightyellow.svg)  |
| light_grey    | #9F9F9F | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_light_grey.svg)   |
| lime          | #00FF00 | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_lime.svg)         |
| limegreen     | #32CD32 | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_limegreen.svg)    |
| linen         | #FAF0E6 | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_linen.svg)        |
| maroon        | #800000 | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_maroon.svg)       |
| mediumaquamarine | #66CDAA | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_mediumaquamarine.svg)|
| mediumblue    | #0000CD | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_mediumblue.svg)   |
| mediumorchid  | #BA55D3 | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_mediumorchid.svg) |
| mediumpurple  | #9370DB | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_mediumpurple.svg) |
| mediumseagreen | #3CB371 | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_mediumseagreen.svg)|
| mediumslateblue | #7B68EE | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_mediumslateblue.svg)|
| mediumspringgreen | #00FA9A | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_mediumspringgreen.svg)|
| mediumturquoise | #48D1CC | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_mediumturquoise.svg)|
| mediumvioletred | #C71585 | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_mediumvioletred.svg)|
| midnightblue  | #191970 | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_midnightblue.svg) |
| mintcream     | #F5FFFA | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_mintcream.svg)    |
| mistyrose     | #FFE4E1 | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_mistyrose.svg)    |
| moccasin      | #FFE4B5 | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_moccasin.svg)     |
| navajowhite   | #FFDEAD | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_navajowhite.svg)  |
| navy          | #000080 | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_navy.svg)         |
| oldlace       | #FDF5E6 | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_oldlace.svg)      |
| olive         | #808000 | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_olive.svg)        |
| olivedrab     | #6B8E23 | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_olivedrab.svg)    |
| orange        | #FE7D37 | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_orange.svg)       |
| orangered     | #FF4500 | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_orangered.svg)    |
| orange_2      | #FFA500 | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_orange_2.svg)     |
| orchid        | #DA70D6 | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_orchid.svg)       |
| palegoldenrod | #EEE8AA | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_palegoldenrod.svg)|
| palegreen     | #98FB98 | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_palegreen.svg)    |
| paleturquoise | #AFEEEE | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_paleturquoise.svg)|
| palevioletred | #DB7093 | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_palevioletred.svg)|
| papayawhip    | #FFEFD5 | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_papayawhip.svg)   |
| peachpuff     | #FFDAB9 | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_peachpuff.svg)    |
| peru          | #CD853F | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_peru.svg)         |
| pink          | #FFC0CB | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_pink.svg)         |
| plum          | #DDA0DD | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_plum.svg)         |
| powderblue    | #B0E0E6 | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_powderblue.svg)   |
| purple        | #800080 | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_purple.svg)       |
| rebeccapurple | #663399 | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_rebeccapurple.svg)|
| red           | #E05D44 | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_red.svg)          |
| rosybrown     | #BC8F8F | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_rosybrown.svg)    |
| royalblue     | #4169E1 | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_royalblue.svg)    |
| saddlebrown   | #8B4513 | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_saddlebrown.svg)  |
| salmon        | #FA8072 | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_salmon.svg)       |
| sandybrown    | #F4A460 | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_sandybrown.svg)   |
| seagreen      | #2E8B57 | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_seagreen.svg)     |
| seashell      | #FFF5EE | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_seashell.svg)     |
| sienna        | #A0522D | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_sienna.svg)       |
| silver        | #C0C0C0 | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_silver.svg)       |
| skyblue       | #87CEEB | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_skyblue.svg)      |
| slateblue     | #6A5ACD | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_slateblue.svg)    |
| slategray     | #708090 | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_slategray.svg)    |
| snow          | #FFFAFA | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_snow.svg)         |
| springgreen   | #00FF7F | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_springgreen.svg)  |
| steelblue     | #4682B4 | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_steelblue.svg)    |
| tan           | #D2B48C | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_tan.svg)          |
| teal          | #008080 | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_teal.svg)         |
| thistle       | #D8BFD8 | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_thistle.svg)      |
| tomato        | #FF6347 | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_tomato.svg)       |
| turquoise     | #40E0D0 | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_turquoise.svg)    |
| violet        | #EE82EE | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_violet.svg)       |
| wheat         | #F5DEB3 | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_wheat.svg)        |
| white         | #FFFFFF | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_white.svg)        |
| whitesmoke    | #F5F5F5 | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_whitesmoke.svg)   |
| yellow        | #DFB317 | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_yellow.svg)       |
| yellowgreen   | #9ACD32 | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_yellowgreen.svg)  |
| yellow_green  | #A4A61D | ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/color_yellow_green.svg) |

### Emojis

It is possible to use emoji characters in badge labels and values. Here are some examples:

![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/pipeline_frown.svg)
![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/pipeline_smile.svg)
![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/documentation_link.svg)
![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/pypi_link.svg)

These files were created by using the **actual** emoji character in the label/value text. For example:

```python
badge = anybadge.Badge(label="Pipeline status", value="😄")
```

If you install the `emoji` extra (`pip install anybadge[emoji]`), you can
instead write `:shortcode:` text in labels and values, and it will be
automatically converted into emoji characters before the badge is rendered.
This is useful in editors and consoles where typing emoji characters is
difficult. Both Unicode CLDR shortcodes and GitHub-style aliases are
supported:

```python
badge = anybadge.Badge(label="Pipeline status", value=":smile:")
# :smile: is a GitHub-style alias for 😄

badge = anybadge.Badge(label="Pipeline status", value=":grinning_face:")
# :grinning_face: is a Unicode CLDR shortcode for 😀
```

See the [emoji package documentation](https://pypi.org/project/emoji/) for the full list of
supported shortcodes. Without the `emoji` package, `:shortcode:` text is rendered
as-is.

Here are the same badges generated with an actual emoji character, with
shortcodes (using the `emoji` package), and with shortcodes where the `emoji`
package is not installed. Note that a badge created with a shortcode renders
exactly the same as one created with the emoji character itself:

| Badge                                                                                                          | Code                                                                                              |
| -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/pipeline_smile.svg)                            | `anybadge.Badge(label="Pipeline status", value="😄")` — actual emoji character                     |
| ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/pipeline_smile_shortcode.svg)                  | `anybadge.Badge(label="Pipeline status", value=":smile:")` — shortcode (requires `emoji` package)  |
| ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/pipeline_smile_without_emoji_package.svg)      | `anybadge.Badge(label="Pipeline status", value=":smile:")` — without `emoji` package: rendered as-is |
| ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/rocket_deploy.svg)                             | `anybadge.Badge(label=":rocket: Deploy", value=":100:")` — shortcodes in label and value           |

Emoji conversion happens before badge dimensions are calculated, so emoji
shortcodes take up exactly the same space as the emoji characters they
produce. Note that the original text is used when matching values against
thresholds, so thresholds should be defined using the text you pass as the
value.

There are some caveats worth mentioning:
- The "look" of the emoji is determined by the client (Emoji characters are placed as-is into the SVG file, and are
  rendered client-side)
- Rendering may fail in some viewers and developer IDEs (for example, PyCharm does not render emojis in the svg viewer)
- Emoji fallback fonts render emoji at a visually smaller size than Latin text at the same font size, so
  anybadge wraps emoji characters in `<tspan>` elements that render them slightly larger, at 3pt above the
  surrounding font size (e.g. 14 when the font size is 11). You can change this with the `emoji_font_size`
  argument, or `--emoji-font-size` on the command line. To render emoji at the surrounding font size without
  the tspan wrapper, pass `emoji_font_size` equal to `font_size`.
- Emojis can have different widths, so the layout may be affected. You can use `num_label_padding_chars` and
  `num_value_padding_chars` to fix (see below)

Here are some examples to show how to use padding to fix layout:

| Badge | Code                                                                 |
| ----- |----------------------------------------------------------------------|
| ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/pipeline_smile.svg) | `anybadge.Badge("Pipeline status", "😄")` |
| ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/pipeline_smile_padding.svg) | `anybadge.Badge("Pipeline status", "😄", num_value_padding_chars=1)` |

### Logos

Badges can include a logo, positioned next to the label or value. A logo can
be specified as a Simple Icons slug, a local image file path, an http(s)
URL, or a `data:` URI. In all cases the image is **embedded into the badge
as a base64 `data:` URI**, so the generated SVG remains fully
self-contained and never loads anything at view time.

Common project logos are bundled with the package (rendered in white to
match the badge text color), and can be used offline:

`docker` `git` `github` `gitlab` `javascript` `jenkins` `kubernetes`
`linux` `nodejs` `python` `typescript`

Bundled logos are sourced from [Simple Icons](https://simpleicons.org)
and released under a
[CC0 1.0](https://github.com/simple-icons/simple-icons/blob/develop/LICENSE.md)
public domain dedication. All logos remain subject to their respective
brand owners' trademarks and usage guidelines.

| Badge | Code |
| ----- | ---- |
| ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/logo_github_left.svg) | `anybadge.Badge("Stars", "23,414", logo="github")` |
| ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/logo_github_right.svg) | `anybadge.Badge("Stars", "23,414", logo="github", logo_position="right")` |
| ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/logo_python.svg) | `anybadge.Badge("Python", "3.13", logo="python")` |
| ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/logo_docker_pipeline.svg) | `anybadge.Badge("Docker", "passing", logo="docker")` |

Logos that are not bundled can be provided as:

```python
badge = anybadge.Badge(label="Stars", value="23,414", logo="https://cdn.simpleicons.org/github/red")

badge = anybadge.Badge(label="Stars", value="23,414", logo="logos/mysprite.svg")

badge = anybadge.Badge(label="Stars", value="23,414", logo="mysprite",
                       logo_dirs=["logos"])
```

When a Simple Icons slug is given, `logo_color` chooses the icon color for
CDN downloads (e.g. `logo_color="#fff"`); bundled, vendored and local-file
logos use the colors stored in the image file.

#### Using logos in network-gated environments

If badges are generated on a CI runner or server that is gated from the
network, logos can be vendored as files wherever network access is
available, and then used from disk:

```bash
# Where there is network access, download logos into a directory
# (e.g. commit this directory, or pass it between CI jobs):
anybadge fetch-logos python github docker --dir=logos

# Where there is no network access, generate badges using vendored logos:
anybadge --label=stars --value=23414 --logo=github --logos-dir=logos --file=stars.svg
```

The same resolution applies in Python, using the `logo_dirs` argument.

The parameters are also accepted by `anybadge-server`, as `logo`,
`logo_color` and `logo_position` query parameters:

```
http://localhost:8000/?label=Stars&value=23414&logo=github&logo_position=right
```

The server additionally takes a `--logos-dir` argument (repeatable),
which is used to resolve logo names, so a server on a network-gated
host can generate badges containing vendored logos without network
access.

### Value or label only

It is possible to create badges with only a label or only a value. This can be done by passing
an empty string to the appropriate field. Note that either a label or value must be provided.

| Badge                                                                           | Code                                 |
|---------------------------------------------------------------------------------|--------------------------------------|
| ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/label_only.svg) | `anybadge.Badge(label="Label only")` |
| ![](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/value_only.svg) | `anybadge.Badge(value="Value only")` |

### Semantic version support

Anybadge supports semantic versions for value and threshold keys. This supports color-coded
badges based on version numbering. Here are some examples:

```python
badge = Badge(
    label='Version',
    value='3.0.0',
    thresholds={'3.0.0': 'red', '3.2.0': 'orange', '999.0.0': 'green'},
    semver=True
)
```

In the above example the thresholds equate to the following:

* If value is < 3.0.0 then badge will be red.
* If value is < 3.2.0 then badge will be orange.
* If value is < 999.0.0 then badge will be green.

Each threshold entry is used to define the upper bounds of the threshold. If you don't know the
upper bound for your version number threshold you will need to provide an extreme upper bound -
in this example it is `999.0.0`.

### Escaping

Badges are generated as .svg files, which utilize an XML-based markup language. Consequently,
any HTML characters present in badge labels or values must be escaped to ensure proper
representation. If you need to disable escaping, the following options are available:

- Python API
  - `escape_label=False`
  - `escape_value=False`
- CLI
  - `--no-escape-label`
  - `--no-escape-value`

### Examples

#### Pylint using template
```bash
anybadge --value=2.22 --file=pylint.svg pylint
```
![pylint](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/pylint.svg)

#### Pylint using arguments
```bash
anybadge -l pylint -v 2.22 -f pylint.svg 2=red 4=orange 8=yellow 10=green
```
![pylint](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/pylint.svg)

#### Coverage using template
```bash
anybadge --value=65 --file=coverage.svg coverage
```
![coverage](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/coverage.svg)

#### Pipeline, using labeled colors
```bash
anybadge --label=pipeline --value=passing --file=pipeline.svg passing=green failing=red
```
![pipeline](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/pipeline.svg)

#### Badge with fixed color
```bash
anybadge --label=awesomeness --value="110%" --file=awesomeness.svg --color='#97CA00'
```
![awesomeness](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/awesomeness.svg)

#### GitLab Scoped style badge
```bash
anybadge --style=gitlab-scoped --label=Project --value=Archimedes --file=gitlab_scoped.svg --color='#c1115d'
```
![gitlab_scoped](https://cdn.rawgit.com/jongracecox/anybadge/master/examples/gitlab_scoped.svg)

#### Thresholds based on semantic versions
```bash
anybadge --label=Version --value=2.4.5 --file=version.svg 1.0.0=red 2.4.6=orange 2.9.1=yellow 999.0.0=green
```

#### Importing in your own app
```python
from anybadge import Badge

test1 = Badge(
    label,
    value,
    font_name='DejaVu Sans,Verdana,Geneva,sans-serif',
    font_size=11,
    num_padding_chars=0.5,
    template='<?xml version="1.0" encoding="UTF-8"?>\n<svg xmlns="http://www.w3.org/2000/svg" width="{{ badge width }}" height="20">\n    <linearGradient id="b" x2="0" y2="100%">\n        <stop offset="0" stop-color="#bbb" stop-opacity=".1"/>\n        <stop offset="1" stop-opacity=".1"/>\n    </linearGradient>\n    <mask id="a">\n        <rect width="{{ badge width }}" height="20" rx="3" fill="#fff"/>\n    </mask>\n    <g mask="url(#a)">\n        <path fill="#555" d="M0 0h{{ color split x }}v20H0z"/>\n        <path fill="{{ color }}" d="M{{ color split x }} 0h{{ value width }}v20H{{ color split x }}z"/>\n        <path fill="url(#b)" d="M0 0h{{ badge width }}v20H0z"/>\n    </g>\n    <g fill="{{ label text color }}" text-anchor="middle" font-family="{{ font name }}" font-size="{{ font size }}">\n        <text x="{{ label anchor shadow }}" y="15" fill="#010101" fill-opacity=".3">{{ label }}</text>\n        <text x="{{ label anchor }}" y="14">{{ label }}</text>\n    </g>\n    <g fill="{{ value text color }}" text-anchor="middle" font-family="{{ font name }}" font-size="{{ font size }}">\n        <text x="{{ value anchor shadow }}" y="15" fill="#010101" fill-opacity=".3">{{ value }}</text>\n        <text x="{{ value anchor }}" y="14">{{ value }}</text>\n    </g>\n</svg>',
    value_prefix='',
    value_suffix='',
    thresholds=None,
    default_color='#4c1',
    use_max_when_value_exceeds=True,
    value_format=None,
    text_color='#fff'
)

test1.write_badge('test1.svg')
```

### Command-line options

The command line options can be viewed using `anybadge --help`.

Examples
--------

Here are some usage specific command line examples that may save time on defining
thresholds.

Pylint::

```
anybadge.py --value=2.22 --file=pylint.svg pylint
anybadge.py --label=pylint --value=2.22 --file=pylint.svg 2=red 4=orange 8=yellow 10=green
```

Coverage::

```
anybadge.py --value=65 --file=coverage.svg coverage
anybadge.py --label=coverage --value=65 --suffix='%%' --file=coverage.svg 50=red 60=orange 80=yellow 100=green
```

CI Pipeline::

```
anybadge.py --label=pipeline --value=passing --file=pipeline.svg passing=green failing=red
```

Python usage
============

For Python API details you can use the inbuilt documentation:

```python
from anybadge import badge
help(badge)
```
