# Timenet.sources

## timenet.sources

Find dataset releases across registries and installed connectors.

### Ask `module-attribute`

```
Ask: TypeAlias = Callable[
    [ReleaseSource, str, Version | None], ReleaseLookup
]
```

A function that asks one source for a release: `ask(source, dataset_id, version)`.

### Found `module-attribute`

```
Found: TypeAlias = FoundInRegistry | FoundInConnector
```

A result for a release that a source serves or builds.

### ReleaseLookup `module-attribute`

```
ReleaseLookup: TypeAlias = Found | NotFound | NotServed
```

The result of looking up a release in a source.

### ReleaseSource `module-attribute`

```
ReleaseSource: TypeAlias = Union[
    "BaseRegistry", "InstalledConnectors"
]
```

A source that can serve or build a dataset release: a registry or the installed connectors.

### FoundInConnector `dataclass`

A result for a release that an installed connector builds.

Attributes:

| Name | Type | Description |
| --- | --- | --- |
| `builder` | `InstalledBuilder` | The backend and card that the lookup read. |

#### builder `instance-attribute`

```
builder: InstalledBuilder
```

#### version `property`

```
version: Version
```

The version that the card declares.

### FoundInRegistry `dataclass`

A result for a release that a registry serves.

Attributes:

| Name | Type | Description |
| --- | --- | --- |
| `version` | `Version` | The exact version. |
| `registry` | `BaseRegistry` | The registry that serves the release. |
| `manifest` | `Manifest | None` | The release manifest that the registry read, or `None`. |

#### manifest `class-attribute` `instance-attribute`

```
manifest: Manifest | None = field(
    default=None, compare=False, repr=False
)
```

#### registry `instance-attribute`

```
registry: BaseRegistry
```

#### version `instance-attribute`

```
version: Version
```

### InstalledConnectors `dataclass`

A source for the datasets that installed connectors build.

A connector counts as installed if a package registers it under the `timenet.builders` entry point group. Each
connector provides only the version its card declares, and all instances are equal.

#### has\_catalog `class-attribute`

```
has_catalog: bool = True
```

Whether :meth:`list_datasets` works. It always does for installed connectors.

#### list\_datasets

```
list_datasets() -> list[DatasetMetadata]
```

Return dataset cards from installed connectors without building the datasets.

The first entry point that claims a dataset takes priority.
The method skips unreadable cards and emits a :class:`~timenet.errors.ConnectorCardWarning`.

Returns:

| Type | Description |
| --- | --- |
| `list[DatasetMetadata]` | The cards, sorted by dataset ID. |

Raises:

| Type | Description |
| --- | --- |
| `TimeNetInvalidCardError` | If a backend cannot list its dataset IDs. |

#### resolve

```
resolve(
    dataset_id: str, version: Version | None
) -> ReleaseLookup
```

Check whether an installed connector can build a release.

The lookup uses the first entry point that claims the dataset.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `dataset_id` | `str` | The dataset ID. | *required* |
| `version` | `Version | None` | An exact version, or `None` for the latest version. | *required* |

Returns:

| Type | Description |
| --- | --- |
| `ReleaseLookup` | `FoundInConnector` if a connector builds the requested version, or `NotFound`. |

Raises:

| Type | Description |
| --- | --- |
| `TimeNetInvalidCardError` | If the connector's card cannot be read. |

### NotFound `dataclass`

A result for a release that the source cannot find.

### NotServed `dataclass`

A result for a listed release whose files the source cannot serve.

Attributes:

| Name | Type | Description |
| --- | --- | --- |
| `version` | `Version` | The exact version that the source lists. |
| `access` | `Access` | The strictest access level of the release's card and the cards in its lineage. |
| `requirements` | `tuple[AccessRequirement, ...]` | Each card that is not open access, with its access level and access page. |
| `manifest` | `Manifest | None` | The release manifest, or `None`. |

#### access `instance-attribute`

```
access: Access
```

#### manifest `class-attribute` `instance-attribute`

```
manifest: Manifest | None = field(
    default=None, compare=False, repr=False
)
```

#### requirements `instance-attribute`

```
requirements: tuple[AccessRequirement, ...]
```

#### version `instance-attribute`

```
version: Version
```

#### access\_error

```
access_error(dataset_id: str) -> TimeNetAccessError
```

Create an error with the release's access requirements.

Parameters:

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

Returns:

| Type | Description |
| --- | --- |
| `TimeNetAccessError` | An error with the release, its access level, and its access pages. |

### resolve\_release

```
resolve_release(
    sources: Sequence[ReleaseSource],
    dataset_id: str,
    version: str | None,
    *,
    ask: Ask | None = None,
) -> ReleaseLookup
```

Find a source that provides the requested dataset release.

An exact version comes from the first source that serves it, and no version means the newest version of the first
source that serves the dataset. `"latest"` is the highest version of any source, source order breaks ties, and
source errors stop the search.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `sources` | `Sequence[ReleaseSource]` | The sources, in order. | *required* |
| `dataset_id` | `str` | The dataset ID. | *required* |
| `version` | `str | None` | An exact version, `"latest"`, or `None` or `""` for no version. | *required* |
| `ask` | `Ask | None` | The function that asks one source, or `None` to call the source's `resolve()`. | `None` |

Returns:

| Type | Description |
| --- | --- |
| `ReleaseLookup` | A `Found` result if available, otherwise the first `NotServed` result or `NotFound`. |

Raises:

| Type | Description |
| --- | --- |
| `TimeFValidationError` | If `version` is neither `"latest"` nor a `major.minor.patch` version. |