aiida.restapi package

In this module, AiiDA provides REST API to access different AiiDA nodes stored in database. The REST API is implemented using Flask RESTFul framework.

Submodules

Implementation of RESTful API for AiiDA based on flask and flask_restful.

Author: Snehal P. Waychal and Fernando Gargiulo @ Theos, EPFL

class aiida.restapi.api.AiidaApi(app=None, **kwargs)[source]

Bases: flask_restful.Api

AiiDA customized version of the flask_restful Api class

__init__(app=None, **kwargs)[source]

The need to have a special constructor is to include directly the addition of resources with the parameters required to initialize the resource classes.

Parameters

kwargs – parameters to be passed to the resources for configuration and PREFIX

__module__ = 'aiida.restapi.api'
handle_error(e)[source]

this method handles the 404 “URL not found” exception and return custom message :param e: raised exception :return: list of available endpoints

class aiida.restapi.api.App(*args, **kwargs)[source]

Bases: flask.app.Flask

Basic Flask App customized for this REST Api purposes

__init__(*args, **kwargs)[source]

Initialize self. See help(type(self)) for accurate signature.

__module__ = 'aiida.restapi.api'

Resources for REST API

class aiida.restapi.resources.BaseResource(**kwargs)[source]

Bases: flask_restful.Resource

Each derived class will instantiate a different type of translator. This is the only difference in the classes.

class BaseTranslator(**kwargs)

Bases: object

Generic class for translator. It contains the methods required to build a related QueryBuilder object

__dict__ = mappingproxy({'__module__': 'aiida.restapi.translator.base', '__doc__': '\n Generic class for translator. It contains the methods\n required to build a related QueryBuilder object\n ', '__label__': None, '_aiida_class': None, '_aiida_type': None, '_has_uuid': None, '_result_type': None, '_default': ['**'], '_default_projections': ['**'], '_is_qb_initialized': False, '_is_id_query': None, '_total_count': None, '__init__': <function BaseTranslator.__init__>, '__repr__': <function BaseTranslator.__repr__>, 'get_projectable_properties': <staticmethod object>, 'init_qb': <function BaseTranslator.init_qb>, 'count': <function BaseTranslator.count>, 'get_total_count': <function BaseTranslator.get_total_count>, 'set_filters': <function BaseTranslator.set_filters>, 'get_default_projections': <function BaseTranslator.get_default_projections>, 'set_default_projections': <function BaseTranslator.set_default_projections>, 'set_projections': <function BaseTranslator.set_projections>, 'set_order': <function BaseTranslator.set_order>, 'set_query': <function BaseTranslator.set_query>, 'get_query_help': <function BaseTranslator.get_query_help>, 'set_limit_offset': <function BaseTranslator.set_limit_offset>, 'get_formatted_result': <function BaseTranslator.get_formatted_result>, 'get_results': <function BaseTranslator.get_results>, '_check_id_validity': <function BaseTranslator._check_id_validity>, '__dict__': <attribute '__dict__' of 'BaseTranslator' objects>, '__weakref__': <attribute '__weakref__' of 'BaseTranslator' objects>})
__init__(**kwargs)

Initialise the parameters. Create the basic query_help

keyword Class (default None but becomes this class): is the class from which one takes the initial values of the attributes. By default is this class so that class atributes are translated into object attributes. In case of inheritance one cane use the same constructore but pass the inheriting class to pass its attributes.

__label__ = None
__module__ = 'aiida.restapi.translator.base'
__repr__()

This function is required for the caching system to be able to compare two NodeTranslator objects. Comparison is done on the value returned by __repr__

Returns

representation of NodeTranslator objects. Returns nothing because the inputs of self.get_nodes are sufficient to determine the identity of two queries.

__weakref__

list of weak references to the object (if defined)

_aiida_class = None
_aiida_type = None
_check_id_validity(node_id)

Checks whether id corresponds to an object of the expected type, whenever type is a valid column of the database (ex. for nodes, but not for users)

Parameters

node_id – id (or id starting pattern)

Returns

True if node_id valid, False if invalid. If True, sets the id filter attribute correctly

Raises

RestValidationError – if no node is found or id pattern does not identify a unique node

_default = ['**']
_default_projections = ['**']
_has_uuid = None
_is_id_query = None
_is_qb_initialized = False
_result_type = None
_total_count = None
count()

Count the number of rows returned by the query and set total_count

get_default_projections()

method to get default projections of the node :return: self._default_projections

get_formatted_result(label)

Runs the query and retrieves results tagged as “label”.

Parameters

label (str) – the tag of the results to be extracted out of the query rows.

Returns

a list of the query results

static get_projectable_properties()

This method is extended in specific translators classes. It returns a dict as follows: dict(fields=projectable_properties, ordering=ordering) where projectable_properties is a dict and ordering is a list

get_query_help()
Returns

return QB json dictionary

get_results()

Returns either list of nodes or details of single node from database.

Returns

either list of nodes or details of single node from database

get_total_count()

Returns the number of rows of the query.

Returns

total_count

init_qb()

Initialize query builder object by means of _query_help

set_default_projections()

It calls the set_projections() methods internally to add the default projections in query_help

Returns

None

set_filters(filters=None)

Add filters in query_help.

Parameters

filters

it is a dictionary where keys are the tag names given in the path in query_help and their values are the dictionary of filters want to add for that tag name. Format for the Filters dictionary:

filters = {
    "tag1" : {k1:v1, k2:v2},
    "tag2" : {k1:v1, k2:v2},
}

Returns

query_help dict including filters if any.

set_limit_offset(limit=None, offset=None)

sets limits and offset directly to the query_builder object

Parameters
  • limit

  • offset

Returns

set_order(orders)

Add order_by clause in query_help :param orders: dictionary of orders you want to apply on final results :return: None or exception if any.

set_projections(projections)

add the projections in query_help

Parameters

projections – it is a dictionary where keys are the tag names given in the path in query_help and values are the list of the names you want to project in the final output

Returns

updated query_help with projections

set_query(filters=None, orders=None, projections=None, query_type=None, node_id=None, attributes=None, attributes_filter=None, extras=None, extras_filter=None)

Adds filters, default projections, order specs to the query_help, and initializes the qb object

Parameters
  • filters – dictionary with the filters

  • orders – dictionary with the order for each tag

  • projections – dictionary with the projection. It is discarded if query_type==’attributes’/’extras’

  • query_type – (string) specify the result or the content (“attr”)

  • id – (integer) id of a specific node

  • filename – name of the file to return its content

  • attributes – flag to show attributes in nodes endpoint

  • attributes_filter – list of node attributes to query

  • extras – flag to show attributes in nodes endpoint

  • extras_filter – list of node extras to query

__init__(**kwargs)[source]

Initialize self. See help(type(self)) for accurate signature.

__module__ = 'aiida.restapi.resources'
_load_and_verify(node_id=None)[source]

Load node and verify it is of the required type

_parse_pk_uuid = None
_translator_class

alias of aiida.restapi.translator.base.BaseTranslator

get(id=None, page=None)[source]

Get method for the resource :param id: node identifier :param page: page no, used for pagination :return: http response

method_decorators = [<AdapterWrapper at 0x7f8d43ab61c0 for function>]
methods = {'GET'}
parse_pk_uuid = None
class aiida.restapi.resources.CalcJobNode(**kwargs)[source]

Bases: aiida.restapi.resources.ProcessNode

Resource for CalcJobNode

class CalcJobTranslator(**kwargs)

Bases: aiida.restapi.translator.nodes.process.process.ProcessTranslator

Translator relative to resource ‘calculations’ and aiida class Calculation

class CalcJobNode(backend: Optional[Backend] = None, user: Optional[aiida.orm.users.User] = None, computer: Optional[aiida.orm.computers.Computer] = None, **kwargs: Any)

Bases: aiida.orm.nodes.process.calculation.calculation.CalculationNode

ORM class for all nodes representing the execution of a CalcJob.

CALC_JOB_STATE_KEY = 'state'
REMOTE_WORKDIR_KEY = 'remote_workdir'
RETRIEVE_LIST_KEY = 'retrieve_list'
RETRIEVE_SINGLE_FILE_LIST_KEY = 'retrieve_singlefile_list'
RETRIEVE_TEMPORARY_LIST_KEY = 'retrieve_temporary_list'
SCHEDULER_DETAILED_JOB_INFO_KEY = 'detailed_job_info'
SCHEDULER_JOB_ID_KEY = 'job_id'
SCHEDULER_LAST_CHECK_TIME_KEY = 'scheduler_lastchecktime'
SCHEDULER_LAST_JOB_INFO_KEY = 'last_job_info'
SCHEDULER_STATE_KEY = 'scheduler_state'
__abstractmethods__ = frozenset({})
__module__ = 'aiida.orm.nodes.process.calculation.calcjob'
_abc_impl = <_abc_data object>
_get_objects_to_hash() → List[Any]

Return a list of objects which should be included in the hash.

This method is purposefully overridden from the base Node class, because we do not want to include the repository folder in the hash. The reason is that the hash of this node is computed in the store method, at which point the input files that will be stored in the repository have not yet been generated. Including these anyway in the computation of the hash would mean that the hash of the node would change as soon as the process has started and the input files have been written to the repository.

_hash_ignored_attributes: Tuple[str, ] = ('queue_name', 'account', 'qos', 'priority', 'max_wallclock_seconds', 'max_memory_kb')
_logger: Optional[logging.Logger] = <Logger aiida.orm.nodes.process.calculation.calcjob.CalcJobNode (REPORT)>
_plugin_type_string = 'process.calculation.calcjob.CalcJobNode.'
_query_type_string = 'process.calculation.calcjob.'
property _raw_input_folder

Get the input folder object.

Returns

the input folder object.

Raise

NotExistent: if the raw folder hasn’t been created yet

_repository_base_path = 'raw_input'
_tools = None
_updatable_attributes: Tuple[str, ] = ('sealed', 'paused', 'checkpoints', 'exception', 'exit_message', 'exit_status', 'process_label', 'process_state', 'process_status', 'state', 'remote_workdir', 'retrieve_list', 'retrieve_temporary_list', 'retrieve_singlefile_list', 'job_id', 'scheduler_state', 'scheduler_lastchecktime', 'last_job_info', 'detailed_job_info')
static _validate_retrieval_directive(directives: Sequence[Union[str, Tuple[str, str, str]]])None

Validate a list or tuple of file retrieval directives.

Parameters

directives – a list or tuple of file retrieval directives

Raises

ValueError – if the format of the directives is invalid

delete_state()None

Delete the calculation job state attribute if it exists.

get_authinfo() → AuthInfo

Return the AuthInfo that is configured for the Computer set for this node.

Returns

AuthInfo

get_builder_restart() → ProcessBuilder

Return a ProcessBuilder that is ready to relaunch the same CalcJob that created this node.

The process class will be set based on the process_type of this node and the inputs of the builder will be prepopulated with the inputs registered for this node. This functionality is very useful if a process has completed and you want to relaunch it with slightly different inputs.

In addition to prepopulating the input nodes, which is implemented by the base ProcessNode class, here we also add the options that were passed in the metadata input of the CalcJob process.

get_description()str

Return a description of the node based on its properties.

get_detailed_job_info() → Optional[dict]

Return the detailed job info dictionary.

The scheduler is polled for the detailed job info after the job is completed and ready to be retrieved.

Returns

the dictionary with detailed job info if defined or None

get_job_id() → Optional[str]

Return job id that was assigned to the calculation by the scheduler.

Returns

the string representation of the scheduler job id

get_last_job_info() → Optional[JobInfo]

Return the last information asked to the scheduler about the status of the job.

The last job info is updated on every poll of the scheduler, except for the final poll when the job drops from the scheduler’s job queue. For completed jobs, the last job info therefore contains the “second-to-last” job info that still shows the job as running. Please use get_detailed_job_info() instead.

Returns

a JobInfo object (that closely resembles a dictionary) or None.

get_option(name: str) → Optional[Any]

Retun the value of an option that was set for this CalcJobNode

Parameters

name – the option name

Returns

the option value or None

Raises

ValueError for unknown option

get_options() → Dict[str, Any]

Return the dictionary of options set for this CalcJobNode

Returns

dictionary of the options and their values

get_parser_class() → Optional[Type[Parser]]

Return the output parser object for this calculation or None if no parser is set.

Returns

a Parser class.

Raises

aiida.common.exceptions.EntryPointError – if the parser entry point can not be resolved.

get_remote_workdir() → Optional[str]

Return the path to the remote (on cluster) scratch folder of the calculation.

Returns

a string with the remote path

get_retrieve_list() → Optional[Sequence[Union[str, Tuple[str, str, str]]]]

Return the list of files/directories to be retrieved on the cluster after the calculation has completed.

Returns

a list of file directives

get_retrieve_singlefile_list()

Return the list of files to be retrieved on the cluster after the calculation has completed.

Returns

list of single file retrieval directives

Deprecated since version 1.0.0: Will be removed in v2.0.0, use aiida.orm.nodes.process.calculation.calcjob.CalcJobNode.get_retrieve_temporary_list() instead.

get_retrieve_temporary_list() → Optional[Sequence[Union[str, Tuple[str, str, str]]]]

Return list of files to be retrieved from the cluster which will be available during parsing.

Returns

a list of file directives

get_retrieved_node() → Optional[FolderData]

Return the retrieved data folder.

Returns

the retrieved FolderData node or None if not found

get_scheduler_lastchecktime() → Optional[datetime.datetime]

Return the time of the last update of the scheduler state by the daemon or None if it was never set.

Returns

a datetime object or None

get_scheduler_state() → Optional[JobState]

Return the status of the calculation according to the cluster scheduler.

Returns

a JobState enum instance.

get_scheduler_stderr() → Optional[AnyStr]

Return the scheduler stdout output if the calculation has finished and been retrieved, None otherwise.

Returns

scheduler stdout output or None

get_scheduler_stdout() → Optional[AnyStr]

Return the scheduler stderr output if the calculation has finished and been retrieved, None otherwise.

Returns

scheduler stderr output or None

get_state() → Optional[aiida.common.datastructures.CalcJobState]

Return the calculation job active sub state.

The calculation job state serves to give more granular state information to CalcJobs, in addition to the generic process state, while the calculation job is active. The state can take values from the enumeration defined in aiida.common.datastructures.CalcJobState and can be used to query for calculation jobs in specific active states.

Returns

instance of aiida.common.datastructures.CalcJobState or None if invalid value, or not set

get_transport() → Transport

Return the transport for this calculation.

Returns

Transport configured with the AuthInfo associated to the computer of this node

Return the link label used for the retrieved FolderData node.

property res

To be used to get direct access to the parsed parameters.

Returns

an instance of the CalcJobResultManager.

Note

a practical example on how it is meant to be used: let’s say that there is a key ‘energy’ in the dictionary of the parsed results which contains a list of floats. The command calc.res.energy will return such a list.

set_detailed_job_info(detailed_job_info: Optional[dict])None

Set the detailed job info dictionary.

Parameters

detailed_job_info – a dictionary with metadata with the accounting of a completed job

set_job_id(job_id: Union[int, str])None

Set the job id that was assigned to the calculation by the scheduler.

Note

the id will always be stored as a string

Parameters

job_id – the id assigned by the scheduler after submission

set_last_job_info(last_job_info: JobInfo)None

Set the last job info.

Parameters

last_job_info – a JobInfo object

set_option(name: str, value: Any)None

Set an option to the given value

Parameters
  • name – the option name

  • value – the value to set

Raises

ValueError for unknown option

Raises

TypeError for values with invalid type

set_options(options: Dict[str, Any])None

Set the options for this CalcJobNode

Parameters

options – dictionary of option and their values to set

set_remote_workdir(remote_workdir: str)None

Set the absolute path to the working directory on the remote computer where the calculation is run.

Parameters

remote_workdir – absolute filepath to the remote working directory

set_retrieve_list(retrieve_list: Sequence[Union[str, Tuple[str, str, str]]])None

Set the retrieve list.

This list of directives will instruct the daemon what files to retrieve after the calculation has completed. list or tuple of files or paths that should be retrieved by the daemon.

Parameters

retrieve_list – list or tuple of with filepath directives

set_retrieve_singlefile_list(retrieve_singlefile_list)

Set the retrieve singlefile list.

The files will be stored as SinglefileData instances and added as output nodes to this calculation node. The format of a single file directive is a tuple or list of length 3 with the following entries:

  1. the link label under which the file should be added

  2. the SinglefileData class or sub class to use to store

  3. the filepath relative to the remote working directory of the calculation

Parameters

retrieve_singlefile_list – list or tuple of single file directives

Deprecated since version 1.0.0: Will be removed in v2.0.0. Use set_retrieve_temporary_list() instead.

set_retrieve_temporary_list(retrieve_temporary_list: Sequence[Union[str, Tuple[str, str, str]]])None

Set the retrieve temporary list.

The retrieve temporary list stores files that are retrieved after completion and made available during parsing and are deleted as soon as the parsing has been completed.

Parameters

retrieve_temporary_list – list or tuple of with filepath directives

set_scheduler_state(state: JobState)None

Set the scheduler state.

Parameters

state – an instance of JobState

set_state(state: aiida.common.datastructures.CalcJobState)None

Set the calculation active job state.

Raise

ValueError if state is invalid

property tools

Return the calculation tools that are registered for the process type associated with this calculation.

If the entry point name stored in the process_type of the CalcJobNode has an accompanying entry point in the aiida.tools.calculations entry point category, it will attempt to load the entry point and instantiate it passing the node to the constructor. If the entry point does not exist, cannot be resolved or loaded, a warning will be logged and the base CalculationTools class will be instantiated and returned.

Returns

CalculationTools instance

__label__ = 'calcjobs'
__module__ = 'aiida.restapi.translator.nodes.process.calculation.calcjob'
_aiida_class

alias of aiida.orm.nodes.process.calculation.calcjob.CalcJobNode

_aiida_type = 'process.calculation.calcjob.CalcJobNode'
_result_type = 'calcjobs'
static get_derived_properties(node)

Generic function extended for calcjob. Currently it is not implemented.

Parameters

node – node object

Returns

empty dict

static get_input_files(node, filename)

Get the submitted input files for job calculation :param node: aiida node :return: the retrieved input files for job calculation

static get_output_files(node, filename)

Get the retrieved output files for job calculation :param node: aiida node :return: the retrieved output files for job calculation

__module__ = 'aiida.restapi.resources'
_translator_class

alias of aiida.restapi.translator.nodes.process.calculation.calcjob.CalcJobTranslator

get(id=None, page=None)[source]

Get method for the Process resource.

Parameters

id – node identifier

Returns

http response

methods = {'GET'}
class aiida.restapi.resources.Computer(**kwargs)[source]

Bases: aiida.restapi.resources.BaseResource

Resource for Computer

class ComputerTranslator(**kwargs)

Bases: aiida.restapi.translator.base.BaseTranslator

Translator relative to resource ‘computers’ and aiida class Computer

__label__ = 'computers'
__module__ = 'aiida.restapi.translator.computer'
_aiida_class

alias of aiida.orm.computers.Computer

_aiida_type = 'Computer'
_has_uuid = True
_result_type = 'computers'
get_projectable_properties()

Get projectable properties specific for Computer :return: dict of projectable properties and column_order list

__module__ = 'aiida.restapi.resources'
_parse_pk_uuid = 'uuid'
_translator_class

alias of aiida.restapi.translator.computer.ComputerTranslator

methods = {'GET'}
class aiida.restapi.resources.Group(**kwargs)[source]

Bases: aiida.restapi.resources.BaseResource

Resource for Group

class GroupTranslator(**kwargs)

Bases: aiida.restapi.translator.base.BaseTranslator

Translator relative to resource ‘groups’ and aiida class Group

__label__ = 'groups'
__module__ = 'aiida.restapi.translator.group'
_aiida_class

alias of aiida.orm.groups.Group

_aiida_type = 'groups.Group'
_has_uuid = True
_result_type = 'groups'
get_projectable_properties()

Get projectable properties specific for Group :return: dict of projectable properties and column_order list

__module__ = 'aiida.restapi.resources'
_parse_pk_uuid = 'uuid'
_translator_class

alias of aiida.restapi.translator.group.GroupTranslator

methods = {'GET'}
class aiida.restapi.resources.Node(**kwargs)[source]

Bases: aiida.restapi.resources.BaseResource

Differs from BaseResource in trans.set_query() mostly because it takes query_type as an input and the presence of additional result types like “tree”

class NodeTranslator(**kwargs)

Bases: aiida.restapi.translator.base.BaseTranslator

Translator relative to resource ‘nodes’ and aiida class Node

__init__(**kwargs)

Initialise the parameters. Create the basic query_help

__label__ = 'nodes'
__module__ = 'aiida.restapi.translator.nodes.node'
_aiida_class

alias of aiida.orm.nodes.node.Node

_aiida_type = 'node.Node'
_attributes_filter = None
_content_type = None
_download = None
_download_format = None
_extras_filter = None
_filename = None
_get_content()

Used by get_results() in case of endpoint include “content” option :return: data: a dictionary containing the results obtained by running the query

_get_subclasses(parent=None, parent_class=None, recursive=True)

Import all submodules of the package containing the present class. Includes subpackages recursively, if specified.

Parameters
  • parent – package/class. If package looks for the classes in submodules. If class, first looks for the package where it is contained

  • parent_class – class of which to look for subclasses

  • recursive – True/False (go recursively into submodules)

_has_uuid = True
_result_type = 'nodes'
static get_all_download_formats(full_type=None)

returns dict of possible node formats for all available node types

static get_comments(node)
Parameters

node – node object

Returns

node comments

get_derived_properties(node)

Generic function to get the derived properties of the node. Actual definition is in child classes as the content to be returned depends on the plugin specific to the resource

Parameters

node – node object that has to be visualized

Returns

derived properties of the node

If this method is called by Node resource it will look for the type of object and invoke the correct method in the lowest-compatible subclass

static get_downloadable_data(node, download_format=None)

Generic function to download file in specified format. Actual definition is in child classes as the content to be returned and its format depends on the download plugin specific to the resource

Parameters
  • node – node object

  • download_format – file extension format

Returns

data in selected format to download

If this method is called for a Data node resource it will invoke the get_downloadable_data method in the Data transaltor. Otherwise it raises RestFeatureNotAvailable exception

static get_file_content(node, file_name)

It reads the file from directory and returns its content.

Instead of using “send_from_directory” from flask, this method is written because in next aiida releases the file can be stored locally or in object storage.

Parameters
  • node – aiida folderData node which contains file

  • file_name – name of the file to return its contents

Returns

get_formatted_result(label)

Runs the query and retrieves results tagged as “label”.

Parameters

label (str) – the tag of the results to be extracted out of the query rows.

Returns

a list of the query results

get_io_tree(uuid_pattern, tree_in_limit, tree_out_limit)

json data to display nodes in tree format :param uuid_pattern: main node uuid :return: json data to display node tree

static get_namespace(user_pk=None, count_nodes=False)

return full_types of the nodes

get_projectable_properties()

Get projectable properties specific for Node :return: dict of projectable properties and column_order list

static get_repo_contents(node, filename='')

Every node in AiiDA is having repo folder. This function returns the metadata using get_object() method :param node: node object :param filename: folder or file name (optional) :return: file content in bytes to download

static get_repo_list(node, filename='')

Every node in AiiDA is having repo folder. This function returns the metadata using list_objects() method :param node: node object :param filename: folder name (optional) :return: folder list

get_results()

Returns either a list of nodes or details of single node from database

Returns

either a list of nodes or the details of single node from the database

get_statistics(user_pk=None)

Return statistics for a given node

set_query(filters=None, orders=None, projections=None, query_type=None, node_id=None, download_format=None, download=None, filename=None, attributes=None, attributes_filter=None, extras=None, extras_filter=None, full_type=None)

Adds filters, default projections, order specs to the query_help, and initializes the qb object

Parameters
  • filters – dictionary with the filters

  • orders – dictionary with the order for each tag

  • projections – dictionary with the projection. It is discarded if query_type==’attributes’/’extras’

  • query_type – (string) specify the result or the content (“attr”)

  • id – (integer) id of a specific node

  • download_format – file format to download e.g. cif, xyz

  • filename – name of the file to return its content

  • attributes – flag to show attributes for nodes

  • attributes_filter – list of attributes to query

  • extras – flag to show extras for nodes

  • extras_filter – list of extras to query

set_query_type(query_type, attributes_filter=None, extras_filter=None, download_format=None, download=None, filename=None)

sets one of the mutually exclusive values for self._result_type and self._content_type.

:param query_type:(string) the value assigned to either variable.

__module__ = 'aiida.restapi.resources'
_parse_pk_uuid = 'uuid'
_translator_class

alias of aiida.restapi.translator.nodes.node.NodeTranslator

get(id=None, page=None)[source]

Get method for the Node resource.

Parameters
  • id – node identifier

  • page – page no, used for pagination

Returns

http response

methods = {'GET'}
class aiida.restapi.resources.ProcessNode(**kwargs)[source]

Bases: aiida.restapi.resources.Node

Resource for ProcessNode

class ProcessTranslator(**kwargs)

Bases: aiida.restapi.translator.nodes.node.NodeTranslator

Translator relative to resource ‘data’ and aiida class ~aiida.orm.nodes.data.data.Data

class ProcessNode(backend: Optional[Backend] = None, user: Optional[aiida.orm.users.User] = None, computer: Optional[aiida.orm.computers.Computer] = None, **kwargs: Any)

Bases: aiida.orm.utils.mixins.Sealable, aiida.orm.nodes.node.Node

Base class for all nodes representing the execution of a process

This class and its subclasses serve as proxies in the database, for actual Process instances being run. The Process instance in memory will leverage an instance of this class (the exact sub class depends on the sub class of Process) to persist important information of its state to the database. This serves as a way for the user to inspect the state of the Process during its execution as well as a permanent record of its execution in the provenance graph, after the execution has terminated.

CHECKPOINT_KEY = 'checkpoints'
EXCEPTION_KEY = 'exception'
EXIT_MESSAGE_KEY = 'exit_message'
EXIT_STATUS_KEY = 'exit_status'
PROCESS_LABEL_KEY = 'process_label'
PROCESS_PAUSED_KEY = 'paused'
PROCESS_STATE_KEY = 'process_state'
PROCESS_STATUS_KEY = 'process_status'
__abstractmethods__ = frozenset({})
__module__ = 'aiida.orm.nodes.process.process'
__str__()str

Return str(self).

_abc_impl = <_abc_data object>
_get_objects_to_hash() → List[Any]

Return a list of objects which should be included in the hash.

_hash_ignored_inputs = ['CALL_CALC', 'CALL_WORK']
_logger: Optional[logging.Logger] = <Logger aiida.orm.nodes.process.process.ProcessNode (REPORT)>
_plugin_type_string = 'process.ProcessNode.'
_query_type_string = 'process.'
_unstorable_message = 'only Data, WorkflowNode, CalculationNode or their subclasses can be stored'
_updatable_attributes: Tuple[str, ] = ('sealed', 'paused', 'checkpoints', 'exception', 'exit_message', 'exit_status', 'process_label', 'process_state', 'process_status')
property called

Return a list of nodes that the process called

Returns

list of process nodes called by this process

property called_descendants

Return a list of all nodes that have been called downstream of this process

This will recursively find all the called processes for this process and its children.

property caller

Return the process node that called this process node, or None if it does not have a caller

Returns

process node that called this process node instance or None

property checkpoint

Return the checkpoint bundle set for the process

Returns

checkpoint bundle if it exists, None otherwise

delete_checkpoint()None

Delete the checkpoint bundle set for the process

property exception

Return the exception of the process or None if the process is not excepted.

If the process is marked as excepted yet there is no exception attribute, an empty string will be returned.

Returns

the exception message or None

property exit_message

Return the exit message of the process

Returns

the exit message

property exit_status

Return the exit status of the process

Returns

the exit status, an integer exit code or None

get_builder_restart() → ProcessBuilder

Return a ProcessBuilder that is ready to relaunch the process that created this node.

The process class will be set based on the process_type of this node and the inputs of the builder will be prepopulated with the inputs registered for this node. This functionality is very useful if a process has completed and you want to relaunch it with slightly different inputs.

Returns

~aiida.engine.processes.builder.ProcessBuilder instance

property is_excepted

Return whether the process has excepted

Excepted means that during execution of the process, an exception was raised that was not caught.

Returns

True if during execution of the process an exception occurred, False otherwise

Return type

bool

property is_failed

Return whether the process has failed

Failed means that the process terminated nominally but it had a non-zero exit status.

Returns

True if the process has failed, False otherwise

Return type

bool

property is_finished

Return whether the process has finished

Finished means that the process reached a terminal state nominally. Note that this does not necessarily mean successfully, but there were no exceptions and it was not killed.

Returns

True if the process has finished, False otherwise

Return type

bool

property is_finished_ok

Return whether the process has finished successfully

Finished successfully means that it terminated nominally and had a zero exit status.

Returns

True if the process has finished successfully, False otherwise

Return type

bool

property is_killed

Return whether the process was killed

Killed means the process was killed directly by the user or by the calling process being killed.

Returns

True if the process was killed, False otherwise

Return type

bool

property is_terminated

Return whether the process has terminated

Terminated means that the process has reached any terminal state.

Returns

True if the process has terminated, False otherwise

Return type

bool

property is_valid_cache

Return whether the node is valid for caching

Returns

True if this process node is valid to be used for caching, False otherwise

property logger

Get the logger of the Calculation object, so that it also logs to the DB.

Returns

LoggerAdapter object, that works like a logger, but also has the ‘extra’ embedded

pause()None

Mark the process as paused by setting the corresponding attribute.

This serves only to reflect that the corresponding Process is paused and so this method should not be called by anyone but the Process instance itself.

property paused

Return whether the process is paused

Returns

True if the Calculation is marked as paused, False otherwise

property process_class

Return the process class that was used to create this node.

Returns

Process class

Raises

ValueError – if no process type is defined, it is an invalid process type string or cannot be resolved to load the corresponding class

property process_label

Return the process label

Returns

the process label

property process_state

Return the process state

Returns

the process state instance of ProcessState enum

property process_status

Return the process status

The process status is a generic status message e.g. the reason it might be paused or when it is being killed

Returns

the process status

set_checkpoint(checkpoint: Dict[str, Any])None

Set the checkpoint bundle set for the process

Parameters

state – string representation of the stepper state info

set_exception(exception: str)None

Set the exception of the process

Parameters

exception – the exception message

set_exit_message(message: Optional[str])None

Set the exit message of the process, if None nothing will be done

Parameters

message – a string message

set_exit_status(status: Union[None, enum.Enum, int])None

Set the exit status of the process

Parameters

state – an integer exit code or None, which will be interpreted as zero

set_process_label(label: str)None

Set the process label

Parameters

label – process label string

set_process_state(state: Union[str, plumpy.process_states.ProcessState])

Set the process state

Parameters

state – value or instance of ProcessState enum

set_process_status(status: Optional[str])None

Set the process status

The process status is a generic status message e.g. the reason it might be paused or when it is being killed. If status is None, the corresponding attribute will be deleted.

Parameters

status – string process status

set_process_type(process_type_string: str)None

Set the process type string.

Parameters

process_type – the process type string identifying the class using this process node as storage.

unpause()None

Mark the process as unpaused by removing the corresponding attribute.

This serves only to reflect that the corresponding Process is unpaused and so this method should not be called by anyone but the Process instance itself.

validate_incoming(source: aiida.orm.nodes.node.Node, link_type: aiida.common.links.LinkType, link_label: str)None

Validate adding a link of the given type from a given node to ourself.

Adding an input link to a ProcessNode once it is stored is illegal because this should be taken care of by the engine in one go. If a link is being added after the node is stored, it is most likely not by the engine and it should not be allowed.

Parameters
  • source – the node from which the link is coming

  • link_type – the link type

  • link_label – the link label

Raises
  • TypeError – if source is not a Node instance or link_type is not a LinkType enum

  • ValueError – if the proposed link is invalid

__label__ = 'process'
__module__ = 'aiida.restapi.translator.nodes.process.process'
_aiida_class

alias of aiida.orm.nodes.process.process.ProcessNode

_aiida_type = 'process.ProcessNode'
_result_type = 'process'
get_projectable_properties()

Get projectable properties specific for Process nodes :return: dict of projectable properties and column_order list

static get_report(process)

Show the log report for one or multiple processes.

__module__ = 'aiida.restapi.resources'
_translator_class

alias of aiida.restapi.translator.nodes.process.process.ProcessTranslator

get(id=None, page=None)[source]

Get method for the Process resource.

Parameters

id – node identifier

Returns

http response

methods = {'GET'}
class aiida.restapi.resources.QueryBuilder(**kwargs)[source]

Bases: aiida.restapi.resources.BaseResource

Representation of a QueryBuilder REST API resource (instantiated with a queryhelp JSON).

It supports POST requests taking in JSON queryhelp() objects and returning the QueryBuilder result accordingly.

class NodeTranslator(**kwargs)

Bases: aiida.restapi.translator.base.BaseTranslator

Translator relative to resource ‘nodes’ and aiida class Node

__init__(**kwargs)

Initialise the parameters. Create the basic query_help

__label__ = 'nodes'
__module__ = 'aiida.restapi.translator.nodes.node'
_aiida_class

alias of aiida.orm.nodes.node.Node

_aiida_type = 'node.Node'
_attributes_filter = None
_content_type = None
_download = None
_download_format = None
_extras_filter = None
_filename = None
_get_content()

Used by get_results() in case of endpoint include “content” option :return: data: a dictionary containing the results obtained by running the query

_get_subclasses(parent=None, parent_class=None, recursive=True)

Import all submodules of the package containing the present class. Includes subpackages recursively, if specified.

Parameters
  • parent – package/class. If package looks for the classes in submodules. If class, first looks for the package where it is contained

  • parent_class – class of which to look for subclasses

  • recursive – True/False (go recursively into submodules)

_has_uuid = True
_result_type = 'nodes'
static get_all_download_formats(full_type=None)

returns dict of possible node formats for all available node types

static get_comments(node)
Parameters

node – node object

Returns

node comments

get_derived_properties(node)

Generic function to get the derived properties of the node. Actual definition is in child classes as the content to be returned depends on the plugin specific to the resource

Parameters

node – node object that has to be visualized

Returns

derived properties of the node

If this method is called by Node resource it will look for the type of object and invoke the correct method in the lowest-compatible subclass

static get_downloadable_data(node, download_format=None)

Generic function to download file in specified format. Actual definition is in child classes as the content to be returned and its format depends on the download plugin specific to the resource

Parameters
  • node – node object

  • download_format – file extension format

Returns

data in selected format to download

If this method is called for a Data node resource it will invoke the get_downloadable_data method in the Data transaltor. Otherwise it raises RestFeatureNotAvailable exception

static get_file_content(node, file_name)

It reads the file from directory and returns its content.

Instead of using “send_from_directory” from flask, this method is written because in next aiida releases the file can be stored locally or in object storage.

Parameters
  • node – aiida folderData node which contains file

  • file_name – name of the file to return its contents

Returns

get_formatted_result(label)

Runs the query and retrieves results tagged as “label”.

Parameters

label (str) – the tag of the results to be extracted out of the query rows.

Returns

a list of the query results

get_io_tree(uuid_pattern, tree_in_limit, tree_out_limit)

json data to display nodes in tree format :param uuid_pattern: main node uuid :return: json data to display node tree

static get_namespace(user_pk=None, count_nodes=False)

return full_types of the nodes

get_projectable_properties()

Get projectable properties specific for Node :return: dict of projectable properties and column_order list

static get_repo_contents(node, filename='')

Every node in AiiDA is having repo folder. This function returns the metadata using get_object() method :param node: node object :param filename: folder or file name (optional) :return: file content in bytes to download

static get_repo_list(node, filename='')

Every node in AiiDA is having repo folder. This function returns the metadata using list_objects() method :param node: node object :param filename: folder name (optional) :return: folder list

get_results()

Returns either a list of nodes or details of single node from database

Returns

either a list of nodes or the details of single node from the database

get_statistics(user_pk=None)

Return statistics for a given node

set_query(filters=None, orders=None, projections=None, query_type=None, node_id=None, download_format=None, download=None, filename=None, attributes=None, attributes_filter=None, extras=None, extras_filter=None, full_type=None)

Adds filters, default projections, order specs to the query_help, and initializes the qb object

Parameters
  • filters – dictionary with the filters

  • orders – dictionary with the order for each tag

  • projections – dictionary with the projection. It is discarded if query_type==’attributes’/’extras’

  • query_type – (string) specify the result or the content (“attr”)

  • id – (integer) id of a specific node

  • download_format – file format to download e.g. cif, xyz

  • filename – name of the file to return its content

  • attributes – flag to show attributes for nodes

  • attributes_filter – list of attributes to query

  • extras – flag to show extras for nodes

  • extras_filter – list of extras to query

set_query_type(query_type, attributes_filter=None, extras_filter=None, download_format=None, download=None, filename=None)

sets one of the mutually exclusive values for self._result_type and self._content_type.

:param query_type:(string) the value assigned to either variable.

__init__(**kwargs)[source]

Initialize self. See help(type(self)) for accurate signature.

__module__ = 'aiida.restapi.resources'
_translator_class

alias of aiida.restapi.translator.nodes.node.NodeTranslator

get()[source]

Static return to state information about this endpoint.

methods = {'GET', 'POST'}
post()[source]

POST method to pass query help JSON.

If the posted JSON is not a valid QueryBuilder queryhelp, the request will fail with an internal server error.

This uses the NodeTranslator in order to best return Nodes according to the general AiiDA REST API data format, while still allowing the return of other AiiDA entities.

Returns

QueryBuilder result of AiiDA entities in “standard” REST API format.

class aiida.restapi.resources.ServerInfo(**kwargs)[source]

Bases: flask_restful.Resource

Endpoint to return general server info

__init__(**kwargs)[source]

Initialize self. See help(type(self)) for accurate signature.

__module__ = 'aiida.restapi.resources'
get()[source]

It returns the general info about the REST API :return: returns current AiiDA version defined in aiida/__init__.py

methods = {'GET'}
class aiida.restapi.resources.User(**kwargs)[source]

Bases: aiida.restapi.resources.BaseResource

Resource for User

class UserTranslator(**kwargs)

Bases: aiida.restapi.translator.base.BaseTranslator

Translator relative to resource ‘users’ and aiida class User

__label__ = 'users'
__module__ = 'aiida.restapi.translator.user'
_aiida_class

alias of aiida.orm.users.User

_aiida_type = 'User'
_default_projections = ['id', 'first_name', 'last_name', 'institution']
_has_uuid = False
_result_type = 'users'
get_projectable_properties()

Get projectable properties specific for User :return: dict of projectable properties and column_order list

__module__ = 'aiida.restapi.resources'
_parse_pk_uuid = 'pk'
_translator_class

alias of aiida.restapi.translator.user.UserTranslator

methods = {'GET'}

It defines the method with all required parameters to run restapi locally.

aiida.restapi.run_api.configure_api(flask_app=<class 'aiida.restapi.api.App'>, flask_api=<class 'aiida.restapi.api.AiidaApi'>, **kwargs)[source]

Configures a flask.Flask instance and returns it.

Parameters
  • flask_app (flask.Flask) – Class inheriting from flask app class

  • flask_api (flask_restful.Api) – flask_restful API class to be used to wrap the app

  • config – directory containing the config.py configuration file

  • catch_internal_server – If true, catch and print internal server errors with full python traceback. Useful during app development.

  • wsgi_profile – use WSGI profiler middleware for finding bottlenecks in the web application

  • posting – Whether or not to include POST-enabled endpoints (currently only /querybuilder).

Returns

Flask RESTful API

Return type

flask_restful.Api

aiida.restapi.run_api.run_api(flask_app=<class 'aiida.restapi.api.App'>, flask_api=<class 'aiida.restapi.api.AiidaApi'>, **kwargs)[source]

Takes a flask.Flask instance and runs it.

Parameters
  • flask_app (flask.Flask) – Class inheriting from flask app class

  • flask_api (flask_restful.Api) – flask_restful API class to be used to wrap the app

  • hostname – hostname to run app on (only when using built-in server)

  • port – port to run app on (only when using built-in server)

  • config – directory containing the config.py file used to configure the RESTapi

  • catch_internal_server – If true, catch and print all inter server errors

  • debug – enable debugging

  • wsgi_profile – use WSGI profiler middleware for finding bottlenecks in web application

  • hookup – If true, hook up application to built-in server, else just return it. This parameter is deprecated as of AiiDA 1.2.1. If you don’t intend to run the API (hookup=False) use configure_api instead.

  • posting – Whether or not to include POST-enabled endpoints (currently only /querybuilder).

Returns

tuple (app, api) if hookup==False or runs app if hookup==True