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
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
|
|
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
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
|
__delitem__
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__
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__
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__
Iterate over stored keys.
Returns:
| Type | Description |
|---|---|
Iterator[str]
|
Iterator yielding each key. |
__enter__
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 |