dantro.containers.general module

This module implements general specialisations of the BaseDataContainer

class dantro.containers.general.ObjectContainer(*, name: str, data, attrs=None)[source]

Bases: dantro.mixins.base.ItemAccessMixin, dantro.base.BaseDataContainer

Generically stores any Python object

This allows item access, but not more.

_format_info() → str[source]

A __format__ helper function: returns info about the stored data

_ATTRS_CLS

alias of dantro.base.BaseDataAttrs

__delitem__(key)

Deletes an item

__format__(spec_str: str) → str

Creates a formatted string from the given specification.

Invokes further methods which are prefixed by _format_.

__getitem__(key)

Returns an item.

__init__(*, name: str, data, attrs=None)

Initialize a BaseDataContainer, which can store data and attributes.

Parameters

  • name (str) – The name of this data container

  • data – The data to store in this container

  • attrs (None, optional) – A mapping that is stored as attributes

__repr__() → str

Same as __str__

__setitem__(key, val)

Sets an item.

__sizeof__() → int

Returns the size of the data (in bytes) stored in this container’s data and its attributes.

Note that this value is approximate. It is computed by calling the sys.getsizeof function on the data, the attributes, the name and some caching attributes that each dantro data tree class contains. Importantly, this is not a recursive algorithm.

Also, derived classes might implement further attributes that are not taken into account either. To be more precise in a subclass, create a specific __sizeof__ method and invoke this parent method additionally.

For more information, see the documentation of sys.getsizeof:

__str__() → str

An info string, that describes the object. This invokes the formatting helpers to show the log string (type and name) as well as the info string of this object.

_abc_impl = <_abc_data object>
_attrs = None
_check_data(data: Any) → None

This method can be used to check the data provided to this container

It is called before the data is stored in the __init__ method and should raise an exception or create a warning if the data is not as desired.

This method can be subclassed to implement more specific behaviour. To propagate the parent classes’ behaviour the subclassed method should always call its parent method using super().

NOTE The CheckDataMixin provides a generalised implementation of this

method to perform some type checks and react to unexpected types.

Parameters

data (Any) – The data to check

_check_name(new_name: str) → None

Called from name.setter and can be used to check the name that the container is supposed to have. On invalid name, this should raise.

This method can be subclassed to implement more specific behaviour. To propagate the parent classes’ behaviour the subclassed method should always call its parent method using super().

Parameters

new_name (str) – The new name, which is to be checked.

_format_cls_name() → str

A __format__ helper function: returns the class name

_format_logstr() → str

A __format__ helper function: returns the log string, a combination of class name and name

_format_name() → str

A __format__ helper function: returns the name

_format_path() → str

A __format__ helper function: returns the path to this container

_item_access_convert_list_key(key)

If given something that is not a list, just return that key

property attrs

The container attributes.

property classname

Returns the name of this DataContainer-derived class

property data

The stored data.

property logstr

Returns the classname and name of this object; a combination often used in logging…

property name

The name of this DataContainer-derived object.

property parent

The associated parent of this container or group

property path

The path to get to this container or group from some root path

class dantro.containers.general.PassthroughContainer(*, name: str, data, attrs=None)[source]

Bases: dantro.mixins.general.ForwardAttrsToDataMixin, dantro.containers.general.ObjectContainer

An object container that forwards all attribute calls to .data

FORWARD_ATTR_EXCLUDE = ()
FORWARD_ATTR_ONLY = None
FORWARD_ATTR_TO = 'data'
_ATTRS_CLS

alias of dantro.base.BaseDataAttrs

__delitem__(key)

Deletes an item

__format__(spec_str: str) → str

Creates a formatted string from the given specification.

Invokes further methods which are prefixed by _format_.

__getattr__(attr_name: str)

Forward attributes that were not available in this class to some other attribute of the group or container.

Parameters

attr_name (str) – The name of the attribute that was tried to be accessed but was not available in self.

Returns

The attribute attr_name of getattr(self, self.FORWARD_ATTR_TO)

__getitem__(key)

Returns an item.

__init__(*, name: str, data, attrs=None)

Initialize a BaseDataContainer, which can store data and attributes.

Parameters

  • name (str) – The name of this data container

  • data – The data to store in this container

  • attrs (None, optional) – A mapping that is stored as attributes

__repr__() → str

Same as __str__

__setitem__(key, val)

Sets an item.

__sizeof__() → int

Returns the size of the data (in bytes) stored in this container’s data and its attributes.

Note that this value is approximate. It is computed by calling the sys.getsizeof function on the data, the attributes, the name and some caching attributes that each dantro data tree class contains. Importantly, this is not a recursive algorithm.

