aiida.common package

Submodules

aiida.common.archive.extract_cif(infile, folder, nodes_export_subfolder='nodes', aiida_export_subfolder='aiida', silent=False)[source]

Extract the nodes to be imported from a TCOD CIF file. TCOD CIFs, exported by AiiDA, may contain an importable subset of AiiDA database, which can be imported. This function prepares SandboxFolder with files required for import.

Parameters:
  • infile – file path
  • folder – a SandboxFolder, used to extract the file tree
  • nodes_export_subfolder – name of the subfolder for AiiDA nodes
  • aiida_export_subfolder – name of the subfolder for AiiDA data inside the TCOD CIF internal file tree
  • silent – suppress debug print
aiida.common.archive.extract_tar(infile, folder, nodes_export_subfolder='nodes', silent=False)[source]

Extract the nodes to be imported from a (possibly zipped) tar file.

Parameters:
  • infile – file path
  • folder – a SandboxFolder, used to extract the file tree
  • nodes_export_subfolder – name of the subfolder for AiiDA nodes
  • silent – suppress debug print
aiida.common.archive.extract_tree(infile, folder, silent=False)[source]

Prepare to import nodes from plain file system tree.

Parameters:
  • infile – path
  • folder – a SandboxFolder, used to extract the file tree
  • silent – suppress debug print
aiida.common.archive.extract_zip(infile, folder, nodes_export_subfolder='nodes', silent=False)[source]

Extract the nodes to be imported from a zip file.

Parameters:
  • infile – file path
  • folder – a SandboxFolder, used to extract the file tree
  • nodes_export_subfolder – name of the subfolder for AiiDA nodes
  • silent – suppress debug print
aiida.common.caching.get_use_cache(*args, **kwargs)[source]
aiida.common.caching.enable_caching(*args, **kwds)[source]

Context manager to enable caching, either for a specific node class, or globally. Note that this does not affect the behavior of the daemon, only the local Python instance.

Parameters:node_class – Node class for which caching should be enabled.
aiida.common.caching.disable_caching(*args, **kwds)[source]

Context manager to disable caching, either for a specific node class, or globally. Note that this does not affect the behavior of the daemon, only the local Python instance.

Parameters:node_class – Node class for which caching should be disabled.

This module defines the (physical) constants that are used throughout the code. Note that

This module defines the main data structures used by Calculations.

class aiida.common.datastructures.CalcInfo[source]

Bases: aiida.common.extendeddicts.DefaultFieldsAttributeDict

This object will store the data returned by the calculation plugin and to be passed to the ExecManager.

In the following descriptions all paths have to be considered relative

  • retrieve_list: a list of strings or tuples that indicate files that are to be retrieved from the remote

    after the calculation has finished and stored in the repository in a FolderData. If the entry in the list is just a string, it is assumed to be the filepath on the remote and it will be copied to ‘.’ of the repository with name os.path.split(item)[1] If the entry is a tuple it is expected to have the following format

    (‘remotepath’, ‘localpath’, depth)

    If the ‘remotepath’ is a file or folder, it will be copied in the repository to ‘localpath’. However, if the ‘remotepath’ contains file patterns with wildcards, the ‘localpath’ should be set to ‘.’ and the depth parameter should be an integer that decides the localname. The ‘remotepath’ will be split on file separators and the local filename will be determined by joining the N last elements, where N is given by the depth variable.

    Example: (‘some/remote/path/files/pattern*[0-9].xml’, ‘.’, 2)

    Will result in all files that match the pattern to be copied to the local repository with path

    ‘files/pattern*[0-9].xml’

  • retrieve_temporary_list: a list of strings or tuples that indicate files that will be retrieved

    and stored temporarily in a FolderData, that will be available only during the parsing call. The format of the list is the same as that of ‘retrieve_list’

  • retrieve_singlefile_list: a list of tuples with format

    (‘linkname_from calc to singlefile’, ‘subclass of singlefile’, ‘filename’) Each tuple represents a file that will be retrieved from cluster and saved in SinglefileData nodes

  • local_copy_list: a list of tuples with format (‘localabspath’, ‘relativedestpath’)

  • remote_copy_list: a list of tuples with format (‘remotemachinename’, ‘remoteabspath’, ‘relativedestpath’)

  • remote_symlink_list: a list of tuples with format (‘remotemachinename’, ‘remoteabspath’, ‘relativedestpath’)

  • codes_info: a list of dictionaries used to pass the info of the execution of a code

  • codes_run_mode: a string used to specify the order in which multi codes can be executed

__module__ = 'aiida.common.datastructures'
_default_fields = ('job_environment', 'email', 'email_on_started', 'email_on_terminated', 'uuid', 'prepend_text', 'append_text', 'num_machines', 'num_mpiprocs_per_machine', 'priority', 'max_wallclock_seconds', 'max_memory_kb', 'rerunnable', 'retrieve_list', 'retrieve_temporary_list', 'retrieve_singlefile_list', 'local_copy_list', 'remote_copy_list', 'remote_symlink_list', 'codes_info', 'codes_run_mode')
class aiida.common.datastructures.CalcState[source]

Bases: aiida.common.extendeddicts.Enumerate

__module__ = 'aiida.common.datastructures'
class aiida.common.datastructures.CodeInfo[source]

Bases: aiida.common.extendeddicts.DefaultFieldsAttributeDict

This attribute-dictionary contains the information needed to execute a code. Possible attributes are:

  • cmdline_params: a list of strings, containing parameters to be written on the command line right after the call to the code, as for example:

    code.x cmdline_params[0] cmdline_params[1] ... < stdin > stdout
    
  • stdin_name: (optional) the name of the standard input file. Note, it is only possible to use the stdin with the syntax:

    code.x < stdin_name
    

    If no stdin_name is specified, the string “< stdin_name” will not be passed to the code. Note: it is not possible to substitute/remove the ‘<’ if stdin_name is specified; if that is needed, avoid stdin_name and use instead the cmdline_params to specify a suitable syntax.

  • stdout_name: (optional) the name of the standard output file. Note, it is only possible to pass output to stdout_name with the syntax:

    code.x ... > stdout_name
    

    If no stdout_name is specified, the string “> stdout_name” will not be passed to the code. Note: it is not possible to substitute/remove the ‘>’ if stdout_name is specified; if that is needed, avoid stdout_name and use instead the cmdline_params to specify a suitable syntax.

  • stderr_name: (optional) a string, the name of the error file of the code.

  • join_files: (optional) if True, redirects the error to the output file. If join_files=True, the code will be called as:

    code.x ... > stdout_name 2>&1
    

    otherwise, if join_files=False and stderr is passed:

    code.x ... > stdout_name 2> stderr_name
    
  • withmpi: if True, executes the code with mpirun (or another MPI installed on the remote computer)

  • code_uuid: the uuid of the code associated to the CodeInfo

__module__ = 'aiida.common.datastructures'
_default_fields = ('cmdline_params', 'stdin_name', 'stdout_name', 'stderr_name', 'join_files', 'withmpi', 'code_uuid')
class aiida.common.datastructures.CodeRunmode[source]

Bases: aiida.common.extendeddicts.Enumerate

__module__ = 'aiida.common.datastructures'
class aiida.common.datastructures.WorkflowDataType[source]

Bases: aiida.common.extendeddicts.Enumerate

__module__ = 'aiida.common.datastructures'
class aiida.common.datastructures.WorkflowDataValueType[source]

Bases: aiida.common.extendeddicts.Enumerate

__module__ = 'aiida.common.datastructures'
class aiida.common.datastructures.WorkflowState[source]

Bases: aiida.common.extendeddicts.Enumerate

__module__ = 'aiida.common.datastructures'
aiida.common.datastructures.sort_states(list_states, use_key=False)[source]

Given a list of state names, return a sorted list of states (the first is the most recent) sorted according to their logical appearance in the DB (i.e., NEW before of SUBMITTING before of FINISHED).

Note

The order of the internal variable _sorted_datastates is used.

