Containers

containers

In-memory bundle containers.

Classes

BundleCollection

BundleCollection(name: str, values: Mapping[str, Any], *, serialized_values: Mapping[str, Any] | None = None)

Bases: Mapping[str, Any]

A named, keyed collection within a :class:Bundle.

Parameters:

Name	Type	Description	Default
`name`	`str`	Collection name from the bundle.	required
`values`	`Mapping[str, Any]`	Objects keyed by their identifiers.	required
`serialized_values`	`Mapping[str, Any] \| None`	Compact objects used when serializing the bundle.	`None`

Initialize a bundle collection.

Parameters:

Name	Type	Description	Default
`name`	`str`	Collection name from the bundle.	required
`values`	`Mapping[str, Any]`	Objects keyed by their identifiers.	required
`serialized_values`	`Mapping[str, Any] \| None`	Compact objects used when serializing the bundle.	`None`

Methods:

to_dict

to_dict() -> dict[str, Any]

Return the collection's compact serialized values.

Returns:

Type	Description
`dict[str, Any]`	Objects keyed by identifier with local references preserved.

serialized

serialized(key: str) -> Any

Return one compact object by identifier.

Parameters:

Name	Type	Description	Default
`key`	`str`	Object identifier.	required

Returns:

Type	Description
`Any`	The stored object with local references preserved.

Raises:

Type	Description
`BundleObjectNotFoundError`	If `key` is absent.

getitem

__getitem__(key: str) -> Any

Return an object by identifier.

Parameters:

Name	Type	Description	Default
`key`	`str`	Object identifier.	required

Returns:

Type	Description
`Any`	The stored object.

Raises:

Type	Description
`BundleObjectNotFoundError`	If `key` is absent.

iter

__iter__() -> Iterator[str]

Iterate over object identifiers.

Returns:

Type	Description
`Iterator[str]`	An iterator over identifiers.

len

__len__() -> int

Return the number of objects in the collection.

Returns:

Type	Description
`int`	Collection size.

keys

keys() -> KeysView[str]

Return the object identifiers in the collection.

Returns:

Type	Description
`KeysView[str]`	A view of the collection's object identifiers.

repr

__repr__() -> str

Return a concise representation of the collection.

Returns:

Type	Description
`str`	Collection name and size.

Bundle

Bundle(collections: Mapping[str, BundleCollection], *, metadata: Mapping[str, Any] | None = None, extras: Mapping[str, Any] | None = None, name: str | None = None, schema: Mapping[str, Any] | None = None)

Bases: Mapping[str, BundleCollection]

Represent a GKM Bundle in memory.

Producer-defined collection names are preserved and can be accessed through mapping syntax, attribute access, or :meth:collection.

Parameters:

Name	Type	Description	Default
`collections`	`Mapping[str, BundleCollection]`	Named object collections in the bundle.	required
`metadata`	`Mapping[str, Any] \| None`	Bundle and provenance metadata.	`None`
`extras`	`Mapping[str, Any] \| None`	Top-level values that are not object collections.	`None`
`name`	`str \| None`	Registered or inferred bundle name.	`None`
`schema`	`Mapping[str, Any] \| None`	Producer JSON Schema used to materialize pointer targets.	`None`

Initialize a bundle.

Parameters:

Name	Type	Description	Default
`collections`	`Mapping[str, BundleCollection]`	Named object collections in the bundle.	required
`metadata`	`Mapping[str, Any] \| None`	Bundle and provenance metadata.	`None`
`extras`	`Mapping[str, Any] \| None`	Top-level values that are not object collections.	`None`
`name`	`str \| None`	Registered or inferred bundle name.	`None`
`schema`	`Mapping[str, Any] \| None`	Producer JSON Schema used to materialize pointer targets.	`None`

Methods:

getitem

__getitem__(name: str) -> BundleCollection

Return a collection by name.

Parameters:

Name	Type	Description	Default
`name`	`str`	Collection name.	required

Returns:

Type	Description
`BundleCollection`	The matching collection.

Raises:

Type	Description
`BundleCollectionNotFoundError`	If `name` is absent.

iter

__iter__() -> Iterator[str]

Iterate over collection names.

Returns:

Type	Description
`Iterator[str]`	An iterator over collection names.

len

__len__() -> int

Return the number of collections.

Returns:

Type	Description
`int`	Collection count.

collection_names

collection_names() -> tuple[str, ...]

Return the collection names in document order.

Returns:

Type	Description
`tuple[str, ...]`	Names of the collections exposed by this bundle.

getattr

__getattr__(name: str) -> BundleCollection

Provide attribute access to named collections.

Parameters:

Name	Type	Description	Default
`name`	`str`	Collection name.	required

Returns:

Type	Description
`BundleCollection`	The matching collection.

