Python Implementation

Relevant source files

Purpose and Scope

This document covers the Python implementation of the dotprompt system, including package structure, core APIs, Pydantic-based type system, and Rust FFI integration. The Python implementation (version 0.1.4) provides both synchronous and asynchronous interfaces with type-safe Pydantic models for prompt templating in Generative AI applications.

For information about other language implementations, see JavaScript Implementation and Go Implementation. For shared concepts across all implementations, see Core Concepts. For testing strategies specific to Python, see Language-Specific Testing.

Package Architecture

Workspace Structure

The Python implementation uses a uv-based workspace containing two primary packages:

Sources: python/pyproject.toml1-190 python/dotpromptz/pyproject.toml1-73

Key Dependencies

The dotpromptz package declares the following core dependencies:

Dependency	Version	Purpose
`dotpromptz-handlebars`	>=0.1.3	Rust-based Handlebars template engine via PyO3
`pydantic[email]`	>=2.10.6	Runtime type validation and data models
`pyyaml`	>=6.0.2	YAML frontmatter parsing
`anyio`	>=4.9.0	Async/sync compatibility layer
`aiofiles`	>=24.1.0	Async file I/O operations
`structlog`	>=25.2.0	Structured logging

Sources: python/dotpromptz/pyproject.toml36-46

Build and Packaging

The Python implementation uses:

uv: Fast Python package manager for dependency resolution
hatchling: Build backend for creating wheel distributions
maturin: Builds the Rust-based handlebarrz package with PyO3 bindings

Sources: python/dotpromptz/pyproject.toml54-59 python/pyproject.toml67-75

Core API: Dotprompt Class

Class Overview

The Dotprompt class in python/dotpromptz/src/dotpromptz/dotprompt.py184-591 is the main entry point for the Python implementation. It extends the Handlebars template engine for use with Generative AI prompts.

Sources: python/dotpromptz/src/dotpromptz/dotprompt.py187-232

Initialization Parameters

The Dotprompt.__init__() method accepts the following parameters:

Parameter	Type	Description
`default_model`	`str \| None`	Default model when not specified in template
`model_configs`	`dict[str, Any] \| None`	Model-specific configuration defaults
`helpers`	`dict[str, HelperFn] \| None`	Custom Handlebars helper functions
`partials`	`dict[str, str] \| None`	Pre-registered partial templates
`tools`	`dict[str, ToolDefinition] \| None`	Static tool definition mappings
`tool_resolver`	`ToolResolver \| None`	Dynamic tool name resolution function
`schemas`	`dict[str, JsonSchema] \| None`	Static schema mappings
`schema_resolver`	`SchemaResolver \| None`	Dynamic schema name resolution function
`partial_resolver`	`PartialResolver \| None`	Dynamic partial name resolution function
`escape_fn`	`EscapeFunction`	HTML escaping strategy (default: NO_ESCAPE)

Sources: python/dotpromptz/src/dotpromptz/dotprompt.py187-213

Primary Methods

parse()

Parses a .prompt file string into a ParsedPrompt object by extracting YAML frontmatter and template body.

Sources: python/dotpromptz/src/dotpromptz/dotprompt.py274-283

compile()

Compiles a prompt template into a reusable PromptFunction. This method:

Parses the source if it's a string
Merges additional metadata if provided
Recursively resolves all partial references
Returns a RenderFunc callable that holds the compiled state

Sources: python/dotpromptz/src/dotpromptz/dotprompt.py301-322

render()

One-shot method that combines compile() and execution. Parses, compiles, and renders a template with the provided data.

Sources: python/dotpromptz/src/dotpromptz/dotprompt.py285-299

render_metadata()

Resolves and merges all metadata without rendering the template. This includes:

Applying model-specific configurations
Resolving tool references to ToolDefinition objects
Expanding Picoschema strings to full JSON Schema

Sources: python/dotpromptz/src/dotpromptz/dotprompt.py324-355

Method Chaining Pattern

The registration methods (define_helper, define_partial, define_tool) all return self, enabling fluent API usage:

Sources: python/dotpromptz/src/dotpromptz/dotprompt.py234-272 python/dotpromptz/tests/dotpromptz/dotprompt_test.py161-184

Type System and Data Models

Pydantic Model Hierarchy

The Python implementation uses Pydantic V2 models for runtime type validation. All models are defined in python/dotpromptz/src/dotpromptz/typing.py1-863

