Wrapping

class sigmaepsilon.core.wrapping.Wrapper(*args, **kwargs)

Wrapper base class that makes it easy (and safe) to extend other objects. Based on the provided arguments at initialization, the wrapper either

1. wraps an existing object at object creation provided as a keyword argument with Wrapper.wrapkey

2. wraps an existing object at object creation if it is a positional argument and an instance of Wrapper.wraptype

2. wraps the object Wrapper.wraptype(*args, **kwargs) if Wrapper.wraptype is not None

The attributes and methods of the wrapped instance are all accessible through the wrapper.

Using a wrapper is a good idea if you want to easily extend the functionality provided by a class of an external library without having to worry about shadowing an important method and thus risking to break the behaviour of the wrapped object.

Examples

>>> import numpy as np
>>>
>>> arr = np.eye(3)
>>> wrapper = Wrapper(wrap=arr)

Now the wrapped NumPy array is accessible as wrapper.wrapped.

A wrapper class can be used to extend the behaviour:

>>> MyWrapper(Wrapper):
>>>     wraptype = np.ndarray
>>>
>>>     def invert() -> None:
>>>         self.wrapped = np.linalg.inv(self.wrapped)

With this solution, you don’t have to worry about shadowing an existing implementation of NumPy arrays. Not that NumPy arrays might not have a method called invert at the time of implementing the class MyWrapper, but it might change in the future. You can even check that internally and get notified:

>>> import warnings
>>>
>>> MyWrapper(Wrapper):
>>>     wraptype = np.ndarray
>>>
>>>     def invert() -> None:
>>>         if hasattr(self.wrapped, "invert"):
>>>             warnings.warn("'invert' already exists in the object")
>>>         self.wrapped = np.linalg.inv(self.wrapped)

Then, to wrap a NumPy array, you can do this (since the wraptype attribute is set, the MyWrapper class is going to catch the object to wrap as a positional argument):

>>> wrapper = MyWrapper(arr)

wrap(obj: Any | None = None) → Any

Wraps the provided object and returns the wrapper instance.

property wrapped

Retruns the wrapped object.

wraps()

Returns True if the instance wraps something or False if it doesn’t.

sigmaepsilon.core.wrapping.customwrapper(*, wrapkey: str = 'wrap', wraptype: ~typing.Any = <class 'NoneType'>) → Wrapper

A factory function that returns a class decorator turning a class type into a wrapper type, that either

1. wraps an existing object at object creation provided as a keyword argument with wrapkey

2. wraps an existing object at object creation if it is a positional argument and an instance of wraptype

2. wraps the object wraptype(*args, **kwargs)

See also

Wrapper

Examples

Take this example from the Wrapper class:

>>> MyWrapper(Wrapper):
>>>     wraptype = np.ndarray
>>>
>>>     def invert() -> None:
>>>         self.wrapped = np.linalg.inv(self.wrapped)

An equivalent implementation of this is the following:

>>> @customwrapper(wraptype=np.ndarray)
>>> MyWrapper:
>>>     def invert() -> None:
>>>         self.wrapped = np.linalg.inv(self.wrapped)

Notice how the class MyWrapper is not inherited from the Wrapper class.

sigmaepsilon.core.wrapping.wrap(obj: object) → Wrapper

Wraps an object and returns the wrapper.

See also

Wrapper

Example

>>> import numpy as np
>>> wrapper = wrap(np.eye(3))

sigmaepsilon.core.wrapping.wrapper(BaseType: Any) → Wrapper

Simple class decorator that turns a type into a wrapper with default behaviour.

Notes

This is the same as using the customwrapper() with the default values.

See also

Wrapper, customwrapper()

Example

>>> @wrapper
>>> MyWrapper:
>>>     def invert() -> None:
>>>         self.wrapped = np.linalg.inv(self.wrapped)