Module

directives.registry

Directive registry for handler lookup and registration.

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

Thread Safety:

DirectiveRegistry is immutable after creation. Safe to share. Use DirectiveRegistryBuilder for mutable construction.

Example:

>>> builder = DirectiveRegistryBuilder()
>>> builder.register(NoteDirective())
>>> builder.register(WarningDirective())
>>> registry = builder.build()
>>> handler = registry.get("note")
2Classes3Functions

Classes

DirectiveRegistry 11 ▼
Immutable registry of directive handlers. Maps directive names to their handlers for lookup during…

Immutable registry of directive handlers.

Maps directive 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[DirectiveHandler, ...] —
_by_name Mapping[str, DirectiveHandler] —
_by_token_type Mapping[str, DirectiveHandler] —

Methods

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

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

Token type identifier (e.g., "admonition")
Returns
DirectiveHandler | None Handler if registered, None otherwise
has 1 bool ▼
Check if directive 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 DirectiveRegistryBuilder to c…
def __init__(self, handlers: tuple[DirectiveHandler, ...], by_name: dict[str, DirectiveHandler], by_token_type: dict[str, DirectiveHandler]) -> None

Initialize registry with pre-built mappings.

Use DirectiveRegistryBuilder 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 directive names.
def __len__(self) -> int
Returns
int
DirectiveRegistryBuilder 5 ▼
Mutable builder for DirectiveRegistry. Use this to register handlers, then call build() to create …

Mutable builder for DirectiveRegistry.

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

Methods

register 1 DirectiveRegistryBuilder ▼
Register a directive handler.
def register(self, handler: DirectiveHandler) -> DirectiveRegistryBuilder
Parameters
Name Type Description
handler —

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

List of handlers to register
Returns
DirectiveRegistryBuilder Self for chaining
build 0 DirectiveRegistry ▼
Build immutable registry from registered handlers.
def build(self) -> DirectiveRegistry
Returns
DirectiveRegistry Immutable DirectiveRegistry
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

_build_default_registry 0 DirectiveRegistry ▼
Build the default registry (internal, not cached).
def _build_default_registry() -> DirectiveRegistry
Returns
DirectiveRegistry
create_default_registry 0 DirectiveRegistry ▼
Get the default directive registry (cached singleton). **Thread Safety:** Retu…
def create_default_registry() -> DirectiveRegistry

Get the default directive registry (cached singleton).

Thread Safety: Returns a cached immutable registry. Safe for concurrent access. Uses lock-protected initialization to prevent import deadlocks in free-threaded Python (3.14t+).

Returns
DirectiveRegistry
create_registry_with_defaults 0 DirectiveRegistryBuilder ▼
Create a builder pre-populated with default directives. **Use this to extend t…
def create_registry_with_defaults() -> DirectiveRegistryBuilder

Create a builder pre-populated with default directives.

Use this to extend the default set with custom directives:

>>> builder = create_registry_with_defaults()

>>> builder.register(MyCustomDirective())
>>> registry = builder.build()
Returns
DirectiveRegistryBuilder