[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 new module timenet.producer adds timenet.build() and timenet.publish(), and the shell gets timenet publish. timenet_connectors.build() and load() are gone.

Details

A build from Python went through timenet_connectors.build(). It took fetch_from and build_parents instead of a list of sources, and it wrote to the store only through glue. Publishing a release had no function of its own, and only the build CLI copied a release to a remote --out.

• build() builds a release into a writable local registry with the installed connector that claims it, and returns the release directory. Missing parents and payload sources come from sources.
• build() takes open_access_only. If it is set, a plan that needs a release without open access raises TimeNetAccessError before any step runs.
• publish() copies a complete release and the payload sources that its manifest lists from a registry, by default the store, to dest. It returns the release that it copied.
• The defaults of build() come from the environment at call time. local_registry is TIMENET_LOCAL_REGISTRY, and sources is the default list. With sources, the sources come only from the argument.
• timenet publish DATASET --dest URL copies a release with timenet.publish(). The release comes from the store, or from the registry that --source names.
• An empty or blank --dest raises TimeNetRegistryError, and timenet publish writes nothing. It never means the current directory.
• as_release_sources() checks and opens the lists of TimeNet(sources=...) and of the sources of build(). Each message names its argument.
• The package timenet imports nothing from timenet_connectors, and the two functions load on first use. A ruff rule checks the first, and a subprocess test checks the second.
• timenet also exports TimeNet, LocalRegistry and InstalledConnectors. They load on first use too, so import timenet is enough to make a client with its sources.
• timenet_connectors.build() and load() are gone, with their hint and the glue that wrote to the store. The tests, the example and the API reference use the new names.
• Size: about 1160 changed lines. The two functions, the command and the removal of the old functions must land together. Otherwise the old functions keep a second way to build.

Design decisions

• A local_registry that is remote or read-only raises TimeFValidationError, because a build always lands in a writable local registry. A blank value or an unknown scheme raises TimeNetRegistryError.
• A registry URL in the list reuses the complete copies of the same releases in the store of the call. So the build does not download what it holds.
• publish() never changes a published version. Other files or another card in dest raise TimeNetVersionConflictError, and the same release copies nothing.
• publish() reads "latest" from the source. If the release is missing, the error names the source, so it shows where publish() looked.
• timenet publish takes the release from the store by default, because a build lands there. If the store lacks it, the error says to run timenet-build build or timenet download.
• The functions wrap the internal coordinator and add no planning of their own, so Python and the CLI cannot plan in different ways.

Breaking changes

• timenet_connectors.build() and timenet_connectors.load() are gone.

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.
• timenet-build build still takes --out, --fetch-from and --build-parents. A bare timenet-build and timenet.build() take their parents from different defaults until the PR on timenet-build --publish-to replaces the flags.
• get(), list() and search() still ask one registry through _catalog(). The PRs on inspection and on list and search replace them.

Merge message

feat!: add timenet.build() and publish()

timenet.build() and timenet.publish() give Python one way to build
into the local registry and to publish a release, with the same list
of sources as the client. The shell gets timenet publish.

- build() builds a release with the installed connector that claims
  it and returns the release directory. Missing parents and payload
  sources come from sources.
- With open_access_only, a plan that needs a release without open
  access fails before any step runs.
- publish() copies a complete release and its payload sources from the
  local registry, or from source, to dest. It never changes a
  published version.
- The defaults come from the environment at call time.
- timenet imports nothing from timenet_connectors, and the new names
  load on first use.

BREAKING CHANGE: timenet_connectors.build() and
timenet_connectors.load() are gone. Use timenet.build() and
TimeNet().load().

[TimoStoff]

LGTM!

[claude]

Nothing blocking. The comments below are optional suggestions. There is no need to push a fix for them before merging.

[claude]

Code review found no issues

No high-confidence issues detected in this change.

[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.