Skip to content

Connectors

timenet.connectors source

The connector contract: :class:BaseConnector.

BaseConnector source

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 source

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 source

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 source

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 source

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 source

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.