Raises:

Type	Description
`BundleCollectionNotFoundError`	If `name` is not a collection.

collection

collection(name: str) -> BundleCollection

Return a collection by name.

Parameters:

Name	Type	Description	Default
`name`	`str`	Collection name.	required

Returns:

Type	Description
`BundleCollection`	The matching collection.

Raises:

Type	Description
`BundleCollectionNotFoundError`	If `name` is absent.

resolve

resolve(pointer: str | iriReference) -> Any

Resolve a bundle-local RFC 6901 JSON Pointer.

Pass a pointer from this bundle's serialized representation, such as a value retrieved from :meth:to_dict. Do not pass a field from a typed object: linked fields on typed GKM models may already be resolved. iriReference objects are accepted directly. When the producer schema identifies the target with a supported GA4GH W3ID reference, return its validated model; otherwise return the JSON value. Use :meth:normalize to expand references recursively. Model traversal is restricted to declared Pydantic fields; methods and other implementation attributes are not valid pointer targets.

Parameters:

Name	Type	Description	Default
`pointer`	`str \| iriReference`	Bundle-local JSON Pointer beginning with `#/`, or an `iriReference` whose `root` contains that pointer.	required

Returns:

Type	Description
`Any`	The referenced value.

Raises:

Type	Description
`BundleReferenceError`	If the pointer is invalid or cannot be resolved, including when it targets an undeclared model field.

normalize

normalize(value: Any | None = None) -> Any

Normalize bundle content for use outside the serialized bundle.

Bundle-local pointers are expanded recursively; cyclic pointers remain pointers. Omitting value normalizes the complete bundle.

Parameters:

Name	Type	Description	Default
`value`	`Any \| None`	Bundle value to normalize, or `None` for the complete bundle.	`None`

Returns:

Type	Description
`Any`	JSON-compatible normalized content.

Raises:

Type	Description
`BundleReferenceError`	If a local reference cannot be resolved.

denormalize

denormalize(value: Any) -> Any

Replace embedded bundle objects with local JSON Pointer references.

Embedded objects matching bundle objects are replaced by local pointers; unknown producer content is preserved. Exact content matches take precedence over the optional id/type identity fallback.

Parameters:

Name	Type	Description	Default
`value`	`Any`	Normalized JSON-compatible value.	required

Returns:

Type	Description
`Any`	Content using bundle-local references where possible.

Raises:

Type	Description
`BundleSerializationError`	If `value` cannot be represented as JSON-compatible content.

export

export(value: Any | None = None, *, deep: bool = False) -> Any

Export a complete bundle or an individual object.

deep=False preserves local pointers; deep=True expands them. Omitting value exports the complete bundle. The result is validated as JSON-compatible.

Parameters:

Name	Type	Description	Default
`value`	`Any \| None`	Object or content to export, or `None` for the bundle.	`None`
`deep`	`bool`	Include reachable referenced content instead of preserving local references.	`False`

Returns:

Type	Description
`Any`	JSON-compatible exported content.

Raises:

Type	Description
`BundleSerializationError`	If content is not JSON-compatible.

to_dict

to_dict() -> dict[str, Any]

Return the complete bundle as a JSON-compatible shallow document.

This preserves bundle-local JSON Pointers rather than resolving them. Use a pointer from this result with :meth:resolve, or use :meth:normalize to recursively replace local pointers with their targets. This method does not write a file.

Returns:

Type	Description
`dict[str, Any]`	The complete serialized bundle.

Raises:

Type	Description
`BundleSerializationError`	If producer-specific extras conflict with a collection name or the reserved `"metadata"` field.

write

write(destination: str | Path, *, serialization: str = 'json', indent: int | None = 2) -> None

Write the bundle to a file.

Writing preserves collection names, identifiers, local references, metadata, and producer-specific values, but the result may not be byte-for-byte identical to the input. Output is not validated against the producer's schema.

Parameters:

Name	Type	Description	Default
`destination`	`str \| Path`	Output file path.	required
`serialization`	`str`	Output serialization. Only `"json"` is supported.	`'json'`
`indent`	`int \| None`	Number of spaces used to indent JSON, or `None` for compact output.	`2`

Raises:

Type	Description
`BundleSerializationError`	If `serialization` is unsupported.

repr

__repr__() -> str

Return a concise representation of the bundle.

Returns:

Type	Description
`str`	Bundle name and collection count.

Containers

containers

Classes

BundleCollection

Methods:

to_dict

serialized

__getitem__

__iter__

__len__

keys

__repr__

Bundle

Methods:

__getitem__

__iter__

__len__

collection_names

__getattr__

collection

resolve

normalize

denormalize

export

to_dict

write

__repr__

Functions:

getitem

iter

len

repr

getitem

iter

len

getattr

repr