Module

roles.registry

Role registry for handler lookup and registration.

The registry maps role names to their handlers, enabling extensibility and custom role support.

Thread Safety:

RoleRegistry is immutable after creation. Safe to share. Use RoleRegistryBuilder for mutable construction.

Example:

>>> builder = RoleRegistryBuilder()
>>> builder.register(RefRole())
>>> builder.register(KbdRole())
>>> registry = builder.build()
>>> handler = registry.get("ref")
2Classes1Function

Classes

RoleRegistry 11 ▼
Immutable registry of role handlers. Maps role names to their handlers for lookup during parsing a…

Immutable registry of role handlers.

Maps role names to their handlers for lookup during parsing and rendering.

Thread Safety:

Truly immutable after creation (uses MappingProxyType).
Safe to share across threads.

Attributes

Name Type Description
_handlers tuple[RoleHandler, ...] —
_by_name Mapping[str, RoleHandler] —
_by_token_type Mapping[str, RoleHandler] —

Methods

names 0 frozenset[str] ▼
Get all registered role names.
property
def names(self) -> frozenset[str]
Returns
frozenset[str]
handlers 0 tuple[RoleHandler, ...] ▼
Get all registered handlers.
property
def handlers(self) -> tuple[RoleHandler, ...]
Returns
tuple[RoleHandler, ...]
get 1 RoleHandler | None ▼
Get handler for role name.
def get(self, name: str) -> RoleHandler | None
Parameters
Name Type Description
name —

Role name (e.g., "ref", "kbd")
Returns
RoleHandler | None Handler if registered, None otherwise
get_by_token_type 1 RoleHandler | None ▼
Get handler by token type.
def get_by_token_type(self, token_type: str) -> RoleHandler | None
Parameters
Name Type Description
token_type —

Token type identifier (e.g., "reference")
Returns
RoleHandler | None Handler if registered, None otherwise
has 1 bool ▼
Check if role name is registered.
def has(self, name: str) -> bool
Parameters
Name Type Description
name —
Returns
bool
Internal Methods 3 ▼
__init__ 3 ▼
Initialize registry with pre-built mappings. Use RoleRegistryBuilder to create…
def __init__(self, handlers: tuple[RoleHandler, ...], by_name: dict[str, RoleHandler], by_token_type: dict[str, RoleHandler]) -> None

Initialize registry with pre-built mappings.

Use RoleRegistryBuilder to create instances.

Parameters
Name Type Description
handlers —
by_name —
by_token_type —
__contains__ 1 bool ▼
Support 'name in registry' syntax.
def __contains__(self, name: str) -> bool
Parameters
Name Type Description
name —
Returns
bool
__len__ 0 int ▼
Number of registered role names.
def __len__(self) -> int
Returns
int
RoleRegistryBuilder 5 ▼
Mutable builder for RoleRegistry. Use this to register handlers, then call build() to create an im…

Mutable builder for RoleRegistry.

Use this to register handlers, then call build() to create an immutable registry.

Methods

register 1 RoleRegistryBuilder ▼
Register a role handler.
def register(self, handler: RoleHandler) -> RoleRegistryBuilder
Parameters
Name Type Description
handler —

Handler implementing RoleHandler protocol
Returns
RoleRegistryBuilder Self for chaining
register_all 1 RoleRegistryBuilder ▼
Register multiple handlers.
def register_all(self, handlers: list[RoleHandler]) -> RoleRegistryBuilder
Parameters
Name Type Description
handlers —

List of handlers to register
Returns
RoleRegistryBuilder Self for chaining
build 0 RoleRegistry ▼
Build immutable registry from registered handlers.
def build(self) -> RoleRegistry
Returns
RoleRegistry Immutable RoleRegistry
Internal Methods 2 ▼
__init__ 0 ▼
Initialize empty builder.
def __init__(self) -> None
__len__ 0 int ▼
Number of registered handlers.
def __len__(self) -> int
Returns
int

Functions

create_default_registry 0 RoleRegistry ▼
Create registry with all built-in roles.
def create_default_registry() -> RoleRegistry
Returns
RoleRegistry