Module

roles.protocol

RoleHandler protocol for extensible inline markup.

Roles are inline directives using MyST syntax: content Implement the RoleHandler protocol to create custom roles.

Thread Safety:

Handlers must be stateless. All state should be in the AST node or passed as arguments. Multiple threads may call the same handler instance concurrently.

Example:

>>> class KbdRole:
...     names = ("kbd",)
...
...     def parse(self, name, content, location):
...         return Role(location, name, content)
...
...     def render(self, node, sb):
...         sb.append(f'<kbd>{node.content}</kbd>')
3Classes

Classes

RoleHandler 5 ▼
Protocol for role implementations. Roles are inline directives like {ref}`target` or {kbd}`Ctrl+C`…

Protocol for role implementations.

Roles are inline directives like target or Ctrl+C. They produce inline AST nodes rather than block nodes.

Thread Safety: Handlers must be stateless. All mutable state must be in the AST node or passed as arguments. Multiple threads may call the same handler instance concurrently.

Attributes

Name Type Description
names ClassVar[tuple[str, ...]]

Tuple of role names this handler responds to.
token_type ClassVar[str]

Token type identifier for the AST.
Example —

("ref", "doc") for reference roles

Methods

parse 3 Role ▼
Build the role AST node. Called by the parser when a role is encountered in in…
def parse(self, name: str, content: str, location: SourceLocation) -> Role

Build the role AST node.

Called by the parser when a role is encountered in inline content. Return a Role node to include in the AST.

Thread Safety: This method is called from parser context. Must not modify any shared state.

Parameters
Name Type Description
name —

The role name used (e.g., "ref" or "kbd")
content —

The content between backticks
location —

Source location for error messages
Returns
Role A Role node for the AST
render 2 ▼
Render the role to HTML. Called by the renderer when a Role node is encountere…
def render(self, node: Role, sb: StringBuilder) -> None

Render the role to HTML.

Called by the renderer when a Role node is encountered. Append HTML output to the StringBuilder.

Thread Safety: This method may be called concurrently from multiple threads. Must not modify any shared state.

Parameters
Name Type Description
node —

The Role AST node to render
sb —

StringBuilder to append output to
RoleParseOnly 3 ▼
Protocol for roles that only need custom parsing. Use this when default rendering is acceptable bu…

Protocol for roles that only need custom parsing.

Use this when default rendering is acceptable but you need custom AST construction.

Attributes

Name Type Description
names ClassVar[tuple[str, ...]] —
token_type ClassVar[str] —

Methods

parse 3 Role ▼
Build the role AST node.
def parse(self, name: str, content: str, location: SourceLocation) -> Role
Parameters
Name Type Description
name —
content —
location —
Returns
Role
RoleRenderOnly 3 ▼
Protocol for roles that only need custom rendering. Use this when default parsing is acceptable bu…

Protocol for roles that only need custom rendering.

Use this when default parsing is acceptable but you need custom HTML output.

Attributes

Name Type Description
names ClassVar[tuple[str, ...]] —
token_type ClassVar[str] —

Methods

render 2 ▼
Render the role to HTML.
def render(self, node: Role, sb: StringBuilder) -> None
Parameters
Name Type Description
node —
sb —