# _protocols

URL: /kida/api/parser/_protocols/
Section: parser
Description: 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

---

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

Open LLM text
(/kida/api/parser/_protocols/index.txt)

Share with AI

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

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

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

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

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:

- Reduces protocol maintenance from ~75 signatures to ~16

- Makes mixins self-documenting (inline declarations show dependencies)

- Enables IDE autocomplete and compile-time safety

- 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:

- Host class attributes (defined in Parser.init)

- Token navigation methods (used by all parsing mixins)

- 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`

1

`bool`

▼

Check if current token matches any of the types.

`def _match(self, *types: TokenType) -> bool`

##### Parameters

Name
Type
Description

`*types`
`—`

##### 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`