Module

directives.options

Typed options system for directive configuration.

Directive options are parsed from :key: value lines in the directive body. This module provides base classes for type-safe option parsing.

Thread Safety:

All options classes are frozen dataclasses (immutable). Safe to share across threads.

Example:

>>> @dataclass(frozen=True, slots=True)
... class AdmonitionOptions(DirectiveOptions):
...     name: str | None = None
...     class_: str | None = None
...     collapsible: bool = False
...
>>> raw = {"name": "my-note", "collapsible": "true"}
>>> opts = AdmonitionOptions.from_raw(raw)
>>> opts.collapsible

True

8Classes

Classes

DirectiveOptions 3 ▼
Base class for typed directive options. Subclass this to define options for your directive. Option…

Base class for typed directive options.

Subclass this to define options for your directive. Options are automatically parsed from :key: value lines in the directive.

Type coercion is automatic based on type hints:

  • str: Used as-is
  • bool: "true", "yes", "1", "" → True; others → False
  • int: Parsed with int()
  • float: Parsed with float()
  • list[str]: Split by whitespace

Thread Safety: Frozen dataclass ensures immutability for safe sharing.

Attributes

Name Type Description
_aliases ClassVar[dict[str, str]] —

Methods

from_raw 1 Self ▼
Parse raw string options into typed values.
classmethod
def from_raw(cls, raw: dict[str, str]) -> Self
Parameters
Name Type Description
raw —

Dictionary of raw string options from directive
Returns
Self Typed options instance
Internal Methods 1 ▼
_coerce 3 Any ▼
Coerce string value to the target type.
classmethod
def _coerce(cls, value: str, target_type: type, field_name: str) -> Any
Parameters
Name Type Description
value —

Raw string value
target_type —

Target type from type hint
field_name —

Field name for error messages
Returns
Any Coerced value
StyledOptions 2 ▼
Common options for styled directives. Provides standard styling options that most directives suppo…
Bases: DirectiveOptions

Common options for styled directives.

Provides standard styling options that most directives support:

  • class_: Additional CSS classes
  • name: Reference ID/anchor

Attributes

Name Type Description
class_ str | None —
name str | None —
AdmonitionOptions 2 ▼
Options for admonition directives (note, warning, tip, etc.).
Bases: StyledOptions

Options for admonition directives (note, warning, tip, etc.).

Attributes

Name Type Description
collapsible bool —
open bool —
CodeBlockOptions 5 ▼
Options for code-block directive.
Bases: DirectiveOptions

Options for code-block directive.

Attributes

Name Type Description
language str | None —
linenos bool —
lineno_start int —
emphasize_lines str | None —
caption str | None —
ImageOptions 4 ▼
Options for image directive.
Bases: StyledOptions

Options for image directive.

Attributes

Name Type Description
width str | None —
height str | None —
alt str | None —
align str | None —
FigureOptions 2 ▼
Options for figure directive (extends ImageOptions).
Bases: ImageOptions

Options for figure directive (extends ImageOptions).

Attributes

Name Type Description
figwidth str | None —
figclass str | None —
TabSetOptions 1 ▼
Options for tab-set directive.
Bases: StyledOptions

Options for tab-set directive.

Attributes

Name Type Description
sync_group str | None —
TabItemOptions 2 ▼
Options for tab-item directive.
Bases: StyledOptions

Options for tab-item directive.

Attributes

Name Type Description
selected bool —
sync str | None —