pyTooling.Decorators

Decorators controlling visibility of entities in a Python module.

Hint

See high-level help for explanations and usage examples.

Variables

Param
RetType
Func
T

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.
InheritDocString(): Copy the doc-string from given base-class to the method this decorator is applied to.

Classes

readonly: Marks a property as read-only.

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

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.

Classes

class pyTooling.Decorators.readonly[source]

Marks a property as read-only.

The doc-string is taken from the getter-method, like property does.

A plain property hands out <property>.setter and <property>.deleter, so a property declared as read-only could be made writable again further down the class body. Both methods therefore raise an AttributeError instead.