loom.etl.runtime¶

Runtime contracts used by executor and backend implementations.

class loom.etl.runtime.TableDiscovery(*args, **kwargs)[source]¶

Bases: Protocol

Protocol for catalog-backed table existence and schema discovery.

Used by ETLCompiler when a catalog is injected at construction time to validate that source and target tables are valid before execution begins.

exists(ref)[source]¶

Return True when the table exists in the catalog.

Parameters:: ref (TableRef) – Logical table reference to check.
Returns:: True when the table is registered.
Return type:: bool

columns(ref)[source]¶

Return table column names in schema order.

Parameters:: ref (TableRef) – Logical table reference.
Returns:: Tuple of column names, or () when unknown.
Return type:: tuple[str, …]

schema(ref)[source]¶

Return full table schema.

Parameters:: ref (TableRef) – Logical table reference.
Returns:: Ordered column schema tuple, or None when table is missing.
Return type:: tuple[ColumnSchema, …] | None

update_schema(ref, schema)[source]¶

Persist table schema after a successful write.

Parameters:

ref (TableRef) – Logical table reference.
schema (tuple[ColumnSchema, ...]) – Authoritative table schema.

Return type:

None

class loom.etl.runtime.SourceReader(*args, **kwargs)[source]¶

Bases: Protocol

Protocol for reading one ETL source specification into a frame.

read(spec, params_instance, /)[source]¶

Read the source and return a frame.

Parameters:

spec (TableSourceSpec | FileSourceSpec | TempSourceSpec | MongoSourceSpec | ClickHouseSourceSpec) – Compiled source specification.
params_instance (Any) – Concrete params for current run.

Returns:

Backend frame type accepted by the step execute() method.

Return type:

Any

class loom.etl.runtime.SQLExecutor(*args, **kwargs)[source]¶

Bases: Protocol

Optional capability protocol for SQL execution over source frames.

execute_sql(frames, query, /)[source]¶

Execute a SQL query against backend frames.

Used by StepSQL execution path in ETLExecutor.

Parameters:

frames (dict[str, Any]) – Alias -> frame mapping from resolved step sources.
query (str) – SQL query text.

Returns:

Backend frame type with query results.

Return type:

Any

class loom.etl.runtime.TargetWriter(*args, **kwargs)[source]¶

Bases: Protocol

Protocol for writing one frame into one ETL target specification.

write(frame, spec, params_instance, /, *, streaming=False, write_ctx=None)[source]¶

Write frame to target.

Parameters:

frame (Any) – Frame returned by step execute().
spec (TargetSpec) – Compiled target specification.
params_instance (Any) – Concrete params for current run.
streaming (bool) – Hint for lazy backends to use streaming materialization.
write_ctx (WriteContext | None) – Execution context for audit-column injection. None disables audit columns regardless of config.

Return type:

None