Loading

loading

Bundle loading entry points.

load_bundle(source: BundleSource, *, schema: BundleSource | None = None, serialization: str | None = None) -> Bundle

Load one bundle from a registered name, JSON file, or JSON stream.

This loader handles local and in-memory sources. To load a published resource from the public repository, use :func:load_repository_bundle.

Loading behavior:

Decode the JSON document.
Require and decode a producer JSON Schema. Verify the schema itself and check its GKM version compatibility before inspecting bundle content.
Check the document and its metadata's basic shape.
Walk the complete decoded document and validate bundle-local pointers before model conversion or bundle construction. Pointer failures are aggregated into one :class:BundleReferenceError; large error lists are truncated with total and omitted counts.
Validate the complete document against the producer JSON Schema after pointer syntax and traversal have been checked.
Convert recognized GKM objects to Pydantic models. Model validation is fail-fast; the first failure prevents a bundle from being returned. Producer-specific content remains dictionaries.

Parameters:

Name	Type	Description	Default
`source`	`BundleSource`	Registered bundle name, file path, or readable JSON stream.	required
`schema`	`BundleSource \| None`	Producer JSON Schema using Draft 2020-12. A registered schema is used when omitted; one must be available from either source.	`None`
`serialization`	`str \| None`	Input serialization. Only `"json"` is supported. When omitted, JSON is assumed.	`None`

Returns:

Type	Description
`Bundle`	The loaded bundle.

Raises:

Type	Description
`ga4gh.gkm.bundles.BundleCompatibilityError`	If the schema references unsupported GKM product versions.
`BundleSerializationError`	If the serialization or data shape is unsupported, or no producer JSON Schema is available.
`ga4gh.gkm.bundles.BundleValidationError`	If a recognized GKM object fails validation by its reference implementation.
`ga4gh.gkm.bundles.BundleReferenceError`	If one or more bundle-local JSON Pointers cannot be resolved.
`BundleNotFoundError`	If `source` cannot be found.

load_bundles(*sources: BundleSource) -> dict[str, Bundle]

Load several local or in-memory bundles and key them by their names.

For published repository resources, use :func:load_repository_bundle for each resource name.

Parameters:

Name	Type	Description	Default
`sources`	`BundleSource`	Registered bundle names, file paths, or readable JSON streams.	`()`

Returns:

Type	Description
`dict[str, Bundle]`	Loaded bundles keyed by name.

Raises:

Type	Description
`BundleConflictError`	If two sources resolve to the same name.

load_repository_bundle(repository: BundleRepository, name: str, *, refresh: bool = False) -> Bundle

Load and validate a bundle through a bundle repository.

Loading behavior:

Confirm name is indexed or completely saved locally.
Retrieve the resource's bundle.json and bundle.schema.json together. Saved local copies are reused by default; missing artifacts or refresh=True retrieve copies from the public repository.
Pass both documents to :func:load_bundle for validation and conversion.
Assign the repository resource name to the returned bundle.

Parameters:

Name	Type	Description	Default
`repository`	`BundleRepository`	Repository that resolves saved or public resource artifacts.	required
`name`	`str`	Name of an indexed resource or complete locally saved resource.	required
`refresh`	`bool`	Whether to retrieve and replace the saved bundle and schema instead of reusing their local copies. A refresh requires the remote resource to remain available.	`False`

Returns:

Type	Description
`Bundle`	The validated bundle.

Raises:

Type	Description
`BundleRepositoryError`	If the repository cannot provide either document.
`BundleCompatibilityError`	If the published schema is incompatible.
`BundleSerializationError`	If either document has an invalid shape.
`BundleValidationError`	If a recognized object fails validation.
`BundleReferenceError`	If a bundle-local reference is invalid.