Module

parser._protocols

Type protocols for parser mixin pattern.

Provides ParserCoreProtocol — a minimal protocol containing only host attributes and frequently-used cross-mixin methods. Individual mixins declare their own requirements via TYPE_CHECKING blocks.

This hybrid approach:

  1. Reduces protocol maintenance from ~75 signatures to ~16
  2. Makes mixins self-documenting (inline declarations show dependencies)
  3. Enables IDE autocomplete and compile-time safety
  4. Has zero runtime cost (protocols erased at runtime)

See: plan/rfc-mixin-protocol-typing.md

1Class

Classes

ParserCoreProtocol 14 ▼
Minimal contract for cross-mixin dependencies. Contains ONLY: 1. Host class attributes (defined in…

Minimal contract for cross-mixin dependencies.

Contains ONLY:

  1. Host class attributes (defined in Parser.init)
  2. Token navigation methods (used by all parsing mixins)
  3. Error handling (used everywhere)

Individual mixin methods are NOT included—mixins declare their own cross-mixin dependencies via inline TYPE_CHECKING declarations.

This protocol is satisfied by the Parser class through structural typing.

Attributes

Name Type Description
_tokens Sequence[Token] —
_pos int —
_name str | None —
_filename str | None —
_source str | None —
_autoescape bool —
_block_stack list[tuple[str, int, int]] —

Methods

Internal Methods 7 ▼
_current 0 Token ▼
Get current token.
property
def _current(self) -> Token
Returns
Token
_peek 1 Token ▼
Peek at token at offset from current position.
def _peek(self, offset: int = 0) -> Token
Parameters
Name Type Description
offset — Default:0
Returns
Token
_advance 0 Token ▼
Advance to next token and return current.
def _advance(self) -> Token
Returns
Token
_expect 1 Token ▼
Expect current token to be of given type.
def _expect(self, token_type: TokenType) -> Token
Parameters
Name Type Description
token_type —
Returns
Token
_match 0 bool ▼
Check if current token matches any of the types.
def _match(self, *types: TokenType) -> bool
Returns
bool
_error 3 ParseError ▼
Create a ParseError with source context and block stack info.
def _error(self, message: str, token: Token | None = None, suggestion: str | None = None) -> ParseError
Parameters
Name Type Description
message —
token — Default:None
suggestion — Default:None
Returns
ParseError
_format_open_blocks 0 str ▼
Format the current block stack for error messages.
def _format_open_blocks(self) -> str
Returns
str