bridge.pipelines.utils.badges module

bridge.pipelines.utils.badges module#

Utilities for constructing and handling badge assets (e.g. Shields.io badges).

class bridge.pipelines.utils.badges.Badge(**data)[source]#

Bases: BaseModel

Representation of a README badge and its Markdown rendering.

Two Badge instances are considered equal if their canonical image URL and link URL match, irrespective of superficial formatting differences in the original Markdown.

Parameters:

  • alt_text (str) – The alternative text for the badge image (used in the Markdown alt field and as a textual fallback).

  • image_url (str) – The URL of the badge image (e.g. a Shields.io badge endpoint).

  • link_url (str | None) – The URL to link to when the badge is clicked. If None, the badge will be rendered as an image without a surrounding link.

  • full_match (str | None) – The original Markdown string representing the badge, if this Badge was created from a parsed README. When set, as_markdown() will return this exact string, preserving original formatting.

alt_text: str#
as_markdown()[source]#

Render the badge as a Markdown-formatted string.

If full_match is set (e.g. when this badge came from a parsed README), that original Markdown string is returned verbatim. This preserves existing formatting and parameter ordering, even if internal fields were canonicalized.

Otherwise, a canonical Markdown representation is generated:

  • If link_url is not None:

    [![alt_text](image_url)](link_url)

  • If link_url is None:

    ![alt_text](image_url)

Returns:

The Markdown representation of the badge.

Return type:

str

full_match: str | None#
image_url: str#
bridge.pipelines.utils.badges.compose_badge(label, message, color, label_color, alt_text, url=None, svg_path=None)[source]#

Construct a Badge with a Shields.io URL and optional embedded SVG logo.

This high-level helper:

  1. Optionally reads an SVG file from svg_path and encodes it as base64.

  2. Builds a Shields.io badge URL with label, message, color, label_color, and the embedded logo (if any).

  3. Instantiates a Badge with alt_text, the generated image_url, and an optional link_url.

  4. Pre-populates the full_match field with the Markdown representation of the badge, so that as_markdown() returns a ready-to-use snippet.

Parameters:

  • label (str) – The text shown on the left-hand side of the badge.

  • message (str) – The text shown on the right-hand side of the badge.

  • color (str) – The color for the right-hand side of the badge (e.g. hex or named).

  • label_color (str) – The color for the label side (left-hand side) of the badge.

  • alt_text (str) – The alternative text for the badge image (used as the alt attribute in Markdown).

  • url (str | None, optional) – The URL to link to when the badge is clicked. If None, the badge is rendered as a plain image without a link.

  • svg_path (str | None, optional) – Filesystem path to an SVG file to embed as a logo in the badge. If None, no logo is embedded.

Returns:

A fully constructed Badge instance with image_url pointing to a Shields.io badge URL and full_match containing the Markdown snippet.

Return type:

Badge

Contents