Python authoring

uptimely.spec.python provides declarations that convert to the spec document model. The sections below follow the authoring modules in the source tree.

For a runnable example, see the analytics project structure.

spec

uptimely.spec.python.spec groups declarations into a PythonSpec definition.

Python-friendly spec declarations.

PythonSpec dataclass

Build a spec document from Python authoring declarations.

entities class-attribute instance-attribute

entities: list[Entity] = dataclasses.field(default_factory=list)

dimensions class-attribute instance-attribute

dimensions: list[Dimension] | dict[str, Dimension] | None = None

name class-attribute instance-attribute

name: str | None = None

iter_datasets

iter_datasets() -> list[dataset_module.Dataset]

Yield all dataset declarations owned by this spec model.

function_catalog

function_catalog() -> spec_model.FunctionCatalog

Collect and merge the function catalog across all entities.

to_model

to_model() -> spec_model.Spec

Return the spec document model without resolving entrypoints.

to_dict

to_dict() -> dict[str, typing.Any]

Return the spec document as a dictionary.

entity

uptimely.spec.python.entity groups related datasets.

Python-friendly entity declaration.

Entity dataclass

A named entity containing datasets and their dimensions.

id instance-attribute

id: str

name instance-attribute

name: str

dimensions instance-attribute

dimensions: list[Dimension]

datasets instance-attribute

datasets: list[Dataset]

description class-attribute instance-attribute

description: str | None = None

to_model

to_model() -> spec_model.Entity

Convert this entity declaration to its JSON model.

dataset

uptimely.spec.python.dataset declares datasets and their features.

Python-friendly dataset declaration.

RowScope dataclass

The conceptual row subset represented by a dataset.

grain class-attribute instance-attribute

grain: str = ''

filtering class-attribute instance-attribute

filtering: str = ''

coverage class-attribute instance-attribute

coverage: str = ''

to_model

to_model() -> spec_model.RowScope

Convert this row scope definition to its document model.

Order dataclass

Declare a logical ordering key, not a required physical sort.

Parameters:

Name	Type	Description	Default
dimension	Reference | str	A dimension reference created by ref.dimension or its $dimensions.<id> reference string used in spec documents.	required
direction	Literal['asc', 'desc']	Ascending (asc) or descending (desc) order.	required

dimension instance-attribute

dimension: Reference | str

direction instance-attribute

direction: Literal['asc', 'desc']

to_model

to_model() -> spec_model.Order

Convert this ordering key to its document model.

Dataset dataclass

A Python declaration of one dataset, its features, and mappings.

id instance-attribute

id: str

features class-attribute instance-attribute

features: list[Feature] = dataclasses.field(default_factory=list)

mappings class-attribute instance-attribute

mappings: list[Mapping] = dataclasses.field(default_factory=list)

description class-attribute instance-attribute

description: str | None = None

row_scope class-attribute instance-attribute

row_scope: RowScope = dataclasses.field(default_factory=RowScope)

order class-attribute instance-attribute

order: list[Order] = dataclasses.field(default_factory=list)

to_model

to_model() -> spec_model.Dataset

Convert this declaration to the Pydantic dataset document model.

function_catalog

function_catalog() -> spec_model.FunctionCatalog

Build the function templates required by this dataset declaration.

dimension

uptimely.spec.python.dimension declares shared dimensions.

Python-friendly dimension declaration.

Dimension dataclass

A reusable dataset-grain identifier.

id instance-attribute

id: str

type instance-attribute

type: str

description class-attribute instance-attribute

description: str | None = None

parent class-attribute instance-attribute

parent: str | None = None

to_model

to_model() -> spec_model.Dimension

Convert this dimension declaration to its JSON model.

feature

uptimely.spec.python.feature declares dataset features and calculations.

Python-friendly dataset feature declarations.

Feature dataclass

Metadata for a dataset feature, independent of how it is produced.

id instance-attribute

id: str

description class-attribute instance-attribute

description: str | None = None

type class-attribute instance-attribute

type: str | None = None

unit class-attribute instance-attribute

unit: str | None = None

to_model

to_model() -> spec_model.Feature

Convert this feature declaration to its JSON model.

mappings

uptimely.spec.python.mappings declares relationships between datasets. It is also exposed as uptimely.spec.mapping.

Python-friendly dataset mapping declarations.

Mapping dataclass

