gnome.persist.save_load

Save/load gnome objects

Module Contents

Classes

Refs	Class to store and handle references during saving/loading.
References	PyGnome objects like the PointWindMover contain other objects, eg Wind object.
Savable	Create a mixin for save/load options for saving and loading serialized

Functions

load(saveloc[, fname, references])	read json from file and load the appropriate object
is_savezip_valid(savezip)	some basic checks on validity of zipfile. Primarily for checking save
zipfile_folders(zip_file)	Get a list of the folders in our archive.
extract_zipfile(zip_file[, to_folder, prefix])

Attributes

log
_max_json_filesize
_max_compress_ratio

gnome.persist.save_load.log

class gnome.persist.save_load.Refs

Bases: dict

Class to store and handle references during saving/loading. Provides some convenience functions

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

__setitem__(i, y)

Set self[key] to value.

gen_default_name(obj)

Goes through the dict, finds all objects of obj.obj_type stored, and provides a unique name by appending length+1

class gnome.persist.save_load.References

Bases: object

PyGnome objects like the PointWindMover contain other objects, eg Wind object. When persisting a Model, the Wind object is not created by the PointWindMover, it is merely referenced by the PointWindMover. When persisting a Model, the referenced objects are saved in their own file and a reference is stored for it. This class manages these references.

property files

__contains__(obj)

get_reference(obj)

return key if obj already exists in references list else return None

_add_reference_with_name(obj, name)

add an object reference specified by ‘name’

reference(obj, name=None)

Get a unique reference to the object. By default this string is the filename in which the json for the object is stored If a reference to obj already exists, then it is returned

Parameters:

• obj – object for which a reference must be added

• name=None – add an object reference specified by ‘name’ for filename

retrieve(ref)

retrieve the object associated with the reference

gnome.persist.save_load.load(saveloc, fname='Model.json', references=None)

read json from file and load the appropriate object This is a general purpose load method that looks at the json[‘obj_type’] and invokes json[‘obj_type’].loads(json) method

Parameters:

• saveloc – path to zipfile that contains data files and json files. It could also be a directory containing files - keep original support for location files.

• fname – .json file to load. Default is ‘Model.json’. zipfile/dir must contain ‘fname’

• references=None – References object that keeps track of objects in a dict as they are constructed, using the filename as the key

Returns:

object constructed from the json

Note

Function first assumes saveloc is a directory and looks for saveloc/fname. If this fails, it checks if saveloc is a zipfile. If this fails, it checks if saveloc is a file and loads this assuming its json for a gnome object. If none of these work, it just returns None.

class gnome.persist.save_load.Savable

Bases: object

Create a mixin for save/load options for saving and loading serialized gnome objects. Mix this in with the Serializable class so all gnome objects can save/load themselves

_allowzip64 = False

_ref_in_saveloc(saveloc, ref)

returns true if reference is found in saveloc, false otherwise

_update_and_save_refs(json_, saveloc, references)

for attributes that are stored as references - ensure the references are moved to saveloc, and update its value in the json_

_json_to_saveloc(json_, saveloc, references=None, name=None)

save json_ to saveloc

-. first save and update references if any attributes are stored as

references

-. add self to references -. move any datafiles to saveloc that need to be persisted -. finally, write json_ directly to zip if saveloc is a zip or dump

to *.json of saveloc is a directory

Parameters:

• json – json data after serialization. Default is the output of self.serialize(‘save’)

• saveloc – Either zipfile to which object’s json can be appended. Or a valid path where object’s *.json can be dumped to a file

• references – References object to keep track of objects that have been constructed. If a referenced object has been saved, no need to add it again to saveloc - don’t want multiple copies

• name – json is stored in ‘name.json’ in zip archive/specified directory. Default is self.__class__.__name__. If references object contains self.__class__.__name__, then let

_write_to_file(saveloc, f_name, json_)

_write_to_zip(saveloc, f_name, s_data)

general function for writing string data directly to zipfile.

f_name is the archive name and s_data is the corresponding string, added to zipfile

_move_data_file(saveloc, json_)

• Look at _state attribute of object.

• Find all fields with ‘isdatafile’ attribute as True.

• If there is a key in json_ corresponding with ‘name’ of the fields with True ‘isdatafile’ attribute

• then - move that datafile and - update the key in the json_ to point to new location

classmethod _load_refs(json_data, saveloc, references)

loads up references. First looks for object in references, if not found then it creates object from json and adds a reference to it. If found in references, it just uses/returns the object

classmethod _update_datafile_path(json_data, saveloc)

update path to attributes that use a datafile if saveloc is a zipfile, then extract the datafile to same location as zipfile and upate path in json_data.

classmethod loads(json_data, saveloc=None, references=None)

loads object from json_data

• load json for references from files

• update paths of datafiles if needed

• deserialize json_data

• and create object with new_from_dict()

json_data: dict containing json data. It has been parsed through the

json.loads() command. The json will be valided here when it gets deserialized. Its references and datafile paths will be recreated here prior to calling new_from_dict()

Optional parameter

Parameters:

• saveloc – location of data files or .json files for objects stored as references. If object requires no datafiles and does not need to read references from a .json file in saveloc, then this can be None.

• references – references object - if this is called by the Model, it will pass a references object. It is not required.

Returns:

object constructed from json_data.

_save_collection(saveloc, coll_, refs, coll_json)

Reference objects inside OrderedCollections or list. Since the OC itself isn’t a reference but the objects in the list are a reference, do something a little differently here

Parameters:

coll (OrderedCollection) – ordered collection/list to be saved

classmethod _load_collection(saveloc, l_coll_dict, refs)

doesn’t need to be classmethod of the Model, but its only used by Model at present

gnome.persist.save_load._max_json_filesize

gnome.persist.save_load._max_compress_ratio = 54

gnome.persist.save_load.is_savezip_valid(savezip)

some basic checks on validity of zipfile. Primarily for checking save zipfiles loaded from the Web. Following are the types of errors it checks:

Returns:

True if zip is valid, False otherwise

1. Failed to open zipfile

2. CRC failed for a file in the archive - rejecting zip

3. Found a *.json with size > _max_json_filesize - rejecting

4. Reject - found a file with:

   uncompressed_size/compressed_size > _max_compress_ratio.

5. Found a file in archive that has path outside of saveloc - rejecting

   rejects zipfile if it contains an archive with ‘..’

Note

can change _max_json_filesize, _max_compress_ratio if required.

gnome.persist.save_load.zipfile_folders(zip_file)

Get a list of the folders in our archive. - MAC OS X created zipfiles contain a folder named ‘__MACOSX/’,

which is intended to contain file and folder related metadata. we would like to ignore this folder.

gnome.persist.save_load.extract_zipfile(zip_file, to_folder='.', prefix='')