# Timenet.client

## timenet.client

Find, inspect, download, and read TimeF datasets.

:class:`TimeNet` checks sources in order and uses :func:`default_sources` by default.

### T `module-attribute`

```
T = TypeVar('T')
```

### TimeNet

Browse, download, and read TimeNet datasets.

#### download

```
download(
    dataset_id: str,
    version: str | None = None,
    *,
    force: bool = False,
    progress: ProgressCallback | None = None,
) -> Path
```

Copy a release and its payload sources into the local registry.

The release resolves as in :meth:`open`, without a build. Missing or damaged releases come from the first
other registry that provides them, with a provenance record that names it.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `dataset_id` | `str` | The dataset ID. | *required* |
| `version` | `str | None` | An exact version, `"latest"`, or `None`, as in :meth:`open`. | `None` |
| `force` | `bool` | Copy the release again, even if the local registry holds a complete copy. | `False` |
| `progress` | `ProgressCallback | None` | Receives step events and byte counts for each copied release. | `None` |

Returns:

| Type | Description |
| --- | --- |
| `Path` | The release directory in the local registry. |

Raises:

| Type | Description |
| --- | --- |
| `TimeFValidationError` | If the sources have no writable local registry. |
| `TimeNetAccessError` | If a required release is only listed or lacks open access in a remote registry. |
| `TimeNetNotBuiltError` | If only installed connectors provide the release. |
| `TimeNetDatasetNotFoundError` | If no registry other than the local registry provides the release. |
| `TimeNetVersionUnavailableError` | If the version is missing and its connector builds another version. |
| `TimeNetMissingParentError` | If no registry provides a missing payload source. |
| `TimeNetVersionConflictError` | If the local registry holds the same release with different files. |
| `TimeNetFileError` | If a stored copy cannot be repaired or a copied file is damaged. |
| `TimeFFormatError` | If a payload source breaks a pin or the payload sources form a cycle. |

#### get\_card

```
get_card(
    dataset_id: str, version: str | None = None
) -> DatasetMetadata
```

Return the card of the release that :meth:`open` reads, without a copy or a build.

The card comes from the manifest or, for an unbuilt release, from the installed connector.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `dataset_id` | `str` | The dataset ID, optionally ending with `@<version>` or `@latest`. | *required* |
| `version` | `str | None` | An exact version, `"latest"`, or `None`, as in :meth:`open`. | `None` |

Returns:

| Type | Description |
| --- | --- |
| `DatasetMetadata` | The release's metadata card. |

Raises:

| Type | Description |
| --- | --- |
| `TimeNetDatasetNotFoundError` | If no source provides the release. |
| `TimeNetVersionUnavailableError` | If the version is unavailable and a connector declares another version. |
| `TimeNetAccessError` | If a registry only lists the release and provides no manifest. |
| `TimeNetInvalidCardError` | If the connector's card is unreadable or invalid. |
| `TimeFValidationError` | If `dataset_id` and `version` both give a version. |

#### get\_manifest

```
get_manifest(
    dataset_id: str, version: str | None = None
) -> Manifest
```

Return the manifest of the release that :meth:`open` reads, without a copy or a build.

For a release that a registry lists but does not serve, return its listed manifest with access links.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `dataset_id` | `str` | The dataset ID, optionally ending with `@<version>` or `@latest`. | *required* |
| `version` | `str | None` | An exact version, `"latest"`, or `None`, as in :meth:`open`. | `None` |

Returns:

| Type | Description |
| --- | --- |
| `Manifest` | The release's manifest. |

Raises:

| Type | Description |
| --- | --- |
| `TimeNetNotBuiltError` | If the release needs a build to create its manifest. |
| `TimeNetDatasetNotFoundError` | If no source provides the release. |
| `TimeNetVersionUnavailableError` | If the version is unavailable and a connector declares another version. |
| `TimeNetAccessError` | If a registry only lists the release and provides no manifest. |
| `TimeNetInvalidCardError` | If the connector's card is unreadable or invalid. |
| `TimeFValidationError` | If `dataset_id` and `version` both give a version. |

#### list

```
list() -> _Metadatas
```

List each dataset at its highest version across all sources, including connector cards.

A listed version can be newer than the one that :meth:`open` reads, which skips a version that a registry
does not serve and, without a version, takes the first source that serves the dataset.
A source without a catalog is left out with a :class:`~timenet.errors.CatalogWarning`. Source errors stop
the call.

Returns:

| Name | Type | Description |
| --- | --- | --- |
| `One` | `_Metadatas` | class:`~timenet.types.DatasetMetadata` per dataset, sorted by dataset ID. |

Raises:

| Type | Description |
| --- | --- |
| `TimeNetNoCatalogError` | If no source has a catalog. |
| `TimeNetInvalidCardError` | If an installed backend cannot list its dataset IDs. |