Parameters:
  • list_states – a list (or tuple) of state strings.
  • use_key – if True, expects that each element is not just a string, but a pair (someobject, string). Only string is used to sort (should be the state string), and only someobject is returned in the final list.
Returns:

a sorted list of the given data states.

Raises:

ValueError – if any of the given states is not a valid state.

aiida.common.example_helpers.test_and_get_code(codename, expected_code_type, use_exceptions=False)[source]

Pass a code name and an expected code (plugin) type. Check that the code exists, is unique, and return the Code object.

Parameters:
  • codename – the name of the code to load (in the form label@machine)
  • expected_code_type – a string with the plugin that is expected to be loaded. In case no plugins exist with the given name, show all existing plugins of that type
  • use_exceptions – if True, raise a ValueError exception instead of calling sys.exit(1)
Returns:

a Code object

exception aiida.common.exceptions.AiidaException[source]

Bases: exceptions.Exception

Base class for all AiiDA exceptions.

Each module will have its own subclass, inherited from this (e.g. ExecManagerException, TransportException, …)

__module__ = 'aiida.common.exceptions'
__weakref__

list of weak references to the object (if defined)

exception aiida.common.exceptions.ConfigurationError[source]

Bases: aiida.common.exceptions.AiidaException

Error raised when there is a configuration error in AiiDA.

__module__ = 'aiida.common.exceptions'
exception aiida.common.exceptions.ConfigurationVersionError[source]

Bases: aiida.common.exceptions.ConfigurationError

Configuration error raised when the configuration file version is not compatible with the current version.

__module__ = 'aiida.common.exceptions'
exception aiida.common.exceptions.ContentNotExistent[source]

Bases: aiida.common.exceptions.NotExistent

Raised when trying to access an attribute, a key or a file in the result nodes that is not present

__module__ = 'aiida.common.exceptions'
exception aiida.common.exceptions.DbContentError[source]

Bases: aiida.common.exceptions.AiidaException

Raised when the content of the DB is not valid. This should never happen if the user does not play directly with the DB.

__module__ = 'aiida.common.exceptions'
exception aiida.common.exceptions.FailedError[source]

Bases: aiida.common.exceptions.AiidaException

Raised when accessing a calculation that is in the FAILED status

__module__ = 'aiida.common.exceptions'
exception aiida.common.exceptions.FeatureDisabled[source]

Bases: aiida.common.exceptions.AiidaException

Raised when a feature is requested, but the user has chosen to disable it (e.g., for submissions on disabled computers).

__module__ = 'aiida.common.exceptions'
exception aiida.common.exceptions.FeatureNotAvailable[source]

Bases: aiida.common.exceptions.AiidaException

Raised when a feature is requested from a plugin, that is not available.

__module__ = 'aiida.common.exceptions'
exception aiida.common.exceptions.InputValidationError[source]

Bases: aiida.common.exceptions.ValidationError

The input data for a calculation did not validate (e.g., missing required input data, wrong data, …)

__module__ = 'aiida.common.exceptions'
exception aiida.common.exceptions.IntegrityError[source]

Bases: aiida.common.exceptions.AiidaException

Raised when there is an underlying data integrity error. This can be database related or a general data integrity error. This can happen if, e.g., a foreign key check fails. See PEP 249 for details.

__module__ = 'aiida.common.exceptions'
exception aiida.common.exceptions.InternalError[source]

Bases: aiida.common.exceptions.AiidaException

Error raised when there is an internal error of AiiDA.

__module__ = 'aiida.common.exceptions'
exception aiida.common.exceptions.InvalidOperation[source]

Bases: aiida.common.exceptions.AiidaException

The allowed operation is not valid (e.g., when trying to add a non-internal attribute before saving the entry), or deleting an entry that is protected (e.g., because it is referenced by foreign keys)

__module__ = 'aiida.common.exceptions'
exception aiida.common.exceptions.LicensingException[source]

Bases: aiida.common.exceptions.AiidaException

Raised when requirements for data licensing are not met.

__module__ = 'aiida.common.exceptions'
exception aiida.common.exceptions.LoadingEntryPointError[source]

Bases: aiida.common.exceptions.AiidaException

Raised when the class corresponding to requested entry point cannot be loaded

__module__ = 'aiida.common.exceptions'
exception aiida.common.exceptions.LoadingPluginFailed[source]

Bases: aiida.common.exceptions.AiidaException

Raised when loading a plugin through the plugin loader fails

__module__ = 'aiida.common.exceptions'
exception aiida.common.exceptions.MissingConfigurationError[source]

Bases: aiida.common.exceptions.ConfigurationError

Configuration error raised when the configuration file is missing.

__module__ = 'aiida.common.exceptions'
exception aiida.common.exceptions.MissingEntryPointError[source]

Bases: aiida.common.exceptions.AiidaException

Raised when the requested entry point is not registered with the entry point manager

__module__ = 'aiida.common.exceptions'
exception aiida.common.exceptions.MissingPluginError[source]

Bases: aiida.common.exceptions.AiidaException

Raised when the user tries to use a plugin that is not available or does not exist.

__module__ = 'aiida.common.exceptions'
exception aiida.common.exceptions.ModificationNotAllowed[source]

Bases: aiida.common.exceptions.AiidaException

Raised when the user tries to modify a field, object, property, … that should not be modified.

__module__ = 'aiida.common.exceptions'
exception aiida.common.exceptions.MultipleEntryPointError[source]

Bases: aiida.common.exceptions.AiidaException

Raised when the requested entry point cannot uniquely be resolved by the entry point manager

__module__ = 'aiida.common.exceptions'
exception aiida.common.exceptions.MultipleObjectsError[source]

Bases: aiida.common.exceptions.AiidaException

Raised when more than one entity is found in the DB, but only one was expected.

__module__ = 'aiida.common.exceptions'
exception aiida.common.exceptions.NotExistent[source]

Bases: aiida.common.exceptions.AiidaException

Raised when the required entity does not exist.

__module__ = 'aiida.common.exceptions'
exception aiida.common.exceptions.ParsingError[source]

Bases: aiida.common.exceptions.AiidaException

Generic error raised when there is a parsing error

__module__ = 'aiida.common.exceptions'
exception aiida.common.exceptions.PluginInternalError[source]

Bases: aiida.common.exceptions.InternalError

Error raised when there is an internal error which is due to a plugin and not to the AiiDA infrastructure.

__module__ = 'aiida.common.exceptions'
exception aiida.common.exceptions.ProfileConfigurationError[source]

Bases: aiida.common.exceptions.ConfigurationError

Configuration error raised when a wrong/inexistent profile is requested.

__module__ = 'aiida.common.exceptions'
exception aiida.common.exceptions.RemoteOperationError[source]

Bases: aiida.common.exceptions.AiidaException

Raised when an error in a remote operation occurs, as in a failed kill() of a scheduler job.

__module__ = 'aiida.common.exceptions'
exception aiida.common.exceptions.TestsNotAllowedError[source]

Bases: aiida.common.exceptions.AiidaException

Raised when tests are required to be run/loaded, but we are not in a testing environment.

This is to prevent data loss.

__module__ = 'aiida.common.exceptions'
exception aiida.common.exceptions.UniquenessError[source]

Bases: aiida.common.exceptions.AiidaException

Raised when the user tries to violate a uniqueness constraint (on the DB, for instance).

__module__ = 'aiida.common.exceptions'
exception aiida.common.exceptions.UnsupportedSpeciesError[source]

Bases: exceptions.ValueError

Raised when StructureData operations are fed species that are not supported by AiiDA such as Deuterium

__module__ = 'aiida.common.exceptions'
__weakref__

list of weak references to the object (if defined)

exception aiida.common.exceptions.ValidationError[source]

Bases: aiida.common.exceptions.AiidaException

Error raised when there is an error during the validation phase of a property.

__module__ = 'aiida.common.exceptions'
exception aiida.common.exceptions.WorkflowInputValidationError[source]

Bases: aiida.common.exceptions.ValidationError

The input data for a workflow did not validate (e.g., missing required input data, wrong data, …)

__module__ = 'aiida.common.exceptions'
class aiida.common.extendeddicts.AttributeDict[source]

