pygsti.baseobjs.mongoserializable

Defines the MongoSerializable class

Module Contents

Classes

MongoSerializable	Base class for objects that can be serialized to a MongoDB database.
WriteOpsByCollection	A dictionary of pymongo write operations stored on a per-collection basis.
RecursiveRemovalSpecification	Specifies which types of objects to remove when performing a recursive removal of MongoDB documents.

Functions

prepare_doc_for_existing_doc_check(doc, existing_doc)	Prepares a to-be inserted document for comparison with an existing document.
recursive_compare_str(a, b[, a_name, b_name, prefix, ...])	Compares two objects and generates a list of strings describing how they differ.

class pygsti.baseobjs.mongoserializable.MongoSerializable(doc_id=None)

Bases: object

Base class for objects that can be serialized to a MongoDB database.

At the very least, saving an object to a database creates a document in the collection named by the collection_name class variable (which can be overriden by derived classes). Additionally, saving the object may create other documents outside of this collection (e.g., if the object contains MongoSerializable attributes that specify their own collection name).

This interface also allows an object to save large chunks of data using, e.g., MongoDB’s GridFS system, when serializing itself instead of trying to write an enourmous JSON dictionary as a single document (as an object that is NicelySerializable might do).

collection_name = 'pygsti_objects'

classmethod from_mongodb(mongodb, doc_id, **kwargs)

Create and initialize an object from a MongoDB instance.

Parameters

mongodbpymongo.database.Database

The MongoDB instance to load from.

doc_idbson.objecctid.ObjectId or dict

The object ID or filter used to find a single object ID wihtin the database. This document is loaded from the collection given by the collection_name attribute of this class.

**kwargsdict

Additional keyword arguments poentially used by subclass implementations. Any arguments allowed by a subclass’s _create_obj_from_doc_and_mongodb method is allowed here.

Returns

object

classmethod from_mongodb_doc(mongodb, collection_name, doc, **kwargs)

Create and initialize an object from a MongoDB instance and pre-loaded primary document.

Parameters

mongodbpymongo.database.Database

The MongoDB instance to load from.

collection_namestr

The collection name within mongodb that doc was loaded from. This is needed for the sole purpose of setting the created (returned) object’s database “coordinates”.

docdict

The already-retrieved main document for the object being loaded. This takes the place of giving an identifier for this object.

**kwargsdict

Additional keyword arguments poentially used by subclass implementations. Any arguments allowed by a subclass’s _create_obj_from_doc_and_mongodb method is allowed here.

Returns

object

write_to_mongodb(mongodb, session=None, overwrite_existing=False, **kwargs)

Write this object to a MongoDB database.

The collection name used is self.collection_name, and the _id is either: 1) the ID used by a previous write or initial read-in, if one exists, OR 2) a new random bson.objectid.ObjectId

Parameters

mongodbpymongo.database.Database

The MongoDB instance to write data to.

sessionpymongo.client_session.ClientSession, optional

MongoDB session object to use when interacting with the MongoDB database. This can be used to implement transactions among other things.

overwrite_existingbool, optional

Whether existing documents should be overwritten. The default of False causes a ValueError to be raised if a document with the given _id already exists and is different from what is being written.

**kwargsdict

Additional keyword arguments poentially used by subclass implementations. Any arguments allowed by a subclass’s _add_auxiliary_write_ops_and_update_doc method is allowed here.

Returns

bson.objectid.ObjectId

The identifier (_id value) of the main document that was written.

add_mongodb_write_ops(write_ops, mongodb, overwrite_existing=False, **kwargs)

Accumulate write and update operations for writing this object to a MongoDB database.

Similar to write_to_mongodb() but collects write operations instead of actually executing any write operations on the database. This function may be preferred to write_to_mongodb() when this object is being written as a part of a larger entity and executing write operations is saved until the end.

As in write_to_mongodb(), self.collection_name is the collection name and _id is either: 1) the ID used by a previous write or initial read-in, if one exists, OR 2) a new random bson.objectid.ObjectId

Parameters

