Skip to content

Timenet.sources

timenet.sources source

Find dataset releases across registries and installed connectors.

Ask module-attribute source

Ask: TypeAlias = Callable[
    [ReleaseSource, str, Version | None], ReleaseLookup
]

A function that asks one source for a release: ask(source, dataset_id, version).

Found module-attribute source

Found: TypeAlias = FoundInRegistry | FoundInConnector

A result for a release that a source serves or builds.

ReleaseLookup module-attribute source

ReleaseLookup: TypeAlias = Found | NotFound | NotServed

The result of looking up a release in a source.

ReleaseSource module-attribute source

ReleaseSource: TypeAlias = Union[
    "BaseRegistry", "InstalledConnectors"
]

A source that can serve or build a dataset release: a registry or the installed connectors.

FoundInConnector dataclass source

A result for a release that an installed connector builds.

Attributes:

Name Type Description
builder InstalledBuilder

The backend and card that the lookup read.

builder instance-attribute source

builder: InstalledBuilder

version property source

version: Version

The version that the card declares.

FoundInRegistry dataclass source

A result for a release that a registry serves.

Attributes:

Name Type Description
version Version

The exact version.
registry BaseRegistry

The registry that serves the release.
manifest Manifest | None

The release manifest that the registry read, or None.

manifest class-attribute instance-attribute source

manifest: Manifest | None = field(
    default=None, compare=False, repr=False
)

registry instance-attribute source

registry: BaseRegistry

version instance-attribute source

version: Version

InstalledConnectors dataclass source

A source for the datasets that installed connectors build.

A connector counts as installed if a package registers it under the timenet.builders entry point group. Each connector provides only the version its card declares, and all instances are equal.

has_catalog class-attribute source

has_catalog: bool = True

Whether :meth:list_datasets works. It always does for installed connectors.

list_datasets source

list_datasets() -> list[DatasetMetadata]

Return dataset cards from installed connectors without building the datasets.

The first entry point that claims a dataset takes priority. The method skips unreadable cards and emits a :class:~timenet.errors.ConnectorCardWarning.

Returns:

Type Description
list[DatasetMetadata]

The cards, sorted by dataset ID.

Raises:

Type Description
TimeNetInvalidCardError

If a backend cannot list its dataset IDs.

resolve source

resolve(
    dataset_id: str, version: Version | None
) -> ReleaseLookup

Check whether an installed connector can build a release.

The lookup uses the first entry point that claims the dataset.

Parameters:

Name Type Description Default
dataset_id str

The dataset ID.

 required
version Version | None

An exact version, or None for the latest version.

 required

Returns:

Type Description
ReleaseLookup

FoundInConnector if a connector builds the requested version, or NotFound.

Raises:

Type Description
TimeNetInvalidCardError

If the connector's card cannot be read.

NotFound dataclass source

A result for a release that the source cannot find.

NotServed dataclass source

A result for a listed release whose files the source cannot serve.

Attributes:

Name Type Description
version Version

The exact version that the source lists.
access Access

The strictest access level of the release's card and the cards in its lineage.
requirements tuple[AccessRequirement, ...]

Each card that is not open access, with its access level and access page.
manifest Manifest | None

The release manifest, or None.

access instance-attribute source

access: Access

manifest class-attribute instance-attribute source

manifest: Manifest | None = field(
    default=None, compare=False, repr=False
)

requirements instance-attribute source

requirements: tuple[AccessRequirement, ...]

version instance-attribute source

version: Version

access_error source

access_error(dataset_id: str) -> TimeNetAccessError

Create an error with the release's access requirements.

Parameters:

Name Type Description Default
dataset_id str

The dataset ID.

 required

Returns:

Type Description
TimeNetAccessError

An error with the release, its access level, and its access pages.

resolve_release source

resolve_release(
    sources: Sequence[ReleaseSource],
    dataset_id: str,
    version: str | None,
    *,
    ask: Ask | None = None,
) -> ReleaseLookup

Find a source that provides the requested dataset release.

An exact version comes from the first source that serves it, and no version means the newest version of the first source that serves the dataset. "latest" is the highest version of any source, source order breaks ties, and source errors stop the search.

Parameters:

Name Type Description Default
sources Sequence[ReleaseSource]

The sources, in order.

 required
dataset_id str

The dataset ID.

 required
version str | None

An exact version, "latest", or None or "" for no version.

 required
ask Ask | None

The function that asks one source, or None to call the source's resolve().

 None

Returns:

Type Description
ReleaseLookup

A Found result if available, otherwise the first NotServed result or NotFound.

Raises:

Type Description
TimeFValidationError

If version is neither "latest" nor a major.minor.patch version.