Module

parsing.backends.patitas.pool

Thread-local parser and renderer instance pools.

Provides pooling for Parser and HtmlRenderer instances to avoid allocation overhead. Thread-safe via thread-local storage.

Pool Size:

Default: 8 per thread (covers typical parallel template includes)
Override: Set BENGAL_PARSER_POOL_SIZE or BENGAL_RENDERER_POOL_SIZE
environment variables to tune.

Memory Overhead:

~1KB per Parser, ~0.5KB per Renderer = ~12KB per thread with default pool size.

Thread Safety:

Uses threading.local() for per-thread pool isolation.
No locks needed - each thread has its own pool.

RFC: rfc-contextvar-downstream-patterns.md

2Classes

Classes

ParserPool 3 ▼
Thread-local parser instance pool. Reuses Parser instances to avoid allocation overhead. Thread-sa…

Thread-local parser instance pool.

Reuses Parser instances to avoid allocation overhead. Thread-safe via thread-local storage.

Pool Size:

Default: 8 per thread (covers typical parallel template includes)
Override: Set BENGAL_PARSER_POOL_SIZE environment variable

Memory: ~1KB per pooled Parser instance

Usage:

with ParserPool.acquire(content) as parser:
    ast = parser.parse()

Thread Safety:

Each thread has its own pool. No locks needed.

Methods

acquire 2 Iterator[Parser] ▼
Acquire a parser from pool or create new one. **Usage:** with ParserPool.acqui…
classmethod
def acquire(cls, source: str, source_file: str | None = None) -> Iterator[Parser]

Acquire a parser from pool or create new one.

Usage: with ParserPool.acquire(content) as parser: ast = parser.parse()

Performance: Pooling reduces allocation overhead by ~78% for high-volume parsing. On a 1,000-page site, this saves ~2,000 Parser allocations.

Requires: patitas>=0.1.1 (provides Parser._reinit() method)

Parameters
Name Type Description
source —

Markdown source text
source_file —

Optional source file path for error messages

Default:None
Returns
Iterator[Parser]
Internal Methods 2 ▼
_create 2 Parser ▼
Create a new Parser instance.
classmethod
def _create(cls, source: str, source_file: str | None = None) -> Parser
Parameters
Name Type Description
source —
source_file — Default:None
Returns
Parser
_reinit 3 ▼
Reinitialize an existing Parser for reuse.
classmethod
def _reinit(cls, instance: Parser, source: str, source_file: str | None = None) -> None
Parameters
Name Type Description
instance —
source —
source_file — Default:None
RendererPool 3 ▼
Thread-local renderer instance pool. Reuses HtmlRenderer instances to avoid allocation overhead. T…

Thread-local renderer instance pool.

Reuses HtmlRenderer instances to avoid allocation overhead. Thread-safe via thread-local storage.

Pool Size:

Default: 8 per thread
Override: Set BENGAL_RENDERER_POOL_SIZE environment variable

Memory: ~0.5KB per pooled Renderer instance

Usage:

with RendererPool.acquire(source) as renderer:
    html = renderer.render(ast)

Thread Safety:

Each thread has its own pool. No locks needed.

Methods

acquire 4 Iterator[HtmlRenderer] ▼
Acquire a renderer from pool or create new one. **Usage:** with RendererPool.a…
classmethod
def acquire(cls, source: str = '', *, delegate: LexerDelegate | None = None, directive_cache: DirectiveCache | None = None, page_context: Any | None = None) -> Iterator[HtmlRenderer]

Acquire a renderer from pool or create new one.

Usage: with RendererPool.acquire(source) as renderer: html = renderer.render(ast)

Parameters
Name Type Description
source —

Original source buffer for zero-copy extraction

Default:''
delegate —

Optional sub-lexer delegate for ZCLH handoff

Default:None
directive_cache —

Optional cache for rendered directive output

Default:None
page_context —

Optional page context for directives

Default:None
Returns
Iterator[HtmlRenderer]
Internal Methods 2 ▼
_create 4 HtmlRenderer ▼
Create a new HtmlRenderer instance.
classmethod
def _create(cls, source: str = '', *, delegate: LexerDelegate | None = None, directive_cache: DirectiveCache | None = None, page_context: Any | None = None) -> HtmlRenderer
Parameters
Name Type Description
source — Default:''
delegate — Default:None
directive_cache — Default:None
page_context — Default:None
Returns
HtmlRenderer
_reinit 5 ▼
Reinitialize an existing HtmlRenderer for reuse.
classmethod
def _reinit(cls, instance: HtmlRenderer, source: str = '', *, delegate: LexerDelegate | None = None, directive_cache: DirectiveCache | None = None, page_context: Any | None = None) -> None
Parameters
Name Type Description
instance —
source — Default:''
delegate — Default:None
directive_cache — Default:None
page_context — Default:None