Bases: dict

This class internally stores values in a dictionary, but exposes the keys also as attributes, i.e. asking for attrdict.key will return the value of attrdict[‘key’] and so on.

Raises an AttributeError if the key does not exist, when called as an attribute, while the usual KeyError if the key does not exist and the dictionary syntax is used.

__deepcopy__(memo=None)[source]

Support deepcopy.

__delattr__(attr)[source]

Delete a key as an attribute. Raise AttributeError on missing key.

__dict__ = dict_proxy({'__module__': 'aiida.common.extendeddicts', 'copy': <function copy>, '__setstate__': <function __setstate__>, '__deepcopy__': <function __deepcopy__>, '__setattr__': <function __setattr__>, '__getattr__': <function __getattr__>, '__delattr__': <function __delattr__>, '__repr__': <function __repr__>, '__dict__': <attribute '__dict__' of 'AttributeDict' objects>, '__getstate__': <function __getstate__>, '__weakref__': <attribute '__weakref__' of 'AttributeDict' objects>, '__doc__': "\n This class internally stores values in a dictionary, but exposes\n the keys also as attributes, i.e. asking for attrdict.key\n will return the value of attrdict['key'] and so on.\n\n Raises an AttributeError if the key does not exist, when called as an attribute,\n while the usual KeyError if the key does not exist and the dictionary syntax is\n used.\n ", '__dir__': <function __dir__>})
__dir__()[source]
__getattr__(attr)[source]

Read a key as an attribute. Raise AttributeError on missing key. Called only for attributes that do not exist.

__getstate__()[source]

Needed for pickling this class.

__module__ = 'aiida.common.extendeddicts'
__repr__()[source]

Representation of the object.

__setattr__(attr, value)[source]

Set a key as an attribute.

__setstate__(dict)[source]

Needed for pickling this class.

__weakref__

list of weak references to the object (if defined)

copy()[source]

Shallow copy.

class aiida.common.extendeddicts.DefaultFieldsAttributeDict[source]

Bases: aiida.common.extendeddicts.AttributeDict

A dictionary with access to the keys as attributes, and with an internal value storing the ‘default’ keys to be distinguished from extra fields.

Extra methods defaultkeys() and extrakeys() divide the set returned by keys() in default keys (i.e. those defined at definition time) and other keys. There is also a method get_default_fields() to return the internal list.

Moreover, for undefined default keys, it returns None instead of raising a KeyError/AttributeError exception.

Remember to define the _default_fields in a subclass! E.g.:

class TestExample(DefaultFieldsAttributeDict):
    _default_fields = ('a','b','c')

When the validate() method is called, it calls in turn all validate_KEY methods, where KEY is one of the default keys. If the method is not present, the field is considered to be always valid. Each validate_KEY method should accept a single argument ‘value’ that will contain the value to be checked.

It raises a ValidationError if any of the validate_KEY function raises an exception, otherwise it simply returns. NOTE: the validate_ functions are called also for unset fields, so if the field can be empty on validation, you have to start your validation function with something similar to:

if value is None:
    return

Todo

Decide behavior if I set to None a field. Current behavior, if a is an instance and ‘def_field’ one of the default fields, that is undefined, we get:

  • a.get('def_field'): None
  • a.get('def_field','whatever'): ‘whatever’
  • Note that a.defaultkeys() does NOT contain ‘def_field’

if we do a.def_field = None, then the behavior becomes

  • a.get('def_field'): None
  • a.get('def_field','whatever'): None
  • Note that a.defaultkeys() DOES contain ‘def_field’

See if we want that setting a default field to None means deleting it.

__getitem__(key)[source]

Return None instead of raising an exception if the key does not exist but is in the list of default fields.

__module__ = 'aiida.common.extendeddicts'
__setattr__(attr, value)[source]

Overridden to allow direct access to fields with underscore.

_default_fields = ()
defaultkeys()[source]

Return the default keys defined in the instance.

extrakeys()[source]

Return the extra keys defined in the instance.

classmethod get_default_fields()[source]

Return the list of default fields, either defined in the instance or not.

validate()[source]

Validate the keys, if any validate_* method is available.

class aiida.common.extendeddicts.Enumerate[source]

Bases: frozenset

__delattr__(name)[source]

x.__delattr__(‘name’) <==> del x.name

__dict__ = dict_proxy({'__module__': 'aiida.common.extendeddicts', '__setattr__': <function __setattr__>, '__getattr__': <function __getattr__>, '__delattr__': <function __delattr__>, '__dict__': <attribute '__dict__' of 'Enumerate' objects>, '__doc__': None})
__getattr__(name)[source]
__module__ = 'aiida.common.extendeddicts'
__setattr__(name, value)[source]

x.__setattr__(‘name’, value) <==> x.name = value

class aiida.common.extendeddicts.FixedFieldsAttributeDict(init=None)[source]

Bases: aiida.common.extendeddicts.AttributeDict

A dictionary with access to the keys as attributes, and with filtering of valid attributes. This is only the base class, without valid attributes; use a derived class to do the actual work. E.g.:

class TestExample(FixedFieldsAttributeDict):
    _valid_fields = ('a','b','c')
__dir__()[source]
__init__(init=None)[source]

x.__init__(…) initializes x; see help(type(x)) for signature

__module__ = 'aiida.common.extendeddicts'
__setattr__(attr, value)[source]

Overridden to allow direct access to fields with underscore.

__setitem__(item, value)[source]

Set a key as an attribute.

_valid_fields = ()
classmethod get_valid_fields()[source]

Return the list of valid fields.

class aiida.common.folders.Folder(abspath, folder_limit=None)[source]

Bases: object

A class to manage generic folders, avoiding to get out of specific given folder borders.

Todo

fix this, os.path.commonprefix of /a/b/c and /a/b2/c will give a/b, check if this is wanted or if we want to put trailing slashes. (or if we want to use os.path.relpath and check for a string starting with os.pardir?)

Todo

rethink whether the folder_limit option is still useful. If not, remove it alltogether (it was a nice feature, but unfortunately all the calls to os.path.abspath or normpath are quite slow).

__dict__ = dict_proxy({'mode_dir': <property object>, '__module__': 'aiida.common.folders', 'exists': <function exists>, 'get_abs_path': <function get_abs_path>, 'abspath': <property object>, 'replace_with_folder': <function replace_with_folder>, 'create_symlink': <function create_symlink>, 'mode_file': <property object>, 'erase': <function erase>, 'insert_path': <function insert_path>, '__dict__': <attribute '__dict__' of 'Folder' objects>, 'remove_path': <function remove_path>, 'open': <function open>, '__init__': <function __init__>, 'isdir': <function isdir>, 'isfile': <function isfile>, 'create': <function create>, 'folder_limit': <property object>, '__weakref__': <attribute '__weakref__' of 'Folder' objects>, 'get_content_list': <function get_content_list>, 'create_file_from_filelike': <function create_file_from_filelike>, '__doc__': '\n A class to manage generic folders, avoiding to get out of\n specific given folder borders.\n\n .. todo::\n fix this, os.path.commonprefix of /a/b/c and /a/b2/c will give\n a/b, check if this is wanted or if we want to put trailing slashes.\n (or if we want to use os.path.relpath and check for a string starting\n with os.pardir?)\n\n .. todo::\n rethink whether the folder_limit option is still useful. If not, remove\n it alltogether (it was a nice feature, but unfortunately all the calls\n to os.path.abspath or normpath are quite slow).\n ', 'get_subfolder': <function get_subfolder>})
__init__(abspath, folder_limit=None)[source]

x.__init__(…) initializes x; see help(type(x)) for signature

__module__ = 'aiida.common.folders'
__weakref__

list of weak references to the object (if defined)

abspath

The absolute path of the folder.

create()[source]

Creates the folder, if it does not exist on the disk yet.

It will also create top directories, if absent.

It is always safe to call it, it will do nothing if the folder already exists.

create_file_from_filelike(src_filelike, dest_name)[source]

Create a file from a file-like object.

Note:

if the current file position in src_filelike is not 0, only the contents from the current file position to the end of the file will be copied in the new file.

