API Reference

This section documents the Python API for Dataface's internal modules. The codebase is organized into three main stages:

YAML → [COMPILE] → CompiledFace → [EXECUTE] → Data → [RENDER] → Output

Architecture Overview

Compile Stage

The compile stage transforms YAML dataface definitions into normalized, validated CompiledFace objects.

• dataface.core.compile - Parser, validator, normalizer, and compiler

Execute Stage

The execute stage runs queries and retrieves data using adapters for various data sources.

• dataface.core.execute - Query executor and data source adapters

Render Stage

The render stage transforms compiled faces with data into visual output (SVG, HTML, PNG).

• dataface.core.render - Layout engine, Vega-Lite integration, and output rendering

Quick Links

Module	Description	Entry Point
compile	Compile YAML to face	compile(yaml_content)
execute	Execute queries	Executor(face)
render	Render to output	render(face, executor)

Type System

Dataface uses Pydantic models throughout. Key types:

• Input types (dataface.core.compile.types) - Represent YAML structure, allow Optional fields
• Compiled types (dataface.core.compile.compiled_types) - Guaranteed structure after normalization
• Query types (dataface.core.compile.query_types) - Unified query interface (SQL, CSV, HTTP, etc.)

See the Compile Stage documentation for detailed type information.