Also, derived classes might implement further attributes that are not taken into account either. To be more precise in a subclass, create a specific __sizeof__ method and invoke this parent method additionally.

For more information, see the documentation of sys.getsizeof:

__str__() → str

An info string, that describes the object. This invokes the formatting helpers to show the log string (type and name) as well as the info string of this object.

_abc_impl = <_abc_data object>
_attrs = None
_check_data(data: Any) → None

This method can be used to check the data provided to this container

It is called before the data is stored in the __init__ method and should raise an exception or create a warning if the data is not as desired.

This method can be subclassed to implement more specific behaviour. To propagate the parent classes’ behaviour the subclassed method should always call its parent method using super().

NOTE The CheckDataMixin provides a generalised implementation of this

method to perform some type checks and react to unexpected types.

Parameters

data (Any) – The data to check

_check_name(new_name: str) → None

Called from name.setter and can be used to check the name that the container is supposed to have. On invalid name, this should raise.

This method can be subclassed to implement more specific behaviour. To propagate the parent classes’ behaviour the subclassed method should always call its parent method using super().

Parameters

new_name (str) – The new name, which is to be checked.

_format_cls_name() → str

A __format__ helper function: returns the class name

_format_info() → str

A __format__ helper function: returns info about the stored data

_format_logstr() → str

A __format__ helper function: returns the log string, a combination of class name and name

_format_name() → str

A __format__ helper function: returns the name

_format_path() → str

A __format__ helper function: returns the path to this container

_forward_attr_get_forwarding_target()

Get the object that the attribute call is to be forwarded to

_forward_attr_post_hook(attr)

Invoked before attribute forwarding occurs

_forward_attr_pre_hook(attr_name: str = None)

Invoked before attribute forwarding occurs

_item_access_convert_list_key(key)

If given something that is not a list, just return that key

property attrs

The container attributes.

property classname

Returns the name of this DataContainer-derived class

property data

The stored data.

property logstr

Returns the classname and name of this object; a combination often used in logging…

property name

The name of this DataContainer-derived object.

property parent

The associated parent of this container or group

property path

The path to get to this container or group from some root path

class dantro.containers.general.MutableSequenceContainer(*, name: str, data, attrs=None)[source]

Bases: dantro.mixins.base.CheckDataMixin, dantro.mixins.base.ItemAccessMixin, dantro.mixins.base.CollectionMixin, dantro.base.BaseDataContainer, collections.abc.MutableSequence

The MutableSequenceContainer stores data that is sequence-like

DATA_EXPECTED_TYPES = (<class 'collections.abc.MutableSequence'>, <class 'list'>)
DATA_ALLOW_PROXY = False
DATA_UNEXPECTED_ACTION = 'warn'
insert(idx: int, val) → None[source]

Insert an item at a given position. The first argument is the index of the element before which to insert, so a.insert(0, x) inserts at the front of the list, and a.insert(len(a), x) is equivalent to a.append(x).

Parameters

  • idx (int) – The index before which to insert

  • val – The value to insert

_ATTRS_CLS

alias of dantro.base.BaseDataAttrs

__contains__(key) → bool

Whether the given key is contained in the items.

__delitem__(key)

Deletes an item

__format__(spec_str: str) → str

Creates a formatted string from the given specification.

Invokes further methods which are prefixed by _format_.

__getitem__(key)

Returns an item.

__init__(*, name: str, data, attrs=None)

Initialize a BaseDataContainer, which can store data and attributes.

Parameters

  • name (str) – The name of this data container

  • data – The data to store in this container

  • attrs (None, optional) – A mapping that is stored as attributes

__iter__()

Iterates over the items.

__len__() → int

The number of items.

__repr__() → str

Same as __str__

__setitem__(key, val)

Sets an item.

__sizeof__() → int

Returns the size of the data (in bytes) stored in this container’s data and its attributes.

Note that this value is approximate. It is computed by calling the sys.getsizeof function on the data, the attributes, the name and some caching attributes that each dantro data tree class contains. Importantly, this is not a recursive algorithm.

Also, derived classes might implement further attributes that are not taken into account either. To be more precise in a subclass, create a specific __sizeof__ method and invoke this parent method additionally.

For more information, see the documentation of sys.getsizeof:

__str__() → str

An info string, that describes the object. This invokes the formatting helpers to show the log string (type and name) as well as the info string of this object.

_abc_impl = <_abc_data object>
_attrs = None
_check_data(data) → None

A general method to check the received data for its type

Parameters

data – The data to check

Raises

  • TypeError – If the type was unexpected and the action was ‘raise’

  • ValueError – Illegal value for DATA_UNEXPECTED_ACTION class variable

Returns

None

_check_name(new_name: str) → None

