Module

rendering.plugins.directives.tokens

Typed token structures for directive AST.

Provides DirectiveToken as a typed replacement for ad-hoc dicts, ensuring consistent structure and IDE support across all directives.

Architecture:

DirectiveToken wraps the dict structure expected by mistune's AST,
providing type safety while maintaining full compatibility via to_dict().

Related:

  • bengal/rendering/plugins/directives/base.py: BengalDirective uses these tokens
  • RFC: plan/active/rfc-directive-system-v2.md
View source
1 Class

Classes

DirectiveToken dataclass
Typed AST token for directives. Replaces ad-hoc dicts like: {"type": "dropdown", "attrs": {...…
4

Typed AST token for directives.

Replaces ad-hoc dicts like: {"type": "dropdown", "attrs": {...}, "children": [...]}

Benefits:

  • Type checking catches typos
  • IDE autocomplete for fields
  • Consistent structure across all directives

Attributes

Name Type Description
type str

Token type string (e.g., "dropdown", "step", "tab_item")
attrs dict[str, Any]

Token attributes dict (title, options, etc.)
children list[Any]

Nested tokens (parsed child content)

Methods 4

to_dict
Convert to dict for mistune AST compatibility.
0 dict[str, Any] 
def to_dict(self) -> dict[str, Any]

Convert to dict for mistune AST compatibility.

Returns

dict[str, Any] —

Dict in the format mistune expects:

{"type": str, "attrs": dict, "children": list}

from_dict classmethod
Create from dict (useful for testing and deserialization).
1 DirectiveToken 
def from_dict(cls, data: dict[str, Any]) -> DirectiveToken

Create from dict (useful for testing and deserialization).

Parameters 1
data dict[str, Any]

Dict with "type", optional "attrs", optional "children"
Returns

DirectiveToken —

DirectiveToken instance

with_attrs
Return new token with additional/updated attributes. Useful for adding compute…
0 DirectiveToken 
def with_attrs(self, **extra_attrs: Any) -> DirectiveToken

Return new token with additional/updated attributes.

Useful for adding computed attributes without mutating original.

Returns

DirectiveToken —

New DirectiveToken with merged attrs

with_children
Return new token with different children.
1 DirectiveToken 
def with_children(self, children: list[Any]) -> DirectiveToken

Return new token with different children.

Parameters 1
children list[Any]

New children list
Returns

DirectiveToken —

New DirectiveToken with specified children