### Navigation

- index
- modules |
- FireWorks 0.11 documentation »

# utilities Package

## `dict_mods` Module

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.

`fireworks.utilities.dict_mods.``apply_mod`(modification, obj)

  Note that modify makes actual in-place modifications. It does not return a copy.

  Args:
    modification:
      Modification must be {action_keyword : settings}, where action_keyword is a supported DictMod
    obj:
      A dict to be modified

`fireworks.utilities.dict_mods.``get_nested_dict`(input_dict, key)

## `fw_serializers` Module

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...

Some advantages:
  - Robust with regard to code refactorings even in implicit loading given certain reasonable guidelines on fw_name.
  - Simple to allow a superclass to define all the serializations for its subclasses, removing code repetition

  (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.

`fireworks.utilities.fw_serializers.``DATETIME_HANDLER`(obj)

class `fireworks.utilities.fw_serializers.``FWSerializable`

  To create a serializable object within FireWorks, you should subclass this class and implement the to_dict() and from_dict() methods.

  If you want the load_object() implicit de-serialization to work, you must also:
    - Use the @serialize_fw decorator on to_dict()
    - Override the _fw_name parameter with a unique key.

  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.

  classmethod `from_dict`(m_dict)
  classmethod `from_file`(filename, f_format='AUTO_DETECT')

    Load a serialization of this object from a file :param filename: filename to read :param f_format: serialization format, default checks the filename extension

  classmethod `from_format`(f_str, f_format='json')

    convert from a String representation to its Object :param f_str: the String representation :param f_format: serialization format of the String (default json)

  `fw_name`
  `to_db_dict`()
  `to_dict`()
  `to_file`(filename, f_format='AUTO_DETECT', *args, **kwargs)

    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

  `to_format`(f_format='json', *args, **kwargs)

    returns a String representation in the given format :param f_format: the format to output to (default json)

`fireworks.utilities.fw_serializers.``load_object`(obj_dict)

  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:

  1. the _fw_name property is maintained the same AND
  2. the refactored module is kept within USER_PACKAGES

  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

`fireworks.utilities.fw_serializers.``load_object_from_file`(filename, f_format='AUTO_DETECT')

  implicitly load an object from a file. just a friendly wrapper to load_object()

  Parameters: | filename – the filename to load an object from f_format – the serialization format (default is auto-detect based on filename extension)

`fireworks.utilities.fw_serializers.``recursive_deserialize`(func)

  a decorator to add FW serializations keys see documentation of FWSerializable for more details

`fireworks.utilities.fw_serializers.``recursive_serialize`(func)

  a decorator to add FW serializations keys see documentation of FWSerializable for more details

`fireworks.utilities.fw_serializers.``serialize_fw`(func)

  a decorator to add FW serializations keys see documentation of FWSerializable for more details

## `fw_utilities` Module

`fireworks.utilities.fw_utilities.``create_datestamp_dir`(root_dir, l_logger, prefix='block_')

  Internal method to create a new block or launcher directory. The dir name is based on the time and the FW_BLOCK_FORMAT

  Parameters: | root_dir – directory to create the new dir in l_logger – the logger to use prefix – the prefix for the new dir, default=”block_“

`fireworks.utilities.fw_utilities.``get_fw_logger`(name, l_dir=None, file_levels=('DEBUG', 'ERROR'), stream_level='DEBUG', formatter=<logging.Formatter object at 0x10728eb90>, clear_logs=False)

  Convenience method to return a logger.

  Parameters: | name – name of the logger that sets the groups, e.g. ‘group1.set2’ l_dir – the directory to put the log file file_levels – iterable describing level(s) to log to file(s). default: (‘DEBUG’, ‘ERROR’) stream_level – level to log to standard output. default: ‘DEBUG’ formatter – logging format. default: FW_LOGGING_FORMATTER clear_logs – whether to clear the logger with the same name

`fireworks.utilities.fw_utilities.``get_my_host`()

`fireworks.utilities.fw_utilities.``get_my_ip`()

`fireworks.utilities.fw_utilities.``log_exception`(m_logger, msgs)

  A shortcut wrapper around log_fancy for exceptions

  Parameters: | m_logger – The logger object msgs – An iterable of Strings, will be joined by newlines

`fireworks.utilities.fw_utilities.``log_fancy`(m_logger, log_lvl, msgs, add_traceback=False)

  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: | m_logger – The logger object log_lvl – The level to log at msgs – a String or iterable of Strings add_traceback – add traceback text, useful when logging exceptions (default False)

## Subpackages

- tests Package
  - `test_fw_serializers` Module
  - `test_serializer` Module

### Navigation

- index
- modules |
- FireWorks 0.11 documentation »