pyTooling.Decorators

Decorators controlling visibility of entities in a Python module.

Hint

See high-level help for explanations and usage examples.

Variables

Functions

  • export(): Register the given function or class as publicly accessible in a module.

  • notimplemented(): Mark a method as not implemented and replace the implementation with a new method raising a NotImplementedError.

  • readonly(): Marks a property as read-only.

  • InheritDocString(): Copy the doc-string from given base-class to the method this decorator is applied to.

Variables

pyTooling.Decorators.Param

A parameter specification for function or method

~Param
pyTooling.Decorators.RetType

Type variable for a return type

~RetType
pyTooling.Decorators.Func

Type specification for a function

typing.Callable[~Param, ~RetType]

alias of Callable[[Param], RetType]

pyTooling.Decorators.T

A type variable for a classes or functions.

~T

Functions

pyTooling.Decorators.export(entity)[source]

Register the given function or class as publicly accessible in a module.

Creates or updates the __all__ attribute in the module in which the decorated entity is defined to include the name of the decorated entity.

to_export.py

another_file.py

 
from pyTooling.Decorators import export

@export
def exported():
  pass

def not_exported():
  pass

from .to_export import *


# 'exported' will be listed in __all__
assert "exported"         in globals()

# 'not_exported' won't be listed in __all__
assert "not_exported" not in globals()
Parameters:

entity (TypeVar(T, bound= Union[Type, FunctionType])) – The function or class to include in __all__.

Return type:

TypeVar(T, bound= Union[Type, FunctionType])

Returns:

The unmodified function or class.

Raises:

  • AttributeError – If parameter entity has no __module__ member.

  • TypeError – If parameter entity is not a top-level entity in a module.

  • TypeError – If parameter entity has no __name__.

pyTooling.Decorators.notimplemented(message)[source]

Mark a method as not implemented and replace the implementation with a new method raising a NotImplementedError.

The original method is stored in <method>.__wrapped__ and it’s doc-string is copied to the replacing method. In additional the field <method>.__notImplemented__ is added.

example.py

class Data:
  @notimplemented
  def method(self) -> bool:
    '''This method needs to be implemented'''
    return True
Parameters:

  • method – Method that is marked as not implemented.

  • message (str)

Return type:

Callable

Returns:

Replacement method, which raises a NotImplementedError.

See also

  • abstractmethod()

  • mustoverride()

pyTooling.Decorators.readonly(func)[source]

Marks a property as read-only.

The doc-string will be taken from the getter-function.

It will remove <property>.setter and <property>.deleter from the property descriptor.

Parameters:

func (Callable) – Function to convert to a read-only property.

Return type:

property

Returns:

A property object with just a getter.

See also

property

A decorator to convert getter, setter and deleter methods into a property applying the descriptor protocol.

pyTooling.Decorators.InheritDocString(baseClass, merge=False)[source]

Copy the doc-string from given base-class to the method this decorator is applied to.

example.py

from pyTooling.Decorators import InheritDocString

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

class Class2(Class1):
  @InheritDocString(Class1)
  def method(self):
    super().method()
Parameters:

  • baseClass (type) – Base-class to copy the doc-string from to the new method being decorated.

  • merge (bool)

Return type:

Callable[[Union[Callable[[ParamSpec(Param, bound= None)], TypeVar(RetType)], type]], Union[Callable[[ParamSpec(Param, bound= None)], TypeVar(RetType)], type]]

Returns:

Decorator function that copies the doc-string.