# Timenet.builders

## timenet.builders

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`

```
ENTRY_POINT_GROUP = 'timenet.builders'
```

### BuildOptions `dataclass`

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`

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

#### keep\_cache `class-attribute` `instance-attribute`

```
keep_cache: bool = False
```

#### progress `class-attribute` `instance-attribute`

```
progress: ProgressCallback | None = None
```

#### quiet `class-attribute` `instance-attribute`

```
quiet: bool = False
```

### BuilderBackend

Bases: `Protocol`

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

#### build

```
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

```
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

```
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`

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`

```
backend: BuilderBackend
```

#### dataset\_id `instance-attribute`

```
dataset_id: str
```

#### entry `instance-attribute`

```
entry: EntryPoint
```

### InstalledBuilder `dataclass`

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`

```
backend: BuilderBackend
```

#### card `instance-attribute`

```
card: DatasetMetadata
```

#### package `instance-attribute`

```
package: str
```

#### release `property`

```
release: DatasetRef
```

The release that the card declares.

### claims

```
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

```
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

```
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

```
has_backends() -> bool
```

Return whether any installed package registers a builder backend.

### installed\_builder

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