Open and cache catalogs

Use a catalog.json location to follow a catalog's current selection. Use an exact release.json location when a task must keep the same contents. Opening either resolves one release for its records, citations, and index files.

Complete Getting started for your interface. The TypeScript examples use the Node.js reader for file access and persistent caching. Browser applications use the browser reader.

Open local files

For a compiled catalog at ./dist/catalog:

from chartcoach import open_catalog

catalog = open_catalog("./dist/catalog")
print(catalog.describe()["entries_digest"])

Python, Node.js, and the CLI open these shared layouts:

Python and the CLI also open authored folders containing MANIFEST.md and entries/<id>/guideline.md. Curate and publish builds bundles and releases from those authored files.

Open a remote release

Set CATALOG_SOURCE to your deployment's full HTTP or HTTPS descriptor URL. Run the example for your interface:

import os
from chartcoach import open_catalog

catalog = open_catalog(os.environ["CATALOG_SOURCE"])
print(catalog.describe()["release_digest"])

Opening a release downloads and verifies the manifest and guideline records. Profile metadata and indexes download when requested. The description reports the resolved release digest, so you can check which catalog each interface uses.

Reuse files across runs

Python and Node.js share the platform's per-user chartcoach artifact-cache layout. The CLI uses the Python reader's cache. Cached files are checked against their release descriptor before reuse.

Reopening a digest-addressed release reuses its cached descriptor and core files, including offline. Opening catalog.json refreshes the selection. Keep a catalog object open for a task when its queries must retain one release.

For direct file access, Python's catalog.artifact("entries.parquet") and Node's artifactPath(catalog, "entries.parquet") return verified local paths. Pass those paths to DuckDB, Polars, or another Parquet reader. The release inventory lists which optional files are available.

Python's catalog.cache() downloads every release artifact and returns a local release directory. This includes every profile's index and optional exports, which can be large. See Use verified files and reopen offline for that workflow, and Node.js files and cache for server-side cache configuration.

Connect private object storage

Set CATALOG_SOURCE to your bucket's descriptor URI and configure read credentials through the storage client.

uv pip install "chartcoach[cloud]"

import os
from chartcoach import open_catalog

catalog = open_catalog(
    os.environ["CATALOG_SOURCE"],
    storage_options={"region": "eu-central-1"},
)

Open the same artifacts in a browser

The browser reader fetches release files over HTTPS and returns verified bytes through catalog.artifact(). Public hosts must allow cross-origin requests. For private storage, use authenticated application routes or a signed-URL flow that keeps storage credentials off the client.

Supply an ArtifactCache to persist bytes beyond the loaded catalog's lifetime. The web app guide shows the same records powering browser-side filtering and server-side search. See Use release files with native tools for the cache interface.

If opening fails

Readers reject mismatched bytes. Rebuild and publish a new release when catalog contents change.