Parameters:
  • src_filelike – the file-like object (e.g., if you have a string called s, you can pass StringIO.StringIO(s))
  • dest_name – the destination filename will have this file name.

Create a symlink inside the folder to the location ‘src’.

Parameters:
  • src – the location to which the symlink must point. Can be either a relative or an absolute path. Should, however, be relative to work properly also when the repository is moved!
  • name – the filename of the symlink to be created.
erase(create_empty_folder=False)[source]

Erases the folder. Should be called only in very specific cases, in general folder should not be erased!

Doesn’t complain if the folder does not exist.

Parameters:create_empty_folder – if True, after erasing, creates an empty dir.
exists()[source]

Return True if the folder exists, False otherwise.

folder_limit

The folder limit that cannot be crossed when creating files and folders.

get_abs_path(relpath, check_existence=False)[source]

Return an absolute path for a file or folder in this folder.

The advantage of using this method is that it checks that filename is a valid filename within this folder, and not something e.g. containing slashes.

Parameters:
  • filename – The file or directory.
  • check_existence – if False, just return the file path. Otherwise, also check if the file or directory actually exists. Raise OSError if it does not.
get_content_list(pattern='*', only_paths=True)[source]

Return a list of files (and subfolders) in the folder, matching a given pattern.

Example: If you want to exclude files starting with a dot, you can call this method with pattern='[!.]*'

Parameters:
  • pattern – a pattern for the file/folder names, using Unix filename pattern matching (see Python standard module fnmatch). By default, pattern is ‘*’, matching all files and folders.
  • only_paths – if False (default), return pairs (name, is_file). if True, return only a flat list.
Returns:

a list of tuples of two elements, the first is the file name and the second is True if the element is a file, False if it is a directory.

get_subfolder(subfolder, create=False, reset_limit=False)[source]

Return a Folder object pointing to a subfolder.

Parameters:
  • subfolder – a string with the relative path of the subfolder, relative to the absolute path of this object. Note that this may also contain ‘..’ parts, as far as this does not go beyond the folder_limit.
  • create – if True, the new subfolder is created, if it does not exist.
  • reset_limit – when doing b = a.get_subfolder('xxx', reset_limit=False), the limit of b will be the same limit of a. if True, the limit will be set to the boundaries of folder b.
Returns:

a Folder object pointing to the subfolder.

insert_path(src, dest_name=None, overwrite=True)[source]

Copy a file to the folder.

Parameters:
  • src – the source filename to copy
  • dest_name – if None, the same basename of src is used. Otherwise, the destination filename will have this file name.
  • overwrite – if False, raises an error on existing destination; otherwise, delete it first.
isdir(relpath)[source]

Return True if ‘relpath’ exists inside the folder and is a directory, False otherwise.

isfile(relpath)[source]

Return True if ‘relpath’ exists inside the folder and is a file, False otherwise.

mode_dir

Return the mode with which the folders should be created

mode_file

Return the mode with which the files should be created

open(name, mode='r')[source]

Open a file in the current folder and return the corresponding file object.

remove_path(filename)[source]

Remove a file or folder from the folder.

Parameters:filename – the relative path name to remove
replace_with_folder(srcdir, move=False, overwrite=False)[source]

This routine copies or moves the source folder ‘srcdir’ to the local folder pointed by this Folder object.

Parameters:
  • srcdir – the source folder on the disk; this must be a string with an absolute path
  • move – if True, the srcdir is moved to the repository. Otherwise, it is only copied.
  • overwrite – if True, the folder will be erased first. if False, a IOError is raised if the folder already exists. Whatever the value of this flag, parent directories will be created, if needed.
Raises:

OSError or IOError: in case of problems accessing or writing the files.

Raises:

ValueError: if the section is not recognized.

class aiida.common.folders.RepositoryFolder(section, uuid, subfolder='.')[source]

Bases: aiida.common.folders.Folder

A class to manage the local AiiDA repository folders.

__init__(section, uuid, subfolder='.')[source]

Initializes the object by pointing it to a folder in the repository.

Pass the uuid as a string.

__module__ = 'aiida.common.folders'
get_topdir()[source]

Returns the top directory, i.e., the section/uuid folder object.

section

The section to which this folder belongs.

subfolder

The subfolder within the section/uuid folder.

uuid

The uuid to which this folder belongs.

class aiida.common.folders.SandboxFolder(sandbox_in_repo=True)[source]

Bases: aiida.common.folders.Folder

A class to manage the creation and management of a sandbox folder.

Note: this class must be used within a context manager, i.e.:

with SandboxFolder as f:
## do something with f

In this way, the sandbox folder is removed from disk (if it wasn’t removed already) when exiting the ‘with’ block.

Todo

Implement check of whether the folder has been removed.

__enter__()[source]

Called when entering in the with statement

__exit__(exc_type, exc_value, traceback)[source]

In exit, I remove the sandbox folder from disk, if it still exists

__init__(sandbox_in_repo=True)[source]

Initializes the object by creating a new temporary folder in the sandbox.

Parameters:sandbox_in_repo (bool) – If True (default), creates the folder in the repository. If false, relies on the defaults of tempfile.mkdtemp
__module__ = 'aiida.common.folders'
aiida.common.graph.draw_graph(origin_node, ancestor_depth=None, descendant_depth=None, format='dot', include_calculation_inputs=False, include_calculation_outputs=False)[source]

The algorithm starts from the original node and goes both input-ward and output-ward via a breadth-first algorithm.

Parameters:
  • origin_node – An Aiida node, the starting point for drawing the graph
  • ancestor_depth (int) – The maximum depth of the ancestors drawn. If left to None, we recurse until the graph is fully explored
  • descendant_depth (int) – The maximum depth of the descendants drawn. If left to None, we recurse until the graph is fully explored
  • format (str) – The format, by default dot
Returns:

The exit_status of the os.system call that produced the valid file

Returns:

The file name of the final output

..note::
If an invalid format is provided graphviz prints a helpful message, so this doesn’t need to be implemented here.
aiida.common.hashing._(object_to_hash, **kwargs)[source]
aiida.common.hashing.create_unusable_pass()[source]
aiida.common.hashing.get_random_string(length=12, allowed_chars='abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789')[source]

Returns a securely generated random string.

The default length of 12 with the a-z, A-Z, 0-9 character set returns a 71-bit value. log_2((26+26+10)^12) =~ 71 bits

aiida.common.hashing.is_password_usable(enc_pass)[source]
aiida.common.hashing.make_hash(*args, **kw)[source]

Makes a hash from a dictionary, list, tuple or set to any level, that contains only other hashable or nonhashable types (including lists, tuples, sets, and dictionaries).

Parameters:object_to_hash – the object to hash
Returns:a unique hash

There are a lot of modules providing functionalities to create unique hashes for hashable values. However, getting hashes for nonhashable items like sets or dictionaries is not easily doable because order is not fixed. This leads to the peril of getting different hashes for the same dictionary.

This function avoids this by recursing through nonhashable items and hashing iteratively. Uses python’s sorted function to sort unsorted sets and dictionaries and hashlib.sha224 to hash the value. We make an example with two dictionaries that should produce the same hash because only the order of the keys is different:

aa = {
    '3':4,
    3:4,
    'a':{
        '1':'hello', 2:'goodbye', 1:'here'
    },
    'b':4,
    'c': set([2, '5','a', 'b', 5])
}
bb = {
    'c': set([2, 'b', 5, 'a', '5']),
    'b':4, 'a':{2:'goodbye', 1:'here', '1':'hello'},
    '3':4, 3:4
}

print str(aa) == str(bb)
print aa == bb
print
print hashlib.sha224(str(aa)).hexdigest()
print hashlib.sha224(str(bb)).hexdigest()
print hashlib.sha224(str(aa)).hexdigest(
    ) == hashlib.sha224(str(bb)).hexdigest()
print
print make_hash(aa)
print make_hash(bb)
print make_hash(aa) == make_hash(bb)

produces the output:

False
True

