Default configuration for the REST API
This file contains the exceptions that are raised by the RESTapi at the highest level, namely that of the interaction with the client. Their specificity resides into the fact that they return a message that is embedded into the HTTP response.
Example:
…/api/v1/nodes/ … (TODO compete this with an actual example)
Other errors arising at deeper level, e.g. those raised by the QueryBuilder or internal errors, are not embedded into the HTTP response.
aiida.restapi.common.exceptions.
RestFeatureNotAvailable
Bases: aiida.common.exceptions.FeatureNotAvailable
aiida.common.exceptions.FeatureNotAvailable
If endpoint is not emplemented for given node type
__module__
RestInputValidationError
Bases: aiida.common.exceptions.InputValidationError
aiida.common.exceptions.InputValidationError
If inputs passed in query strings are wrong
RestValidationError
Bases: aiida.common.exceptions.ValidationError
aiida.common.exceptions.ValidationError
If validation error in code E.g. more than one node available for given uuid
Utility functions to work with node “full types” which are unique node identifiers.
A node’s full_type is defined as a string that uniquely defines the node type. A valid full_type is constructed by concatenating the node_type and process_type of a node with the FULL_TYPE_CONCATENATOR. Each segment of the full type can optionally be terminated by a single LIKE_OPERATOR_CHARACTER to indicate that the node_type or process_type should start with that value but can be followed by any amount of other characters. A full type is invalid if it does not contain exactly one FULL_TYPE_CONCATENATOR character. Additionally, each segment can contain at most one occurrence of the LIKE_OPERATOR_CHARACTER and it has to be at the end of the segment.
Examples of valid full types:
‘data.bool.Bool.|’ ‘process.calculation.calcfunction.%|%’ ‘process.calculation.calcjob.CalcJobNode.|aiida.calculations:arithmetic.add’ ‘process.calculation.calcfunction.CalcFunctionNode.|aiida.workflows:codtools.primitive_structure_from_cif’
Examples of invalid full types:
‘data.bool’ # Only a single segment without concatenator ‘data.|bool.Bool.|process.’ # More than one concatenator ‘process.calculation%.calcfunction.|aiida.calculations:arithmetic.add’ # Like operator not at end of segment ‘process.calculation%.calcfunction.%|aiida.calculations:arithmetic.add’ # More than one operator in segment
aiida.restapi.common.identifiers.
Namespace
Bases: collections.abc.MutableMapping
collections.abc.MutableMapping
Namespace that can be used to map the node class hierarchy.
__abstractmethods__
__delitem__
__dict__
__getitem__
__init__
Construct a new node class namespace.
__iter__
__len__
__setitem__
__str__
Return str(self).
__weakref__
list of weak references to the object (if defined)
_abc_impl
_infer_full_type
Infer the full type based on the current namespace path and the given full type of the leaf.
create_namespace
Create and return a new Namespace in this Namespace.
If the name is namespaced, the sub Namespaces will be created recursively, except if one of the namespaces is already occupied at any level by a Port in which case a ValueError will be thrown
name – name (potentially namespaced) of the port to create and return
kwargs – constructor arguments that will be used only for the construction of the terminal Namespace
ValueError if any sub namespace is occupied by a non-Namespace port
get_description
Return a dictionary with a description of the ports this namespace contains.
Nested PortNamespaces will be properly recursed and Ports will print their properties in a list
a dictionary of descriptions of the Ports contained within this PortNamespace
is_leaf
mapping_path_to_label
namespace_separator
process_full_type_mapping
process_full_type_mapping_unplugged
construct_full_type
Return the full type, which uniquely identifies any Node with the given node_type and process_type.
node_type – the node_type of the Node
process_type – the process_type of the Node
the full type, which is a unique identifier
get_full_type_filters
Return the QueryBuilder filters that will return all Nodes identified by the given full_type.
full_type – the full_type unique node identifier
dictionary of filters to be passed for the filters keyword in QueryBuilder.append
ValueError – if the full_type is invalid
TypeError – if the full_type is not a string type
get_node_namespace
Return the full namespace of all available nodes in the current database.
complete node Namespace
load_entry_point_from_full_type
Return the loaded entry point for the given full_type unique node identifier.
EntryPointError – if the corresponding entry point cannot be loaded
validate_full_type
Validate that the full_type is a valid full type unique node identifier.
full_type – a Node full type
Util methods
aiida.restapi.common.utils.
CustomJSONEncoder
Bases: flask.json.JSONEncoder
flask.json.JSONEncoder
Custom json encoder for serialization. This has to be provided to the Flask app in order to replace the default encoder.
default
Override default method from JSONEncoder to change serializer :param o: Object e.g. dict, list that will be serialized :return: serialized object
DatetimePrecision
Bases: object
object
A simple class which stores a datetime object with its precision. No internal check is done (cause itis not possible).
2 (date plus hour) 3 (date + hour + minute) 4 (dare + hour + minute +second)
Constructor to check valid datetime object and precision
Utils
A class that gathers all the utility functions for parsing URI, validating request, pass it to the translator, and building HTTP response
An istance of Utils has to be included in the api class so that the configuration parameters used to build the api are automatically accessible by the methods of Utils without the need to import them from the config.py file.
Sets internally the configuration parameters
build_datetime_filter
This function constructs a filter for a datetime object to be in a certain datetime interval according to the precision.
The interval is [reference_datetime, reference_datetime + delta_time], where delta_time is a function fo the required precision.
This function should be used to replace a datetime filter based on the equality operator that is inehrently “picky” because it implies matching two datetime objects down to the microsecond or something, by a “tolerant” operator which checks whether the datetime is in an interval.
a suitable entry of the filter dictionary
build_headers
Construct the header dictionary for an HTTP response. It includes related pages, total count of results (before pagination).
rel_pages – a dictionary defining related pages (first, prev, next, last)
url – (string) the full url, i.e. the url that the client uses to get Rest resources
build_response
Build the response
status – status of the response, e.g. 200=OK, 400=bad request
headers – dictionary for additional header k,v pairs, e.g. X-total-count=<number of rows resulting from query>
data – a dictionary with the data returned by the Resource
a Flask response object
build_translator_parameters
Takes a list of elements resulting from the parsing the query_string and elaborates them in order to provide translator-compliant instructions
field_list – a (nested) list of elements resulting from parsing the query_string
the filters in the
op_conv_map
paginate
Calculates limit and offset for the reults of a query, given the page and the number of restuls per page. Moreover, calculates the last available page and raises an exception if the required page exceeds that limit. If number of rows==0, only page 1 exists :param page: integer number of the page that has to be viewed :param perpage: integer defining how many results a page contains :param total_count: the total number of rows retrieved by the query :return: integers: limit, offset, rel_pages
parse_path
Takes the path and parse it checking its validity. Does not parse “io”, “content” fields. I do not check the validity of the path, since I assume that this is done by the Flask routing methods.
path_string – the path string
parse_id_uuid – if ‘pk’ (‘uuid’) expects an integer (uuid starting pattern)
resource_type (string) page (integer) node_id (string: uuid starting pattern, int: pk) query_type (string))
parse_query_string
Function that parse the querystring, extracting infos for limit, offset, ordering, filters, attribute and extra projections. :param query_string (as obtained from request.query_string) :return: parsed values for the querykeys
split_path
path – entire path contained in flask request
list of each element separated by ‘/’
strip_api_prefix
Removes the PREFIX from an URL path. PREFIX must be defined in the config.py file:
PREFIX = "/api/v2" path = "/api/v2/calculations/page/2" strip_api_prefix(path) ==> "/calculations/page/2"
path – the URL path string
the same URL without the prefix
validate_request
Performs various checks on the consistency of the request. Add here all the checks that you want to do, except validity of the page number that is done in paginate(). Future additional checks must be added here
close_session
Close AiiDA SQLAlchemy (QueryBuilder) session
This decorator can be used for router endpoints to close the SQLAlchemy global scoped session after the response has been created. This is needed, since the QueryBuilder uses a SQLAlchemy global scoped session no matter the profile’s database backend.
list_routes
List available routes