A function binding that produces one or more declared dataset features.

bind instance-attribute

bind: Bind

id class-attribute instance-attribute

id: str | None = None

inputs class-attribute instance-attribute

inputs: list[Reference | str] = dataclasses.field(default_factory=list)

outputs class-attribute instance-attribute

outputs: list[Feature | Reference | str] = dataclasses.field(default_factory=list)

description class-attribute instance-attribute

description: str | None = None

row_context class-attribute instance-attribute

row_context: RowContext | RowContextBinding[Any] | None = None

operation property

operation: FunctionOperation

Return the operation declared by this mapping's function reference.

to_model

to_model() -> spec_model.Mapping

Convert this mapping declaration to its document model.

bind

uptimely.spec.python.bind binds function arguments to declared values.

Python-friendly function bindings.

Bind dataclass

A function reference and its Python-friendly argument bindings.

function instance-attribute

function: FunctionReference

args instance-attribute

args: dict[str, Any]

function_id class-attribute instance-attribute

function_id: str | None = None

bind

bind(function: FunctionReference, /, function_id: str | None = None, **args: Any) -> Bind

Bind named arguments to a function reference.

Parameters:

Name	Type	Description	Default
function	FunctionReference	A reference created with ref.function(callable_or_entrypoint).	required
function_id	str | None	Optional catalog identifier.	None
**args	Any	Actual function arguments, optionally annotated with row context.	{}

Returns:

Type	Description
Bind	A declaration preserving primitive arguments and separate metadata.

Raises:

Type	Description
TypeError	If function is not a reference created with ref.function.

ref

uptimely.spec.python.ref builds references to functions and spec objects.

Function references accept validate_signature, defaulting to True. Conversion preserves it in the function catalog and exported JSON. When False, compilation and documentation do not import the implementation or inspect its signature. Spec-level contracts and declared feature dependencies are still validated, and execution still requires a loadable implementation.

Use an entrypoint string when the implementation must not be imported while loading the Python spec:

ref.function(
    "other_project.functions:calculate",
    operation="vectorize",
    validate_signature=False,
)

Python spec declarations execute during source loading. Do not import an unavailable analytical implementation from the declaration module itself; pass its entrypoint as a string instead.

Python-friendly structural references and reference factories.

FunctionReference dataclass

A function location normalized without importing or executing its module.

module instance-attribute

module: str

name instance-attribute

name: str

operation class-attribute instance-attribute

operation: FunctionOperation | None = None

validate_signature class-attribute instance-attribute

validate_signature: bool = True

entrypoint property

entrypoint: str

Return the entrypoint in module:function format.

Reference dataclass

A Python declaration reference resolved to a structural binding value.

type instance-attribute

type: str

value instance-attribute

value: str

id property

id: Reference

Pass the referenced resource's identifier as a string argument.

dataframe property

dataframe: Reference

Pass a dataset's materialized dataframe as an argument.

to_model

to_model() -> str

Convert this reference to the spec document's reference string format.

function

function(function: Callable[..., object] | str, *, operation: FunctionOperation | None = None, validate_signature: bool = True) -> FunctionReference

Reference a callable or a module:function entrypoint string.

Parameters:

Name	Type	Description	Default
function	Callable[..., object] | str	A named Python callable such as module.calculate, or an entrypoint string such as path/to/module.py:calculate, https://example.org/module.py:calculate, or s3://bucket/module.py:calculate. Creating a reference does not load code; compilation and execution do.	required
operation	FunctionOperation | None	Optional operation metadata for generic mapping declarations.	None
validate_signature	bool	Whether compilation and documentation should inspect the Python signature and validate implementation contracts.	True

Returns:

Type	Description
FunctionReference	A reference containing the module location and function name.

Raises:

Type	Description
TypeError	If the argument is neither callable nor a string, or validate_signature is not a boolean.
ValueError	If the entrypoint is invalid or the callable has no valid module and function name, or if operation is unsupported.

current_dataset

current_dataset() -> Reference

Reference the dataset currently being evaluated.

dataset

dataset(name: str) -> Reference

Reference a dataset by name.

source

source(name: str, attribute: str = 'path') -> str

Reference a runtime-configured source attribute by name.

sink

sink(name: str, attribute: str = 'path') -> str

Reference a runtime-configured sink attribute by name.

feature

feature(name: str) -> Reference

Reference a source or calculated feature by name.