0f6f0cc1e3256f6486e998e934d07cb192ea78d3ce75595267b4c665
86877298dfb629201055e8bc410b5a2157ce65cf246677c54316723a
False

696cdf26b46d7abc5d6fdfb2244829dad9dd2b0100afd1e2f20a8002
696cdf26b46d7abc5d6fdfb2244829dad9dd2b0100afd1e2f20a8002
True

We can conclude that using simple hashfunctions operating on the string of dictionary do not suffice if we want to check for equality of dictionaries using hashes.

aiida.common.hashing.make_hash_with_type(type_chr, string_to_hash)[source]
Convention: type_chr should be a single char, lower case
for simple datatypes, upper case for composite datatypes We don’t check anything for speed efficiency
aiida.common.hashing.truncate_array64(x, num_bits=4)[source]
aiida.common.hashing.truncate_float64(x, num_bits=4)[source]
class aiida.common.links.LinkType[source]

Bases: enum.Enum

A simple enum of allowed link types.

CALL = 'calllink'
CREATE = 'createlink'
INPUT = 'inputlink'
RETURN = 'returnlink'
UNSPECIFIED = 'unspecified'
__module__ = 'aiida.common.links'
class aiida.common.log.DBLogHandler(level=0)[source]

Bases: logging.Handler

__module__ = 'aiida.common.log'
emit(record)[source]

Do whatever it takes to actually log the specified logging record.

This version is intended to be implemented by subclasses and so raises a NotImplementedError.

class aiida.common.log.NotInTestingFilter(name='')[source]

Bases: logging.Filter

__module__ = 'aiida.common.log'
filter(record)[source]

Determine if the specified record is to be logged.

Is the specified record to be logged? Returns 0 for no, nonzero for yes. If deemed appropriate, the record may be modified in-place.

aiida.common.log.configure_logging(daemon=False, daemon_log_file=None)[source]

Setup the logging by retrieving the LOGGING dictionary from aiida and passing it to the python module logging.config.dictConfig. If the logging needs to be setup for the daemon, set the argument ‘daemon’ to True and specify the path to the log file. This will cause a ‘daemon_handler’ to be added to all the configured loggers, that is a RotatingFileHandler that writes to the log file.

Parameters:
  • daemon – configure the logging for a daemon task by adding a file handler instead of the default ‘console’ StreamHandler
  • daemon_log_file – absolute filepath of the log file for the RotatingFileHandler
aiida.common.log.get_dblogger_extra(obj)[source]

Given an object (Node, Calculation, …) return a dictionary to be passed as extra to the aiidalogger in order to store the exception also in the DB. If no such extra is passed, the exception is only logged on file.

class aiida.common.profile.ProfileConfig(profile_name=None)[source]

Bases: object

Convenience class that loads the current profile name and corresponding configuration and can subsequently provide profile specific information

_RMQ_PREFIX = 'aiida-{uuid}'
__dict__ = dict_proxy({'rmq_prefix': <property object>, '__module__': 'aiida.common.profile', 'profile_uuid': <property object>, 'filepaths': <property object>, '__dict__': <attribute '__dict__' of 'ProfileConfig' objects>, '_RMQ_PREFIX': 'aiida-{uuid}', '__weakref__': <attribute '__weakref__' of 'ProfileConfig' objects>, '__doc__': '\n Convenience class that loads the current profile name and corresponding configuration and\n can subsequently provide profile specific information\n ', '__init__': <function __init__>})
__init__(profile_name=None)[source]

Construct the ProfileConfig for the given profile_name or retrieve it from the backend settings

__module__ = 'aiida.common.profile'
__weakref__

list of weak references to the object (if defined)

filepaths
profile_uuid
rmq_prefix
aiida.common.profile.get_current_profile_config()[source]

Return the configuration of the currently active profile or if not set, the default profile

aiida.common.profile.get_current_profile_name()[source]

Return the currently configured profile name or if not set, the default profile

class aiida.common.setup._NoDefaultValue[source]

Bases: object

__dict__ = dict_proxy({'__dict__': <attribute '__dict__' of '_NoDefaultValue' objects>, '__module__': 'aiida.common.setup', '__weakref__': <attribute '__weakref__' of '_NoDefaultValue' objects>, '__doc__': None})
__module__ = 'aiida.common.setup'
__weakref__

list of weak references to the object (if defined)

aiida.common.setup._load_config()[source]

Return the current configurations, without checking their version.

aiida.common.setup.backup_config()[source]

Backup the previous configuration file.

aiida.common.setup.create_base_dirs(config_dir=None)[source]

Create dirs for AiiDA, and install default daemon files.

aiida.common.setup.create_config_noninteractive(profile='default', force_overwrite=False, dry_run=False, **kwargs)[source]

Non-interactively creates a profile. :raises: a ValueError if the profile exists. :raises: a ValueError if one of the values not a valid input :param profile: The profile to be configured :param values: The configuration inputs :return: The populated profile that was also stored

aiida.common.setup.create_configuration(profile='default')[source]
Parameters:profile – The profile to be configured
Returns:The populated profile that was also stored.
aiida.common.setup.create_htaccess_file()[source]

Creates a suitable .htaccess file in the .aiida folder (if it does not exist yet), that is important

Note

some default Apache configurations ignore the .htaccess files unless otherwise specified: read the documentation on how to setup properly your Apache server!

Note

if a .htaccess file already exists, this is not overwritten.

aiida.common.setup.del_property(name)[source]

Delete a property in the json file.

Parameters:name – the name of the property to delete.
Raise:KeyError if the key is not found in the configuration file.
aiida.common.setup.exists_property(name)[source]

Check if a property exists in the DB.

Note

this is useful if one wants explicitly to know if a property is defined just because it has a default value, or because it is explicitly defined in the config file.

Parameters:name – the name of the property to check.
Raises:ValueError – if the given name is not a valid property (as stored in the _property_table dictionary).
aiida.common.setup.generate_new_profile_uuid()[source]

Return a UUID for a new profile

Returns:the hexadecimal represenation of a uuid4 UUID
aiida.common.setup.generate_random_secret_key()[source]

Generate a random secret key to put in the django settings module.

This should be the same function used by Django in core/management/commands/startproject.

aiida.common.setup.get_aiida_dir()[source]
aiida.common.setup.get_config()[source]

Return all the configurations

aiida.common.setup.get_default_profile()[source]

Return the default profile name from the configuration

Returns:None if no default profile is found
aiida.common.setup.get_or_create_config()[source]
aiida.common.setup.get_profile_config(profile, conf_dict=None)[source]

Return the profile specific configurations

Parameters:conf_dict – if passed, use the provided dictionary rather than reading it from file.
aiida.common.setup.get_profiles_list()[source]

Return the list of names of installed configurations

aiida.common.setup.get_property(name, default=<aiida.common.setup._NoDefaultValue object>)[source]

Get a property from the json file.

Parameters:
  • name – the name of the property to get.
  • default – if provided, this value is returned if no value is found in the database.
Raises:
  • ValueError – if the given name is not a valid property (as stored in the _property_table dictionary).
  • KeyError – if the given property is not found in the config file, and no default value is given or provided in _property_table.
aiida.common.setup.get_secret_key()[source]

Return the secret key.

Raise ConfigurationError if the secret key cannot be found/read from the disk.

aiida.common.setup.parse_repository_uri(repository_uri)[source]

This function validates the REPOSITORY_URI, that should be in the format protocol://address

Note:At the moment, only the file protocol is supported.
Returns:a tuple (protocol, address).
aiida.common.setup.profile_exists(profile)[source]

return True if profile exists, else return False

aiida.common.setup.set_default_profile(profile, force_rewrite=False)[source]

Set the default profile

Parameters:
  • profile – A string specifying the profile that should be used as default
  • force_rewrite – if False, does not change the default profile if already set
aiida.common.setup.set_property(name, value)[source]

Set a property in the json file.

Parameters:
  • name – The name of the property value to set.
  • value – the value to set. If it is a string, it is possibly casted to the correct type according to the information in the _property_table dictionary.
Raises:

ValueError – if the provided name is not among the set of valid properties, or if the value provided as a string cannot be casted to the correct type.