#### load

```
load(
    dataset_id: str, version: str | None = None
) -> TimeFDataset
```

Read a whole dataset version into memory, with every stored value loaded.

The dataset needs no storage afterwards: its reader is closed before it is returned. For a
large dataset, use :meth:`open` and read what you need instead.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `dataset_id` | `str` | The dataset id. | *required* |
| `version` | `str | None` | An exact version, `"latest"`, or `None`, as in :meth:`open`. | `None` |

Returns:

| Type | Description |
| --- | --- |
| `TimeFDataset` | The dataset with every signal array, time offset, and text value loaded. |

Raises:

| Type | Description |
| --- | --- |
| `TimeNetAccessError` | If a registry lists the version or a payload source but does not serve its files, and no later source provides it. |
| `TimeNetDatasetNotFoundError` | If no source provides the version. |
| `TimeNetVersionUnavailableError` | If no source provides the version, and the installed connector declares another version. The build does not start then. |
| `TimeNetInvalidCardError` | If the card of a connector cannot be read. |
| `TimeNetMissingParentError` | If no source provides a payload source, or a release that a build needs. |
| `TimeNetFileError` | If a release that the call opens in a local registry has a missing file or a file of another size. |
| `TimeFFormatError` | If a payload source differs from the files that the version pins. |
| `TimeNetBuildError` | If a build runs but fails. |

#### open

```
open(
    dataset_id: str, version: str | None = None
) -> TimeFReader
```

Open a dataset version for lazy reads, where it is.

Opening reads the version's manifest, but neither its catalog nor any value. The reader's
reads leave stored values behind value handles unless their load plan names them. Close
the reader after use, or use it as a context manager. Remote backends open payload sources
from their manifests upfront and read payload ranges on demand, reusing complete cached
releases.

The call reads each release where it is, and copies nothing. Without a version, it reads the
newest version of the first source that serves the dataset. An exact version comes from the
first source that serves it, and `"latest"` is the highest version of any source. Each
payload source of the version resolves on its own, at its exact version. If the call builds
the version, the build also needs the declared parents of the version and their payload
sources.

If only `InstalledConnectors()` provides a release, the call builds it into the local registry first.
The call builds a payload source with its own connector, at the exact version of the
source. The build gets the pins of the version. The build runs in staging. It publishes the
source only if it reproduces the pinned files.

A local copy is damaged if its manifest is present but a file is missing or has another
size. The call checks each release that it opens in a local registry before it reads or
builds anything. It never reads past a damaged copy to a later source, and it never builds
a release over a damaged copy.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `dataset_id` | `str` | The dataset id. | *required* |
| `version` | `str | None` | An exact version, `"latest"`, or `None` for no version. | `None` |

Returns:

| Type | Description |
| --- | --- |
| `TimeFReader` | A reader for the version. |

Raises:

| Type | Description |
| --- | --- |
| `TimeNetAccessError` | If a registry lists the version or a payload source but does not serve its files, and no later source provides it. |
| `TimeNetDatasetNotFoundError` | If no source provides the version. The message says which source to add. |
| `TimeNetVersionUnavailableError` | If no source provides the version, and the installed connector declares another version. The build does not start then. |
| `TimeNetInvalidCardError` | If the card of a connector cannot be read. |
| `TimeNetMissingParentError` | If no source provides a payload source, or a release that a build needs. The message says which source to add. |
| `TimeNetFileError` | If a release that the call opens in a local registry has a missing file or a file of another size. If the damaged copy is in the local registry, the message says how to replace it: with the :meth:`download` that copies an intact release from a registry, else with a new build, if an installed connector builds the release. |
| `TimeFFormatError` | If a payload source differs from the files that the version pins, for example because its build does not reproduce them. |
| `TimeNetBuildError` | If a build runs but fails. |

#### open\_torch

```
open_torch(
    dataset_id: str,
    version: str | None = None,
    *,
    load: LoadPlan = ALL_EAGER,
) -> TimeFTorchDataset
```

Open a dataset version as a read-only PyTorch `Dataset` that reads it a batch at a time.

The view holds an open reader from :meth:`open`. Close the view with its `close()`
method, or use it in a `with` block. This method needs the `torch` extra
(`pip install 'timenet[torch]'`). The code imports the torch view lazily, so base users do
not need torch installed.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `dataset_id` | `str` | The dataset id. | *required* |
| `version` | `str | None` | An exact version, `"latest"`, or `None`, as in :meth:`open`. | `None` |
| `load` | `LoadPlan` | The plan that each batch loads with. A text-only plan, for example, skips the arrays of candidate and target Records. | `ALL_EAGER` |

Returns:

| Name | Type | Description |
| --- | --- | --- |
| `A` | `TimeFTorchDataset` | class:`~timenet.torch.TimeFTorchDataset` over a reader of the version, which reads |
|  | `TimeFTorchDataset` | and loads one batch of records at a time. |

#### search

```
search(
    *,
    query: _OrList[str] = None,
    domain: _OrList[Domain] = None,
    task: _OrList[type[Task]] = None,
    license: _OrList[License] = None,
    time_series_spec: _OrList[str] = None,
    dataset_id: _OrList[str] = None,
    tag: _OrList[str] = None,
    limit: int = 100,
) -> _Metadatas
```

Search the rows of :meth:`list`: each dataset at its highest version across all sources.

So the search checks only the highest version of each dataset, and an older version that matches is not found.
A `task` or `time_series_spec` filter reads the manifest of a row only if its card matches, and the search
stops at `limit` matches. Connector cards lack schemas, so they never match these filters.
A source without a catalog is left out with a :class:`~timenet.errors.CatalogWarning`. Source errors stop
the call.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `query` | `_OrList[str]` | Match any term in the name, description, or tags, ignoring case. | `None` |
| `domain` | `_OrList[Domain]` | Match any of these domains. | `None` |
| `task` | `_OrList[type[Task]]` | Match any of these task classes in the schema. | `None` |
| `license` | `_OrList[License]` | Match any of these licenses. | `None` |
| `time_series_spec` | `_OrList[str]` | Match all of these `spec_type` values. | `None` |
| `dataset_id` | `_OrList[str]` | Match any of these IDs. | `None` |
| `tag` | `_OrList[str]` | Match all of these tags. | `None` |
| `limit` | `int` | The maximum number of results. | `100` |

Returns:

| Type | Description |
| --- | --- |
| `_Metadatas` | The matching dataset metadata, sorted by dataset ID. |

Raises:

| Type | Description |
| --- | --- |
| `TimeFValidationError` | If `limit` is negative. |
| `TimeNetNoCatalogError` | If no source has a catalog. |
| `TimeNetInvalidCardError` | If an installed backend cannot list its dataset IDs. |

### as\_release\_sources

```
as_release_sources(
    items: Sequence[ReleaseSource | str | Path],
    *,
    keyword: str,
) -> list[ReleaseSource]
```

Convert registry URLs and paths to release sources.

Existing source objects keep their identity and position. A path opens a writable local registry.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `items` | `Sequence[ReleaseSource | str | Path]` | A sequence of sources, registry URLs, or local paths. | *required* |
| `keyword` | `str` | The argument name to show in errors. | *required* |

Returns:

| Type | Description |
| --- | --- |
| `list[ReleaseSource]` | The sources in their original order, or an empty list for empty input. |

Raises:

| Type | Description |
| --- | --- |
| `TimeFValidationError` | If `items` is not a valid list. |
| `TimeNetRegistryError` | If a registry URL or path is blank or cannot be opened. |

### default\_local\_registry

```
default_local_registry(
    *, local_registry: str | Path | None = None
) -> LocalRegistry
```

Open the default local registry for downloaded and built releases.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `local_registry` | `str | Path | None` | The local registry directory (`TIMENET_LOCAL_REGISTRY`, default `~/.timenet/registry`). | `None` |

Returns:

| Type | Description |
| --- | --- |
| `LocalRegistry` | A writable local registry. |

Raises:

| Type | Description |
| --- | --- |
| `TimeFValidationError` | If the local registry path or another setting is invalid. |
| `TimeNetRegistryError` | If `local_registry` names a remote registry. |

### default\_sources

```
default_sources(
    *,
    local_registry: str | Path | None = None,
    remote_registry: str | Path | None = None,
    auto_build: bool | None = None,
) -> list[ReleaseSource]
```

Return the local registry, the remote registry and optional installed connectors in lookup order.

A `None` argument uses the current environment setting or its default.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `local_registry` | `str | Path | None` | The local registry directory (`TIMENET_LOCAL_REGISTRY`, default `~/.timenet/registry`). | `None` |
| `remote_registry` | `str | Path | None` | A registry URL or path (`TIMENET_REMOTE_REGISTRY`, default `timenet://`). | `None` |
| `auto_build` | `bool | None` | Whether to end with `InstalledConnectors()` (`TIMENET_AUTO_BUILD`, default true). | `None` |

Returns:

| Type | Description |
| --- | --- |
| `list[ReleaseSource]` | A new list of sources in lookup order. |

Raises:

| Type | Description |
| --- | --- |
| `TimeFValidationError` | If an argument or environment setting is invalid. |
| `TimeNetRegistryError` | If `local_registry` names a remote registry, or the remote registry cannot be opened. |