decorators

Module which defines decorators

MDMC.common.decorators.mod_docstring(replacements: dict[str, str]) → Callable[source]

Decorator for modifying the docstring of a function, method, class or property

This is done by replacing specified substrings. After replacement the docstring is text wrapped to ensure that line length and indentations are preserved.

While this can be used for replacements in equations, care must be taken to ensure that wrapping does not cause line breaks in invalid places in the Latex.

Parameters:: replacements (dict) – {old:new} pairs where old is a str in the docstring which will be replaced, and new is the str it should be replaced with.
Returns:: A decorator which modifies the docstring of a function, method, class or property
Return type:: function
Raises:: TypeError – If mod_docstring is applied to an object which is not a function, method, class, or property

Examples

To dynamically modify the docstring of a function so “this” is replaced with “that”:

@mod_docstring({'this':'that'})
def function():
    """
    The word this will be replaced
    """

To dynamically modify the docstring of a class so “this” is replaced with “that”:

@mod_docstring({'this':'that'})
class DocClass():
    """
    This is the class level docstring. The word this will be
    replaced.
    """

To dynamically modify the docstring of a property so “this” is replaced with “that”:

@property
@mod_docstring({'this':'that'})
def prop():
    """
    The word this will be replaced.
    """

MDMC.common.decorators.repr_decorator(attribute: str, *attributes: str | None)[source]

Implements __repr__ for a class using passed attributes (including properties)

The first element of all __repr__ returns is always the name of the class

Warning

Testing for repr_decorator is restricted to testing the decorator outputs the correct format, not whether each occurence it is used is valid. It is strongly recommended that classes decorated with repr_decorator are tested to ensure that repr(class) is valid, for instance whether the class actually has all of the attributes passed as str to repr_decorator.

Parameters:

attribute (str) – The name of an attribute of the class being decorated. This attribute (or property) will be included in the __repr__ of the class.
*attributes (str) – Zero or more str with the name of an attribute (or property) of the class being decorated. These attributes will be included in the __repr__ of the class.

Returns:

A class with __repr__ implemented such that attribute and attributes are printed

Return type:

class

Example

Add a repr_decorator to the Atom class to include the name attribute and the position property:

>>> @repr_decorator('name', 'position')
... Class Atom(Structure):
...
...     def __init__(self, element, name, position):
...         self.element = element
...         self.name = name
...         self.position = position
...
...     @property
...     def position(self):
...         return self._position
...
... atom = Atom('H', 'Hydrogen', [1., 1., 1.])
... atom
< Atom
 {name: 'Hydrogen',
  position: [1., 1., 1.]}>

MDMC.common.decorators.set_docstring(docstring: str) → Callable[source]

Decorator for setting the docstring of a function, method, class or property

The new docstring is text wrapped to ensure that the line length is valid. It is assumed that the specified docstring has the correct indentations.

Parameters:: docstring (str) – The new docstring for the function, method, class or property
Returns:: A decorator which sets the docstring of a function, method, class or property
Return type:: function
Raises:: TypeError – If set_docstring is applied to an object which is not a function, method, class, or property

Examples

To dynamically set the docstring of a function:

@set_docstring("This is the new docstring")
def function():
    """
    This docstring will be replaced
    """

To dynamically set the docstring of a class:

@set_docstring("This is the new docstring")
class DocClass():
    """
    This is a class level docstring. This docstring will be
    replaced.
    """

To dynamically set the docstring of a property:

@property
@set_docstring("This is the new docstring")
def prop():
    """
    This docstring will be replaced
    """

MDMC.common.decorators.time_function_execution(func) → Callable[source]

Creates an instance of the TimeKeeper and stores the function execution time in TimeKeeper’s class attributes.

This decorator is meant to be used on functions that are likely to be using up too much CPU time, so the scale of the problem can be assessed.

MDMC.common.decorators.unit_decorator(unit: str | None) → Callable[source]

Decorates property.setter methods to add units

Adds units to the values passed to property.setter methods. These units are displayed when either repr or str is called for the corresponding property.getter method.

Suitable for use with setter methods that either take float (or objects that can be cast to float), or NumPy array (or objects that can be cast to NumPy array).

Parameters:: unit (str or None) – The unit applied to the property. If None then self.unit is used, which enables classes to have properties with units defined at runtime.
Returns:: A property.setter function with a value parameter which has a unit.
Return type:: function

Example

Add a unit_decorator to the position property:

>>> Class Atom(Structure):
...
...     @property
...     def position(self):
...         return self._position
...
...     @position.setter
...     @unit_decorator(unit=Unit('Ang'))
...     def position(self, value):
...         self._position = value

MDMC.common.decorators.unit_decorator_getter(unit: str | None) → Callable[source]

Decorates property.getter methods to add units

Adds units to the return values of property.getter methods. These units are displayed when either repr or str is called.

Suitable for use with setter methods that either take float (or objects that can be cast to float), or NumPy array (or objects that can be cast to NumPy array). This method exists for properties which have no setter method.

Parameters:: unit (str or None) – The unit applied to the property. If None then self.unit is used, which enables classes to have properties with units defined at runtime.
Returns:: A property.getter function with a return type which has a unit (e.g. UnitFloat or UnitArray)
Return type:: function

Example

Add a unit_decorator_getter to the volume property:

>>> Class Universe:
...
...     @property
...     @unit_decorator_getter(unit=Unit('Ang') ^ 3)
...     def volume(self):
...         return self.dimensions ** 3

MDMC.common.decorators.weakref_cache(maxsize=128) → Callable[source]

Weakref LRU cache to avoid memory leaks

Caches on instance methods store self, which can lead to excess memory use. This avoids it by only holding a weakref to the instance.

MDMC.common.decorators.wrap_docstring(docstring: str, line_length: int) → str[source]

Wraps a docstring to a specific line length.

This maintains any indentation which exists at the start of a line. While equations should not be affected by this wrapping, it is recommended that docstrings with .. math:: are visually checked after wrapping.

Parameters:

docstring (str) – The docstring to be wrapped
line_length (int) – The maximum line length of the docstring before it is wrapped

Returns:

The wrapped docstring

Return type:

str

Raises:

ValueError – If any indent has more characters than the line_length, as the wrapping cannot then preserve the correct indent