aiida.common.setup.store_config(confs)[source]

Given a configuration dictionary, stores it in the configuration file.

Parameters:confs – the dictionary to store.
aiida.common.setup.try_create_secret_key()[source]

Creates a new secret key file, if this does not exist, otherwise do nothing (to avoid that the secret key is regenerated each time).

If you really want that the secret key is regenerated, delete the secret key file, and then call this function again.

aiida.common.setup.update_config(settings, write=True)[source]

back up the config file, create or change config.

Parameters:
  • settings – dictionary with the new or changed configuration
  • write – if False, do not touch the config file (dryrun)
Returns:

the new / changed configuration

aiida.common.setup.update_profile(profile, updates, write=True)[source]

back up the config file, create or changes profile

Parameters:
  • profile – name of the profile
  • updates – dictionary with the new or changed profile
  • write – if False, do not touch the config file (dryrun)
Returns:

the new / changed profile

class aiida.common.test_extendeddicts.TestAttributeDictAccess(methodName='runTest')[source]

Bases: unittest.case.TestCase

Try to access the dictionary elements in various ways, copying (shallow and deep), check raised exceptions.

__module__ = 'aiida.common.test_extendeddicts'
test_access_attr_to_dict()[source]
test_access_dict_to_attr()[source]
test_access_nonexisting_asattr()[source]
test_access_nonexisting_askey()[source]
test_copy()[source]
test_deepcopy1()[source]
test_del_nonexisting_asattr()[source]
test_del_nonexisting_askey()[source]
test_delete_after_copy()[source]
test_shallowcopy1()[source]
test_shallowcopy2()[source]

Also test access at nested levels

class aiida.common.test_extendeddicts.TestAttributeDictNested(methodName='runTest')[source]

Bases: unittest.case.TestCase

Test the functionality of nested AttributeDict classes.

__module__ = 'aiida.common.test_extendeddicts'
test_comparison()[source]
test_nested()[source]
test_nested_deepcopy()[source]
class aiida.common.test_extendeddicts.TestAttributeDictSerialize(methodName='runTest')[source]

Bases: unittest.case.TestCase

Test serialization/deserialization (with json, pickle, …)

__module__ = 'aiida.common.test_extendeddicts'
test_json()[source]
test_json_recursive()[source]
test_pickle()[source]
test_pickle_recursive()[source]
class aiida.common.test_extendeddicts.TestDFAD(methodName='runTest')[source]

Bases: unittest.case.TestCase

__module__ = 'aiida.common.test_extendeddicts'
test_class_attribute()[source]

I test that the get_default_fields() is working as a class method, so I don’t need to instantiate the class to get the list.

test_insertion_and_retrieval()[source]
test_keylist_method()[source]
test_validation()[source]
class aiida.common.test_extendeddicts.TestDFADExample[source]

Bases: aiida.common.extendeddicts.DefaultFieldsAttributeDict

An example class that has ‘a’, ‘b’ and ‘c’ as default keys.

__module__ = 'aiida.common.test_extendeddicts'
_default_fields = ('a', 'b', 'c')
validate_a(value)[source]
class aiida.common.test_extendeddicts.TestFFAD(methodName='runTest')[source]

Bases: unittest.case.TestCase

__module__ = 'aiida.common.test_extendeddicts'
test_class_attribute()[source]

I test that the get_valid_fields() is working as a class method, so I don’t need to instantiate the class to get the list.

test_insertion()[source]
test_insertion_on_init()[source]
test_pickle()[source]

Note: pickle works here because self._valid_fields is defined at the class level!

class aiida.common.test_extendeddicts.TestFFADExample(init=None)[source]

Bases: aiida.common.extendeddicts.FixedFieldsAttributeDict

An example class that accepts only the ‘a’, ‘b’ and ‘c’ keys/attributes.

__module__ = 'aiida.common.test_extendeddicts'
_valid_fields = ('a', 'b', 'c')
class aiida.common.test_folders.FoldersTest(methodName='runTest')[source]

Bases: unittest.case.TestCase

Tests for the Folder class.

__module__ = 'aiida.common.test_folders'
test_get_abs_path_without_limit()[source]
test_unicode()[source]

Check that there are no exceptions raised when using unicode folders.

class aiida.common.test_logging.TestLogger(methodName='runTest')[source]

Bases: unittest.case.TestCase

Test global python logging module

__module__ = 'aiida.common.test_logging'
test_logger()[source]

The python logging module is configured with a DbLogHandler upon runtime, but we do not want any fired log messages to crash when they reach the handler and no database is set yet

class aiida.common.test_utils.UniqueTest(methodName='runTest')[source]

Bases: unittest.case.TestCase

Tests for the get_unique_filename function.

__module__ = 'aiida.common.test_utils'
array_counter()[source]
seq = -1
test_ask_backup_question()[source]

This method checks that the combined use of query_string and query_yes_no by the ask_backup_question is done as expected.

test_query_string()[source]

This method tests that the query_string method behaves as expected.

test_query_yes_no()[source]

This method tests the query_yes_no method behaves as expected. To perform this, a lambda function is used to simulate the user input.

test_unique_1()[source]
test_unique_2()[source]
test_unique_3()[source]
test_unique_4()[source]
class aiida.common.utils.ArrayCounter[source]

Bases: object

A counter & a method that increments it and returns its value. It is used in various tests.

__dict__ = dict_proxy({'__module__': 'aiida.common.utils', 'seq': None, 'array_counter': <function array_counter>, '__dict__': <attribute '__dict__' of 'ArrayCounter' objects>, '__weakref__': <attribute '__weakref__' of 'ArrayCounter' objects>, '__doc__': '\n A counter & a method that increments it and returns its value.\n It is used in various tests.\n ', '__init__': <function __init__>})
__init__()[source]

x.__init__(…) initializes x; see help(type(x)) for signature

__module__ = 'aiida.common.utils'
__weakref__

list of weak references to the object (if defined)

array_counter()[source]
seq = None
class aiida.common.utils.EmptyContextManager[source]

Bases: object

__dict__ = dict_proxy({'__module__': 'aiida.common.utils', '__exit__': <function __exit__>, '__enter__': <function __enter__>, '__dict__': <attribute '__dict__' of 'EmptyContextManager' objects>, '__weakref__': <attribute '__weakref__' of 'EmptyContextManager' objects>, '__doc__': None})
__enter__()[source]
__exit__(exc_type, exc_value, traceback)[source]
__module__ = 'aiida.common.utils'
__weakref__

list of weak references to the object (if defined)

class aiida.common.utils.HiddenPrints[source]

Class to prevent any print to the std output. Usage:

with HiddenPrints():
print(“I won’t print this”)
__enter__()[source]
__exit__(exc_type, exc_val, exc_tb)[source]
__module__ = 'aiida.common.utils'
class aiida.common.utils.Prettifier(format)[source]

Bases: object

Class to manage prettifiers (typically for labels of kpoints in band plots)

__dict__ = dict_proxy({'_prettify_label_agr_simple': <classmethod object>, '__module__': 'aiida.common.utils', 'prettify': <function prettify>, '_prettify_label_gnuplot': <classmethod object>, '_prettify_label_latex_simple': <classmethod object>, '_prettify_label_agr': <classmethod object>, '_prettify_label_pass': <classmethod object>, 'prettifiers': <aiida.common.utils.classproperty object>, '_prettify_label_gnuplot_simple': <classmethod object>, 'get_prettifiers': <classmethod object>, '__dict__': <attribute '__dict__' of 'Prettifier' objects>, '_prettify_label_latex': <classmethod object>, '__weakref__': <attribute '__weakref__' of 'Prettifier' objects>, '__doc__': '\n Class to manage prettifiers (typically for labels of kpoints\n in band plots)\n ', '__init__': <function __init__>})
__init__(format)[source]

Create a class to pretttify strings of a given format

Parameters:format – a string with the format to use to prettify. Valid formats are obtained from self.prettifiers
__module__ = 'aiida.common.utils'
__weakref__

list of weak references to the object (if defined)

classmethod _prettify_label_agr(label)[source]

