Module

icons

Icon resolver protocol and injection for Patitas.

Provides optional icon support for directives. Icons are rendered as placeholders unless an icon resolver is injected.

Usage:

# With patitas[bengal] or custom resolver
from patitas.icons import set_icon_resolver

def my_resolver(name: str) -> str | None:
    return f'<svg class="icon icon-{name}">...</svg>'

set_icon_resolver(my_resolver)

Without a resolver, directives render without icons (CSS class only).

Thread Safety:

set_icon_resolver() should be called once at application startup,
before any concurrent rendering. The resolver reference is protected
by a lock for safe updates in multi-threaded environments.
1Class4Functions

Classes

IconResolver 1 ▼
Protocol for icon resolvers. Icon resolvers take an icon name and return SVG markup or None if the…
Bases: Protocol

Protocol for icon resolvers.

Icon resolvers take an icon name and return SVG markup or None if the icon is not found.

Methods

Internal Methods 1 ▼
__call__ 1 str | None ▼
Resolve icon name to SVG markup.
def __call__(self, name: str) -> str | None
Parameters
Name Type Description
name —

Icon name (e.g., "github", "warning", "check")
Returns
str | None SVG markup string, or None if icon not found

Functions

set_icon_resolver 1 None ▼
Set the global icon resolver. **Thread Safety:** This function is thread-safe.…
def set_icon_resolver(resolver: Callable[[str], str | None] | None) -> None

Set the global icon resolver.

Thread Safety: This function is thread-safe. However, for best performance, call it once at application startup before concurrent rendering.

Parameters
Name Type Description
resolver Callable[[str], str | None] | None

Function that takes icon name and returns SVG or None. Pass None to clear the resolver.
get_icon 1 str | None ▼
Get icon SVG by name using the global resolver. **Thread Safety:** This functi…
def get_icon(name: str) -> str | None

Get icon SVG by name using the global resolver.

Thread Safety: This function is thread-safe. Reads the resolver reference atomically (GIL-protected simple read).

Parameters
Name Type Description
name str

Icon name
Returns
str | None
get_icon_or_placeholder 1 str ▼
Get icon SVG or a placeholder span.
def get_icon_or_placeholder(name: str) -> str
Parameters
Name Type Description
name str

Icon name
Returns
str
has_icon_resolver 0 bool ▼
Check if an icon resolver is configured.
def has_icon_resolver() -> bool
Returns
bool