dantro.mixins package#

This sub-package provides mixin classes for easily adding functionality to a derived contaier or group class

Submodules#

dantro.mixins.base module#

This sub-module implements the basic mixin classes that are required in the dantro.base module

class AttrsMixin[source]#

Bases: object

This Mixin class supplies the attrs property getter and setter and the private _attrs attribute.

Hereby, the setter function will initialize a BaseDataAttrs -derived object and store it as an attribute. This relays the checking of the correct attribute format to the actual BaseDataAttrs-derived class.

For changing the class that is used for the attributes, an overwrite of the _ATTRS_CLS class variable suffices.

_attrs = None#

The attribute that data attributes will be stored to

_ATTRS_CLS: type = None#

The type of object to use for storing data attributes

property attrs#

The container attributes.

class SizeOfMixin[source]#

Bases: object

Provides the __sizeof__ magic method and attempts to take into account the size of the attributes.

__sizeof__() int[source]#

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.

class LockDataMixin[source]#

Bases: object

This mixin class provides a flag for marking the data of a group or container as locked.

__locked = False#

Whether the data is regarded as locked. Note name-mangling here.

property locked: bool#

Whether this object is locked

lock()[source]#

Locks the data of this object

unlock()[source]#

Unlocks the data of this object

raise_if_locked(*, prefix: Optional[str] = None)[source]#

Raises an exception if this object is locked; does nothing otherwise

_lock_hook()[source]#

Invoked upon locking.

_unlock_hook()[source]#

Invoked upon unlocking.

class BasicComparisonMixin[source]#

Bases: object

Provides a (very basic) __eq__ method to compare equality.

__eq__(other) bool[source]#

Evaluates equality by making the following comparisons: identity, strict type equality, and finally: equality of the _data and _attrs attributes, i.e. the private attribute. This ensures that comparison does not trigger any downstream effects like resolution of proxies.

If types do not match exactly, NotImplemented is returned, thus referring the comparison to the other side of the ==.

class CollectionMixin[source]#

Bases: object

This Mixin class implements the methods needed for being a Collection.

It relays all calls forward to the data attribute.

__contains__(key) bool[source]#

Whether the given key is contained in the items.

__len__() int[source]#

The number of items.

__iter__()[source]#

Iterates over the items.

class ItemAccessMixin[source]#

Bases: object

This Mixin class implements the methods needed for getting, setting, and deleting items. It relays all calls forward to the data attribute, but if given a list (passed down from above), it extracts it.

__getitem__(key)[source]#

Returns an item.

__setitem__(key, val)[source]#

Sets an item.

__delitem__(key)[source]#

Deletes an item

_item_access_convert_list_key(key)[source]#

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

class MappingAccessMixin[source]#

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

Supplies all methods that are needed for Mapping access.

All calls are relayed to the data attribute.

keys()[source]#

Returns an iterator over the data’s keys.

values()[source]#

Returns an iterator over the data’s values.

items()[source]#

Returns an iterator over data’s (key, value) tuples

get(key, default=None)[source]#

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

__contains__(key) bool#

Whether the given key is contained in the items.

__delitem__(key)#

Deletes an item

__getitem__(key)#

Returns an item.

__iter__()#

Iterates over the items.

__len__() int#

The number of items.

__setitem__(key, val)#

Sets an item.

_item_access_convert_list_key(key)#

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

class CheckDataMixin[source]#

Bases: object

This mixin class extends a BaseDataContainer-derived class to check the provided data before storing it in the container.

It implements a general _check_data() method, overwriting the placeholder method in the BaseDataContainer, and can be controlled via class variables.

Note

This is not suitable for checking containers that are added to an object of a BaseDataGroup-derived class!

DATA_EXPECTED_TYPES: tuple = None#

Which types to allow. If None, all types are allowed.

DATA_ALLOW_PROXY: bool = False#

Whether to allow all proxy types, i.e. classes derived from AbstractDataProxy.

DATA_UNEXPECTED_ACTION = 'warn'#

The action to take when an unexpected type was supplied. Can be: raise, warn, ignore.

_check_data(data) None[source]#

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

class DirectInsertionModeMixin[source]#

Bases: object

A mixin class that provides a context manager, within which insertion into the mixed-in class (think: group or container) can happen more directly. This is useful in cases where more assumptions can be made about the to-be-inserted data, thus allowing to make fewer checks during insertion (think: duplicates, key order, etc.).

Note

This direct insertion mode is not (yet) part of the public interface, as it has to be evaluated how robust and error-prone it is.

__in_direct_insertion_mode = False#

A name-mangled state flag that determines the state of the object.

