dantro.mixins package
Contents
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 actualBaseDataAttrs
-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
- 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.
- 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.
- 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.
- 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.
- __delitem__(key)#
Deletes an item
- __getitem__(key)#
Returns an item.
- __iter__()#
Iterates over the 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 theBaseDataContainer
, 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_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.
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_EXCLUDE: Sequence[str] = ()#
Attributes to not forward. Evaluated after
FORWARD_ATTR_ONLY
- __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
ofgetattr(self, self.FORWARD_ATTR_TO)
- _forward_attr_pre_hook(attr_name: Optional[str] = None)[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
- __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
ofgetattr(self, self.FORWARD_ATTR_TO)
- _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
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!- __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
- 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
- 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__
, …
- class NumbersMixin[source]#
Bases:
dantro.mixins.numeric.UnaryOperationsMixin
This mixin implements the methods needed for calculating with numbers.
- __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
- __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
- 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.
- Either the
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
- 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]
- class Hdf5ProxySupportMixin[source]#
Bases:
dantro.mixins.proxy_support.ProxySupportMixin
Specializes the
ProxySupportMixin
to the capabilities ofHdf5DataProxy
, i.e. it allows access to the cached properties of the proxy object without resolving it.- 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
- 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
.