anybadge 1.14.0

Simple, flexible badge generator for project badges.

anybadge

Python project for generating badges for your projects

Supports: Python 3.4-3.9 (2.7 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. 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:

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:

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.

Python

Here is the same example implemented in Python code:

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.python.org/pypi/anybadge

You can install the latest release of anybadge using pip:

pip install anybadge

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

Getting help

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

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

Some thresholds have been built in to save time. To use these thresholds you can simply specify the template name instead of threshold value/color pairs.

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

For example:

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

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.

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

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
antiquewhite	#FAEBD7
aqua	#00FFFF
aquamarine	#7FFFD4
azure	#F0FFFF
beige	#F5F5DC
bisque	#FFE4C4
black	#000000
blanchedalmond	#FFEBCD
blue	#0000FF
blueviolet	#8A2BE2
bright_red	#FF0000
bright_yellow	#FFFF00
brown	#A52A2A
burlywood	#DEB887
cadetblue	#5F9EA0
chartreuse	#7FFF00
chocolate	#D2691E
coral	#FF7F50
cornflowerblue	#6495ED
cornsilk	#FFF8DC
crimson	#DC143C
darkblue	#00008B
darkcyan	#008B8B
darkgoldenrod	#B8860B
darkgray	#A9A9A9
darkgreen	#006400
darkkhaki	#BDB76B
darkmagenta	#8B008B
darkolivegreen	#556B2F
darkorange	#FF8C00
darkorchid	#9932CC
darkred	#8B0000
darksalmon	#E9967A
darkseagreen	#8FBC8F
darkslateblue	#483D8B
darkslategray	#2F4F4F
darkturquoise	#00CED1
darkviolet	#9400D3
deeppink	#FF1493
deepskyblue	#00BFFF
dimgray	#696969
dodgerblue	#1E90FF
firebrick	#B22222
floralwhite	#FFFAF0
forestgreen	#228B22
fuchsia	#FF00FF
gainsboro	#DCDCDC
ghostwhite	#F8F8FF
gold	#FFD700
goldenrod	#DAA520
gray	#808080
green	#4C1
greenyellow	#ADFF2F
green_2	#008000
honeydew	#F0FFF0
hotpink	#FF69B4
indianred	#CD5C5C
indigo	#4B0082
ivory	#FFFFF0
khaki	#F0E68C
lavender	#E6E6FA
lavenderblush	#FFF0F5
lawngreen	#7CFC00
lemonchiffon	#FFFACD
lightblue	#ADD8E6
lightcoral	#F08080
lightcyan	#E0FFFF
lightgoldenrodyellow	#FAFAD2
lightgray	#D3D3D3
lightgreen	#90EE90
lightpink	#FFB6C1
lightsalmon	#FFA07A
lightseagreen	#20B2AA
lightskyblue	#87CEFA
lightslategray	#778899
lightsteelblue	#B0C4DE
lightyellow	#FFFFE0
light_grey	#9F9F9F
lime	#00FF00
limegreen	#32CD32
linen	#FAF0E6
maroon	#800000
mediumaquamarine	#66CDAA
mediumblue	#0000CD
mediumorchid	#BA55D3
mediumpurple	#9370DB
mediumseagreen	#3CB371
mediumslateblue	#7B68EE
mediumspringgreen	#00FA9A
mediumturquoise	#48D1CC
mediumvioletred	#C71585
midnightblue	#191970
mintcream	#F5FFFA
mistyrose	#FFE4E1
moccasin	#FFE4B5
navajowhite	#FFDEAD
navy	#000080
oldlace	#FDF5E6
olive	#808000
olivedrab	#6B8E23
orange	#FE7D37
orangered	#FF4500
orange_2	#FFA500
orchid	#DA70D6
palegoldenrod	#EEE8AA
palegreen	#98FB98
paleturquoise	#AFEEEE
palevioletred	#DB7093
papayawhip	#FFEFD5
peachpuff	#FFDAB9
peru	#CD853F
pink	#FFC0CB
plum	#DDA0DD
powderblue	#B0E0E6
purple	#800080
rebeccapurple	#663399
red	#E05D44
rosybrown	#BC8F8F
royalblue	#4169E1
saddlebrown	#8B4513
salmon	#FA8072
sandybrown	#F4A460
seagreen	#2E8B57
seashell	#FFF5EE
sienna	#A0522D
silver	#C0C0C0
skyblue	#87CEEB
slateblue	#6A5ACD
slategray	#708090
snow	#FFFAFA
springgreen	#00FF7F
steelblue	#4682B4
tan	#D2B48C
teal	#008080
thistle	#D8BFD8
tomato	#FF6347
turquoise	#40E0D0
violet	#EE82EE
wheat	#F5DEB3
white	#FFFFFF
whitesmoke	#F5F5F5
yellow	#DFB317
yellowgreen	#9ACD32
yellow_green	#A4A61D

Emojis

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

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

badge = anybadge.Badge(label="Pipeline status", 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)
• 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
	anybadge.Badge("Pipeline status", "😄")
	anybadge.Badge("Pipeline status", "😄", num_value_padding_chars=1)

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:

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.

Examples

Pylint using template

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

Pylint using arguments

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

Coverage using template

anybadge --value=65 --file=coverage.svg coverage

Pipeline, using labeled colors

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

Badge with fixed color

anybadge --label=awesomeness --value="110%" --file=awesomeness.svg --color='#97CA00'

GitLab Scoped style badge

anybadge --style=gitlab-scoped --label=Project --value=Archimedes --file=gitlab_scoped.svg --color='#c1115d'

Thresholds based on semantic versions

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

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:

from anybadge import badge
help(badge)