property with_direct_insertion: bool#

Whether the class this mixin is mixed into is currently in direct insertion mode.

_direct_insertion_mode(*, enabled: bool = True)[source]#

A context manager that brings the class this mixin is used in into direct insertion mode. While in that mode, the with_direct_insertion() property will return true.

This context manager additionally invokes two callback functions, which can be specialized to perform certain operations when entering or exiting direct insertion mode: Before entering, _enter_direct_insertion_mode() is called. After exiting, _exit_direct_insertion_mode() is called.

Parameters

enabled (bool, optional) – whether to actually use direct insertion mode. If False, will yield directly without setting the toggle. This is equivalent to a null-context.

_enter_direct_insertion_mode()[source]#

Called after entering direct insertion mode; can be overwritten to attach additional behaviour.

_exit_direct_insertion_mode()[source]#

Called before exiting direct insertion mode; can be overwritten to attach additional behaviour.

dantro.mixins.general module#

This module implements general mixin classes for containers and groups

class ForwardAttrsMixin[source]#

Bases: object

This Mixin class forwards all calls to unavailable attributes to a certain other attribute, specified by FORWARD_ATTR_TO class variable.

By including naive __getstate__ and __setstate__ methods, classes that include this mixin remain pickleable.

FORWARD_ATTR_TO: str = None#

The name of the existing attribute to forward to. For None, this behaves as if no forwarding would occur, i.e. as if __getattr__ was not called.

FORWARD_ATTR_ONLY: Sequence[str] = None#

If set, the only attributes to be forwarded

FORWARD_ATTR_EXCLUDE: Sequence[str] = ()#

Attributes to not forward. Evaluated after FORWARD_ATTR_ONLY

__getstate__() dict[source]#

Returns the object’s __dict__

__setstate__(d: dict)[source]#

Sets the object’s __dict__ to the given one

__getattr__(attr_name: str)[source]#

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)

_forward_attr_pre_hook(attr_name: Optional[str] = None)[source]#

Invoked before attribute forwarding occurs

_forward_attr_get_forwarding_target()[source]#

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

_forward_attr_post_hook(attr)[source]#

Invoked before attribute forwarding occurs

class ForwardAttrsToDataMixin[source]#

Bases: dantro.mixins.general.ForwardAttrsMixin

This mixin class forwards all calls to unavailable attributes to the data attribute (a property) and thus allows to replace most behaviour that is not implemented in the group or container with that of the underlying data.

FORWARD_ATTR_EXCLUDE: Sequence[str] = ()#

Attributes to not forward. Evaluated after FORWARD_ATTR_ONLY

FORWARD_ATTR_ONLY: Sequence[str] = None#

If set, the only attributes to be forwarded

__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)

__getstate__() dict#

Returns the object’s __dict__

__setstate__(d: dict)#

Sets the object’s __dict__ to the given one

_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: Optional[str] = None)#

Invoked before attribute forwarding occurs

FORWARD_ATTR_TO: str = 'data'#

The name of the existing attribute to forward to. For None, this behaves as if no forwarding would occur, i.e. as if __getattr__ was not called.

dantro.mixins.indexing module#

This module implement mixin classes that provide indexing capabilities

class IntegerItemAccessMixin[source]#

Bases: object

This mixin allows accessing items via integer keys and also supports calling the __contains__ magic method with integer keys. It is meant to be used to add features to an AbstractDataGroup-derived class, although this is not enforced.

Note

The __setitem__ method is not covered by this!

Note

The class using this mixin has to implement index access methods and the __contains__ magic method independently from this mixin!

_parse_key(key: Union[str, int]) str[source]#

Makes sure a key is a string

__getitem__(key: Union[str, int])[source]#

Adjusts the parent method to allow integer key item access

__setitem__(key: Union[str, int])[source]#

Adjusts the parent method to allow item setting by integer key

__delitem__(key: Union[str, int])[source]#

Adjusts the parent method to allow item deletion by integer key

__contains__(key: Union[str, int]) bool[source]#

Adjusts the parent method to allow checking for integers

class PaddedIntegerItemAccessMixin[source]#

Bases: dantro.mixins.indexing.IntegerItemAccessMixin

This mixin allows accessing items via integer keys that map to members that have a zero-padded integer name. It can only be used as mixin for AbstractDataGroup-derived classes!

The __contains__ magic method is also supported in this mixin.

Note

The class using this mixin has to implement index access methods and the __contains__ magic method independently from this mixin!

_PADDED_INT_KEY_WIDTH: int = None#

The number of digits of the padded string representing the integer

