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
) -> Path

Build the dataset into a registry directory.

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

Returns:

Type Description
Path

The committed version directory.

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 it 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.

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.