Skip to content

Object references and storage

Convert VRS objects between inline objects and identifier references.

Given an Allele with an inline SequenceLocation::

from ga4gh.vrs import vrs_deref, vrs_enref

store = {}
allele_id, referenced = vrs_enref(allele, store, return_id_obj_tuple=True)
restored = vrs_deref(referenced, store)

The round trip is::

allele.location       -> SequenceLocation(...)
referenced.location   -> "ga4gh:SL.<digest>"
store[allele_id]       -> referenced Allele
restored.location     -> stored SequenceLocation

Both operations copy the top-level input. Dereferencing inserts store values directly, so resolving nested references can mutate those stored objects.

vrs_enref

vrs_enref(
    o: BaseModel,
    object_store: MutableMapping[str, BaseModel]
    | None = None,
    return_id_obj_tuple: bool = False,
) -> BaseModel | tuple[str | None, BaseModel]

Copy a VRS object and replace referable attributes with identifiers.

Parameters:

Name Type Description Default
o BaseModel

Identifiable VRS object to copy.

required
object_store MutableMapping[str, BaseModel] | None

Optional store for objects replaced by references.

None
return_id_obj_tuple bool

Include the identifier alongside the copied object.

False

Returns:

Type Description
BaseModel | tuple[str | None, BaseModel]

Referenced copy, optionally paired with its identifier.

Raises:

Type Description
ValueError

If the input is not an identifiable Pydantic object.

TypeError

If a root-model CURIE reference has a non-GA4GH prefix. Plain string references are left unchanged.

vrs_deref

vrs_deref(
    o: BaseModel, object_store: Mapping[str, BaseModel]
) -> BaseModel

Copy a VRS object and resolve its identifier references.

Parameters:

Name Type Description Default
o BaseModel

Identifiable VRS object to copy.

required
object_store Mapping[str, BaseModel]

Store mapping identifiers to referenced objects. Retrieved objects are inserted directly and may be mutated during dereferencing.

required

Returns:

Type Description
BaseModel

Copy with references replaced by inline objects.

Raises:

Type Description
ValueError

If the input is not an identifiable Pydantic object.

KeyError

If a referenced identifier is absent from the store.

Convert ga4gh objects between inlined and referenced forms.

Referable attributes are those that may be either an object or CURIE.

These functions require a "class referable attribute" map, which will typically be generated from the schema by pydantic_class_refatt_map() in .models.py.

ga4gh_enref

ga4gh_enref(
    o: BaseModel,
    cra_map: Mapping[str, Sequence[str]],
    object_store: MutableMapping[str, BaseModel]
    | None = None,
    return_id_obj_tuple: bool = False,
) -> BaseModel | tuple[str | None, BaseModel]

Recursively convert "referable attributes" from inlined to referenced form. Returns a new object.

Parameters:

Name Type Description Default
o BaseModel

VRS object

required
cra_map Mapping[str, Sequence[str]]

class referrable-attribute map; { o.type: [attr, attr, ...] }

required
object_store MutableMapping[str, BaseModel] | None

collections.abc.MutableMapping subclass that stores objects as they are referenced. If not given, referenced objects are not stored.

None
return_id_obj_tuple bool

include ID with return value or not

False

Returns:

Type Description
BaseModel | tuple[str | None, BaseModel]

new, enref'd object, as well as object ID if param set

Raises:

Type Description
TypeError

If a root-model CURIE reference has a non-GA4GH prefix. Plain string references are left unchanged.

ValueError

If the input is not an identifiable Pydantic model.

ga4gh_deref

ga4gh_deref(
    o: BaseModel,
    cra_map: Mapping[str, Sequence[str]],
    object_store: Mapping[str, BaseModel],
) -> BaseModel

Copy an object and replace referable identifiers with inline objects.

object_store must be a mappable object and is required for dereferencing.

The top-level input is copied. Objects retrieved from the store are inserted directly and may be mutated while their own references are resolved.

Parameters:

Name Type Description Default
o BaseModel

Object to process.

required
cra_map Mapping[str, Sequence[str]]

Mapping from model names to referable attribute names.

required
object_store Mapping[str, BaseModel]

Mapping from identifiers to referenced objects.

required

Returns:

Type Description
BaseModel

Copy with identifier references replaced by objects.

Raises:

Type Description
ValueError

If the input is not an identifiable Pydantic model.

KeyError

If a referenced object is absent from the store.

Store pickled Python objects in a SQLite-backed mutable mapping.

Sqlite3MutableMapping

Sqlite3MutableMapping(
    sqlite3_db: str | Connection, autocommit: bool = True
)

Bases: MutableMapping[str, object]

Store a mutable mapping in SQLite.

The context manager commits or rolls back pending transactions. With autocommit enabled, earlier writes have already been committed and cannot be rolled back by the context manager. Call close to release the connection. With autocommit disabled, call commit to persist changes outside a context manager.

Open a database connection and initialize the mapping schema.

Parameters:

Name Type Description Default
sqlite3_db str | Connection

Database path or existing connection. Schema initialization commits pending work on an existing connection; close also closes it.

required
autocommit bool

Commit after each insertion or deletion when true.

True

__del__

__del__() -> None

Commit pending changes and close the connection.

__delitem__

__delitem__(key: str) -> None

Delete a stored value.

Parameters:

Name Type Description Default
key str

Key to remove.

required

Raises:

Type Description
KeyError

If the key is absent.

__setitem__

__setitem__(key: str, value: object) -> None

Pickle and store a value, replacing any existing entry.

Parameters:

Name Type Description Default
key str

Storage key.

required
value object

Picklable value to store.

required

__getitem__

__getitem__(key: str) -> object

Load and unpickle a stored value.

Parameters:

Name Type Description Default
key str

Storage key.

required

Returns:

Type Description
object

Stored Python object.

Raises:

Type Description
KeyError

If the key is absent.

__iter__

__iter__() -> Iterator[str]

Iterate over stored keys.

Returns:

Type Description
Iterator[str]

Iterator yielding each key.

__len__

__len__() -> int

Count stored entries.

Returns:

Type Description
int

Number of entries.

commit

commit() -> None

Commit pending changes to the database.

close

close() -> None

Commit pending changes and close the connection once.

__enter__

__enter__() -> Self

Enter the database transaction context.

Returns:

Type Description
Self

This mapping.

__exit__

__exit__(
    exc_type: type[BaseException] | None,
    exc_value: BaseException | None,
    traceback: TracebackType | None,
) -> None

Commit a successful transaction or roll back a failed transaction.

Parameters:

Name Type Description Default
exc_type type[BaseException] | None

Exception class, if the context raised.

required
exc_value BaseException | None

Exception instance, if the context raised.

required
traceback TracebackType | None

Traceback for the exception, if any.

required