# protocol

URL: /patitas/api/roles/protocol/
Section: roles
Description: RoleHandler protocol for extensible inline markup.

Roles are inline directives using MyST syntax: \{role}`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>')

---

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

Open LLM text
(/patitas/api/roles/protocol/index.txt)

Share with AI

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

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

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

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

Module

#
`roles.protocol`

RoleHandler protocol for extensible inline markup.

Roles are inline directives using MyST syntax: {role}`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+…

Bases:

`Protocol`

Protocol for role implementations.

Roles are inline directives like {ref}`target` (/patitas/api/nodes/#Role) or {kbd}`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 (/patitas/api/nodes/#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 (/patitas/api/nodes/#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…

Bases:

`Protocol`

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 (/patitas/api/nodes/#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 (/patitas/api/nodes/#Role)`

`RoleRenderOnly`

3

▼

Protocol for roles that only need custom rendering.

Use this when default parsing is acceptable bu…

Bases:

`Protocol`

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`
`—`