Skip to content

Typing Protocols

Structural protocols defining the expected interfaces for: - ORM table classes - CSV-loadable tables - Parquet-loadable tables - serialisable row instances

Protocols allow infrastructure to remain decoupled from concrete base classes.

ORMTableProtocol

Bases: Protocol

Structural protocol for ORM-mapped table classes.

This protocol defines the minimal structural surface expected of SQLAlchemy ORM table classes within orm-loader.

It is intentionally lightweight and model-agnostic, focusing on: - core SQLAlchemy table attributes - primary key introspection - column discovery helpers

This protocol is used for static typing, runtime checks, and to decouple higher-level infrastructure from concrete base classes.

CSVTableProtocol

Bases: ORMTableProtocol, Protocol

Structural protocol for ORM tables that support CSV-based ingestion.

This protocol captures the expected interface for tables that can participate in staged, file-based loading workflows using CSV input.

It defines the contract for: - staging table management - loader selection - CSV ingestion and merging semantics

No assumptions are made about the underlying database or schema.

SerializedTableProtocol

Bases: Protocol

Structural protocol for ORM instances that support stable serialisation.

This protocol defines the expected interface for ORM row instances that can be converted to dictionaries, JSON strings, and deterministic fingerprints.

It is primarily used for typing and interoperability with downstream consumers such as validators, APIs, and audit tooling.