[karhu]

The Stack

This stack covers refactoring the internal logic of how releases are resolved during read, download & build, in particular also in the context of parent releases / parent datasets. On top of that it refactors the public TimeNet APIs and CLI interfaces around these actions, to streamline the behavior across them.

This PR

The client takes one ordered list of sources, TimeNet(sources=[...]), instead of a registry and the fetch_from= and auto_build= keywords.

Details

#660 reads through the read coordinator with a thin mapping of the old keywords onto a list. This PR makes the list the public interface and removes the mapping.

• TimeNet(sources=[...]) takes registries, InstalledConnectors(), and strings or paths that open_registry() opens.
• LocalRegistry takes read_only=True. Builds land in the first LocalRegistry of the list without it, the store. InstalledConnectors() needs such a registry.
• open_registry() is the one parser of a registry value. A blank value, an unknown scheme, a file:// URI with a host and a timenet:// URI with a path raise TimeNetRegistryError. The message names the value by its label, for example sources[1]. local_registry_path() uses the same messages. open_writable_registry() goes away, because open_registry() returns a WritableRegistry.
• timenet.client.default_sources() makes the list of TimeNet(): the store at <TIMENET_HOME>/registry, then timenet://, then InstalledConnectors(). A registry URL in TIMENET_REGISTRY takes the place of timenet://. A local path in TIMENET_REGISTRY is the store, and the list then has no other registry.
• open(), load() and open_torch() pass the list and the store to read_release(). The hints depend on the list. For a release that no source provides, the hint asks for a registry that holds it. Only a list without InstalledConnectors() gets a hint that names it.
• get(), list(), search() and download() still ask one registry: the first registry of the list that is not the store, else the store.
• Each command of the consumer CLI builds its client from default_sources(), and --registry names the registry that the command reads.
• timenet info and timenet download take org/name@version and no --version.
• timenet_connectors.load() reads with TimeNet().load().
• The examples show the list of sources.
• Size: about 1060 changed lines.

Design decisions

• The constructor checks the list. These raise TimeFValidationError: a bare string or path, an empty list, an item of another type, and InstalledConnectors() without a writable local registry. Each message shows the call that works, for example sources=['<path>'].
• A string is a Sequence, so the client checks for a string or path before it treats the value as a list. Without that check, TimeNet(".timenet-registry") takes one source per character.
• A list without InstalledConnectors() never builds, also for a newer version that a connector declares.
• str() of a store stays "local registry ", so error messages do not change.

Breaking changes

• TimeNet takes sources= instead of registry= and storage_path=.
• open(), load() and open_torch() no longer take fetch_from= and auto_build=.
• The default client also reads the local store and builds with the installed connectors.
• timenet download no longer takes --storage.
• open_registry() raises TimeNetRegistryError, not ValueError, and rejects a blank value.
• open_writable_registry() is gone. Use open_registry().
• timenet info and timenet download no longer take --version. Use org/name@version.

Stack

• docs: update the docs for the build coordinator #683
• feat(hints)!: give every error one hint for the SDK and one for the CLI #698
• feat(cache)!: record where each release in the local registry comes from #674
• feat(client)!: list and search every source #673
• feat(client)!: replace get() with get_manifest() and get_card() #672
• feat(build)!: build into the local registry, publish with --publish-to #671
• feat!: add timenet.build() and publish() #670
• feat(cli)!: take --local-registry, --remote-registry and --auto-build #669
• feat(config)!: make the default list of sources from three variables #668
• test: isolate every test from the real home and guard it #667
• feat(client)!: download releases into the local registry #662
• 👉 feat(client)!: take an ordered list of sources #661
• feat(client)!: read releases through the coordinator #660
• feat(coordinator)!: plan and run reads through the list of sources #659
• feat(coordinator)!: plan parents through an ordered list of sources #658
• feat(sources)!: resolve a release through an ordered list of sources #657
• feat(build)!: run every build through the coordinator #655
• feat(build)!: move the build CLI and build() onto the coordinator #654
• feat(build)!: build one prepared release in the built-in backend #653
• feat(coordinator)!: plan and run builds through build_release #652
• refactor(coordinator)!: name the plan step type Step #651
• feat(registry)!: copy a release between registries #649
• feat(registry)!: publish a local release with put_release #648
• refactor(build)!: let the connector choose the values backend #646

Changes later in the stack:

• docs: update the docs for the build coordinator #683 holds the doc changes of this PR.
• _catalog() for get(), list() and search(), the interim download(), the body of default_sources() and the --registry mapping are thin glue. The next PR moves download() into the store. The PRs on defaults and on inspection replace the rest.

Merge message

feat(client)!: take an ordered list of sources

TimeNet(sources=[...]) takes one ordered list of registries,
InstalledConnectors() and registry paths or URLs, in place of a
registry and the fetch_from and auto_build keywords.

- Builds land in the first LocalRegistry of the list without
  read_only=True. InstalledConnectors() needs such a registry.
- A list without InstalledConnectors() never builds.
- default_sources() makes the list of TimeNet(): the local registry,
  then timenet:// or the registry URL in TIMENET_REGISTRY, then
  InstalledConnectors().
- open_registry() is the one parser of a registry value.

BREAKING CHANGE: TimeNet takes sources= instead of registry= and
storage_path=. open(), load() and open_torch() lose fetch_from= and
auto_build=. The default client also reads the local registry and
builds with the installed connectors.

BREAKING CHANGE: open_registry() raises TimeNetRegistryError instead
of ValueError, and open_writable_registry() is gone.

BREAKING CHANGE: timenet info and timenet download take
org/name@version and lose --version. timenet download loses --storage.

[TimoStoff]

LGTM!

[claude]

Code review completed

Nothing new to post: everything this review found is already covered by existing comments on this pull request or didn't merit a separate one.

[claude]

⚠️ Code review skipped: your organization has reached its API usage limit, so Code Review can't run right now.

An organization admin can review the limit in your organization's usage and billing settings.

Once the limit resets or is raised, someone with write access to this repository can comment @claude review on this pull request to trigger a review.