assertionlib.dataclass

A class with a number of generic pre-defined (magic) methods inspired by dataclass of Python 3.7.

Index

`AbstractDataClass`()	A dataclass with a number of generic pre-defined (magic) methods.
`AbstractDataClass.__repr__`()	Return a (machine readable) string representation of this instance.
`AbstractDataClass.__eq__`(value)	Check if this instance is equivalent to value.
`AbstractDataClass.__hash__`()	Return the hash of this instance.
`AbstractDataClass.__copy__`()	Return a shallow copy of this instance; see `AbstractDataClass.copy()`.
`AbstractDataClass.__deepcopy__`([memo])	Return a deep copy of this instance; see `AbstractDataClass.copy()`.".
`AbstractDataClass.copy`([deep])	Return a shallow or deep copy of this instance.
`AbstractDataClass.as_dict`([return_private])	Construct a dictionary from this instance with all non-private instance variables.
`AbstractDataClass.from_dict`(dct)	Construct a instance of this objects' class from a dictionary with keyword arguments.
`AbstractDataClass.inherit_annotations`()	A decorator for inheriting annotations and docstrings.

API

class assertionlib.dataclass.AbstractDataClass[source]

A dataclass with a number of generic pre-defined (magic) methods.

Provides methods for:

String conversion: AbstractDataClass.__repr__().
Object comparisons: AbstractDataClass.__eq__().
Hash construction: AbstractDataClass.__hash__().
Copying: AbstractDataClass.copy(), AbstractDataClass.__copy__() and AbstractDataClass.__deepcopy__().
Dictionary interconversion: AbstractDataClass.as_dict() and AbstractDataClass.from_dict().
Inherting method docstrings and annotations: AbstractDataClass.inherit_annotations().

_PRIVATE_ATTR

A class variable with the names of private instance variable. These attributes will be excluded whenever calling AbstractDataClass.as_dict(), printing or comparing objects. The set is unfrozen (and added as instance variables) the moment a class instance is initiated.

Type:: frozenset [str] or set [str]

_HASHABLE

A class variable denoting whether or not class instances are hashable. The AbstractDataClass.__hash__ method will be unavailable if False.

Type:: bool

_hash

An attribute for caching the hash() of this instance. Only available if AbstractDataClass._HASHABLE is True.

Type:: int

AbstractDataClass.__repr__() → str[source]

Return a (machine readable) string representation of this instance.

The string representation consists of this instances’ class name in addition to all (non-private) instance variables.

Returns:: A string representation of this instance.
Return type:: str

See also

AbstractDataClass._PRIVATE_ATTR: A set with the names of private instance variables.
AbstractDataClass._repr_fallback: Fallback function for AbstractDataClass.__repr__() incase of recursive calls.
AbstractDataClass._str_iterator(): Return an iterable for the iterating over this instances’ attributes.
AbstractDataClass._str(): Returns a string representation of a single key/value pair.

AbstractDataClass.__eq__(value: Any) → bool[source]

Check if this instance is equivalent to value.

The comparison checks if the class type of this instance and value are identical and if all (non-private) instance variables are equivalent.

Returns:: Whether or not this instance and value are equivalent.
Return type:: bool

See also

AbstractDataClass._PRIVATE_ATTR: A set with the names of private instance variables.
AbstractDataClass._eq: Return if v1 and v2 are equivalent.
AbstractDataClass._eq_fallback: Fallback function for AbstractDataClass.__eq__() incase of recursive calls.

AbstractDataClass.__hash__() → int

Return the hash of this instance.

The returned hash is constructed from two components: * The hash of this instances’ class type. * The hashes of all key/value pairs in this instances’ (non-private) attributes.

If an unhashable instance variable is encountered, e.g. a list, then its id() is used for hashing.

This method will raise a TypeError if the class attribute AbstractDataClass._HASHABLE is False.

See also

AbstractDataClass._PRIVATE_ATTR: A set with the names of private instance variables.
AbstractDataClass._HASHABLE: Whether or not this class is hashable.
AbstractDataClass._hash_fallback: Fallback function for AbstractDataClass.__hash__() incase of recursive calls.
AbstractDataClass._hash: An instance variable for caching the hash() of this instance.

AbstractDataClass.__copy__() → AT[source]: Return a shallow copy of this instance; see AbstractDataClass.copy().

AbstractDataClass.__deepcopy__(memo: Dict[int, Any] | None = None) → AT[source]: Return a deep copy of this instance; see AbstractDataClass.copy().”.

AbstractDataClass.copy(deep: bool = False) → AT[source]

Return a shallow or deep copy of this instance.

Parameters:: deep (bool) – Whether or not to return a deep or shallow copy.
Returns:: A new instance constructed from this instance.
Return type:: AbstractDataClass

AbstractDataClass.as_dict(return_private: bool = False) → Dict[str, Any][source]

Construct a dictionary from this instance with all non-private instance variables.

The returned dictionary values are shallow copies.

Parameters:: return_private (bool) – If True, return both public and private instance variables. Private instance variables are defined in AbstractDataClass._PRIVATE_ATTR.
Returns:: A dictionary with keyword arguments for initializing a new instance of this class.
Return type:: dict [str, Any]

See also

AbstractDataClass.from_dict(): Construct a instance of this objects’ class from a dictionary with keyword arguments.
AbstractDataClass._PRIVATE_ATTR: A set with the names of private instance variables.

classmethod AbstractDataClass.from_dict(dct: Mapping[str, Any]) → AT[source]

Construct a instance of this objects’ class from a dictionary with keyword arguments.

Parameters:: dct (Mapping [str, Any]) – A dictionary with keyword arguments for constructing a new AbstractDataClass instance.
Returns:: A new instance of this object’s class constructed from dct.
Return type:: AbstractDataClass

See also

AbstractDataClass.as_dict(): Construct a dictionary from this instance with all non-private instance variables.

classmethod AbstractDataClass.inherit_annotations() → Callable[[FT], FT][source]

A decorator for inheriting annotations and docstrings.

Can be applied to methods of AbstractDataClass subclasses to automatically inherit the docstring and annotations of identical-named functions of its superclass.

References to AbstractDataClass are replaced with ones pointing to the respective subclass.

Returns:: A decorator for updating the annotations and docstring of a callable.
Return type:: type

Examples

>>> class SubClass(AbstractDataClass):
...
...     @AbstractDataClass.inherit_annotations()
...     def __copy__(self): pass

>>> print(SubClass.__copy__.__doc__)
Return a shallow copy of this instance; see :meth:`SubClass.copy`.

>>> print(SubClass.__copy__.__annotations__)
{'self': ~AT, 'return': ~AT}