Skip to content

Bundle repository

repository

Access and persist bundles hosted in the public GKM Starter Kit repository.

The repository index and every retrieved bundle artifact are stored locally so published data remains usable after it has been fetched once.

The initial implementation makes the following assumptions:

  • The repository root contains an index.json file listing available resource names.
  • Each resource directory contains exactly two files: bundle.json and bundle.schema.json.

For example, the expected repository layout is:

/
├── index.json
├── civic/
│   ├── bundle.json
│   └── bundle.schema.json

Classes

BundleRepository 

BundleRepository(timeout: int = 15, *, data_dir: str | PathLike[str] | None = None, refresh: bool = False)

Access bundles from the canonical GKM Starter Kit R2 repository.

Repository documents are persisted in :attr:data_dir, selected in this order:

  1. An explicit data_dir argument.
  2. The GKM_STARTER_KIT_DIR environment variable.
  3. XDG_DATA_HOME/gkm-starter-kit.
  4. ~/.local/share/gkm-starter-kit.

The saved index.json is reused by default, which permits offline construction after the index has been retrieved once. Pass refresh=True to retrieve and atomically replace the saved index.

Initialize the bundle repository and load its resource index.

Parameters:

Name Type Description Default
timeout int

HTTP request timeout in seconds.

 15
data_dir str | PathLike[str] | None

Directory for persisted repository documents. When omitted, the directory is derived from the environment and XDG data-directory conventions.

 None
refresh bool

When true, retrieve and replace the saved index rather than reuse it.

 False

Raises:

Type Description
BundleRepositoryRequestError

If a required index cannot be retrieved from the repository.
BundleRepositoryFormatError

If the saved or retrieved index is not a JSON object with a resource_names string list.
Attributes
cached_resource_names property 
cached_resource_names: tuple[str, ...]

Return complete resource artifacts available in local storage.

A cached resource has both bundle.json and bundle.schema.json. It remains available here and can be loaded even if a later refreshed repository index no longer lists it.

Returns:

Type Description
tuple[str, ...]

Locally saved resource names in alphabetical order.
Methods:
get_bundle 
get_bundle(name: str, *, refresh: bool = False) -> dict[str, Any]

Retrieve a bundle, preferring its saved local copy.

Parameters:

Name Type Description Default
name str

Name of the bundle resource to retrieve.

 required
refresh bool

When true, retrieve and atomically replace the saved bundle instead of reusing it. A refresh requires the remote resource to remain available.

 False

Returns:

Type Description
dict[str, Any]

Bundle contents.

Raises:

Type Description
BundleRepositoryResourceNotFoundError

If name is absent from the repository index and does not have both saved artifacts.
BundleRepositoryRequestError

If a missing or refreshed bundle cannot be retrieved.
BundleRepositoryFormatError

If the saved or retrieved bundle is not a JSON object.
get_bundle_json_schema 
get_bundle_json_schema(name: str, *, refresh: bool = False) -> dict[str, Any]

Retrieve a bundle JSON Schema, preferring its saved local copy.

Parameters:

Name Type Description Default
name str

Name of the bundle resource whose JSON Schema to retrieve.

 required
refresh bool

When true, retrieve and atomically replace the saved schema instead of reusing it. A refresh requires the remote resource to remain available.

 False

Returns:

Type Description
dict[str, Any]

Bundle JSON Schema contents.

Raises:

Type Description
BundleRepositoryResourceNotFoundError

If name is absent from the repository index and does not have both saved artifacts.
BundleRepositoryRequestError

If a missing or refreshed schema cannot be retrieved.
BundleRepositoryFormatError

If the saved or retrieved schema is not a JSON object.
get_bundle_documents 
get_bundle_documents(name: str, *, refresh: bool = False) -> tuple[dict[str, Any], dict[str, Any]]

Retrieve a bundle and schema together.

Missing or refreshed artifacts are both downloaded and validated before either local file is replaced. Each artifact is written atomically.

Parameters:

Name Type Description Default
name str

Name of the bundle resource to retrieve.

 required
refresh bool

When true, retrieve and replace both saved artifacts. A refresh requires the remote resource to remain available.

 False

Returns:

Type Description
tuple[dict[str, Any], dict[str, Any]]

Bundle contents and its JSON Schema, in that order.

Raises:

Type Description
BundleRepositoryResourceNotFoundError

If name is absent from the repository index and does not have both saved artifacts.
BundleRepositoryRequestError

If either required remote artifact cannot be retrieved.
BundleRepositoryFormatError

If a saved or retrieved artifact is not a JSON object.