Sources: python/dotpromptz/src/dotpromptz/typing.py179-554

Generic Type Parameters

The Python implementation uses three primary generic type variables:

TypeVar	Bound	Purpose
`ModelConfigT`	None	Model-specific configuration structure (e.g., temperature, top_p)
`VariablesT`	`dict[str, Any]`	Input variables passed to template rendering
`InputT` / `OutputT`	None	Tool request/response payload types

Sources: python/dotpromptz/src/dotpromptz/typing.py166-176

Key Type Definitions

PromptMetadata

Generic container for prompt configuration and metadata:

Sources: python/dotpromptz/src/dotpromptz/typing.py271-308

ParsedPrompt

Extends PromptMetadata with the template string:

Sources: python/dotpromptz/src/dotpromptz/typing.py311-318

Message and Part

Messages represent conversation turns with role and content:

Sources: python/dotpromptz/src/dotpromptz/typing.py497-507 python/dotpromptz/src/dotpromptz/typing.py476

DataArgument

Runtime data provided during rendering:

Sources: python/dotpromptz/src/dotpromptz/typing.py521-534

Document Parsing and Message Generation

Parsing Pipeline

The document parsing system in python/dotpromptz/src/dotpromptz/parse.py1-546 transforms raw .prompt files into structured messages.

Sources: python/dotpromptz/src/dotpromptz/parse.py199-284 python/dotpromptz/src/dotpromptz/parse.py287-344

parse_document()

The parse_document() function in python/dotpromptz/src/dotpromptz/parse.py216-284 performs frontmatter extraction and metadata parsing:

Extract frontmatter: Uses FRONTMATTER_AND_BODY_REGEX to split YAML from template body
Parse YAML: Calls yaml.safe_load() on frontmatter
Separate reserved keywords: Filters fields in RESERVED_METADATA_KEYWORDS list
Process namespaced keys: Converts dotted keys (e.g., genkit.input) into nested objects
Construct ParsedPrompt: Returns Pydantic model with validated metadata and template

Sources: python/dotpromptz/src/dotpromptz/parse.py216-284

Reserved Metadata Keywords

The following frontmatter keys receive special handling:

config, description, ext, input, model, name, output, 
raw, toolDefs, tools, variant, version

Keys containing dots (e.g., genkit.input) are automatically converted to nested structures in the ext field.

Sources: python/dotpromptz/src/dotpromptz/parse.py105-119

to_messages()

The to_messages() function in python/dotpromptz/src/dotpromptz/parse.py287-344 converts rendered template strings into structured Message objects:

Sources: python/dotpromptz/src/dotpromptz/parse.py287-344

Marker Patterns

The parsing system recognizes special markers inserted by helper functions:

Marker Pattern	Regex	Purpose
`<<<dotprompt:role:xxx>>>`	`ROLE_AND_HISTORY_MARKER_REGEX`	Separates messages by role (user, model, tool, system)
`<<<dotprompt:history>>>`	`ROLE_AND_HISTORY_MARKER_REGEX`	Inserts conversation history
`<<<dotprompt:media:url>>>`	`MEDIA_AND_SECTION_MARKER_REGEX`	Embeds media content (image, audio, video)
`<<<dotprompt:section xxx>>>`	`MEDIA_AND_SECTION_MARKER_REGEX`	Creates pending sections for special purposes

Sources: python/dotpromptz/src/dotpromptz/parse.py68-101

Part Parsing

The to_parts() function in python/dotpromptz/src/dotpromptz/parse.py447-458 converts message content into typed Part objects:

MediaPart: Parsed from <<<dotprompt:media:url content_type>>> markers
PendingPart: Parsed from <<<dotprompt:section type>>> markers
TextPart: All other content is treated as plain text

Sources: python/dotpromptz/src/dotpromptz/parse.py447-545

Handlebarrz FFI Architecture

Rust-Python Bridge

The Python implementation leverages native Rust performance through the handlebarrz package, which exposes the handlebars-rust library via PyO3 bindings.

Sources: python/dotpromptz/src/dotpromptz/dotprompt.py67 python/dotpromptz/src/dotpromptz/dotprompt.py214

Handlebars Class API

The Handlebars class from the handlebarrz package provides the following interface:

Method	Signature	Purpose
`__init__`	`(escape_fn: EscapeFunction)`	Creates Handlebars instance with escaping strategy
`register_helper`	`(name: str, fn: HelperFn)`	Registers custom helper function
`register_partial`	`(name: str, source: str)`	Registers partial template
`has_partial`	`(name: str) -> bool`	Checks if partial is registered
`compile`	`(source: str) -> Callable`	Compiles template into callable render function

Sources: python/dotpromptz/src/dotpromptz/dotprompt.py67 python/dotpromptz/src/dotpromptz/dotprompt.py214 python/dotpromptz/src/dotpromptz/dotprompt.py245-260

EscapeFunction Enum

The handlebarrz package provides three escaping strategies:

EscapeFunction.NO_ESCAPE: No HTML escaping (default for AI prompts)
EscapeFunction.HTML: Standard HTML entity escaping
EscapeFunction.JSON: JSON string escaping

Sources: python/dotpromptz/src/dotpromptz/dotprompt.py198

HelperFn Protocol

Custom helpers must match this signature:

Where HelperOptions provides:

params: Positional parameters
hash: Named parameters
data: Context data stack
block: Block content for block helpers

Sources: python/dotpromptz/src/dotpromptz/dotprompt.py67

Performance Characteristics

The Rust backend provides:

Native speed: Handlebars compilation and rendering at native code speeds
GIL avoidance: Template compilation occurs without holding Python's Global Interpreter Lock
Memory efficiency: Zero-copy template storage where possible

Resolvers and Extensibility

Resolver Pattern

The Python implementation uses async-capable resolver functions to lazily load external resources. Resolvers enable separation between prompt definition and resource location.

Sources: python/dotpromptz/src/dotpromptz/typing.py537-544 python/dotpromptz/src/dotpromptz/dotprompt.py446-511

ToolResolver

The ToolResolver type alias in python/dotpromptz/src/dotpromptz/typing.py540 allows both sync and async resolution:

Tool resolution occurs in Dotprompt._resolve_tools() at python/dotpromptz/src/dotpromptz/dotprompt.py446-511:

Check Dotprompt._tools static mapping
If not found and tool_resolver is set, call resolver
Resolve all tools concurrently using anyio.create_task_group()
Populate PromptMetadata.tool_defs with resolved definitions
Leave unresolved tool names in PromptMetadata.tools

Sources: python/dotpromptz/src/dotpromptz/dotprompt.py446-511

SchemaResolver

The SchemaResolver type alias in python/dotpromptz/src/dotpromptz/typing.py537 enables dynamic schema loading:

Schema resolution occurs in Dotprompt._wrapped_schema_resolver() at python/dotpromptz/src/dotpromptz/dotprompt.py428-444:

Check Dotprompt._schemas static mapping
If not found and schema_resolver is set, call resolver
Return resolved JSON Schema or None

Schemas are resolved during Picoschema expansion in _render_picoschema().

Sources: python/dotpromptz/src/dotpromptz/dotprompt.py428-444 python/dotpromptz/src/dotpromptz/dotprompt.py387-426

PartialResolver

The PartialResolver type alias in python/dotpromptz/src/dotpromptz/typing.py543 enables dynamic partial template loading:

Partial resolution occurs in Dotprompt._resolve_partials() at python/dotpromptz/src/dotpromptz/dotprompt.py513-558:

Scan template for partial references using _identify_partials() (regex-based)
Check if partial is already registered in handlebarrz.Handlebars
If not found, call partial_resolver if available
Register resolved partial with define_partial()
Recursively resolve partials within the resolved partial

Sources: python/dotpromptz/src/dotpromptz/dotprompt.py513-558 python/dotpromptz/src/dotpromptz/dotprompt.py108-117

Partial Identification Strategy

Since the Rust-based handlebars library doesn't expose AST visitors, partial references are detected using a regular expression:

This pattern matches Handlebars partial syntax: {{> partialName}}

Sources: python/dotpromptz/src/dotpromptz/dotprompt.py74

RenderFunc: Compiled Prompt Function

PromptFunction Protocol

The PromptFunction protocol in python/dotpromptz/src/dotpromptz/typing.py557-582 defines the interface for compiled prompt callables:

Sources: python/dotpromptz/src/dotpromptz/typing.py557-582

RenderFunc Implementation

The RenderFunc class in python/dotpromptz/src/dotpromptz/dotprompt.py120-182 implements the PromptFunction protocol:

Sources: python/dotpromptz/src/dotpromptz/dotprompt.py120-182

Execution Steps

