Models

models

In-memory bundle containers.

Classes

BundleCollection

BundleCollection(name: str, values: Mapping[str, Any])

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

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

Methods:

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)

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`

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`

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) -> Any

Resolve an RFC 6901 JSON Pointer into this bundle.

Parameters:

Name	Type	Description	Default
`pointer`	`str`	Bundle-local pointer beginning with `#/`.	required

Returns:

Type	Description
`Any`	The referenced value.

Raises:

Type	Description
`BundleReferenceError`	If the pointer is invalid or cannot be resolved.

dereference

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

Return a value with all reachable local references replaced inline.

The complete bundle is used when value is omitted. The bundle itself remains referenced.

Cycle-closing pointers remain referenced because JSON cannot represent a cyclic inline value.

Parameters:

Name	Type	Description	Default
`value`	`Any \| None`	Value from this bundle to dereference, or `None` for the complete bundle.	`None`

Returns:

Type	Description
`Any`	A JSON-compatible, inline representation of the value.

to_dict

to_dict() -> dict[str, Any]

Serialize the bundle to JSON-compatible Python values.

Returns:

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

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.