Timenet.client

timenet.client ¶source

Find, inspect, download, and read TimeF datasets.

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

T `module-attribute` ¶source

T = TypeVar('T')

TimeNet ¶source

Browse, download, and read TimeNet datasets.

download ¶source

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 ¶source

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 ¶source

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 ¶source

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 ¶source

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 ¶source

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 ¶source

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 ¶source

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 ¶source

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 ¶source

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 ¶source

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.

Timenet.client

timenet.client ¶source

T module-attribute ¶source

TimeNet ¶source

download ¶source

get_card ¶source

get_manifest ¶source

list ¶source

load ¶source

open ¶source

open_torch ¶source

search ¶source

as_release_sources ¶source

default_local_registry ¶source

default_sources ¶source

T `module-attribute` ¶source