_PADDED_INT_FSTR: str = None#

The format string to generate a padded integer; deduced upon first call

_PADDED_INT_STRICT_CHECKING: bool = True#

Whether to use strict checking when parsing keys, i.e. check that the range of keys is valid and an error is thrown when an integer key was given that cannot be represented consistently by a padded string of the determined key width.

_PADDED_INT_MAX_VAL: int = None#

The allowed maximum value of an integer key; checked only in strict mode

__contains__(key: Union[str, int]) bool#

Adjusts the parent method to allow checking for integers

__delitem__(key: Union[str, int])#

Adjusts the parent method to allow item deletion by integer key

__getitem__(key: Union[str, int])#

Adjusts the parent method to allow integer key item access

__setitem__(key: Union[str, int])#

Adjusts the parent method to allow item setting by integer key

property padded_int_key_width: Optional[int]#

Returns the width of the zero-padded integer key or None, if it is not already specified.

_parse_key(key: Union[str, int]) str[source]#

Parse a potentially integer key to a zero-padded string

_check_cont(cont: AbstractDataContainer) None[source]#

This method is invoked when adding a member to a group and makes sure the name of the added group is correctly zero-padded.

Also, upon first call, communicates the zero padded integer key width, i.e.: the length of the container name, to the PaddedIntegerItemAccessMixin.

Parameters

cont – The member container to add

Returns

None: No return value needed

dantro.mixins.numeric module#

This module implements mixin classes which provide numeric interfaces for containers

class UnaryOperationsMixin[source]#

Bases: object

This mixin class implements the methods needed for unary operations.

It leaves out those that expect that return values are of a certain type, e.g. __complex__, __int__, …

__neg__()[source]#

Make negative

Returns

A new object with negative elements

__pos__()[source]#

Make positive

Returns

A new object with negative elements

__abs__()[source]#

Absolute value

Returns

A new object with the absolute value of the elements

__invert__()[source]#

Inverse value

Returns

A new object with the inverted values of the elements

__round__()[source]#

Rounds number to nearest integer

Returns

A new object as rounded number to nearest integer

__ceil__()[source]#

Smallest integer

Returns

A new object containing the smallest integer

__floor__()[source]#

Largest integer

Returns

A new object containing the largest element

__trunc__()[source]#

Truncated to the nearest integer toward 0

Returns

A new object containing the truncated element

class NumbersMixin[source]#

Bases: dantro.mixins.numeric.UnaryOperationsMixin

This mixin implements the methods needed for calculating with numbers.

__add__(other)[source]#

Add two objects

Returns

A new object containing the summed data

__sub__(other)[source]#

Subtract two objects

Returns

A new object containing the subtracted data

__mul__(other)[source]#

Multiply two objects

Returns

A object containing the multiplied data

__truediv__(other)[source]#

Divide two objects

Returns

A new object containing the divided data

__floordiv__(other)[source]#

Floor divide two objects

Returns

A new object containing the floor divided data

__mod__(other)[source]#

Calculate the modulo of two objects

Returns

A new object containing the summed data

__divmod__(other)[source]#

Calculate the floor division and modulo of two objects

Returns

A new object containing the floor divided data and its modulo

__pow__(other)[source]#

Calculate the self data to the power of other data

Returns

A new object containing the result

__iadd__(other)[source]#

Add two objects

Returns

Self with modified data

__isub__(other)[source]#

Subtract two objects

Returns

Self with modified data

__imul__(other)[source]#

Multiply two objects

Returns

Self with modified data

__itruediv__(other)[source]#

Divide two objects

Returns

Self with modified data

__ifloordiv__(other)[source]#

Floor divide two objects

Returns

Self with modified data

__imod__(other)[source]#

Calculate the modulo of two objects

Returns

Self with modified data

__ipow__(other)[source]#

Calculate the self data to the power of other data

Returns

Self with modified data

__abs__()#

Absolute value

Returns

A new object with the absolute value of the elements

__ceil__()#

Smallest integer

Returns

A new object containing the smallest integer

__floor__()#

Largest integer

Returns

A new object containing the largest element

__invert__()#

Inverse value

Returns

A new object with the inverted values of the elements

__neg__()#

Make negative

Returns

A new object with negative elements

__pos__()#

Make positive

Returns

A new object with negative elements

__round__()#

Rounds number to nearest integer

Returns

A new object as rounded number to nearest integer

__trunc__()#

Truncated to the nearest integer toward 0

Returns

A new object containing the truncated element

class ComparisonMixin[source]#

Bases: object

This Mixin implements functions to compare objects

__eq__(other)[source]#

