pygsti.io.metadir

Serialization routines to/from a meta.json based directory

Module Contents

Functions

_full_class_name(x)

Returns the <module>.<classname> for x.

_class_for_name(module_and_class_name)

Return the class object given an name.

_get_auxfile_ext(typ)

load_meta_based_dir(root_dir, auxfile_types_member='auxfile_types', ignore_meta=('type', ), separate_auxfiletypes=False, quick_load=False)

Load the contents of a root_dir into a dict.

_load_auxfile_member(root_dir, filenm, typ, metadata, quick_load)

write_meta_based_dir(root_dir, valuedict, auxfile_types=None, init_meta=None)

Write a dictionary of quantities to a directory.

_write_auxfile_member(root_dir, filenm, typ, val)

_cls_from_meta_json(dirname)

Get the object-type corresponding to the 'type' field in dirname/meta.json.

_obj_to_meta_json(obj, dirname)

Create a meta.json file within dirname that contains (only) the type of obj in its 'type' field.

write_obj_to_meta_based_dir(obj, dirname, auxfile_types_member, omit_attributes=())

Write the contents of obj to dirname using a 'meta.json' file and an auxfile-types dictionary.

_read_json_or_pkl_files_to_dict(dirname)

Load any .json or .pkl files in dirname into a dict.

write_dict_to_json_or_pkl_files(d, dirname)

Write each element of d into a separate file in dirname.

_check_jsonable(x)

Checks that x can be properly converted to JSON, detecting

Attributes

QUICK_LOAD_MAX_SIZE

pygsti.io.metadir.QUICK_LOAD_MAX_SIZE
pygsti.io.metadir._full_class_name(x)

Returns the <module>.<classname> for x.

Parameters

x (class) – The class whose full name you want.

Returns

str

pygsti.io.metadir._class_for_name(module_and_class_name)

Return the class object given an name.

Parameters

module_and_class_name (strictly) – The module and class name, e.g. “mymodule.MyClass”

Returns

class

pygsti.io.metadir._get_auxfile_ext(typ)
pygsti.io.metadir.load_meta_based_dir(root_dir, auxfile_types_member='auxfile_types', ignore_meta=('type',), separate_auxfiletypes=False, quick_load=False)

Load the contents of a root_dir into a dict.

The de-serialization uses the ‘meta.json’ file within root_dir to describe how the directory was serialized.

Parameters
  • root_dir (str) – The directory name.

  • auxfile_types_member (str, optional) – The key within meta.json that is used to describe how other members have been serialized into files. Unless you know what you’re doing, leave this as the default.

  • ignore_meta (tuple, optional) – Keys within meta.json that should be ignored, i.e. not loaded into elements of the returned dict. By default, “type” is in this category because it describes a class name to be built and is used in a separate first-pass processing to construct a object. Unless you know what you’re doing, leave this as the default.

  • separate_auxfiletypes (bool, optional) – If True, then return the auxfile_types_member element (a dict describing how quantities that aren’t in ‘meta.json’ have been serialized) as a separate return value, instead of placing it within the returned dict.

  • quick_load (bool, optional) – Setting this to True skips the loading of members that may take a long time to load, namely those in separate files whose files are large. When the loading of an attribute is skipped, it is set to None.

Returns

  • loaded_qtys (dict) – A dictionary of the quantities in ‘meta.json’ plus any loaded from the auxiliary files.

  • auxfile_types (dict) – Only returned as a separate value when separate_auxfiletypes=True. A dict describing how members of loaded_qtys that weren’t loaded directly from ‘meta.json’ were serialized.

pygsti.io.metadir._load_auxfile_member(root_dir, filenm, typ, metadata, quick_load)
pygsti.io.metadir.write_meta_based_dir(root_dir, valuedict, auxfile_types=None, init_meta=None)

Write a dictionary of quantities to a directory.

Write the dictionary by placing everything in a ‘meta.json’ file except for special key/value pairs (“special” usually because they lend themselves to an non-JSON format or they simply cannot be rendered as JSON) which are placed in “auxiliary” files formatted according to auxfile_types (which itself is saved in meta.json).

Parameters
  • root_dir (str) – The directory to write to (will be created if needed).

  • valuedict (dict) – The dictionary of values to serialize to disk.

  • auxfile_types (dict, optional) – A dictionary whose keys are a subset of the keys of valuedict, and whose values are known “aux-file” types. auxfile_types[key] says that valuedict[key] should be serialized into a separate file (whose name is usually key + an appropriate extension) of the given format rather than be included directly in ‘meta.json`. If None, this dictionary is assumed to be valuedict[‘auxfile_types’].

  • init_meta (dict, optional) – A dictionary of “initial” meta-data to be included in the ‘meta.json’ (but that isn’t in valuedict). For example, the class name of an object is often stored as in the “type” field of meta.json when the_model objects .__dict__ is used as valuedict.

Returns

None

pygsti.io.metadir._write_auxfile_member(root_dir, filenm, typ, val)
pygsti.io.metadir._cls_from_meta_json(dirname)

Get the object-type corresponding to the ‘type’ field in dirname/meta.json.

Parameters

dirname (str) – the directory name.

Returns

class

pygsti.io.metadir._obj_to_meta_json(obj, dirname)

Create a meta.json file within dirname that contains (only) the type of obj in its ‘type’ field.

This is used to save an object that contains essentially no other data to a directory, in lieu of :function:`write_obj_to_meta_based_dir`.

Parameters
  • obj (object) – he object whose type you want to save.

  • dirname (str) – the directory name.

Returns

None

pygsti.io.metadir.write_obj_to_meta_based_dir(obj, dirname, auxfile_types_member, omit_attributes=())

Write the contents of obj to dirname using a ‘meta.json’ file and an auxfile-types dictionary.

This is similar to :function:`write_meta_based_dir`, except it takes an object (obj) whose .__dict__, minus omitted attributes, is used as the dictionary to write and whose auxfile-types comes from another object attribute..

Parameters
  • obj (object) – the object to serialize

  • dirname (str) – the directory name

  • auxfile_types_member (str) – the name of the attribute within obj that holds the dictionary mapping of attributes to auxiliary-file types. Usually this is “auxfile_types”.

  • omit_attributes (list or tuple) – List of (string-valued) names of attributes to omit when serializing this object. Usually you should just leave this empty.

Returns

None

pygsti.io.metadir._read_json_or_pkl_files_to_dict(dirname)

Load any .json or .pkl files in dirname into a dict.

Parameters

dirname (str) – the directory name.

Returns

dict

pygsti.io.metadir.write_dict_to_json_or_pkl_files(d, dirname)

Write each element of d into a separate file in dirname.

If the element is json-able, it is JSON-serialized and the “.json” extension is used. If not, pickle is used to serialize the element, and the “.pkl” extension is used. This is the reverse of :function:`_read_json_or_pkl_files_to_dict`.

Parameters
  • d (dict) – the dictionary of elements to serialize.

  • dirname (str) – the directory name.

Returns

None

pygsti.io.metadir._check_jsonable(x)

Checks that x can be properly converted to JSON, detecting errors that the json modules doesn’t pick up. E.g. ensures that x doesn’t contain dicts with non-string-valued keys