write_opsWriteOpsByCollection

An object that keeps track of pymongo write operations on a per-collection basis. This object accumulates write operations to be performed at some point in the future.

mongodbpymongo.database.Database

The MongoDB instance to write data to.

overwrite_existingbool, optional

Whether existing documents should be overwritten. The default of False causes a ValueError to be raised if a document with the given _id already exists and is different from what is being written.

**kwargsdict

Additional keyword arguments poentially used by subclass implementations. Any arguments allowed by a subclass’s _add_auxiliary_write_ops_and_update_doc method is allowed here.

Returns

bson.objectid.ObjectId

The identifier (_id value) of the main document that was written.

remove_me_from_mongodb(mongodb, session=None, recursive='default')

classmethod remove_from_mongodb(mongodb, doc_id, collection_name=None, session=None, recursive='default')

Remove the documents corresponding to an instance of this class from a MongoDB database.

Parameters

mongodbpymongo.database.Database

The MongoDB instance to remove documents from.

doc_idbson.objectid.ObjectId

The identifier of the root document stored in the database.

collection_namestr, optional

the MongoDB collection within mongodb where the main document resides. If None, then <this_class>.collection_name is used (which is usually what you want).

sessionpymongo.client_session.ClientSession, optional

MongoDB session object to use when interacting with the MongoDB database. This can be used to implement transactions among other things.

recursiveRecursiveRemovalSpecification, optional

An object that filters the type of documents that are removed. Used when working with inter-related experiment designs, data, and results objects to only remove the types of documents you know aren’t being shared with other documents.

Returns

None

class pygsti.baseobjs.mongoserializable.WriteOpsByCollection(session=None, allowed_collection_names=None)

Bases: dict

A dictionary of pymongo write operations stored on a per-collection basis.

A dictionary with collection-name (string) keys and where each value is a list of pymongo.InsertOne and pymongo.ReplaceOne operations to be performed on the named collection at some later (unpsecified) time.

The collection names (keys) can be restricted to a predefined set if desired.

Initialize self. See help(type(self)) for accurate signature.

add_ops_by_collection(other_ops)

Merge the information from another WriteOpsByCollection into this one.

Parameters

other_opsWriteOpsByCollection

The dictionary of write operations to merge in.

Returns

None

add_one_op(collection_name, uid, doc, overwrite_existing, mongodb, check_local_ops=True)

Add a single write operation to this dictionary, if one is allowed and needed.

Adds a pymongo.InsertOne or pymongo.ReplaceOne object to self[collection_name] in order to write a document doc with unique identifer uid. If overwrite_existing is False then an error is raised if a document with uid already exists – either in the database or within the list of existing write operations – and the existing document doesn’t match the document being written (doc).

Parameters

collection_namestr

The collection name (key) to add an operation to.

uidbson.object.ObjectId or dict

Unique identifier for the document to write.

docdict

The document to write.

overwrite_existingbool, optional

Whether existing documents should be overwritten. The default of False causes a ValueError to be raised if a document with the given uid already exists and is different from doc.

mongodbpymongo.database.Database

The MongoDB instance documents will eventually be written to. This database is not written to, and used solely to test for existing documents so that insert vs. replace operations are chosen correctly.

check_local_opsbool, optional

Whether the queued-up write operations contained within this WriteOpsByCollection object are considered when testing for the existence of documents. Leaving this set to True is the safe option. Set this to False to get a performance increase when you’re sure there’s no possibility a document with uid could have been “written” to this WriteOpsByCollection since its initialization.

Returns

bson.objectid.ObjectId

The identifier (_id value) of the document to be written or that already exists and matches the one being written.

add_gridfs_put_op(collection_name, doc_id, binary_data, overwrite_existing, mongodb)

Add a GridFS put operation to this dictionary of write operations.

This is a special type of operation for placing large chunks of binary data into a MongoDB. Arguments are similar to add_one_op().

execute(mongodb)

Execute all of the “queued” operations within this dictionary on a MongoDB instance.