Prettifier for XMGrace

Parameters:label – a string to prettify
classmethod _prettify_label_agr_simple(label)[source]

Prettifier for XMGrace (for old label names)

Parameters:label – a string to prettify
classmethod _prettify_label_gnuplot(label)[source]

Prettifier for Gnuplot

Note:uses unicode, returns unicode strings (potentially, if needed)
Parameters:label – a string to prettify
classmethod _prettify_label_gnuplot_simple(label)[source]

Prettifier for Gnuplot (for old label names)

Note:uses unicode, returns unicode strings (potentially, if needed)
Parameters:label – a string to prettify
classmethod _prettify_label_latex(label)[source]

Prettifier for matplotlib, using LaTeX syntax

Parameters:label – a string to prettify
classmethod _prettify_label_latex_simple(label)[source]

Prettifier for matplotlib, using LaTeX syntax (for old label names)

Parameters:label – a string to prettify
classmethod _prettify_label_pass(label)[source]

No-op prettifier, simply returns the same label

Parameters:label – a string to prettify
classmethod get_prettifiers()[source]

Return a list of valid prettifier strings

Returns:a list of strings
prettifiers = {'agr_seekpath': <bound method type._prettify_label_agr of <class 'aiida.common.utils.Prettifier'>>, 'agr_simple': <bound method type._prettify_label_agr_simple of <class 'aiida.common.utils.Prettifier'>>, 'gnuplot_seekpath': <bound method type._prettify_label_gnuplot of <class 'aiida.common.utils.Prettifier'>>, 'gnuplot_simple': <bound method type._prettify_label_gnuplot_simple of <class 'aiida.common.utils.Prettifier'>>, 'latex_seekpath': <bound method type._prettify_label_latex of <class 'aiida.common.utils.Prettifier'>>, 'latex_simple': <bound method type._prettify_label_latex_simple of <class 'aiida.common.utils.Prettifier'>>, 'pass': <bound method type._prettify_label_pass of <class 'aiida.common.utils.Prettifier'>>}
prettify(label)[source]

Prettify a label using the format passed in the initializer

Parameters:label – the string to prettify
Returns:a prettified string
class aiida.common.utils.abstractclassmethod(callable)[source]

Bases: classmethod

A decorator indicating abstract classmethods.

Backported from python3.

__dict__ = dict_proxy({'__module__': 'aiida.common.utils', '__isabstractmethod__': True, '__dict__': <attribute '__dict__' of 'abstractclassmethod' objects>, '__weakref__': <attribute '__weakref__' of 'abstractclassmethod' objects>, '__doc__': '\n A decorator indicating abstract classmethods.\n\n Backported from python3.\n ', '__init__': <function __init__>})
__init__(callable)[source]

x.__init__(…) initializes x; see help(type(x)) for signature

__isabstractmethod__ = True
__module__ = 'aiida.common.utils'
__weakref__

list of weak references to the object (if defined)

class aiida.common.utils.abstractstaticmethod(callable)[source]

Bases: staticmethod

A decorator indicating abstract staticmethods.

Similar to abstractmethod. Backported from python3.

__dict__ = dict_proxy({'__module__': 'aiida.common.utils', '__isabstractmethod__': True, '__dict__': <attribute '__dict__' of 'abstractstaticmethod' objects>, '__weakref__': <attribute '__weakref__' of 'abstractstaticmethod' objects>, '__doc__': '\n A decorator indicating abstract staticmethods.\n\n Similar to abstractmethod.\n Backported from python3.\n ', '__init__': <function __init__>})
__init__(callable)[source]

x.__init__(…) initializes x; see help(type(x)) for signature

__isabstractmethod__ = True
__module__ = 'aiida.common.utils'
__weakref__

list of weak references to the object (if defined)

aiida.common.utils.are_dir_trees_equal(dir1, dir2)[source]

Compare two directories recursively. Files in each directory are assumed to be equal if their names and contents are equal.

@param dir1: First directory path @param dir2: Second directory path

@return: True if the directory trees are the same and
there were no errors while accessing the directories or files, False otherwise.
aiida.common.utils.ask_question(question, reply_type, allow_none_as_answer=True)[source]

This method asks a specific question, tries to parse the given reply and then it verifies the parsed answer. :param question: The question to be asked. :param reply_type: The type of the expected answer (int, datetime etc). It is needed for the parsing of the answer. :param allow_none_as_answer: Allow empty answers? :return: The parsed reply.

class aiida.common.utils.classproperty(getter)[source]

Bases: object

A class that, when used as a decorator, works as if the two decorators @property and @classmethod where applied together (i.e., the object works as a property, both for the Class and for any of its instance; and is called with the class cls rather than with the instance as its first argument).

__dict__ = dict_proxy({'__module__': 'aiida.common.utils', '__dict__': <attribute '__dict__' of 'classproperty' objects>, '__weakref__': <attribute '__weakref__' of 'classproperty' objects>, '__doc__': '\n A class that, when used as a decorator, works as if the\n two decorators @property and @classmethod where applied together\n (i.e., the object works as a property, both for the Class and for any\n of its instance; and is called with the class cls rather than with the\n instance as its first argument).\n ', '__init__': <function __init__>, '__get__': <function __get__>})
__get__(instance, owner)[source]
__init__(getter)[source]

x.__init__(…) initializes x; see help(type(x)) for signature

__module__ = 'aiida.common.utils'
__weakref__

list of weak references to the object (if defined)

class aiida.common.utils.combomethod(method)[source]

Bases: object

A decorator that wraps a function that can be both a classmethod or instancemethod and behaves accordingly:

class A():

    @combomethod
    def do(self, **kwargs):
        isclass = kwargs.get('isclass')
        if isclass:
            print "I am a class", self
        else:
            print "I am an instance", self

A.do()
A().do()

>>> I am a class __main__.A
>>> I am an instance <__main__.A instance at 0x7f2efb116e60>

Attention: For ease of handling, pass keyword isclass equal to True if this was called as a classmethod and False if this was called as an instance. The argument self is therefore ambiguous!

__dict__ = dict_proxy({'__module__': 'aiida.common.utils', '__dict__': <attribute '__dict__' of 'combomethod' objects>, '__weakref__': <attribute '__weakref__' of 'combomethod' objects>, '__doc__': '\n A decorator that wraps a function that can be both a classmethod or\n instancemethod and behaves accordingly::\n\n class A():\n\n @combomethod\n def do(self, **kwargs):\n isclass = kwargs.get(\'isclass\')\n if isclass:\n print "I am a class", self\n else:\n print "I am an instance", self\n\n A.do()\n A().do()\n\n >>> I am a class __main__.A\n >>> I am an instance <__main__.A instance>\n\n Attention: For ease of handling, pass keyword **isclass**\n equal to True if this was called as a classmethod and False if this\n was called as an instance.\n The argument self is therefore ambiguous!\n ', '__init__': <function __init__>, '__get__': <function __get__>})
__get__(obj=None, objtype=None)[source]
__init__(method)[source]

x.__init__(…) initializes x; see help(type(x)) for signature

__module__ = 'aiida.common.utils'
__weakref__

list of weak references to the object (if defined)

aiida.common.utils.conv_to_fortran(val, quote_strings=True)[source]
Parameters:val – the value to be read and converted to a Fortran-friendly string.
aiida.common.utils.conv_to_fortran_withlists(val, quote_strings=True)[source]

Same as conv_to_fortran but with extra logic to handle lists :param val: the value to be read and converted to a Fortran-friendly string.

aiida.common.utils.create_display_name(field)[source]

Given a string, creates the suitable “default” display name: replace underscores with spaces, and capitalize each word.

Returns:the converted string
aiida.common.utils.escape_for_bash(str_to_escape)[source]

This function takes any string and escapes it in a way that bash will interpret it as a single string.

Explanation:

At the end, in the return statement, the string is put within single quotes. Therefore, the only thing that I have to escape in bash is the single quote character. To do this, I substitute every single quote ‘ with ‘”’”’ which means:

First single quote: exit from the enclosing single quotes

Second, third and fourth character: “’” is a single quote character, escaped by double quotes

