Timenet.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'

BuildOptions `dataclass` ¶source

Build settings that do not change the files of the release.

Attributes:

Name	Type	Description
`keep_cache`	`bool`	Keep the raw download cache after the build.
`progress`	`ProgressCallback \| None`	The callback for build progress events, or `None`.
`quiet`	`bool`	Suppress output from the backend and its child processes.
`isolation`	`Literal['on', 'off'] \| None`	Use a separate environment (`"on"`), this process (`"off"`), or `TIMENET_ISOLATION` (`None`).

isolation `class-attribute` `instance-attribute` ¶source

isolation: Literal['on', 'off'] | None = None

keep_cache `class-attribute` `instance-attribute` ¶source

keep_cache: bool = False

progress `class-attribute` `instance-attribute` ¶source

progress: ProgressCallback | None = None

quiet `class-attribute` `instance-attribute` ¶source

quiet: bool = False

BuilderBackend ¶source

Bases: Protocol

Define the interface for reading connector cards and building dataset releases.

build ¶source

build(
    release: DatasetRef,
    store: LocalRegistry,
    *,
    force: bool,
    pinned_by: Mapping[DatasetRef, PayloadSource],
    options: BuildOptions,
) -> None

Build the requested dataset version into a local registry.

The local registry must already contain all parents and their payload sources. Publish only if all pinned files keep the same path, size, and checksum.

Parameters:

Name	Type	Description	Default
`release`	`DatasetRef`	The exact dataset ID and version to build.	required
`store`	`LocalRegistry`	The local registry to build into.	required
`force`	`bool`	Rebuild even if `store` already holds the release.	required
`pinned_by`	`Mapping[DatasetRef, PayloadSource]`	The releases that pin files in this release, with their file records.	required
`options`	`BuildOptions`	Build settings, including `options.progress` to receive build events.	required

Raises:

Type	Description
`TimeNetDatasetNotFoundError`	If this backend has no connector for the dataset ID.
`TimeNetVersionUnavailableError`	If the connector declares a different version.
`TimeFFormatError`	If the build omits or changes a pinned file.
`TimeNetBuildError`	If the build fails.

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:dataset_ids.

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.

dataset_ids ¶source

dataset_ids() -> Iterable[str]

List the datasets this backend can build.

Implementations must answer without importing a connector.

Returns:

Type	Description
`Iterable[str]`	The dataset IDs.

Raises:

Type	Description
`TimeNetInvalidCardError`	If a connector card cannot be read.

ConnectorClaim `dataclass` ¶source

A dataset ID and the installed backend that owns it.

Attributes:

Name	Type	Description
`dataset_id`	`str`	The dataset ID.
`backend`	`BuilderBackend`	The first backend that lists the ID.
`entry`	`EntryPoint`	The entry point that registers the backend.

backend `instance-attribute` ¶source

backend: BuilderBackend

dataset_id `instance-attribute` ¶source

dataset_id: str

entry `instance-attribute` ¶source

entry: EntryPoint

InstalledBuilder `dataclass` ¶source

A dataset's build backend and connector card.

Attributes:

Name	Type	Description
`backend`	`BuilderBackend`	The installed backend that builds the dataset.
`card`	`DatasetMetadata`	The dataset's connector card.
`package`	`str`	`"<distribution> <version>"` of the package that registers the backend.

backend `instance-attribute` ¶source

backend: BuilderBackend

card `instance-attribute` ¶source

card: DatasetMetadata

package `instance-attribute` ¶source

package: str

release `property` ¶source

release: DatasetRef

The release that the card declares.

claims ¶source

claims() -> Iterator[ConnectorClaim]

Yield each dataset ID of the installed backends once, owned by the first backend that lists it.

The walk loads each backend only when it reaches its entry point.

Yields:

Type	Description
`ConnectorClaim`	One claim per dataset ID, in the order of the entry points.

declared ¶source

declared(
    dataset_id: str, version: Version | str | None = None
) -> InstalledBuilder

Find a dataset's build backend and check its version.

Parameters:

Name	Type	Description	Default
`dataset_id`	`str`	The dataset ID.	required
`version`	`Version \| str \| None`	The version to build, or `None` for the version that the card declares.	`None`

Returns:

Type	Description
`InstalledBuilder`	The installed builder, whose `release` is the release to build.

Raises:

Type	Description
`TimeNetDatasetNotFoundError`	If no installed connector builds the dataset.
`TimeNetVersionUnavailableError`	If the connector builds another version.
`TimeNetInvalidCardError`	If the dataset's card cannot be read.

find_card ¶source

find_card(dataset_id: str) -> DatasetMetadata | None

Read a dataset's card from the first registered backend that lists it.

Parameters:

Name	Type	Description	Default
`dataset_id`	`str`	The dataset ID.	required

Returns:

Type	Description
`DatasetMetadata \| None`	The card, or `None` if no backend lists the dataset or the backend has no card.

Raises:

Type	Description
`TimeNetInvalidCardError`	If the card cannot be read.

has_backends ¶source

has_backends() -> bool

Return whether any installed package registers a builder backend.

installed_builder ¶source

installed_builder(
    dataset_id: str,
) -> InstalledBuilder | None

Find the first registered backend that lists a dataset, and read its card.

Parameters:

Name	Type	Description	Default
`dataset_id`	`str`	The dataset ID.	required

Returns:

Type	Description
`InstalledBuilder \| None`	The installed builder, or `None` if no backend lists the dataset or the backend has no card for it.

Raises:

Type	Description
`TimeNetInvalidCardError`	If the dataset's card cannot be read.
`TimeNetBuildError`	If no installed distribution declares the entry point of the backend.

Timenet.builders