directives

Directive system for Patitas.

Provides extensible block-level markup through the directive syntax:

Key components:

• DirectiveHandler: Protocol for custom directive implementations
• DirectiveOptions: Base class for typed option parsing
• DirectiveContract: Nesting validation rules
• DirectiveRegistry: Handler lookup and registration

Thread Safety:

All components are designed for thread-safety:

• Options are frozen dataclasses
• Contracts are frozen dataclasses
• Registry is immutable after creation
• Handlers must be stateless

Example:

>>> from patitas.directives import DirectiveHandler, DirectiveOptions
>>>
>>> @dataclass(frozen=True, slots=True)
... class VideoOptions(DirectiveOptions):
...     width: int | None = None
...     autoplay: bool = False
...
>>> class VideoDirective:
...     names = ("video",)
...     token_type = "video"
...     options_class = VideoOptions
...
...     def parse(self, name, title, options, content, children, location):
...         return Directive(location, name, title, options, children)
...
...     def render(self, node, rendered_children, sb):
...         sb.append(f'<video src="{node.title}"></video>')