aiida.tools.groups package#

Provides tools for interacting with AiiDA Groups.

Submodules#

Provides functionality for managing large numbers of AiiDA Groups, via label delimitation.

class aiida.tools.groups.paths.GroupAttr(group_path: GroupPath)[source]#

Bases: object

A class to provide attribute access to a GroupPath children.

The only public attributes on this class are dynamically created from the GroupPath child keys. NOTE: any child keys that do not conform to an acceptable (public) attribute string will be ignored. The GroupPath can be retrieved via a function call, e.g.:

group_path = GroupPath()
group_attr = GroupAttr(group_path)
group_attr.a.b.c() == GroupPath("a/b/c")

__call__() → GroupPath[source]#: Return the GroupPath.

__dict__ = mappingproxy({'__module__': 'aiida.tools.groups.paths', '__doc__': 'A class to provide attribute access to a ``GroupPath`` children.\n\n The only public attributes on this class are dynamically created from the ``GroupPath`` child keys.\n NOTE: any child keys that do not conform to an acceptable (public) attribute string will be ignored.\n The ``GroupPath`` can be retrieved *via* a function call, e.g.::\n\n group_path = GroupPath()\n group_attr = GroupAttr(group_path)\n group_attr.a.b.c() == GroupPath("a/b/c")\n\n ', '__init__': <function GroupAttr.__init__>, '__repr__': <function GroupAttr.__repr__>, '__call__': <function GroupAttr.__call__>, '__dir__': <function GroupAttr.__dir__>, '__getattr__': <function GroupAttr.__getattr__>, '__dict__': <attribute '__dict__' of 'GroupAttr' objects>, '__weakref__': <attribute '__weakref__' of 'GroupAttr' objects>, '__annotations__': {}})#

__dir__()[source]#: Return a list of available attributes.

__getattr__(attr) → GroupAttr[source]#: Return the requested attribute name.

__init__(group_path: GroupPath) → None[source]#: Instantiate the GroupPath, and a mapping of its children.

__module__ = 'aiida.tools.groups.paths'#

__repr__() → str[source]#: Represent the instantiated class.

__weakref__#: list of weak references to the object

exception aiida.tools.groups.paths.GroupNotFoundError(grouppath)[source]#

Bases: Exception

An exception raised when a path does not have an associated group.

__init__(grouppath)[source]#

__module__ = 'aiida.tools.groups.paths'#

__weakref__#: list of weak references to the object

exception aiida.tools.groups.paths.GroupNotUniqueError(grouppath)[source]#

Bases: Exception

An exception raised when a path has multiple associated groups.

__init__(grouppath)[source]#

__module__ = 'aiida.tools.groups.paths'#

__weakref__#: list of weak references to the object

class aiida.tools.groups.paths.GroupPath(path: str = '', cls: ~aiida.orm.groups.Group = <class 'aiida.orm.groups.Group'>, warn_invalid_child: bool = True)[source]#

Bases: object

A class to provide label delimited access to groups.

See tests for usage examples.

__contains__(key: str) → bool[source]#: Return whether a child exists for this key.

__dict__ = mappingproxy({'__module__': 'aiida.tools.groups.paths', '__doc__': 'A class to provide label delimited access to groups.\n\n See tests for usage examples.\n ', '__init__': <function GroupPath.__init__>, '_validate_path': <function GroupPath._validate_path>, '__repr__': <function GroupPath.__repr__>, '__eq__': <function GroupPath.__eq__>, '__lt__': <function GroupPath.__lt__>, 'path': <property object>, 'path_list': <property object>, 'key': <property object>, 'delimiter': <property object>, 'cls': <property object>, 'parent': <property object>, '__truediv__': <function GroupPath.__truediv__>, '__getitem__': <function GroupPath.__getitem__>, 'get_group': <function GroupPath.get_group>, 'group_ids': <property object>, 'is_virtual': <property object>, 'get_or_create_group': <function GroupPath.get_or_create_group>, 'delete_group': <function GroupPath.delete_group>, 'children': <property object>, '__iter__': <function GroupPath.__iter__>, '__len__': <function GroupPath.__len__>, '__contains__': <function GroupPath.__contains__>, 'walk': <function GroupPath.walk>, 'walk_nodes': <function GroupPath.walk_nodes>, 'browse': <property object>, '__dict__': <attribute '__dict__' of 'GroupPath' objects>, '__weakref__': <attribute '__weakref__' of 'GroupPath' objects>, '__hash__': None, '__gt__': <function _gt_from_lt>, '__le__': <function _le_from_lt>, '__ge__': <function _ge_from_lt>, '__annotations__': {}})#

