custodian.ansible package

Subpackages

Submodules

custodian.ansible.actions module

This module defines various classes of supported actions. All actions are implemented as static methods, but are defined using classes (as opposed to modules) so that a set of well-defined actions can be namespaced easily.

class DictActions[source]

Bases: object

Class to implement the supported mongo-like modifications on a dict. Supported keywords include the following Mongo-based keywords, with the usual meanings (refer to Mongo documentation for information):

_inc _set _unset _push _push_all _add_to_set (but _each is not supported) _pop _pull _pull_all _rename

However, note that “_set” does not support modification of nested dicts using the mongo {“a.b”:1} notation. This is because mongo does not allow keys with “.” to be inserted. Instead, nested dict modification is supported using a special “->” keyword, e.g. {“a->b”: 1}

static add_to_set(input_dict, settings)[source]

Add to set using MongoDB syntax.

Parameters
  • input_dict (dict) – The input dictionary to be modified.

  • settings (dict) – The specification of the modification to be made.

static inc(input_dict, settings)[source]

Increment a value using MongdoDB syntax.

Parameters
  • input_dict (dict) – The input dictionary to be modified.

  • settings (dict) – The specification of the modification to be made.

static pop(input_dict, settings)[source]

Pop item from a list using MongoDB syntax.

Parameters
  • input_dict (dict) – The input dictionary to be modified.

  • settings (dict) – The specification of the modification to be made.

static pull(input_dict, settings)[source]

Pull an item using MongoDB syntax.

Parameters
  • input_dict (dict) – The input dictionary to be modified.

  • settings (dict) – The specification of the modification to be made.

static pull_all(input_dict, settings)[source]

Pull multiple items to a list using MongoDB syntax.

Parameters
  • input_dict (dict) – The input dictionary to be modified.

  • settings (dict) – The specification of the modification to be made.

static push(input_dict, settings)[source]

Push to a list using MongoDB syntax.

Parameters
  • input_dict (dict) – The input dictionary to be modified.

  • settings (dict) – The specification of the modification to be made.

static push_all(input_dict, settings)[source]

Push multiple items to a list using MongoDB syntax.

Parameters
  • input_dict (dict) – The input dictionary to be modified.

  • settings (dict) – The specification of the modification to be made.

static rename(input_dict, settings)[source]

Rename a key using MongoDB syntax.

Parameters
  • input_dict (dict) – The input dictionary to be modified.

  • settings (dict) – The specification of the modification to be made.

static set(input_dict, settings)[source]

Sets a value using MongoDB syntax.

Parameters
  • input_dict (dict) – The input dictionary to be modified.

  • settings (dict) – The specification of the modification to be made.

static unset(input_dict, settings)[source]

Unsets a value using MongoDB syntax.

Parameters
  • input_dict (dict) – The input dictionary to be modified.

  • settings (dict) – The specification of the modification to be made.

class FileActions[source]

Bases: object

Class of supported file actions. For FileActions, the modder class takes in a filename as a string. The filename should preferably be a full path to avoid ambiguity.

static file_copy(filename, settings)[source]

Copies a file. {‘_file_copy’: {‘dest’: ‘new_file_name’}}

Parameters
  • filename (str) – Filename.

  • settings (dict) – Must be {“dest”: path of new file}

static file_create(filename, settings)[source]

Creates a file.

Parameters
  • filename (str) – Filename.

  • settings (dict) – Must be {“content”: actual_content}

static file_delete(filename, settings)[source]

Deletes a file. {‘_file_delete’: {‘mode’: “actual”}}

Parameters
  • filename (str) – Filename.

  • settings (dict) – Must be {“mode”: actual/simulated}. Simulated mode only prints the action without performing it.

static file_modify(filename, settings)[source]

Modifies file access

Parameters
  • filename (str) – Filename.

  • settings (dict) – Can be “mode” or “owners”

static file_move(filename, settings)[source]

Moves a file. {‘_file_move’: {‘dest’: ‘new_file_name’}}

Parameters
  • filename (str) – Filename.

  • settings (dict) – Must be {“dest”: path of new file}

get_nested_dict(input_dict, key)[source]

Helper function to interpret a nested dict input.

custodian.ansible.interpreter module

This module implements a Modder class that performs modifications on objects using support actions.

class Modder(actions=None, strict=True)[source]

Bases: object

Class to modify a dict/file/any object using a mongo-like language. Keywords are mostly adopted from mongo’s syntax, but instead of $, an underscore precedes action keywords. This is so that the modification can be inserted into a mongo db easily.

Allowable actions are supplied as a list of classes as an argument. Refer to the action classes on what the actions do. Action classes are in pymatpro.ansible.actions.

Examples: >>> modder = Modder() >>> d = {“Hello”: “World”} >>> mod = {‘_set’: {‘Hello’:’Universe’, ‘Bye’: ‘World’}} >>> modder.modify(mod, d) >>> d[‘Bye’] ‘World’ >>> d[‘Hello’] ‘Universe’

Initializes a Modder from a list of supported actions.

Parameters
  • actions ([Action]) – A sequence of supported actions. See custodian.ansible.actions. Default is None, which means only DictActions are supported.

  • strict (bool) – Indicating whether to use strict mode. In non-strict mode, unsupported actions are simply ignored without any errors raised. In strict mode, if an unsupported action is supplied, a ValueError is raised. Defaults to True.

modify(modification, obj)[source]

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

Parameters
  • modification (dict) – Modification must be {action_keyword : settings}. E.g., {‘_set’: {‘Hello’:’Universe’, ‘Bye’: ‘World’}}

  • obj (dict/str/object) – Object to modify depending on actions. For example, for DictActions, obj will be a dict to be modified. For FileActions, obj will be a string with a full pathname to a file.

modify_object(modification, obj)[source]

Modify an object that supports pymatgen’s as_dict() and from_dict API.

Parameters
  • modification (dict) – Modification must be {action_keyword : settings}. E.g., {‘_set’: {‘Hello’:’Universe’, ‘Bye’: ‘World’}}

  • obj (object) – Object to modify

Module contents

The ansible package provides modules that provides a mongo-like syntax for making modifications to dicts, objects and files. The mongo-like syntax itself is a dict.

The main use of this package is to allow changes to objects or files to be stored in a json file or MongoDB database, i.e., a form of version control or tracked changes (though without undo capability unless the input is stored at each step).