Called from name.setter and can be used to check the name that the container is supposed to have. On invalid name, this should raise.

This method can be subclassed to implement more specific behaviour. To propagate the parent classes’ behaviour the subclassed method should always call its parent method using super().

Parameters

new_name (str) – The new name, which is to be checked.

_format_cls_name() → str

A __format__ helper function: returns the class name

_format_info() → str

A __format__ helper function: returns info about the content of this data container.

_format_logstr() → str

A __format__ helper function: returns the log string, a combination of class name and name

_format_name() → str

A __format__ helper function: returns the name

_format_path() → str

A __format__ helper function: returns the path to this container

_item_access_convert_list_key(key)

If given something that is not a list, just return that key

append(value)

S.append(value) – append value to the end of the sequence

property attrs

The container attributes.

property classname

Returns the name of this DataContainer-derived class

clear() → None -- remove all items from S
count(value) → integer -- return number of occurrences of value
property data

The stored data.

extend(values)

S.extend(iterable) – extend sequence by appending elements from the iterable

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

property logstr

Returns the classname and name of this object; a combination often used in logging…

property name

The name of this DataContainer-derived object.

property parent

The associated parent of this container or group

property path

The path to get to this container or group from some root path

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

class dantro.containers.general.MutableMappingContainer(*, name: str, data=None, **dc_kwargs)[source]

Bases: dantro.mixins.base.CheckDataMixin, dantro.mixins.base.MappingAccessMixin, dantro.base.BaseDataContainer, collections.abc.MutableMapping

The MutableMappingContainer stores mutable mapping data, e.g. dicts

DATA_EXPECTED_TYPES = (<class 'collections.abc.MutableMapping'>, <class 'dict'>)
DATA_ALLOW_PROXY = False
DATA_UNEXPECTED_ACTION = 'warn'
__init__(*, name: str, data=None, **dc_kwargs)[source]

Initialize a MutableMappingContainer, storing mapping data.

Parameters

  • name (str) – The name of this container

  • data – The mapping-like data to store. If not given, an empty dict is created

  • **dc_kwargs – Additional arguments for container initialization

_ATTRS_CLS

alias of dantro.base.BaseDataAttrs

_MutableMapping__marker = <object object>
__contains__(key) → bool

Whether the given key is contained in the items.

__delitem__(key)

Deletes an item

__format__(spec_str: str) → str

Creates a formatted string from the given specification.

Invokes further methods which are prefixed by _format_.

__getitem__(key)

Returns an item.

__iter__()

Iterates over the items.

__len__() → int

The number of items.

__repr__() → str

Same as __str__

__setitem__(key, val)

Sets an item.

__sizeof__() → int

Returns the size of the data (in bytes) stored in this container’s data and its attributes.

Note that this value is approximate. It is computed by calling the sys.getsizeof function on the data, the attributes, the name and some caching attributes that each dantro data tree class contains. Importantly, this is not a recursive algorithm.

Also, derived classes might implement further attributes that are not taken into account either. To be more precise in a subclass, create a specific __sizeof__ method and invoke this parent method additionally.

For more information, see the documentation of sys.getsizeof:

__str__() → str

An info string, that describes the object. This invokes the formatting helpers to show the log string (type and name) as well as the info string of this object.

_abc_impl = <_abc_data object>
_attrs = None
_check_data(data) → None

A general method to check the received data for its type

Parameters

data – The data to check

Raises

  • TypeError – If the type was unexpected and the action was ‘raise’

  • ValueError – Illegal value for DATA_UNEXPECTED_ACTION class variable

Returns

None

_check_name(new_name: str) → None

Called from name.setter and can be used to check the name that the container is supposed to have. On invalid name, this should raise.

This method can be subclassed to implement more specific behaviour. To propagate the parent classes’ behaviour the subclassed method should always call its parent method using super().

Parameters

new_name (str) – The new name, which is to be checked.

_format_cls_name() → str

A __format__ helper function: returns the class name

_format_info() → str

A __format__ helper function: returns info about the content of this data container.

_format_logstr() → str

A __format__ helper function: returns the log string, a combination of class name and name

_format_name() → str

A __format__ helper function: returns the name

_format_path() → str

A __format__ helper function: returns the path to this container

_item_access_convert_list_key(key)

If given something that is not a list, just return that key

property attrs

The container attributes.

property classname

Returns the name of this DataContainer-derived class

clear() → None. Remove all items from D.
property data

The stored data.

get(key, default=None)

Return the value at key, or default if key is not available.

items()

Returns an iterator over the (keys, values) tuple of the attributes.

keys()

Returns an iterator over the attribute names.

property logstr

Returns the classname and name of this object; a combination often used in logging…

property name

The name of this DataContainer-derived object.

property parent

