Welcome to RegD’s documentation!

Contents:

class regd.DecoratorRegistry

Decorators registry. Adds tracking meta-info to the decorators and decorated functions and provides the API to work with it.

Actually it makes possible to trace which function or class/object method decorated with each decorator. Sometimes it maybe really usefull to know.

Registry works simply by registering the decorator before it’s usage and after it’s available to track the decorator usage. Here is a simple example:

from regd import DecoratorRegisrty

# let's assume we have a decorator which do sume stuff and having name "cooldeco"
# so we need only to register the decorator function with DecoratorRegistry
cooldeco = DecoratorRegistry.decorator( cooldeco)

# now we define a function which will be decorated with "cooldeco"
@cooldeco
def coolfunc() :
        # ... do something here ...
        return "I'm cool!"

# Now at any place we can do, for example, such check
if DecoratorRegistry.is_decorated_with( coolfunc, cooldeco) :
        # ... do something usefull ...
        print( "Yes, it is!")

Current implementation does not use inspect module or code parsing, but have some rules and restrictions required to take into account:

1. Only registered decorators are possible to track
2. It’s possible to track third-party decorators, them just required to be registered with DecoratorRegistry before they are used
3. Does not matter if registered decorator was used directly (f = d(f)) or by using syntax sugar (@d) - it will work fine
4. It is not possible to register and track builtin decorators like staticmethod or classmethod.

Author :Mykhailo Stadnyk <mikhus@gmail.com> Version :1.3.1b

classmethod all_decorated_module_functions(this, module, exclude_methods=False, exclude_functions=False)

Returns generator of functions decorated with any registered decorator in a given module.

By defualt it will find all functions and class methods.

NOTE: only **registered* decorators are taken into account while searching the module. So it means taht you need to register all the decorators which are used in a given module before module import is done. Or registration of decorators should be done inside the module before their actual use.*

Usage example:

from regd import DecoratorRegisrty

# import the module containing decorators definition 
import somedecomodule

# register the decorators
somedecomodule.deco1 = DecoratorRegistry.decorator( deco1)
somedecomodule.deco2 = DecoratorRegistry.parametrized_decorator( deco2)

# now import the module where deco1 and deco2 should be actually used
# to decorate the functions/methods
import somemodule

# now we can trace all registered decorators usage in a module like:
print( "All decorated functions/methods in a module are:")
print( list( DecoratorRegistry.all_decorated_module_functions( somemodule)))

Parameters:

• module – module to lookup for decorated functions
• exclude_methods – bool flag to turn on/off class method inclusion into result
• exclude_functions – bool flag to turn on/off function inclusion into result

Return type:

generator of dict { function_name : function }

classmethod decorated_methods(this, cls, decorator)

Returns generator for all found methods decorated with given decorator in a given class

Usage example:

from regd import DecoratorRegisrty

# defining decorator function
def my_decorator( fn) :
        def wrapper( *args, **kwargs) :
                print( "%s called" %fn.__name__)
                return fn( *args, **kwargs)
        return wrapper

# registering decorator function with DecoratorRegistry
my_decorator = DecoratorRegistry.decorator( my_decorator)

# example class
class MyClass :
        @my_decorator
        def my_method( self) :
                pass
        
        @my_decorator
        def my_internal_call( self) :
                print( "Internal class lookup result:")
                print( list( DecoratorRegistry.decorated_methods( self, my_decorator)))

print( "External class lookup result:")
print( list( DecoratorRegistry.decorated_methods( MyClass, my_decorator)))

inst = MyClass()
inst.my_internal_call()

Parameters:

• cls – class or object to search
• decorator – decorator function to search

Return type:

generator of dict {methodname : method} contains found decorated class methods

classmethod decorator(this, native_decorator)

Register primitive decorator The primitive decorator is a decorator is a usual decorator which takes only decorating function as an argument Actually this method creates the new decorator function which is intended to replace the given native one. The new function do only the call of a native one but add registry meta-info to all decorator stuff

Usage example:

from regd import DecoratorRegisrty

# defining decorator function
def my_decorator( fn) :
        def wrapper( *args, **kwargs) :
                print( "%s called" %fn.__name__)
                return fn( *args, **kwargs)
        return wrapper

# registering decorator function with DecoratorRegistry
my_decorator = DecoratorRegistry.decorator( my_decorator)

