Module

parser

Recursive descent parser producing typed AST.

Consumes token stream from Lexer and builds typed AST nodes. Produces immutable (frozen) dataclass nodes for thread-safety.

Architecture:

The parser uses a mixin-based design for separation of concerns:

  • TokenNavigationMixin: Token stream traversal
  • InlineParsingMixin: Inline content (emphasis, links, code spans)
  • BlockParsingMixin: Block-level content (paragraphs, lists, tables)

Thread Safety:

Parser produces immutable AST (frozen dataclasses). Safe to share AST across threads.

1Class

Classes

Parser 3 ▼
Recursive descent parser for Markdown. Consumes tokens from Lexer and builds typed AST. A…

Recursive descent parser for Markdown.

Consumes tokens from Lexer and builds typed AST.

Architecture:
    Uses mixin inheritance to separate concerns while maintaining
    a single entry point. Each mixin handles one aspect of the grammar:

  • TokenNavigationMixin: Token stream access, advance, peek

  • InlineParsingMixin: Emphasis, links, code spans, etc.

  • BlockParsingMixin: Lists, tables, code blocks, directives, etc.

    Usage:

    >> parser = Parser("# Hello

    World")

    >> ast = parser.parse() >> ast[0]

    Heading(level=1, children=(Text(content='Hello'),), ...)

    Thread Safety:

    Parser instances are single-use and not thread-safe. Create one per

    parse operation. The resulting AST is immutable and thread-safe.

Methods

parse 0 Sequence[Block] ▼
Parse source into AST blocks. **Thread Safety:** Returns immutable AST (frozen…
def parse(self) -> Sequence[Block]

Parse source into AST blocks.

Thread Safety: Returns immutable AST (frozen dataclasses).

Returns
Sequence[Block] Sequence of Block nodes
Internal Methods 2 ▼
__init__ 2 ▼
Initialize parser with source text.
def __init__(self, source: str, source_file: str | None = None) -> None
Parameters
Name Type Description
source —

Markdown source text
source_file —

Optional source file path for error messages

Default:None
_parse_nested_content 2 tuple[Block, ...] ▼
Parse nested content as blocks (for block quotes, list items). Creates a sub-p…
def _parse_nested_content(self, content: str, location) -> tuple[Block, ...]

Parse nested content as blocks (for block quotes, list items).

Creates a sub-parser to handle nested block-level content while preserving plugin settings and link reference definitions.

Parameters
Name Type Description
content —

The markdown content to parse as blocks
location —

Source location for error reporting
Returns
tuple[Block, ...] Tuple of Block nodes