Note that mongodb should be the same as the mongodb given to any add_one_op() and add_gridfs_put_op() method calls. The session given at the initialization of this object is used for these write operations. On exit, this dictionary is empty, indicating there are no more queued operations.

Parameters

mongodbpymongo.database.Database

The MongoDB instance to execute write operations on.

Returns

None

pygsti.baseobjs.mongoserializable.prepare_doc_for_existing_doc_check(doc, existing_doc, set_id=True, convert_tuples_to_lists=True, convert_numpy_dtypes=True, round_to_sigfigs=6)

Prepares a to-be inserted document for comparison with an existing document.

Optionally (see parameters): 1. sets _id of doc to that of existing_doc . This is useful in cases where the _id

field is redundant with other uniquely identifying fields in the document, and so inserted documents don’t need to match this field.

2. converts all of doc ‘s tuples to lists, as the existing_doc is typically read from a MongoDB which only stores lists and doesn’t distinguish between lists and tuples.

3. converts numpy datatypes to native python types

4. rounds floating point values

Parameters

docdict

the document to prepare

existing_docdict

the existing document

set_idbool, optional

when True, add an ‘_id’ field to doc matching existing_doc when one is not already present.

convert_tuples_to_listsbool, optional

when True convert all of the tuples within doc to lists.

convert_numpy_dtypesbool, optional

when True convert numpy data types to native python types, e.g. np.float64 -> float.

Returns

dict

the prepared document.

pygsti.baseobjs.mongoserializable.recursive_compare_str(a, b, a_name='first obj', b_name='second obj', prefix='', diff_accum=None)

Compares two objects and generates a list of strings describing how they differ.

Recursively traverses dictionaries, tuples, and lists.

Parameters

a, bobject

The objects to compare

a_name, b_namestr, optional

Names for the a and b objects for referencing them in the output strings.

prefixstr, optional

An optional prefix to the descriptions in the returned strings.

diff_accumlist, optional

An existing list that is accumulating difference-descriptions. None means start a new list.

Returns

list

A list of strings, each describing a difference between the objects.

class pygsti.baseobjs.mongoserializable.RecursiveRemovalSpecification(edesigns=False, data=False, results=False, circuits=False, protocols=False, children=False)

Bases: object

Specifies which types of objects to remove when performing a recursive removal of MongoDB documents.

Parameters

edesignsbool, optional

Whether experiment designs are allowed to be removed.

databool, optional

Whether protocol data objects are allowed to be removed.

resultsbool, optional

Whether result objects and directories are allowed to be removed.

circuitsbool, optional

Whether circuit objects stored in common collections (e.g. “pygsti_circuits”) are allowed to be removed.

protocolsbool, optional

Whether protocol objects are allowed to be removed.

childrenbool, optional

Whether child objects of TreeNode objects are allowed to be removed.

classmethod cast(obj, root_cls_being_deleted=None)

Create a RecursiveRemovalSpecification object from another object.

If obj is already a RecursiveRemovalSpecification object then it is just returned directly. Otherwise, obj can be a string, boolean value, or None:

• False, None, or “none”: no objects are removed recursively (the safe option)

• True or “all”: all recursive removal operation are permitted (the un-safe option)

• “default”: only recursive removal of the type being removed is allowed. For example,

  when removing a ProtocolData object, it and any child ProtocolData objects are removed but experiment designs are not, nor are (potentially shared) circuits.

• “upstream”: recursive removal of the type being removed and “upstream” types is allowed. “Upstream”

  refers to items closer to the front of the list: experiment designs, data objects, result objects. For example, when removing a ProtocolData object, it and any child ProtocolData objects, along with their experiment designs are removed, but circuit objects are not.

• “all_but_circuits”: everything but circuit objects are allowed to be removed. Circuit objects are

  treated specially because they are very likely to be re-used (shared).

Parameters

objobject

The object to convert. See description above.

root_cls_being_deletedclass, optional

The Python class of the main object being deleted. This additional information is needed when (and only when) obj == “default”.

Returns

RecursiveRemovalSpecification