When a RenderFunc is called at python/dotpromptz/src/dotpromptz/dotprompt.py142-181:

Resolve metadata: Call render_metadata() to merge all configuration
Merge input defaults: Combine default values from options with runtime data.input
Prepare runtime options: Build RuntimeOptions with data.context
Compile template: Call _handlebars.compile() to get render function
Render string: Execute compiled template with merged context
Parse messages: Call to_messages() to structure output
Construct result: Create RenderedPrompt with metadata and messages

Sources: python/dotpromptz/src/dotpromptz/dotprompt.py142-181

Reusability

The RenderFunc object holds compiled template state, enabling efficient reuse:

The expensive compilation step (parsing, partial resolution, Rust template compilation) occurs only once.

Sources: python/dotpromptz/src/dotpromptz/dotprompt.py120-182

Built-in Helpers

Helper Registry

The Python implementation provides built-in helpers defined in dotpromptz.helpers.BUILTIN_HELPERS that are automatically registered during Dotprompt initialization.

Sources: python/dotpromptz/src/dotpromptz/dotprompt.py228-231 python/dotpromptz/src/dotpromptz/dotprompt.py560-580

Helper Descriptions

Helper Name	Purpose	Example Usage
`role`	Inserts role marker to separate messages	`{{role "user"}}`
`history`	Inserts conversation history placeholder	`{{history}}`
`section`	Creates pending part with purpose metadata	`{{section "thinking"}}`
`media`	Embeds media content (image, audio, video)	`{{media url contentType}}`
`json`	Serializes object to JSON string	`{{json myObject}}`
`ifEquals`	Conditional block if values equal	`{{#ifEquals role "user"}}...{{/ifEquals}}`
`unlessEquals`	Inverted conditional block	`{{#unlessEquals role "user"}}...{{/unlessEquals}}`

Sources: python/dotpromptz/src/dotpromptz/helpers.py (referenced but not included in provided files)

Testing Infrastructure

Test Organization

Python tests are organized in python/dotpromptz/tests/dotpromptz/:

tests/
├── dotpromptz/
│   ├── dotprompt_test.py         # Dotprompt class unit tests
│   ├── models_test.py             # Model utility tests
│   ├── parse_test.py              # Document parsing tests
│   ├── picoschema_test.py         # Picoschema conversion tests
│   ├── resolvers_test.py          # Resolver function tests
│   └── spec_test.py               # Cross-language spec tests

Sources: python/dotpromptz/tests/dotpromptz/dotprompt_test.py1-564 python/dotpromptz/tests/dotpromptz/models_test.py1-43

Test Framework Configuration

The workspace uses pytest with the following configuration from python/pyproject.toml53-64:

Setting	Value	Purpose
`asyncio_mode`	`"strict"`	Enforces explicit async fixture/test marking
`asyncio_default_fixture_loop_scope`	`"function"`	Creates new event loop per test
`log_cli`	`true`	Enables console logging during tests
`python_files`	`["*/_test.py"]`	Test file naming pattern

Sources: python/pyproject.toml53-64

Coverage Requirements

The workspace enforces 85% minimum code coverage:

Sources: python/pyproject.toml63-64

Async Test Utilities

The test suite uses pytest-asyncio for async testing:

Sources: python/dotpromptz/tests/dotpromptz/dotprompt_test.py271-323

Mock Usage Patterns

Tests extensively use unittest.mock for isolating dependencies:

Sources: python/dotpromptz/tests/dotpromptz/dotprompt_test.py147-158

Specification Tests

Cross-language behavioral consistency is verified through YAML-based specification tests. The Python implementation generates dynamic test cases from spec/**/*.yaml files.

For details on the specification test system, see Shared Specification Suite.

Sources: python/dotpromptz/tests/dotpromptz/dotprompt_test.py1-28

Summary

The Python implementation provides a type-safe, async-capable prompt templating system with the following key characteristics:

Type Safety: Pydantic V2 models with generic type parameters for model configurations
Performance: Native Rust template rendering via PyO3 bindings (handlebarrz package)
Async Support: Full async/await support using anyio for compatibility
Extensibility: Resolver pattern for tools, schemas, and partials
Testing: 85% coverage requirement with pytest and async test utilities
Package Management: uv-based workspace with dual package structure

The implementation maintains API consistency with the JavaScript reference implementation while leveraging Python-specific features like type hints, async context managers, and Pydantic validation.