Module

rendering.plugins.directives.options

Typed option parsing for directives.

Provides DirectiveOptions base class for automatic parsing of directive options with type coercion, validation, and field aliasing.

Architecture:

Subclass DirectiveOptions with typed fields to get automatic:
  • **Parsing from **: option: syntax
  • Type coercion (str -> bool, str -> int, str -> list)
  • Validation (via _allowed_values)
  • Default values
  • Self-documentation

Related:

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

Classes

DirectiveOptions dataclass
Base class for typed directive options. Subclass with typed fields to get automatic: - Parsing fro…
2

Base class for typed directive options.

Subclass with typed fields to get automatic:

  • Parsing from :option: syntax
  • Type coercion (str -> bool, str -> int, str -> list)
  • Validation (via post_init)
  • Default values
  • Self-documentation

Attributes

Name Type Description
_field_aliases ClassVar[dict[str, str]]
_allowed_values ClassVar[dict[str, list[str]]]

Methods 1

from_raw classmethod
Parse raw string options into typed instance. Handles: - Field aliases (:class…
1 DirectiveOptions 
def from_raw(cls, raw_options: dict[str, str]) -> DirectiveOptions

Parse raw string options into typed instance.

Handles:

  • Field aliases (:class: -> css_class)
  • Type coercion (str -> bool, int, list)
  • Validation via _allowed_values and post_init
  • Unknown options are logged and ignored
Parameters 1
raw_options dict[str, str]

Dict from mistune's parse_options()
Returns

DirectiveOptions —

Typed options instance with defaults applied

Internal Methods 1
_coerce_value classmethod
Coerce string value to target type. Supports: - bool: "true", "1", "yes", "" -…
2 Any 
def _coerce_value(cls, value: str, target_type: type) -> Any

Coerce string value to target type.

Supports:

  • bool: "true", "1", "yes", "" -> True; others -> False
  • int: numeric strings
  • float: numeric strings
  • list[str]: comma-separated values
  • str: pass-through
Parameters 2
value str

String value from options
target_type type

Target Python type
Returns

Any —

Coerced value

StyledOptions dataclass
Common options for styled directives. Provides css_class field with :class: alias.
0

Common options for styled directives.

Provides css_class field with :class: alias.

Inherits from DirectiveOptions

Attributes

Name Type Description
css_class str
_field_aliases ClassVar[dict[str, str]]
ContainerOptions dataclass
Options for container-style directives (cards, tabs, etc.). Extends StyledOptions with layout options.
0

Options for container-style directives (cards, tabs, etc.).

Extends StyledOptions with layout options.

Inherits from StyledOptions

Attributes

Name Type Description
columns str
gap str
style str
_allowed_values ClassVar[dict[str, list[str]]]
TitledOptions dataclass
Options for directives with optional title. Extends StyledOptions with icon support.
0

Options for directives with optional title.

Extends StyledOptions with icon support.

Inherits from StyledOptions

Attributes

Name Type Description
icon str