# Connectors

## timenet.connectors

The connector contract: :class:`BaseConnector`.

### BaseConnector

Bases: `ABC`, `Generic[TRaw]`

Abstract base for dataset connectors. One concrete subclass per dataset.

A connector lives in its own folder and declares its descriptive identity in a `dataset.yaml`
card beside it (read by :meth:`metadata`); set :attr:`CARD` to point elsewhere. Subclasses
implement `convert` (CPU-only) and, for networked sources, `download` (I/O-only); a synthetic
connector that generates everything in `convert` can skip `download`, which defaults to
returning no references. Connectors take no constructor arguments.

#### CARD `class-attribute`

```
CARD: str | Path | None = None
```

Optional explicit path to the dataset card YAML. When `None` (the default), the card is read
from `dataset.yaml` in the connector's own folder.

#### convert `abstractmethod`

```
convert(raw_refs: list[TRaw]) -> TimeFDataset
```

Parse raw references and populate a :class:`~timenet.dataset.TimeFDataset`.

CPU-bound: no network I/O. Time-series values are attached as lazy loaders, not materialized.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `raw_refs` | `list[TRaw]` | The references returned by :meth:`download`. | *required* |

Returns:

| Type | Description |
| --- | --- |
| `TimeFDataset` | The populated dataset. |

#### download

```
download(cache_dir: Path) -> list[TRaw]
```

Fetch or discover raw source files and return lightweight references to them.

I/O only: no parsing, no array work. Must be idempotent for a given `cache_dir`. Defaults to
returning no references, so a synthetic connector that builds everything in :meth:`convert`
need not override it.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `cache_dir` | `Path` | Directory to write downloaded files into (created by the engine). | *required* |

Returns:

| Type | Description |
| --- | --- |
| `list[TRaw]` | Raw references passed directly to :meth:`convert` (empty by default). |

#### metadata

```
metadata() -> DatasetMetadata
```

Return the dataset's descriptive identity, loaded and validated from its card YAML.

Reads the card by convention (`dataset.yaml` beside the connector, unless :attr:`CARD`
overrides it). Its `dataset_id` must match the id the connector is registered/curated under.

Returns:

| Type | Description |
| --- | --- |
| `DatasetMetadata` | The dataset's :class:`~timenet.types.DatasetMetadata`. |

#### store

```
store(
    dataset: TimeFDataset,
    root: Path,
    *,
    progress_cb: Callable[[WriteProgressEvent], None]
    | None = None,
) -> Path
```

Serialize a populated dataset to the TimeF format under `root`.

Derives the schema first if the dataset has none, then streams it through a
:class:`~timenet.writer.TimeFWriter`. Most connectors do not override this.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `dataset` | `TimeFDataset` | The populated dataset from :meth:`convert`. | *required* |
| `root` | `Path` | Parent directory; the version directory is created beneath it. | *required* |
| `progress_cb` | `Callable[[WriteProgressEvent], None] | None` | Optional writer progress callback. | `None` |

Returns:

| Type | Description |
| --- | --- |
| `Path` | The committed version directory. |