Skip to content

Builders

timenet.builders source

Builder discovery: how the SDK finds something able to build a dataset the registry lacks.

The SDK cannot import a connectors package (the dependency runs the other way), so a build backend registers itself under the timenet.builders entry-point group instead. This keeps the SDK's whole knowledge of building to one protocol and one lookup, and lets a third-party connector package plug in the same way the first-party one does.

ENTRY_POINT_GROUP module-attribute source

ENTRY_POINT_GROUP = 'timenet.builders'

BuilderBackend source

Bases: Protocol

Something that can build a dataset from its connector.

build source

build(
    dataset_id: str,
    root: Path,
    *,
    force: bool = False,
    build_parents: bool = False,
    fetch_from: str | BaseRegistry | None = None,
    pinned_by: Mapping[DatasetRef, PayloadSource]
    | None = None,
) -> Path

Build the dataset into a registry directory.

Missing parent releases are prepared before the build starts, or the build fails before any download. Each one is reused, copied from fetch_from, or built when build_parents is set. A build with pinned_by publishes the release only if it reproduces each pinned file.

Parameters:

Name Type Description Default
dataset_id str

The dataset id.

 required
root Path

The output registry directory.

 required
force bool

Rebuild even if the version is already built.

 False
build_parents bool

Build missing parent releases from their installed connectors.

 False
fetch_from str | BaseRegistry | None

The registry, or its URI, to copy missing parent releases from.

 None
pinned_by Mapping[DatasetRef, PayloadSource] | None

The releases that already read files of this release, with their pins.

 None

Returns:

Type Description
Path

The committed version directory.

card source

card(dataset_id: str) -> DatasetMetadata | None

Return the card the connector declares, without importing or building it.

A build planner reads the card for a parent's exact version, its own parents, and its access requirement before anything runs. Answer without importing the connector, like :meth:knows.

Parameters:

Name Type Description Default
dataset_id str

The dataset id.

 required

Returns:

Type Description
DatasetMetadata | None

The validated card, or None if the backend has no connector for the id.

Raises:

Type Description
TimeNetInvalidCardError

If the card cannot be read.

declared_version source

declared_version(dataset_id: str) -> str | None

Return the version the connector declares, without importing or building it.

A caller checks a version pin against this before the build runs, so a pin the connector cannot satisfy fails fast instead of after a full build. Answer without importing the connector, like :meth:knows.

Parameters:

Name Type Description Default
dataset_id str

The dataset id.

 required

Returns:

Type Description
str | None

The declared version string, or None if the backend has no connector for the id.

Raises:

Type Description
TimeNetInvalidCardError

If the card of the connector cannot be read.

knows source

knows(dataset_id: str) -> bool

Report whether this backend has a connector for the id.

Implementations must answer without importing the connector: this runs before any connector environment exists.

Parameters:

Name Type Description Default
dataset_id str

The dataset id.

 required

Returns:

Type Description
bool

Whether the backend can build it.

exact_builder source

exact_builder(
    reference: DatasetRef,
) -> BuilderBackend | None

Return the backend that can build exactly this release.

A connector builds only the dataset version that its card declares. So a pinned release can only be built by a connector whose card declares that exact version.

Parameters:

Name Type Description Default
reference DatasetRef

The dataset ID and the version.

 required

Returns:

Type Description
BuilderBackend | None

The backend, or None if no installed backend claims the dataset or its card declares
BuilderBackend | None

another version.

Raises:

Type Description
TimeNetInvalidCardError

If the card of the connector cannot be read.

find_builder source

find_builder(dataset_id: str) -> BuilderBackend | None

Return the first registered backend that claims this dataset id.

Parameters:

Name Type Description Default
dataset_id str

The dataset id.

 required

Returns:

Type Description
BuilderBackend | None

The backend, or None when no installed package claims the id.

find_card source

find_card(dataset_id: str) -> DatasetMetadata | None

Return the card of the installed connector that claims this dataset.

Parameters:

Name Type Description Default
dataset_id str

The dataset id.

 required

Returns:

Type Description
DatasetMetadata | None

The card, or None when no installed package claims the dataset.

Raises:

Type Description
TimeNetInvalidCardError

If the card of the connector cannot be read.