# protocols

URL: /patitas/api/parsing/protocols/
Section: parsing
Description: 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.

---

> For a complete page index, fetch /patitas/llms.txt.

Open LLM text
(/patitas/api/parsing/protocols/index.txt)

Share with AI

Ask Claude
(https://claude.ai/new?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpatitas%2Fapi%2Fparsing%2Fprotocols%2Findex.txt)

Ask ChatGPT
(https://chatgpt.com/?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpatitas%2Fapi%2Fparsing%2Fprotocols%2Findex.txt)

Ask Gemini
(https://gemini.google.com/app?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpatitas%2Fapi%2Fparsing%2Fprotocols%2Findex.txt)

Ask Copilot
(https://copilot.microsoft.com/?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpatitas%2Fapi%2Fparsing%2Fprotocols%2Findex.txt)

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 (/patitas/api/tokens/#Token)]`

—

`_tokens_len`

`int`

—

`_pos`

`int`

—

`_current`

`Token (/patitas/api/tokens/#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 (/patitas/api/parsing/protocols/#TokenNavHost)`,

`ConfigHost (/patitas/api/parsing/protocols/#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 (/patitas/api/parsing/protocols/#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 (/patitas/api/parsing/protocols/#InlineParsingHost)`,

`BlockParsingHost (/patitas/api/parsing/protocols/#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 (/patitas/api/parsing/containers/#ContainerStack)`

—

`_allow_setext_headings`

`bool`

—

`_directive_stack`

`list[str]`

—

`_nesting_depth`

`int`

—