The associated parent of this container or group

property path

The path to get to this container or group from some root path

pop(k[, d]) → v, remove specified key and return the corresponding value.

If key is not found, d is returned if given, otherwise KeyError is raised.

popitem() → (k, v), remove and return some (key, value) pair

as a 2-tuple; but raise KeyError if D is empty.

setdefault(k[, d]) → D.get(k,d), also set D[k]=d if k not in D
update([E, ]**F) → None. Update D from mapping/iterable E and F.

If E present and has a .keys() method, does: for k in E: D[k] = E[k] If E present and lacks .keys() method, does: for (k, v) in E: D[k] = v In either case, this is followed by: for k, v in F.items(): D[k] = v

values()

Returns an iterator over the attribute values.

class dantro.containers.general.StringContainer(*, name: str, data, attrs=None)[source]

Bases: dantro.mixins.base.CollectionMixin, dantro.containers.general.PassthroughContainer

A data container to store string-like data.

DATA_EXPECTED_TYPES = (<class 'str'>,)
DATA_ALLOW_PROXY = False
DATA_UNEXPECTED_ACTION = 'raise'
FORWARD_ATTR_EXCLUDE = ()
FORWARD_ATTR_ONLY = None
FORWARD_ATTR_TO = 'data'
_ATTRS_CLS

alias of dantro.base.BaseDataAttrs

__contains__(key) → bool

Whether the given key is contained in the items.

__delitem__(key)

Deletes an item

__format__(spec_str: str) → str

Creates a formatted string from the given specification.

Invokes further methods which are prefixed by _format_.

__getattr__(attr_name: str)

Forward attributes that were not available in this class to some other attribute of the group or container.

Parameters

attr_name (str) – The name of the attribute that was tried to be accessed but was not available in self.

Returns

The attribute attr_name of getattr(self, self.FORWARD_ATTR_TO)

__getitem__(key)

Returns an item.

__init__(*, name: str, data, attrs=None)

Initialize a BaseDataContainer, which can store data and attributes.

Parameters

  • name (str) – The name of this data container

  • data – The data to store in this container

  • attrs (None, optional) – A mapping that is stored as attributes

__iter__()

Iterates over the items.

__len__() → int

The number of items.

__repr__() → str

Same as __str__

__setitem__(key, val)

Sets an item.

__sizeof__() → int

Returns the size of the data (in bytes) stored in this container’s data and its attributes.

Note that this value is approximate. It is computed by calling the sys.getsizeof function on the data, the attributes, the name and some caching attributes that each dantro data tree class contains. Importantly, this is not a recursive algorithm.

Also, derived classes might implement further attributes that are not taken into account either. To be more precise in a subclass, create a specific __sizeof__ method and invoke this parent method additionally.

For more information, see the documentation of sys.getsizeof:

__str__() → str

An info string, that describes the object. This invokes the formatting helpers to show the log string (type and name) as well as the info string of this object.

_abc_impl = <_abc_data object>
_attrs = None
_check_data(data: Any) → None

This method can be used to check the data provided to this container

It is called before the data is stored in the __init__ method and should raise an exception or create a warning if the data is not as desired.

This method can be subclassed to implement more specific behaviour. To propagate the parent classes’ behaviour the subclassed method should always call its parent method using super().

NOTE The CheckDataMixin provides a generalised implementation of this

method to perform some type checks and react to unexpected types.

Parameters

data (Any) – The data to check

_check_name(new_name: str) → None

Called from name.setter and can be used to check the name that the container is supposed to have. On invalid name, this should raise.

This method can be subclassed to implement more specific behaviour. To propagate the parent classes’ behaviour the subclassed method should always call its parent method using super().

Parameters

new_name (str) – The new name, which is to be checked.

_format_cls_name() → str

A __format__ helper function: returns the class name

_format_info() → str

A __format__ helper function: returns info about the stored data

_format_logstr() → str

A __format__ helper function: returns the log string, a combination of class name and name

_format_name() → str

A __format__ helper function: returns the name

_format_path() → str

A __format__ helper function: returns the path to this container

_forward_attr_get_forwarding_target()

Get the object that the attribute call is to be forwarded to

_forward_attr_post_hook(attr)

Invoked before attribute forwarding occurs

_forward_attr_pre_hook(attr_name: str = None)

Invoked before attribute forwarding occurs

_item_access_convert_list_key(key)

If given something that is not a list, just return that key

property attrs

The container attributes.

property classname

Returns the name of this DataContainer-derived class

property data

The stored data.

property logstr

Returns the classname and name of this object; a combination often used in logging…

property name

The name of this DataContainer-derived object.

property parent

The associated parent of this container or group

property path

The path to get to this container or group from some root path