# icons

URL: /patitas/api/icons/
Section: api
Description: 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.

---

> For a complete page index, fetch /patitas/llms.txt.

Open LLM text
(/patitas/api/icons/index.txt)

Share with AI

Ask Claude
(https://claude.ai/new?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpatitas%2Fapi%2Ficons%2Findex.txt)

Ask ChatGPT
(https://chatgpt.com/?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpatitas%2Fapi%2Ficons%2Findex.txt)

Ask Gemini
(https://gemini.google.com/app?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpatitas%2Fapi%2Ficons%2Findex.txt)

Ask Copilot
(https://copilot.microsoft.com/?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpatitas%2Fapi%2Ficons%2Findex.txt)

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`