anybadge

You can include emoji characters directly in the label or value strings.

Important Considerations:

• Rendering: The appearance of the emoji depends on the client rendering the SVG. Emojis are embedded as-is.
• Layout: Emojis can have varying widths which may affect the badge layout. Use num_label_padding_chars or num_value_padding_chars to adjust spacing if necessary.
• Compatibility: Some IDEs (like PyCharm) may not render emojis in their built-in SVG viewers.

Python Example:

badge = anybadge.Badge(label="Pipeline status", value="😄", num_value_padding_chars=1)

Unlike many badge tools that require a static color, anybadge uses thresholds to select a color based on the badge value.

When you provide thresholds (e.g., 2=red 4=orange), the utility selects the color associated with the highest threshold that the current value has not yet exceeded. This allows for dynamic coloring of badges (like linting scores or coverage percentages) based on predefined ranges.

You can generate SVG badges from the terminal. By default, the SVG content is written to stdout, which can be redirected to a file. To write directly to a file, use the --file option.

To use built-in thresholds, specify the template name instead of manual threshold/color pairs.

Example: Using a template

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

Example: Manual thresholds

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

Install the anybadge package using pip. This installation provides both the Python library for programmatic badge generation and the anybadge command-line utility.

pip install anybadge

To generate badges programmatically, import anybadge and use the anybadge.Badge class.

1. Define a thresholds dictionary where keys are numeric values and values are color strings.
2. Instantiate anybadge.Badge(label, value, thresholds=thresholds).
3. Call .write_badge(filename) to save the .svg file.

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

Anybadge supports two types of colors for default_color, text_color, and thresholds:

1. Named colors: Uses names from the Mozilla color keywords list (e.g., teal, aliceblue, crimson).
2. Hex codes: Custom colors using hex representation (e.g., #008080).

Python Usage Example:

import anybadge

# Using a named color
badge = anybadge.Badge(label='custom color', value='teal', default_color='teal', num_padding_chars=1)

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

The anybadge.Badge class is the primary interface for generating badges programmatically. You can customize the label, value, font, size, padding, and thresholds.

Core Parameters:

• label: The text displayed as the label.
• value: The numeric or string value.
• font_name: Font family string.
• font_size: Integer font size.
• num_padding_chars: Padding for the label.
• num_value_padding_chars: Padding for the value.
• thresholds: A dictionary mapping values/versions to colors.
• default_color: The color used if no threshold is met.
• template: A custom SVG template string using Jinja2-style placeholders (e.g., {{ label }}).

Example:

from anybadge import Badge

badge = Badge(
    label='Status',
    value='100%',
    default_color='#4c1',
    text_color='#fff'
)
badge.write_badge('status.svg')

Anybadge supports semantic versioning for value and threshold keys when semver=True is enabled. This allows color-coded badges based on version numbers.

Thresholds define the upper bounds of a version range. If a value is less than the threshold, it falls into that color category.

Python Example:

from anybadge import Badge

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

In this example:

• Value < 3.0.0 $\rightarrow$ red
• Value < 3.2.0 $\rightarrow$ orange
• Value < 999.0.0 $\rightarrow$ green

Note: Always provide an extreme upper bound (e.g., 999.0.0) if you do not know the maximum possible version.

Since badges are generated as SVG (XML) files, HTML characters in labels or values are escaped by default. To prevent this, use the following options:

Python API:

• escape_label=False
• escape_value=False

CLI:

• --no-escape-label
• --no-escape-value

You can generate .svg badges directly from the command line. You must specify a label (-l), a value (-v), and an output filename (-f). You can also provide thresholds to automatically determine the badge color based on the value.

Thresholds are provided as pairs of <value>=color. Values can be integers or floats, and colors are specified as strings.

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

The server respects several environment variables for configuration, which can be used instead of or in addition to CLI flags: