Module with the implementations of the various backend entities for various database backends.
aiida.orm.implementation.
Backend
Bases: abc.ABC
abc.ABC
The public interface that defines a backend factory that creates backend specific concrete objects.
__abstractmethods__
__dict__
__module__
__weakref__
list of weak references to the object (if defined)
_abc_impl
authinfos
Return the collection of authorisation information objects
the authinfo collection
aiida.orm.implementation.BackendAuthInfoCollection
comments
Return the collection of comments
the comment collection
aiida.orm.implementation.BackendCommentCollection
computers
Return the collection of computers
the computers collection
aiida.orm.implementation.BackendComputerCollection
get_session
Return a database session that can be used by the QueryBuilder to perform its query.
an instance of sqlalchemy.orm.session.Session
sqlalchemy.orm.session.Session
groups
Return the collection of groups
the groups collection
aiida.orm.implementation.BackendGroupCollection
logs
Return the collection of logs
the log collection
aiida.orm.implementation.BackendLogCollection
migrate
Migrate the database to the latest schema generation or version.
nodes
Return the collection of nodes
the nodes collection
aiida.orm.implementation.BackendNodeCollection
query
Return an instance of a query builder implementation for this backend
a new query builder instance
aiida.orm.implementation.BackendQueryBuilder
query_manager
Return the query manager for the objects stored in the backend
The query manger
aiida.backends.general.abstractqueries.AbstractQueryManager
transaction
Get a context manager that can be used as a transaction context for a series of backend operations. If there is an exception within the context then the changes will be rolled back and the state will be as before entering. Transactions can be nested.
a context manager to group database operations
users
Return the collection of users
the users collection
aiida.orm.implementation.BackendUserCollection
BackendAuthInfo
Bases: aiida.orm.implementation.entities.BackendEntity
aiida.orm.implementation.entities.BackendEntity
Backend implementation for the AuthInfo ORM class.
METADATA_WORKDIR
computer
Return the computer associated with this instance.
aiida.orm.implementation.computers.BackendComputer
enabled
Return whether this instance is enabled.
boolean, True if enabled, False otherwise
get_auth_params
Return the dictionary of authentication parameters
a dictionary with authentication parameters
get_metadata
Return the dictionary of metadata
a dictionary with metadata
set_auth_params
Set the dictionary of authentication parameters
auth_params – a dictionary with authentication parameters
set_metadata
Set the dictionary of metadata
metadata – a dictionary with metadata
user
Return the user associated with this instance.
aiida.orm.implementation.users.BackendUser
BackendAuthInfoCollection
Bases: aiida.orm.implementation.entities.BackendCollection
aiida.orm.implementation.entities.BackendCollection
The collection of backend AuthInfo entries.
ENTITY_CLASS
alias of BackendAuthInfo
__orig_bases__
__parameters__
delete
Delete an entry from the collection.
pk – the pk of the entry to delete
get
Return an entry from the collection that is configured for the given computer and user
computer – a aiida.orm.implementation.computers.BackendComputer instance
user – a aiida.orm.implementation.users.BackendUser instance
aiida.orm.implementation.authinfos.BackendAuthInfo
aiida.common.exceptions.NotExistent – if no entry exists for the computer/user pair
aiida.common.exceptions.MultipleObjectsError – if multiple entries exist for the computer/user pair
BackendComment
Base class for a node comment.
content
ctime
mtime
node
set_content
set_mtime
set_user
uuid
BackendCommentCollection
The collection of Comment entries.
alias of BackendComment
create
Create a Comment for a given node and user
node – a Node instance
user – a User instance
content – the comment content
a Comment object associated to the given node and user
Remove a Comment from the collection with the given id
comment_id (int) – the id of the comment to delete
TypeError – if comment_id is not an int
comment_id
NotExistent – if Comment with ID comment_id is not found
delete_all
Delete all Comment entries.
IntegrityError – if all Comments could not be deleted
delete_many
Delete Comments based on filters
filters
filters (dict) – similar to QueryBuilder filter
(former) PK s of deleted Comments
PK
list
TypeError – if filters is not a dict
ValidationError – if filters is empty
BackendComputer
Base class to map a node in the DB + its permanent repository counterpart.
Stores attributes starting with an underscore.
Caches files and attributes before the first save, and saves everything only on store(). After the call to store(), attributes cannot be changed.
Only after storing (or upon loading from uuid) metadata can be modified and in this case they are directly set on the db.
In the plugin, also set the _plugin_type_string, to be set in the DB in the ‘type’ field.
_logger
description
get_description
get_hostname
Get this computer hostname :rtype: str
get_name
get_scheduler_type
get_transport_type
hostname
is_stored
Is the computer stored?
True if stored, False otherwise
bool
name
set_description
set_hostname
Set the hostname of this computer :param val: The new hostname :type val: str
Set the metadata.
set_name
set_scheduler_type
set_transport_type
BackendComputerCollection
The collection of Computer entries.
alias of BackendComputer
Delete an entry with the given pk
BackendGroup
Bases: aiida.orm.implementation.entities.BackendEntity, aiida.orm.implementation.entities.BackendEntityExtrasMixin
aiida.orm.implementation.entities.BackendEntityExtrasMixin
An AiiDA ORM implementation of group of nodes.
__int__
Convert the class to an integer. This is needed to allow querying with Django. Be careful, though, not to pass it to a wrong field! This only returns the local DB principal key (pk) value.
the integer pk of the node or None if not stored.
__repr__
Return repr(self).
__str__
Return str(self).
add_nodes
Add a set of nodes to the group.
all the nodes and the group itself have to be stored.
nodes – a list of BackendNode instances to be added to this group
clear
Remove all the nodes from this group.
count
Return the number of entities in this group.
integer number of entities contained within the group
Create and store a new group.
Note: This method does not check for presence of the group. You may want to use get_or_create().
group
the description of the group as a string
get_or_create
Try to retrieve a group from the DB with the given arguments; create (and store) a new group if such a group was not present yet.
(group, created) where group is the group (new or existing, in any case already stored) and created is a boolean saying
id
the principal key (the ID) as an integer, or None if the node was not stored yet
Return whether the group is stored.
boolean, True if the group is stored, False otherwise
label
the name of the group as a string
Return a generator/iterator that iterates over all nodes and returns the respective AiiDA subclasses of Node, and also allows to ask for the number of nodes in the group using len().
remove_nodes
Remove a set of nodes from the group.
nodes – a list of BackendNode instances to be removed from this group
store
Store this entity in the backend.
Whether it is possible to call store more than once is delegated to the object itself
type_string
the string defining the type of the group
a backend user object, representing the user associated to this group.
aiida.orm.implementation.BackendUser
a string with the uuid
BackendGroupCollection
The collection of Group entries.
alias of BackendGroup
Delete a group with the given id
id – the id of the group to delete
Get the group matching the given filters
filters – the attributes of the group to get
the group
aiida.orm.implementation.BackendGroup
Query for groups.
By default, query for user-defined groups only (type_string==””). If you want to query for all type of groups, pass type_string=None. If you want to query for a specific type of groups, pass a specific string as the type_string argument.
name – the name of the group
nodes – a node or list of nodes that belongs to the group (alternatively, you can also pass a DbNode or list of DbNodes)
pk – the pk of the group
uuid – the uuid of the group
type_string – the string for the type of node; by default, look only for user-defined groups (see note above).
user – by default, query for groups of all users; if specified, must be a DbUser object, or a string for the user email.
past_days – by default, query for all groups; if specified, query the groups created in the last past_days. Must be a datetime object.
name_filters – dictionary that can contain ‘startswith’, ‘endswith’ or ‘contains’ as keys
node_attributes – if not None, must be a dictionary with format {k: v}. It will filter and return only groups where there is at least a node with an attribute with key=k and value=v. Different keys of the dictionary are joined with AND (that is, the group should satisfy all requirements. v can be a base data type (str, bool, int, float, …) If it is a list or iterable, that the condition is checked so that there should be at least a node in the group with key=k and value=each of the values of the iterable.
kwargs –
any other filter to be passed to DbGroup.objects.filter
node_attributes = {'elements': ['Ba', 'Ti'], 'md5sum': 'xxx'}
it will find groups that contain the node with md5sum = ‘xxx’, and moreover contain at least one node for element ‘Ba’ and one node for element ‘Ti’.
BackendLog
Backend Log interface
dbnode_id
Get the id of the object that created the log entry
The id of the object that created the log entry
int
levelname
The name of the log level
The entry log level name
str
loggername
The name of the logger that created this entry
The entry loggername
message
Get the message corresponding to the entry
The entry message
metadata
Get the metadata corresponding to the entry
The entry metadata
dict
time
Get the time corresponding to the entry
The entry timestamp
datetime.datetime
Get the UUID of the log entry
The entry’s UUID
uuid.UUID
BackendLogCollection
The collection of Log entries.
alias of BackendLog
Remove a Log entry from the collection with the given id
log_id (int) – id of the Log to delete
TypeError – if log_id is not an int
log_id
NotExistent – if Log with ID log_id is not found
Delete all Log entries.
IntegrityError – if all Logs could not be deleted
Delete Logs based on filters
(former) PK s of deleted Logs
BackendNode
Bases: aiida.orm.implementation.entities.BackendEntity, aiida.orm.implementation.entities.BackendEntityExtrasMixin, aiida.orm.implementation.entities.BackendEntityAttributesMixin
aiida.orm.implementation.entities.BackendEntityAttributesMixin
Wrapper around a DbNode instance to set and retrieve data independent of the database implementation.
add_incoming
Add a link of the given type from a given node to ourself.
source – the node from which the link is coming
link_type – the link type
link_label – the link label
True if the proposed link is allowed, False otherwise
TypeError – if source is not a Node instance or link_type is not a LinkType enum
ValueError – if the proposed link is invalid
clone
Return an unstored clone of ourselves.
an unstored BackendNode with the exact same attributes and extras as self
Return the computer of this node.
the computer or None
BackendComputer or None
Return the node ctime.
the ctime
Return the node description.
the description
Return the node label.
the label
Return the node mtime.
the mtime
node_type
Return the node type.
the node type
process_type
Return the node process type.
the process type
Store the node in the database.
links – optional links to add before storing
with_transaction – if False, do not use a transaction because the caller will already have opened one.
clean – boolean, if True, will clean the attributes and extras before attempting to store
Return the user of this node.
the user
BackendUser
Return the node UUID.
the string representation of the UUID
str or None
BackendNodeCollection
The collection of BackendNode entries.
alias of BackendNode
Remove a Node entry from the collection with the given id
pk – id of the node to delete
Return a Node entry from the collection with the given id
pk – id of the node
BackendQueryBuilder
Bases: object
object
Backend query builder interface
AiidaNode
A property, decorated with @property. Returns the implementation for the AiiDA-class for Node
AuthInfo
A property, decorated with @property. Returns the implementation for the AuthInfo
Comment
A property, decorated with @property. Returns the implementation for the Comment
Computer
A property, decorated with @property. Returns the implementation for the Computer
Group
A property, decorated with @property. Returns the implementation for the Group
Link
A property, decorated with @property. Returns the implementation for the DbLink
Log
A property, decorated with @property. Returns the implementation for the Log
Node
Decorated as a property, returns the implementation for DbNode. It needs to return a subclass of sqlalchemy.Base, which means that for different ORM’s a corresponding dummy-model must be written.
User
A property, decorated with @property. Returns the implementation for the User
__init__
backend – the backend
the number of results
first
Executes query in the backend asking for one instance.
One row of aiida results
get_aiida_res
Some instance returned by ORM (django or SA) need to be converted to AiiDA instances (eg nodes). Choice (sqlalchemy_utils) will return their value
res – the result returned by the query
an aiida-compatible instance
get_column
Return the column for a given projection.
get_column_names
Return the column names of the given table (alias).
get_corresponding_properties
This method returns a list of updated properties for a given list of properties. If there is no update for the property, the given property is returned in the list.
get_corresponding_property
This method returns an updated property for a given a property. If there is no update for the property, the given property is returned.
get_filter_expr_from_attributes
Returns an valid SQLAlchemy expression.
operator – The operator provided by the user (‘==’, ‘>’, …)
value – The value to compare with, e.g. (5.0, ‘foo’, [‘a’,’b’])
attr_key (str) – The path to that attribute as a tuple of values. I.e. if that attribute I want to filter by is the 2nd element in a list stored under the key ‘mylist’, this is (‘mylist’, ‘2’).
column – Optional, an instance of sqlalchemy.orm.attributes.InstrumentedAttribute or
column_name (str) – The name of the column, and the backend should get the InstrumentedAttribute.
alias – The aliased class.
An instance of sqlalchemy.sql.elements.BinaryExpression
get_filter_expr_from_column
A method that returns an valid SQLAlchemy expression.
column – an instance of sqlalchemy.orm.attributes.InstrumentedAttribute or
get_projectable_attribute
An attribute store in a JSON field of the give column
a valid session, an instance of sqlalchemy.orm.session.Session
get_table_name
Returns the table name given an Aliased class.
inner_to_outer_schema
iterall
An iterator over all the results of a list of lists.
iterdict
An iterator over all the results of a list of dictionaries.
modify_expansions
Modify names of projections if ** was specified. This is important for the schema having attributes in a different table.
outer_to_inner_schema
table_groups_nodes
A property, decorated with @property. Returns the implementation for the many-to-many relationship between group and nodes.
yield_per
batch_size (int) – Number of rows to yield per step
Yields count rows at a time
a generator
This is the base class for User information in AiiDA. An implementing backend needs to provide a concrete version.
REQUIRED_FIELDS
email
Get the email address of the user
the email address
first_name
Get the user’s first name
the first name
institution
Get the user’s institution
the institution
last_name
Get the user’s last name
the last name
For now users do not have UUIDs so always return false
None
BackendUserCollection
alias of BackendUser
Module for the backend implementation of the AuthInfo ORM class.
aiida.orm.implementation.authinfos.
Generic backend related objects
aiida.orm.implementation.backends.
Module for comment backend classes.
aiida.orm.implementation.comments.
Backend specific computer objects and methods
aiida.orm.implementation.computers.
Classes and methods for backend non-specific entities
aiida.orm.implementation.entities.
BackendCollection
Bases: typing.Generic
typing.Generic
Container class that represents a collection of entries of a particular backend entity.
backend (aiida.orm.implementation.Backend) – the backend this collection belongs to
aiida.orm.implementation.Backend
backend
Return the backend.
Create new a entry and set the attributes to those specified in the keyword arguments
the newly created entry of type ENTITY_CLASS
from_dbmodel
Create an entity from the backend dbmodel
dbmodel – the dbmodel to create the entity from
the entity instance
BackendEntity
An first-class entity in the backend
Initialize self. See help(type(self)) for accurate signature.
_flush_if_stored
Return the backend this entity belongs to
the backend instance
dbmodel
Return the id for this entity.
This is unique only amongst entities of this type for a particular backend.
the entity id
Return whether the entity is stored.
pk
BackendEntityAttributesMixin
Mixin class that adds all methods for the attributes column to a backend entity
Flush the fields
attributes
Return the complete attributes dictionary.
Warning
While the entity is unstored, this will return references of the attributes on the database model, meaning that changes on the returned values (if they are mutable themselves, e.g. a list or dictionary) will automatically be reflected on the database model as well. As soon as the entity is stored, the returned attributes will be a deep copy and mutations of the database attributes will have to go through the appropriate set methods. Therefore, once stored, retrieving a deep copy can be a heavy operation. If you only need the keys or some values, use the iterators attributes_keys and attributes_items, or the getters get_attribute and get_attribute_many instead.
the attributes as a dictionary
attributes_items
Return an iterator over the attributes.
an iterator with attribute key value pairs
attributes_keys
Return an iterator over the attribute keys.
an iterator with attribute keys
clear_attributes
Delete all attributes.
delete_attribute
Delete an attribute.
key – name of the attribute
AttributeError – if the attribute does not exist
delete_attribute_many
Delete multiple attributes.
keys – names of the attributes to delete
AttributeError – if at least one of the attribute does not exist
get_attribute
Return the value of an attribute.
While the entity is unstored, this will return a reference of the attribute on the database model, meaning that changes on the returned value (if they are mutable themselves, e.g. a list or dictionary) will automatically be reflected on the database model as well. As soon as the entity is stored, the returned attribute will be a deep copy and mutations of the database attributes will have to go through the appropriate set methods.
the value of the attribute
get_attribute_many
Return the values of multiple attributes.
keys – a list of attribute names
a list of attribute values
AttributeError – if at least one attribute does not exist
reset_attributes
Reset the attributes.
Note
This will completely clear any existing attributes and replace them with the new dictionary.
attributes – a dictionary with the attributes to set
set_attribute
Set an attribute to the given value.
value – value of the attribute
set_attribute_many
Set multiple attributes.
This will override any existing attributes that are present in the new dictionary.
BackendEntityExtrasMixin
Mixin class that adds all methods for the extras column to a backend entity
clear_extras
Delete all extras.
delete_extra
Delete an extra.
key – name of the extra
AttributeError – if the extra does not exist
delete_extra_many
Delete multiple extras.
keys – names of the extras to delete
AttributeError – if at least one of the extra does not exist
extras
Return the complete extras dictionary.
While the entity is unstored, this will return references of the extras on the database model, meaning that changes on the returned values (if they are mutable themselves, e.g. a list or dictionary) will automatically be reflected on the database model as well. As soon as the entity is stored, the returned extras will be a deep copy and mutations of the database extras will have to go through the appropriate set methods. Therefore, once stored, retrieving a deep copy can be a heavy operation. If you only need the keys or some values, use the iterators extras_keys and extras_items, or the getters get_extra and get_extra_many instead.
the extras as a dictionary
extras_items
Return an iterator over the extras.
an iterator with extra key value pairs
extras_keys
Return an iterator over the extra keys.
an iterator with extra keys
get_extra
Return the value of an extra.
While the entity is unstored, this will return a reference of the extra on the database model, meaning that changes on the returned value (if they are mutable themselves, e.g. a list or dictionary) will automatically be reflected on the database model as well. As soon as the entity is stored, the returned extra will be a deep copy and mutations of the database extras will have to go through the appropriate set methods.
the value of the extra
get_extra_many
Return the values of multiple extras.
keys – a list of extra names
a list of extra values
AttributeError – if at least one extra does not exist
reset_extras
Reset the extras.
This will completely clear any existing extras and replace them with the new dictionary.
extras – a dictionary with the extras to set
set_extra
Set an extra to the given value.
value – value of the extra
set_extra_many
Set multiple extras.
This will override any existing extras that are present in the new dictionary.
Backend group module
aiida.orm.implementation.groups.
aiida.orm.implementation.logs.
Abstract BackendNode and BackendNodeCollection implementation.
aiida.orm.implementation.nodes.
Abstract QueryBuilder definition.
Note that this abstract class actually contains parts of the implementation, which are tightly coupled to SqlAlchemy. This is done because currently, both database backend implementations, both Django and SqlAlchemy, directly use the SqlAlchemy library to implement the query builder. If there ever is another database backend to be implemented that does not go through SqlAlchemy, this class will have to be refactored. The SqlAlchemy specific implementations should most likely be moved to a SqlAlchemyBasedQueryBuilder class and restore this abstract class to being a pure agnostic one.
aiida.orm.implementation.querybuilder.
Backend user
aiida.orm.implementation.users.
Utility methods for backend non-specific implementations.
aiida.orm.implementation.utils.
clean_value
Get value from input and (recursively) replace, if needed, all occurrences of BaseType AiiDA data nodes with their value, and List with a standard list. It also makes a deep copy of everything The purpose of this function is to convert data to a type which can be serialized and deserialized for storage in the DB without its value changing.
Note however that there is no logic to avoid infinite loops when the user passes some perverse recursive dictionary or list. In any case, however, this would not be storable by AiiDA…
value – A value to be set as an attribute or an extra
a “cleaned” value, potentially identical to value, but with values replaced where needed.
validate_attribute_extra_key
Validate the key for an entity attribute or extra.
aiida.common.ValidationError – if the key is not a string or contains reserved separator character