Equality

__ne__(other)[source]#

Inequality

__lt__(other)[source]#

Less than

__le__(other)[source]#

Less than or equal

__gt__(other)[source]#

Greater than

__ge__(other)[source]#

Greater than or equal

__bool__()[source]#

Truth value

get_data(obj)[source]#

Get the data of obj depending on whether it is part of dantro or not.

Parameters

obj – The object to check

Returns

Either the .data attribute of a dantro-based object or otherwise

the object itself.

apply_func_to_copy(obj, func, other=None)[source]#

Apply a given function to a copy for all datatypes

Returns

An object with the data on which the function was applied

apply_func_inplace(obj, func, other=None)[source]#

Apply a given function inplace for all data types.

Returns

An object with the data on which the function was applied

dantro.mixins.proxy_support module#

This module implements mixins that provide proxy support

class ProxySupportMixin[source]#

Bases: object

This mixin class overwrites the data property to allow and resolve proxy objects.

It should be used to add support for certain proxy types to a container.

A proxy object is a place holder for data that is not yet loaded. It will only be loaded if the data property is directly or indirectly accessed.

DATA_ALLOW_PROXY = True#
PROXY_RESOLVE_ASTYPE = None#

Which type to resolve the proxy to

PROXY_RETAIN = False#

Whether to retain the proxy object after resolving

PROXY_REINSTATE_FAIL_ACTION = 'raise'#

Behaviour upon failure of reinstating a proxy.

Can be: raise, warn, log_warning, log_debug

PROXY_REINSTATE_FOR_PICKLING = True#

If true, populates the pickling state with the proxy instead of the data

_retained_proxy = None#
__getstate__() dict[source]#

If the data is no longer a proxy, but a proxy was retained, this overload adjusts the pickling state such that the proxy object is returned instead of the data that was resolved from it. This hels to reduce the file size of the pickle.

property data#

The container data. If the data is a proxy, this call will lead to the resolution of the proxy.

Returns

The data stored in this container

property data_is_proxy: bool#

Returns true, if this is proxy data

Returns

Whether the currently stored data is a proxy object

Return type

bool

property proxy: Optional[AbstractDataProxy]#

If the data is proxy, returns the proxy data object without using the .data attribute (which would trigger resolving the proxy); else returns None.

Returns

If the data is proxy, return the

proxy object; else None.

Return type

Union[AbstractDataProxy, None]

reinstate_proxy()[source]#

Re-instate a previously retained proxy object, discarding _data.

_format_info() str[source]#

Adds an indicator to whether data is proxy to the info string. Additionally, the proxy tags are appended.

class Hdf5ProxySupportMixin[source]#

Bases: dantro.mixins.proxy_support.ProxySupportMixin

Specializes the ProxySupportMixin to the capabilities of Hdf5DataProxy, i.e. it allows access to the cached properties of the proxy object without resolving it.

property dtype: dtype#

Returns dtype, proxy-aware

DATA_ALLOW_PROXY = True#
PROXY_REINSTATE_FAIL_ACTION = 'raise'#

Behaviour upon failure of reinstating a proxy.

Can be: raise, warn, log_warning, log_debug

PROXY_REINSTATE_FOR_PICKLING = True#

If true, populates the pickling state with the proxy instead of the data

PROXY_RESOLVE_ASTYPE = None#

Which type to resolve the proxy to

PROXY_RETAIN = False#

Whether to retain the proxy object after resolving

__getstate__() dict#

If the data is no longer a proxy, but a proxy was retained, this overload adjusts the pickling state such that the proxy object is returned instead of the data that was resolved from it. This hels to reduce the file size of the pickle.

_format_info() str#

Adds an indicator to whether data is proxy to the info string. Additionally, the proxy tags are appended.

_retained_proxy = None#
property data#

The container data. If the data is a proxy, this call will lead to the resolution of the proxy.

Returns

The data stored in this container

property data_is_proxy: bool#

Returns true, if this is proxy data

Returns

Whether the currently stored data is a proxy object

Return type

bool

property proxy: Optional[AbstractDataProxy]#

If the data is proxy, returns the proxy data object without using the .data attribute (which would trigger resolving the proxy); else returns None.

Returns

If the data is proxy, return the

proxy object; else None.

Return type

Union[AbstractDataProxy, None]

reinstate_proxy()#

Re-instate a previously retained proxy object, discarding _data.

property shape: tuple#

Returns shape, proxy-aware

property ndim: int#

Returns ndim, proxy-aware

property size: int#

Returns size, proxy-aware

property chunks: tuple#

Returns chunks, proxy-aware