Execution engine

uptimely.engine executes compiled plans. Configuration and results are separate from the adapters used to access data, resources, and Python callables.

engine

uptimely.engine.engine provides the execution entry point.

Execution engine for portable spec plans.

Engine

Execute an explicit portable plan.

plan instance-attribute

plan = plan

resources instance-attribute

resources = dict(self.plan.plan.resources)

config instance-attribute

config = config or config_module.EngineConfig()

backend instance-attribute

backend = backend or backend_module.PolarsBackend()

resource_resolver instance-attribute

resource_resolver = resource_resolver or backend_module.PlanResourceResolver(self.resources)

callable_loader instance-attribute

callable_loader = callable_loader or backend_module.EntrypointLoader()

bind instance-attribute

bind = bind or {}

execute

execute() -> result_module.ExecutionResult

Execute plan stages and return explicit runtime state and statuses.

config

uptimely.engine.config defines runtime settings.

Runtime configuration for spec plan execution.

EngineConfig dataclass

Runtime configuration supplied to an execution engine.

evaluation and batch_size are reserved and do not currently affect execution.

type class-attribute instance-attribute

type: str = 'python_venv'

definition class-attribute instance-attribute

definition: str | None = None

dataframe class-attribute instance-attribute

dataframe: str = 'polars'

evaluation class-attribute instance-attribute

evaluation: str = 'eager'

batch_size class-attribute instance-attribute

batch_size: int | str | None = None

result

uptimely.engine.result describes execution outputs.

Explicit results returned by plan execution.

ExecutionResult dataclass

Immutable summary and outputs produced by one engine execution.

datasets instance-attribute

datasets: dict[tuple[str, str], object]

calculated_outputs instance-attribute

calculated_outputs: dict[tuple[str, str, str], object]

callable_statuses instance-attribute

callable_statuses: dict[str, CallableStatus]

durations instance-attribute

durations: dict[str, float]

failures instance-attribute

failures: dict[str, str]

plan_version instance-attribute

plan_version: str

backend

uptimely.engine.backend defines adapter protocols and their built-in implementations.

Adapter protocols

Implement these interfaces to customize dataframe operations, resource resolution, or callable loading.

Backend and runtime protocols used by the execution engine.

DataFrameBackend

Bases: Protocol

Operations required by the engine from a dataframe backend.

name instance-attribute

name: str

is_frame

is_frame(value: object) -> bool

column_names

column_names(frame: object) -> list[str]

select

select(frame: object, columns: Sequence[str]) -> object

lazy

lazy(frame: object) -> object

join

join(left: object, right: object, keys: Sequence[str]) -> object

collect

collect(frame: object) -> object

is_duplicated

is_duplicated(frame: object) -> bool

row_count

row_count(frame: object) -> int

same_keys

same_keys(left: object, right: object, keys: Sequence[str]) -> bool

validate_types

validate_types(frame: object, types: Mapping[str, str]) -> None

ResourceResolver

Bases: Protocol

Resolve plan resources needed during execution.

entity_dimensions

entity_dimensions(entity_id: str) -> list[str]

CallableLoader

Bases: Protocol

Load an executable callable from a plan entrypoint.

load

load(entrypoint: str) -> abc.Callable[..., typing.Any]

Built-in adapters

The default implementations use Polars, plan resources, and Python entry points.

Backend and runtime protocols used by the execution engine.

PolarsBackend

Polars implementation of the engine dataframe contract.

name class-attribute instance-attribute

name = 'polars'

is_frame

is_frame(value: object) -> bool

column_names

column_names(frame: object) -> list[str]

select

select(frame: object, columns: Sequence[str]) -> object

lazy

lazy(frame: object) -> object

join

join(left: object, right: object, keys: Sequence[str]) -> object

collect

collect(frame: object) -> object

is_duplicated

is_duplicated(frame: object) -> bool

row_count

row_count(frame: object) -> int

Return the row count without materializing all columns of a lazy frame.

same_keys

same_keys(left: object, right: object, keys: Sequence[str]) -> bool

Compare observation identities without assuming physical row order.

validate_types

validate_types(frame: object, types: Mapping[str, str]) -> None

Check declared logical column types against the returned schema.

PlanResourceResolver

Resolve resources from the portable plan resource mapping.

resources instance-attribute

resources = resources

entity_dimensions

entity_dimensions(entity_id: str) -> list[str]

EntrypointLoader

Default callable loader using the package entrypoint implementation.

load

load(entrypoint: str) -> abc.Callable[..., typing.Any]