Parameters:native_decorator – real decorator function to register Return type:new decorator function to replace the native one

classmethod get_decorators(this, fn)

Returns list of registered decorators for the given function

Usage example:

from regd import DecoratorRegisrty

# defining decorator function
def my_decorator( fn) :
        def wrapper( *args, **kwargs) :
                print( "%s called" %fn.__name__)
                return fn( *args, **kwargs)
        return wrapper

# registering decorator function with DecoratorRegistry
my_decorator = DecoratorRegistry.decorator( my_decorator)

# defining decorated function
@my_decorator
def myfunc() : pass

print( DecoratorRegistry.get_decorators( myfunc))

Parameters:fn – function to extract the decorators Return type:list of dict {decoratorname : decoratorfunction} contains found decorators

classmethod get_real_function(this, fn)

Returns the reference to the real function which was decorated and bypasses as fn argument to this method

Parameters:fn – function which was decorated Returns:function - reference to the real function decorated with registered decorators

classmethod is_decorated_with(this, fn, decorator)

Checks if a given function decorated with the given decorator

Usage example:

from regd import DecoratorRegisrty

# defining decorator function
def my_decorator( fn) :
        def wrapper( *args, **kwargs) :
                print( "%s called" %fn.__name__)
                return fn( *args, **kwargs)
        return wrapper

# registering decorator function with DecoratorRegistry
my_decorator = DecoratorRegistry.decorator( my_decorator)

# example class
class MyClass :
        @my_decorator
        def my_method( self) :
                if (DecoratorRegistry.is_decorated_with( self.my_method, my_decorator)) :
                        print( "my_method is decorated with my_decorator" %())
                else :
                        print( "my_method is not decorated with my_decorator")

inst = MyClass()
inst.my_method()

Parameters:

• fn – function to check
• decorator – decorator function to check with

Return type:

bool

classmethod module_functions_decorated_with(this, module, decorator, exclude_methods=False, exclude_functions=False)

Returns generator of functions decorated with a given registered decorator in a given module.

By default it will find all functions and class methods.

NOTE: only **registered* decorators are taken into account while searching the module. So it means taht you need to register all the decorators which are used in a given module before module import is done. Or registration of decorators should be done inside the module before their actual use.*

Usage example:

from regd import DecoratorRegisrty

# import the module containing decorators definition 
import somedecomodule

# register the decorators
somedecomodule.deco1 = DecoratorRegistry.decorator( deco1)
somedecomodule.deco2 = DecoratorRegistry.parametrized_decorator( deco2)

# now import the module where deco1 and deco2 should be actually used
# to decorate the functions/methods
import somemodule

# now we can trace decorators usage in a module like:
print( "deco1 is applied to:")
print( list( DecoratorRegistry.module_functions_decorated_with( somemodule, somedecomodule.deco1)))

print( "deco2 is applied to:")
print( list( DecoratorRegistry.module_functions_decorated_with( somemodule, somedecomodule.deco2)))

Parameters:

• module – module to lookup for decorated functions
• decorator – function which is used as decorator
• exclude_methods – bool flag to turn on/off class method inclusion into result
• exclude_functions – bool flag to turn on/off function inclusion into result

Return type:

generator of dict { function_name : function }

classmethod parametrized_decorator(this, native_parametrized_decorator)

Register parametrized decorator The parametrized decorator is a decorator which is able to take an arguments So it looks like @mydecorator(param1=True,param2=False) When it is required to register parametrized decorator function this method should be used instead of DecoratorRegistry:decorator() Actually this method creates the new decorator function which is intended to replace the given native one. The new function do only the call of a native one but add registry meta-info to all decorator stuff

Usage example:

from regd import DecoratorRegisrty

# defining parametrized decorator function
def my_decorator( *dargs, **dkwargs) :
        # ...
        # do some stuff with decorator arguments passed as *dargs, **dkwargs
        # ...
        # define a function decorator
        def decorator( fn) :
                def wrapper( *args, **kwargs) :
                        print( "%s called" %fn.__name__)
                        return fn( *args, **kwargs)
                return wrapper
        return decorator

# registering decorator function with DecoratorRegistry
my_decorator = DecoratorRegistry.parametrized_decorator( my_decorator)

Parameters:native_parametrized_decorator – real decorator function to register Return type:new parametrized decorator function to replace the native one

Indices and tables

• Index
• Module Index
• Search Page