dimension

dimension(name: str) -> Reference

Reference a dataset dimension by name.

row_context

uptimely.spec.python.row_context declares row windows for functions. The runtime value is documented under row context.

Annotate bound values with observation requirements, not function types.

UNBOUNDED module-attribute

UNBOUNDED = row_context.UNBOUNDED

RowContext module-attribute

RowContext = row_context.RowContext

ContextExtent module-attribute

ContextExtent = row_context.ContextExtent

RowContextBinding dataclass

A function argument preserved unchanged alongside its row context.

value instance-attribute

value: T

row_context instance-attribute

row_context: RowContext

time

time(value: T, *, dimension: Reference | str, before: str = '0s', after: str = '0s') -> RowContextBinding[T]

Bind a value with preceding/following fixed-time requirements.

Parameters:

Name	Type	Description	Default
value	T	The original argument, without conversion to a duration.	required
dimension	Reference | str	Datetime dimension along which the window is measured.	required
before	str	Required preceding duration, or UNBOUNDED.	'0s'
after	str	Required following duration, or UNBOUNDED.	'0s'

Returns:

Type	Description
RowContextBinding[T]	A binding annotation that is unwrapped during Spec conversion.

Raises:

Type	Description
ValueError	If an extent is not a supported fixed duration.

steps

steps(value: T, *, dimension: Reference | str, before: CountExtent = 0, after: CountExtent = 0) -> RowContextBinding[T]

Bind a value with integer-coordinate distances, not observation counts.

Parameters:

Name	Type	Description	Default
value	T	The unchanged function argument.	required
dimension	Reference | str	Integer dimension along which distance is measured.	required
before	CountExtent	Preceding coordinate distance, or UNBOUNDED.	0
after	CountExtent	Following coordinate distance, or UNBOUNDED.	0

Returns:

Type	Description
RowContextBinding[T]	The argument annotated with its context requirements.

Raises:

Type	Description
ValueError	If a bound is not a nonnegative integer or UNBOUNDED.

rows

rows(value: T, *, before: CountExtent = 0, after: CountExtent = 0) -> RowContextBinding[T]

Bind a value with ordered observation-count requirements.

Parameters:

Name	Type	Description	Default
value	T	The unchanged function argument.	required
before	CountExtent	Preceding observation count, or UNBOUNDED.	0
after	CountExtent	Following observation count, or UNBOUNDED.	0

Returns:

Type	Description
RowContextBinding[T]	The argument annotated with its context requirements.

Raises:

Type	Description
ValueError	If a bound is not a nonnegative integer or UNBOUNDED.

current

current() -> row_context.RowContext

Declare that only the current observation is required.

dataset

dataset() -> RowContext

Declare that the entire input dataset is required.

conversion

uptimely.spec.python.conversion converts declarations to document model objects. Use api.from_python to convert and semantically validate in one operation.

Convert Python declarations to the spec document format.

Datasets

Datasets = Iterable[Dataset | Dataset] | Mapping[str, Dataset | Dataset]

Entities

Entities = Iterable[Entity | Entity] | Mapping[str, Entity | Entity]

Dimensions

Dimensions = Iterable[Dimension | Dimension] | Mapping[str, Dimension | Dimension]

Functions

Functions = FunctionCatalog | dict[str, FunctionTemplate | dict[str, Any]]

to_dict

to_dict(datasets: Datasets | None = None, functions: Functions | None = None, name: str | None = None, dimensions: Dimensions | None = None, *, entities: Entities | None = None) -> dict[str, typing.Any]

Encode Python declarations using the same codec as JSON file exports.

to_model

to_model(datasets: Datasets | None = None, functions: Functions | None = None, name: str | None = None, dimensions: Dimensions | None = None, *, entities: Entities | None = None) -> spec_model.Spec

Build structural spec without importing function entrypoints.

Parameters:

Name	Type	Description	Default
datasets	Datasets | None	Datasets wrapped in a single entity named after name.	None
functions	Functions | None	Explicit function catalog, or infer it from declarations.	None
name	str | None	Optional spec display name.	None
dimensions	Dimensions | None	Global dimension declarations.	None
entities	Entities | None	Explicit entities, mutually exclusive with datasets.	None

Raises:

Type	Description
ValueError	No declarations were supplied or function definitions conflict.
TypeError	A resource is not a supported declaration or document model.