Module

parsing.protocols

Protocols defining the parser mixin contracts.

These protocols formalize the implicit contracts between parser mixins. Each mixin documents "Required Host Attributes/Methods" in its docstring; this module turns those requirements into type-checkable Protocol classes.

Usage:

Mixin methods that call across mixin boundaries annotate ``self`` as the
narrowest protocol they require::

    def _parse_block(self: ParserHost) -> Block | None:
        token = self._current  # type-checked via ParserHost
        ...

Use ``TokenNavHost`` for pure token navigation, ``InlineParsingHost`` for
inline content parsing, ``BlockParsingHost`` for block-level parsing, and
``ParserHost`` when a method needs the full parser surface (config,
container stack, cross-domain dispatch, nesting guards, etc.).

Type checkers (ty) verify that the concrete Parser class satisfies all
protocol requirements at composition time, and that ``self``-typed methods
only touch members the chosen protocol guarantees.

Thread Safety:

Protocols are purely structural -- no runtime overhead. The annotations are
runtime-inert and never change behaviour.
5Classes

Classes

TokenNavHost 6 ▼
Contract for token stream navigation. Provided by: TokenNavigationMixin Required by: BlockParsingC…
Bases: Protocol

Contract for token stream navigation.

Provided by: TokenNavigationMixin Required by: BlockParsingCoreMixin, ListParsingMixin, InlineParsingCoreMixin

Attributes

Name Type Description
_tokens list[Token] —
_tokens_len int —
_pos int —
_current Token | None —
_source str —
_line_starts list[int] | None —
ConfigHost 1 ▼
Contract for parse configuration access. Provided by: Parser (config properties read from a Contex…
Bases: Protocol

Contract for parse configuration access.

Provided by: Parser (config properties read from a ContextVar). Required by: mixins that branch on enabled features or recurse with a nesting guard.

Attributes

Name Type Description
_link_refs dict[str, tuple[str, str]] —
InlineParsingHost 0 ▼
Contract for inline content parsing. Provided by: InlineParsingMixin (composed from core + emphasi…
Bases: TokenNavHost, ConfigHost, Protocol

Contract for inline content parsing.

Provided by: InlineParsingMixin (composed from core + emphasis + links + special) Required by: BlockParsingCoreMixin, ListParsingMixin, and the inline mixins themselves (cross-mixin dispatch within inline parsing).

BlockParsingHost 0 ▼
Contract for block-level parsing. Provided by: BlockParsingMixin (composed from core + list + tabl…
Bases: TokenNavHost, Protocol

Contract for block-level parsing.

Provided by: BlockParsingMixin (composed from core + list + table + directive + footnote) Required by: ListParsingMixin (calls _parse_block for nested content) and the block mixins themselves (cross-mixin dispatch within block parsing).

ParserHost 4 ▼
Full parser contract combining all mixin requirements. The concrete Parser class must satisfy this…
Bases: InlineParsingHost, BlockParsingHost, Protocol

Full parser contract combining all mixin requirements.

The concrete Parser class must satisfy this protocol. Any class that composes TokenNavigationMixin + InlineParsingMixin + BlockParsingMixin and provides the required instance attributes will satisfy this protocol.

Required instance attributes (set in init): _source: str -- original source text _tokens: list[Token] -- token stream from Lexer _tokens_len: int -- cached len(_tokens) for hot loops _pos: int -- current position in token stream _current: Token | None -- current token (or None at end) _line_starts: list[int] | None -- lazy line index (O(log n) lookup) _containers: ContainerStack -- nesting context tracker _link_refs: dict[str, tuple[str, str]] -- link reference definitions _allow_setext_headings: bool -- setext heading control _directive_stack: list[str] -- directive nesting context _nesting_depth: int -- block-container recursion guard

Attributes

Name Type Description
_containers ContainerStack —
_allow_setext_headings bool —
_directive_stack list[str] —
_nesting_depth int —