# Client

## timenet.client

The :class:`TimeNet` SDK: the single entry point for using TimeNet from code.

Wraps a :class:`~timenet.registry.BaseRegistry` (the catalog) and a local storage path (the download
cache), exposing `list` / `get` / `search` / `download` / `load`. It never runs connector
code; producing datasets is the curation side.

### T `module-attribute`

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

### TimeNet

Browse a registry and fetch datasets to local storage.

#### download

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

Fetch a dataset version's files into local storage and return its directory.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `dataset_id` | `str` | The dataset id. | *required* |
| `version` | `str | None` | The version string, or `None` for the latest. | `None` |
| `force` | `bool` | Re-download even if an up-to-date copy already exists. | `False` |

Returns:

| Type | Description |
| --- | --- |
| `Path` | The local `<storage>/<dataset_id>/<version>/` directory. |

#### get

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

Return a dataset's manifest.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `dataset_id` | `str` | The dataset id. | *required* |
| `version` | `str | None` | The version string, or `None` for the latest. | `None` |

Returns:

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

#### list

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

Return the metadata of every dataset in the registry.

Returns:

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

#### load

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

Download if needed, then read the dataset into memory.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `dataset_id` | `str` | The dataset id. | *required* |
| `version` | `str | None` | The version string, or `None` for the latest. | `None` |

Returns:

| Type | Description |
| --- | --- |
| `TimeFDataset` | The dataset with lazy per-series loaders backed by the local copy. |

#### load\_torch

```
load_torch(
    dataset_id: str, version: str | None = None
) -> TimeFTorchDataset
```

Download if needed and return the dataset as a read-only PyTorch `Dataset`.

Requires the `torch` extra (install coming soon); the torch view is imported
lazily so base users don't need torch.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `dataset_id` | `str` | The dataset id. | *required* |
| `version` | `str | None` | The version string, or `None` for the latest. | `None` |

Returns:

| Name | Type | Description |
| --- | --- | --- |
| `A` | `TimeFTorchDataset` | class:`~timenet.torch.TimeFTorchDataset` over the loaded dataset. |

#### 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 registry. Mirrors :meth:`~timenet.registry.BaseRegistry.search`.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `query` | `_OrList[str]` | Free-text terms over name/description/tags. | `None` |
| `domain` | `_OrList[Domain]` | Keep datasets sharing any of these domains. | `None` |
| `task` | `_OrList[type[Task]]` | Keep datasets whose schema includes any of these task classes. | `None` |
| `license` | `_OrList[License]` | Keep datasets with any of these licenses. | `None` |
| `time_series_spec` | `_OrList[str]` | Keep datasets declaring all of these `spec_type` values. | `None` |
| `dataset_id` | `_OrList[str]` | Keep only these ids. | `None` |
| `tag` | `_OrList[str]` | Keep datasets declaring all of these tags. | `None` |
| `limit` | `int` | Maximum number of results. | `100` |

Returns:

| Type | Description |
| --- | --- |
| `_Metadatas` | The matching dataset metadata. |