API¶

    def badges_content(self) -> str:
        """Return the project banner followed by the generated badge groups.

        Returns:
            Markdown containing the banner image and the base badge content.
        """
        return f"""{self.logo_content()}

{super().badges_content()}"""

def image_path(self) -> Path:
    """Return the configured banner file's path.

    Returns:
        Path to the project's banner asset.
    """
    return BannerConfigFile.I.path()

def logo_content(self) -> str:
    """Return a linked Markdown image for the project's banner.

    Returns:
        Markdown linking the banner image to its own file, using the
        project name as its alternative text.
    """
    image_path = self.image_path().as_posix()
    return f"[![{PackageManager.I.project_name()}]({image_path})]({image_path})"

def extension(self) -> str:
    """Return the SVG file extension without a leading dot."""
    return "svg"

def height(self) -> str:
    """Return the stored SVG height, or `"200"` if absent."""
    return self.safe_load_svg().get("@height", "200")

def insert_svg(self, svg: "type[SVGConfigFile]") -> dict[str, Any]:
    """Return `svg`'s content as a nested `<svg>` element.

    The nested element mirrors the loaded root of `svg`, including its
    attributes and children, so this SVG is self-contained and changes to
    `svg` propagate on sync. Its `width`, `height`, and `viewBox` are
    `svg`'s values, and its `x` and `y` place it at this SVG's viewBox
    origin plus half the remaining space, rounded down to integers; these
    five attributes override any same-named attributes of `svg`. The
    inserted dimensions must be integer strings and are used unchanged as
    this SVG's user-space dimensions, so `svg` is not scaled to fit.

    Args:
        svg: The `SVGConfigFile` subclass whose content is inserted. If its
            file does not exist, only the generated attributes are set.

    Returns:
        A dictionary representing a nested `<svg>` element containing
        `svg`'s content, sized to its dimensions and positioned within
        this SVG's viewBox.

    Raises:
        ValueError: If the inserted dimensions are not integer strings or
            the viewBox is not four whitespace-separated integer values.
    """
    x = int(self.view_box_x()) + (
        (int(self.view_box_width()) - int(svg.I.width())) // 2
    )
    y = int(self.view_box_y()) + (
        (int(self.view_box_height()) - int(svg.I.height())) // 2
    )
    return {
        "svg": {
            **svg.I.safe_load_svg(),
            "@x": str(x),
            "@y": str(y),
            "@width": svg.I.width(),
            "@height": svg.I.height(),
            "@viewBox": svg.I.view_box(),
        },
    }

def safe_load_svg(self) -> dict[str, Any]:
    """Return the loaded SVG root, or an empty dict if the file/root is absent."""
    return self.safe_load().get("svg", {})

@abstractmethod
def svg_configs(self) -> dict[str, Any]:
    """Return the SVG-specific configuration dictionary.

    The `_configs` method adds the root `<svg>` element, namespace,
    dimensions, and viewBox. Returned attributes override those defaults.

    Returns:
        A dictionary representing the SVG configuration.
    """

def view_box(self) -> str:
    """Return the stored viewBox, or `"0 0 200 200"` if absent."""
    return self.safe_load_svg().get("@viewBox", "0 0 200 200")

def view_box_attributes(self) -> tuple[str, str, str, str]:
    """Split the viewBox into its four whitespace-separated values.

    Returns:
        Minimum x, minimum y, width, and height, in that order, as strings.

    Raises:
        ValueError: If the viewBox does not contain exactly four
            whitespace-separated values.
    """
    x, y, width, height = self.view_box().split()
    return x, y, width, height

def view_box_height(self) -> str:
    """Return the height of the viewBox."""
    _, _, _, height = self.view_box_attributes()
    return height

def view_box_width(self) -> str:
    """Return the width of the viewBox."""
    _, _, width, _ = self.view_box_attributes()
    return width

def view_box_x(self) -> str:
    """Return the minimum x-coordinate of the viewBox."""
    x, _, _, _ = self.view_box_attributes()
    return x

def view_box_y(self) -> str:
    """Return the minimum y-coordinate of the viewBox."""
    _, y, _, _ = self.view_box_attributes()
    return y

def width(self) -> str:
    """Return the stored SVG width, or `"200"` if absent."""
    return self.safe_load_svg().get("@width", "200")

def extension(self) -> str:
    """Return the XML file extension without a leading dot."""
    return "xml"

def dependencies(self) -> Iterable[type[ConfigFile[Any]]]:
    """Return the logo asset required to construct this badge.

    Returns:
        The logo configuration file, appended to inherited dependencies.
    """
    return (*super().dependencies(), LogoConfigFile)

def parent_path(self) -> Path:
    """Return the directory containing the logo and badge assets.

    Returns:
        Parent directory used by the logo configuration file.
    """
    return LogoConfigFile.I.parent_path()

def stem(self) -> str:
    """Return the filename stem `"badge"`."""
    return "badge"

def dependencies(self) -> Iterable[type[ConfigFile[Any]]]:
    """Return the logo config file as a dependency.

    Returns:
        A tuple of config file classes that must be validated first.
    """
    return (*super().dependencies(), LogoConfigFile)

def parent_path(self) -> Path:
    """Return the documentation assets directory.

    Returns:
        The same directory used by the project logo.
    """
    return LogoConfigFile.I.parent_path()

def stem(self) -> str:
    """Return the banner filename stem."""
    return "banner"

def svg_configs(self) -> dict[str, Any]:
    """Return the logo's SVG content inserted within the banner's viewBox.

    Centering offsets are rounded down to integers by `insert_svg`.

    Returns:
        A dictionary representing a nested `<svg>` element that mirrors
        the logo's content.
    """
    return self.insert_svg(LogoConfigFile)

def view_box(self) -> str:
    """Return the stored viewBox, enlarged to fit the logo if needed.

    The inserted logo is sized in the banner's user units, so the viewBox
    width and height are raised to at least the logo's width and height
    to prevent cropping. The minimum coordinates are kept, and the
    banner's `width` and `height` are unchanged because the viewBox
    scales to them.

    Returns:
        The viewBox as four whitespace-separated integers.

    Raises:
        ValueError: If the stored viewBox does not contain exactly four
            whitespace-separated values, or its size or the logo's
            dimensions are not integers.
    """
    x, y, width, height = super().view_box().split()
    width = max(int(width), int(LogoConfigFile.I.width()))
    height = max(int(height), int(LogoConfigFile.I.height()))
    return f"{x} {y} {width} {height}"

def image_path(self) -> Path:
    """Return the banner path relative to the documentation source directory.

    Returns:
        Documentation-relative path to the configured banner asset.
    """
    return super().image_path().relative_to(DocsBuilder.I.docs_dir())

def parent_path(self) -> Path:
    """Return the documentation assets directory.

    Returns:
        The documentation source directory joined with `"assets"`.
    """
    return DocsBuilder.I.docs_dir() / "assets"

def stem(self) -> str:
    """Return the logo filename stem."""
    return "logo"

def svg_configs(self) -> dict[str, Any]:
    """Return no additional SVG elements or attributes.

    Returns:
        An empty dictionary; the base SVG config supplies the required
        root element, namespace, dimensions, and viewBox, and Pyrig merges
        existing SVG content.
    """
    return {}