API Reference

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

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

Architecture Overview

Compile Stage

The compile stage transforms YAML dashboard definitions into normalized, validated CompiledBoard objects.

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

Execute Stage

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

• dataface.execute - Query executor and data source adapters

Render Stage

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

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

Quick Links

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

Type System

Dataface uses Pydantic models throughout. Key types:

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

See the Compile Stage documentation for detailed type information.