Last single quote: reopen the single quote to continue the string

Finally, note that for python I have to enclose the string ‘”’”’ within triple quotes to make it work, getting finally: the complicated string found below.

aiida.common.utils.export_shard_uuid(uuid)[source]

Sharding of the UUID for the import/export

aiida.common.utils.flatten_list(value)[source]

Flattens a list or a tuple In [2]: flatten_list([[[[[4],3]],[3],[‘a’,[3]]]]) Out[2]: [4, 3, 3, ‘a’, 3]

Parameters:value – A value, whether iterable or not
Returns:a list of nesting level 1
aiida.common.utils.get_class_string(obj)[source]

Return the string identifying the class of the object (module + object name, joined by dots).

It works both for classes and for class instances.

aiida.common.utils.get_configured_user_email()[source]

Return the email (that is used as the username) configured during the first verdi install.

aiida.common.utils.get_extremas_from_positions(positions)[source]

returns the minimum and maximum value for each dimension in the positions given

aiida.common.utils.get_fortfloat(key, txt, be_case_sensitive=True)[source]

Matches a fortran compatible specification of a float behind a defined key in a string. :param key: The key to look for :param txt: The string where to search for the key :param be_case_sensitive: An optional boolean whether to search case-sensitive, defaults to True

If abc is a key, and f is a float, number, than this regex will match t and return f in the following cases:

  • charsbefore, abc = f, charsafter
  • charsbefore abc = f charsafter
  • charsbefore, abc = f charsafter

and vice-versa. If no float is matched, returns None

Exampes of matchable floats are:

  • 0.1d2
  • 0.D-3
  • .2e1
  • -0.23
  • 232
aiida.common.utils.get_mode_string(mode)[source]

Convert a file’s mode to a string of the form ‘-rwxrwxrwx’. Taken (simplified) from cpython 3.3 stat module: https://hg.python.org/cpython/file/3.3/Lib/stat.py

aiida.common.utils.get_new_uuid()[source]

Return a new UUID (typically to be used for new nodes). It uses the UUID version specified in aiida.backends.settings.AIIDANODES_UUID_VERSION

aiida.common.utils.get_object_from_string(string)[source]

Given a string identifying an object (as returned by the get_class_string method) load and return the actual object.

aiida.common.utils.get_object_string(obj)[source]

Get a string that identifies this object which can be used to retrieve it via get_object_from_string().

Parameters:obj – The object to get the string for
Returns:The string that identifies the object
aiida.common.utils.get_repository_folder(subfolder=None)[source]

Return the top folder of the local repository.

aiida.common.utils.get_suggestion(provided_string, allowed_strings)[source]

Given a string and a list of allowed_strings, it returns a string to print on screen, with sensible text depending on whether no suggestion is found, or one or more than one suggestions are found.

Args:
provided_string: the string to compare allowed_strings: a list of valid strings
Returns:
A string to print on output, to suggest to the user a possible valid value.
aiida.common.utils.get_unique_filename(filename, list_of_filenames)[source]

Return a unique filename that can be added to the list_of_filenames.

If filename is not in list_of_filenames, it simply returns the filename string itself. Otherwise, it appends a integer number to the filename (before the extension) until it finds a unique filename.

Parameters:
  • filename – the filename to add
  • list_of_filenames – the list of filenames to which filename should be added, without name duplicates
Returns:

Either filename or its modification, with a number appended between the name and the extension.

aiida.common.utils.grouper(n, iterable)[source]

Given an iterable, returns an iterable that returns tuples of groups of elements from iterable of length n, except the last one that has the required length to exaust iterable (i.e., there is no filling applied).

Parameters:
  • n – length of each tuple (except the last one,that will have length <= n
  • iterable – the iterable to divide in groups
aiida.common.utils.gunzip_string(string)[source]

Gunzip string contents.

Parameters:string – a gzipped string
Returns:a string
aiida.common.utils.gzip_string(string)[source]

Gzip string contents.

Parameters:string – a string
Returns:a gzipped string
aiida.common.utils.indent(txt, spaces=4)[source]
aiida.common.utils.issingular(singularForm)[source]

Checks whether a noun is singular :param pluralForm: a string defining an English noun :return: the t-ple (singular, pluralform). singular: True/Flalse if noun is singular/plural pluralfrom: (a string with the noun in the plural form))

aiida.common.utils.join_labels(labels, join_symbol='|', threshold=1e-06)[source]

Join labels with a joining symbol when they are very close

Parameters:
  • labels – a list of length-2 tuples, in the format(position, label)
  • join_symbol – the string to use to join different paths. By default, a pipe
  • threshold – the threshold to decide if two float values are the same and should be joined
Returns:

the same list as labels, but with the second value possibly replaced with strings joined when close enough

aiida.common.utils.md5_file(filename, block_size_factor=128)[source]

Open a file and return its md5sum (hexdigested).

Parameters:
  • filename – the filename of the file for which we want the md5sum
  • block_size_factor – the file is read at chunks of size block_size_factor * md5.block_size, where md5.block_size is the block_size used internally by the hashlib module.
Returns:

a string with the hexdigest md5.

Raises:

No checks are done on the file, so if it doesn’t exists it may raise IOError.

aiida.common.utils.prettify_labels(labels, format=None)[source]

Prettify label for typesetting in various formats

Parameters:
  • labels – a list of length-2 tuples, in the format(position, label)
  • format – a string with the format for the prettifier (e.g. ‘agr’, ‘matplotlib’, …)
Returns:

the same list as labels, but with the second value possibly replaced with a prettified version that typesets nicely in the selected format

aiida.common.utils.query_string(question, default)[source]

Asks a question (with the option to have a default, predefined answer, and depending on the default answer and the answer of the user the following options are available: - If the user replies (with a non empty answer), then his answer is returned. - If the default answer is None then the user has to reply with a non-empty answer. - If the default answer is not None, then it is returned if the user gives an empty answer. In the case of empty default answer and empty reply from the user, None is returned. :param question: The question that we want to ask the user. :param default: The default answer (if there is any) to the question asked. :return: The returned reply.

aiida.common.utils.query_yes_no(question, default='yes')[source]

Ask a yes/no question via raw_input() and return their answer.

“question” is a string that is presented to the user. “default” is the presumed answer if the user just hits <Enter>. It must be “yes” (the default), “no” or None (meaning an answer is required of the user).

The “answer” return value is True for “yes” or False for “no”.

aiida.common.utils.sha1_file(filename, block_size_factor=128)[source]

Open a file and return its sha1sum (hexdigested).

Parameters:
  • filename – the filename of the file for which we want the sha1sum
  • block_size_factor – the file is read at chunks of size block_size_factor * sha1.block_size, where sha1.block_size is the block_size used internally by the hashlib module.
Returns:

a string with the hexdigest sha1.

Raises:

No checks are done on the file, so if it doesn’t exists it may raise IOError.

aiida.common.utils.str_timedelta(dt, max_num_fields=3, short=False, negative_to_zero=False)[source]

Given a dt in seconds, return it in a HH:MM:SS format.

Parameters:
  • dt – a TimeDelta object
  • max_num_fields – maximum number of non-zero fields to show (for instance if the number of days is non-zero, shows only days, hours and minutes, but not seconds)
  • short – if False, print always max_num_fields fields, even if they are zero. If True, do not print the first fields, if they are zero.
  • negative_to_zero – if True, set dt = 0 if dt < 0.
aiida.common.utils.type_check(what, of_type)[source]
aiida.common.utils.validate_list_of_string_tuples(val, tuple_length)[source]

Check that:

  1. val is a list or tuple
  2. each element of the list:
  1. is a list or tuple
  2. is of length equal to the parameter tuple_length
  3. each of the two elements is a string

Return if valid, raise ValidationError if invalid

aiida.common.utils.xyz_parser_iterator(string)[source]

Yields a tuple (natoms, comment, atomiter)`for each frame in a XYZ file where `atomiter is an iterator yielding a nested tuple (symbol, (x, y, z)) for each entry.

Parameters:string – a string containing XYZ-structured text