__eq__(other: Any) → bool[source]#: Compare equality of path and Group subclass to another GroupPath object.

__ge__(other)#: Return a >= b. Computed by @total_ordering from (not a < b).

__getitem__(path: str) → GroupPath[source]#: Return a child GroupPath, with a new path formed by appending path to the current path.

__gt__(other)#: Return a > b. Computed by @total_ordering from (not a < b) and (a != b).

__hash__ = None#

__init__(path: str = '', cls: ~aiida.orm.groups.Group = <class 'aiida.orm.groups.Group'>, warn_invalid_child: bool = True) → None[source]#

Instantiate the class.

Parameters:

path – The initial path of the group.
cls – The subclass of Group to operate on.
warn_invalid_child – Issue a warning, when iterating children, if a child path is invalid.

__iter__() → Iterator[GroupPath][source]#: Iterate through all (direct) children of this path.

__le__(other)#: Return a <= b. Computed by @total_ordering from (a < b) or (a == b).

__len__() → int[source]#: Return the number of children for this path.

__lt__(other: Any) → bool[source]#: Compare less-than operator of path and Group subclass to another GroupPath object.

__module__ = 'aiida.tools.groups.paths'#

__repr__() → str[source]#: Represent the instantiated class.

__truediv__(path: str) → GroupPath[source]#: Return a child GroupPath, with a new path formed by appending path to the current path.

__weakref__#: list of weak references to the object

_validate_path(path)[source]#: Validate the supplied path.

property browse#: Return a GroupAttr instance, for attribute access to children.

property children: Iterator[GroupPath]#: Iterate through all (direct) children of this path.

property cls: Group#: Return the cls used to query for and instantiate a Group with.

delete_group()[source]#

Delete the concrete group associated with this path.

Raises:: GroupNotFoundError, GroupNotUniqueError

property delimiter: str#: Return the delimiter used to split path into components.

get_group() → GroupPath | None[source]#: Return the concrete group associated with this path.

get_or_create_group() → Tuple[Group, bool][source]#: Return the concrete group associated with this path or, create it, if it does not already exist.

property group_ids: List[int]#

Return all the UUID associated with this GroupPath.

Returns:: and empty list, if no group associated with this label, or can be multiple if cls was None

This is an efficient method for checking existence, which does not require the (slow) loading of the ORM entity.

property is_virtual: bool#: Return whether there is one or more concrete groups associated with this path.

property key: str | None#: Return the final component of the the path.

property parent: GroupPath | None#: Return the parent path.

property path: str#: Return the path string.

property path_list: List[str]#: Return a list of the path components.

walk(return_virtual: bool = True) → Iterator[GroupPath][source]#: Recursively iterate through all children of this path.

walk_nodes(filters: dict | None = None, node_class: Node | None = None, query_batch: int | None = None) → Iterator[WalkNodeResult][source]#

Recursively iterate through all nodes of this path and its children.

Parameters:

filters – filters to apply to the node query
node_class – return only nodes of a certain class (or list of classes)
query_batch – The size of the batches to ask the backend to batch results in subcollections. You can optimize the speed of the query by tuning this parameter. Be aware though that is only safe if no commit will take place during this transaction.

exception aiida.tools.groups.paths.InvalidPath[source]#

Bases: Exception

An exception to indicate that a path is not valid.

__module__ = 'aiida.tools.groups.paths'#

__weakref__#: list of weak references to the object

exception aiida.tools.groups.paths.NoGroupsInPathError(grouppath)[source]#

Bases: Exception

An exception raised when a path has multiple associated groups.

__init__(grouppath)[source]#

__module__ = 'aiida.tools.groups.paths'#

__weakref__#: list of weak references to the object

class aiida.tools.groups.paths.WalkNodeResult(group_path, node)#

Bases: tuple

__getnewargs__()#: Return self as a plain tuple. Used by copy and pickle.

__match_args__ = ('group_path', 'node')#

__module__ = 'aiida.tools.groups.paths'#

static __new__(_cls, group_path, node)#: Create new instance of WalkNodeResult(group_path, node)

__repr__()#: Return a nicely formatted representation string

__slots__ = ()#

_asdict()#: Return a new dict which maps field names to their values.

_field_defaults = {}#

_fields = ('group_path', 'node')#

classmethod _make(iterable)#: Make a new WalkNodeResult object from a sequence or iterable

_replace(**kwds)#: Return a new WalkNodeResult object replacing specified fields with new values

group_path#: Alias for field number 0

node#: Alias for field number 1