This module allows you to modify a dict (a spec) using another dict (an instruction). The main method of interest is apply_dictmod().
This code is based heavily on the Ansible class of custodian <https://pypi.python.org/pypi/custodian>, but simplifies it considerably for the limited use cases required by FireWorks.
Note that modify makes actual in-place modifications. It does not return a copy.
This module aids in serializing and deserializing objects.
To serialize a FW object, refer to the documentation for the FWSerializable class. To de-serialize an object, refer to the documentation for the FWSerializable class and load_object() method.
- you can de-serialize explicitly, e.g. FWObject.from_dict() to enforce a FWObject instance as the result
- you can de-serialize implicitly, e.g. load_object() to search for the correct Class dynamically
The implicit method is especially useful if you don’t know in advance which subclass of a base class your serialization might point to. e.g. if you require some type of Quadrilateral, a serialization from your collaborator might point to a Square, Rhombus, or Rectangle, and you might not know which one in advance...
(in particular, note that from_dict is a class method rather than a static method, allowing use of self) - Decorators aid in some of the routine parts of the serialization, such as adding the _fw_name key - Both JSON and YAML file import/export are naturally and concisely supported within the framework. - Auto-detect and proper loading of JSON and YAML files - Proper JSON handling of datetime (both encoding and decoding) and UTF-8 strings - In some cases, objects can be serialized/deserialized extremely concisely, by use of only their fw_name (if no parameters are needed to describe the object)
A dict created using FWSerializer’s to_dict() method should be readable by Pymatgen’s PMGDecoder, when the serialize_fw() decorator is used.
To create a serializable object within FireWorks, you should subclass this class and implement the to_dict() and from_dict() methods.
See documentation of load_object() for more details.
The use of @classmethod for from_dict allows you to define a superclass that implements the to_dict() and from_dict() for all its subclasses.
For an example of serialization, see the class QueueAdapterBase.
Load a serialization of this object from a file :param filename: filename to read :param f_format: serialization format, default checks the filename extension
convert from a String representation to its Object :param f_str: the String representation :param f_format: serialization format of the String (default json)
Write a serialization of this object to a file :param filename: filename to write to :param f_format: serialization format, default checks the filename extension
returns a String representation in the given format :param f_format: the format to output to (default json)
Creates an instantiation of a class based on a dictionary representation. We implicitly determine the Class through introspection along with information in the dictionary.
We search for a class with the _fw_name property equal to obj_dict[‘_fw_name’] If the @module key is set, that module is checked first for a matching class to improve speed of lookup. Afterwards, the modules in the USER_PACKAGES global parameter are checked.
Refactoring class names, module names, etc. will not break object loading as long as:
You can get around these limitations if you really want: i) If you want to change the fw_name of an object you can set the FW_NAME_UPDATES key ii) If you want to put a refactored module in a new place add an entry to USER_PACKAGES
Parameters: | obj_dict – the dict representation of the class |
---|
implicitly load an object from a file. just a friendly wrapper to load_object()
Parameters: |
|
---|
a decorator to add FW serializations keys see documentation of FWSerializable for more details
Internal method to create a new block or launcher directory. The dir name is based on the time and the FW_BLOCK_FORMAT
Parameters: |
|
---|
Convenience method to return a logger.
Parameters: |
|
---|
A shortcut wrapper around log_fancy for exceptions
Parameters: |
|
---|
A wrapper around the logger messages useful for multi-line logs. Helps to group log messages by adding a fancy border around it, which enhances readability of log lines meant to be read as a unit.
Parameters: |
|
---|