Overview

The pyTooling.Decorators package provides decorators to:

mark functions or methods as not implemented.
control the visibility of classes and functions defined in a module.
help with copying doc-strings from base-classes.

Abstract Methods

Todo

DECO:: Refer to abstractmethod() and mustoverride() decorators from meta classes.

Important

Classes using method decorators @abstractmethod or @mustoverride need to use the meta-class ExtendedType.

Alternatively, classes can be derived from SlottedObject or apply decorators @slotted or @mixin.

@abstractmethod

The abstractmethod() decorator marks a method as abstract.

The original method gets replaced by a method raising a NotImplementedError. This can happen, if an abstract method is overridden but called via super()....

When a class containing abstract methods is instantiated, an AbstractClassError is raised.

Hint

If the abstract method contains code that should be called from an overriding method in a derived class, use the @mustoverride decorator.

Important

The class declaration must apply the metaclass ExtendedType so the decorator has an effect.

class A(metaclass=ExtendedType):
  @abstractmethod
  def method(self) -> int:
    """Methods documentation."""

class B(A):
  @InheritDocString(A)
  def method(self) -> int:
    return 2

@mustoverride

The mustoverride() decorator marks a method as must override.

When a class containing must override methods is instantiated, an MustOverrideClassError is raised.

In contrast to @abstractmethod, the method can still be called from a derived class implementing an overridden method.

Hint

If the method contain no code and if it should throw an exception when called, use the @abstractmethod decorator.

Important

The class declaration must apply the metaclass ExtendedType so the decorator has an effect.

class A(metaclass=ExtendedType):
  @mustoverride
  def method(self) -> int:
    """Methods documentation."""
    return 2

class B(A):
  @InheritDocString(A)
  def method(self) -> int:
    result = super().method()
    return result + 1

Data Access

@readonly

The readonly() decorator makes a property read-only. Thus the properties setter and deleter can’t be used.

class Data:
  _data: int

  def __init__(self, data: int) -> None:
    self._data = data

  @readonly
  def Length(self) -> int:
    return 2 ** self._data

@classproperty

Attention

Class properties are currently broken in Python.

Documentation

@export

The export() decorator makes module’s entities (classes and functions) publicly visible. Therefore, these entities get registered in the module’s variable __all__.

Besides making these entities accessible via from foo import *, Sphinx extensions like autoapi are reading __all__ to infer what entities from a module should be auto documented.

# Creating __all__ is only required, if variables need to be listed too
__all__ = ["MY_CONST"]

# Decorators can't be applied to fields, so it was manually registered in __all__
MY_CONST = 42

@export
class MyClass:
  """This is a public class."""

@export
def myFunc():
  """This is a public function."""

# Each application of "@export" will append an entry to __all__

@InheritDocString

When a method in a derived class shall have the same doc-string as the doc-string of the base-class, then the decorator InheritDocString() can be used to copy the doc-string from base-class’ method to the method in the derived class.

Inherit class documentation

class BaseClass:
  """Method's doc-string."""

@InheritDocString(BaseClass, merge=True)
class DerivedClass(BaseClass):
  """Will ne written underneath"""

Inherit method documentation

class BaseClass:
  def method(self):
    """Method's doc-string."""


class DerivedClass(BaseClass):
  @InheritDocString(BaseClass)
  def method(self):
    pass

Performance

@slotted

The size of class instances (objects) can be reduced by using __slots__. This decreases the object creation time and memory footprint. In addition access to fields faster because there is no time consuming field lookup in __dict__. A class with 2 __dict__ members has around 520 B whereas the same class structure uses only around 120 B if slots are used. On CPython 3.10 using slots, the code accessing class fields is 10..25 % faster.

The ExtendedType meta-class can automatically infer slots from type annotations. Because the syntax for applying a meta-class is quite heavy, this decorator simplifies the syntax.

Syntax using Decorator slotted

@export
@slotted
class A:
  _field1: int
  _field2: str

  def __init__(self, arg1: int, arg2: str) -> None:
    self._field1 = arg1
    self._field2 = arg2

Syntax using meta-class ExtendedType

@export
class A(metaclass=ExtendedType, slots=True):
  _field1: int
  _field2: str

  def __init__(self, arg1: int, arg2: str) -> None:
    self._field1 = arg1
    self._field2 = arg2

@mixin

The size of class instances (objects) can be reduced by using __slots__ (see @slotted). If slots are used in multiple inheritance scenarios, only one ancestor line can use slots. For other ancestor lines, it’s allowed to define the slot fields in the inheriting class. Therefore pyTooling allows marking classes as mixin-classes.

The ExtendedType meta-class can automatically infer slots from type annotations. If a class is marked as a mixin-class, the inferred slots are collected and handed over to class defining slots. Because the syntax for applying a meta-class is quite heavy, this decorator simplifies the syntax.

Syntax using Decorator mixin

@export
@slotted
class A:
  _field1: int
  _field2: str

  def __init__(self, arg1: int, arg2: str) -> None:
    self._field1 = arg1
    self._field2 = arg2

@export
class B(A):
  _field3: int
  _field4: str

  def __init__(self, arg1: int, arg2: str) -> None:
    self._field3 = arg1
    self._field4 = arg2
    super().__init__(arg1, arg2)

@export
@mixin
class C(A):
  _field5: int
  _field6: str

  def Method(self) -> str:
    return f"{self._field5} -> {self._field6}"

@export
class D(B, C):
  def __init__(self, arg1: int, arg2: str) -> None:
    super().__init__(arg1, arg2)

Syntax using meta-class ExtendedType

@export
class A(metaclass=ExtendedType, slots=True):
  _field1: int
  _field2: str

  def __init__(self, arg1: int, arg2: str) -> None:
    self._field1 = arg1
    self._field2 = arg2

@export
class B(A):
  _field3: int
  _field4: str

  def __init__(self, arg1: int, arg2: str) -> None:
    self._field3 = arg1
    self._field4 = arg2
    super().__init__(arg1, arg2)


@export
class C(A, mixin=True):
  _field5: int
  _field6: str

  def Method(self) -> str:
    return f"{self._field5} -> {self._field6}"

@export
class D(B, C):
  def __init__(self, arg1: int, arg2: str) -> None:
    super().__init__(arg1, arg2)

@singleton

Todo

DECO::singleton needs documentation

Miscellaneous

@notimplemented

The notimplemented() decorator replaces a callable (function or method) with a callable raising a NotImplementedError containing the decorators message parameter as an error message.

The original callable might contain code, but it’s made unreachable by the decorator. The callable’s name and doc-string is copied to the replacing callable. A reference to the original callable is preserved in the <callable>.__orig_func__ field.

class Data:
  @notimplemented("This function isn't tested yet.")
  def method(self, param: int):
    return 2 ** param