### Navigation

- index
- modules |
- FireWorks 0.66 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=None)

    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=None, **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', **kwargs)

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

`fireworks.utilities.fw_serializers.``get_default_serialization`(cls)

`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=None)

  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

class `fireworks.utilities.fw_utilities.``DataServer`(address=None, authkey=None, serializer='pickle')

  Bases: `multiprocessing.managers.BaseManager`

  Provide a server that can host shared objects between multiprocessing Processes (that normally can’t share data). For example, a common LaunchPad is shared between processes and pinging launches is coordinated to limit DB hits.

  classmethod `setup`(launchpad)

    Parameters: | launchpad – (LaunchPad) object
    Returns: |

class `fireworks.utilities.fw_utilities.``NestedClassGetter`

  Bases: `object`

  Used to help pickle inner classes, e.g. see Workflow.Links When called with the containing class as the first argument, and the name of the nested class as the second argument, returns an instance of the nested class.

`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.``explicit_serialize`(o)

`fireworks.utilities.fw_utilities.``get_fw_logger`(name, l_dir=None, file_levels=('DEBUG', 'ERROR'), stream_level='DEBUG', formatter=<logging.Formatter object at 0x110e75690>, 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.``get_slug`(m_str)

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

  A shortcut wrapper around log_fancy for exceptions

  Parameters: | m_logger – (logger) The logger object msgs – ([str]) String or iterable of Strings, will be joined by newlines

`fireworks.utilities.fw_utilities.``log_fancy`(m_logger, msgs, log_lvl='info', 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 – (logger) The logger object log_lvl – (str) The level to log at msgs – ([str]) a String or iterable of Strings add_traceback – (bool) add traceback text, useful when logging exceptions (default False)

`fireworks.utilities.fw_utilities.``log_multi`(m_logger, msg, log_lvl='info')

  Parameters: | m_logger – (logger) The logger object msg – (str) a String to log log_lvl – (str) The level to log at

`fireworks.utilities.fw_utilities.``reverse_readline`(m_file, blk_size=4096, max_mem=4000000)

  Generator method to read a file line-by-line, but backwards. This allows one to efficiently get data at the end of a file.

  Based on code by Peter Astrand <astrand@cendio.se>, using modifications by Raymond Hettinger and Kevin German. http://code.activestate.com/recipes/439045-read-a-text-file-backwards -yet-another-implementat/

  Reads file forwards and reverses in memory for files smaller than the max_mem parameter, or for gzip files where reverse seeks are not supported.

  Files larger than max_mem are dynamically read backwards.

  Args:
    m_file:
      File stream to read (backwards)
    blk_size:
      The buffer size. Defaults to 4096.
    max_mem:
      The maximum amount of memory to involve in this operation. This is used to determine when to reverse a file in-memory versus seeking portions of a file. For bz2 files, this sets the maximum block size.
  Returns:
    Generator that returns lines from the file. Similar behavior to the file.readline() method, except the lines are returned from the back of the file.

## Subpackages

- tests Package
  - `test_fw_serializers` Module

### Navigation

- index
- modules |
- FireWorks 0.66 documentation »