Introduction

The dectools module overcomes some challenges in the Python decorators. It provides a clear and convenient method for writing your own decorators. The dectools modules also provides a library of common decorations for logging and testing your code.

The prebuilt libraries can be used with minimal understanding and provide immediate benefit to users. The constructors for writing your own decorators require following a convention for naming the required arguments of your decorator. In all cases, care is taken to provide correct function signatures, metadata, and record when decorators are applied in the function metadata.

The support for class decoration is still coming.

Prebuilt Decorators (the library)

Prebuilt decorators can be of immediate benefit to users and can be used without a good understanding of decorators. These are used for common problems such as caching, logging, and programming with invariants or pre-conditions and post-conditions.

Make_call Decorators (the constructors)

There are five special constructors that allow users to make their own decorators that are called before, after, if (conditionally), instead, or once during declaration of another function. These provide for most use cases of writing custom decorators. Using these constructors removes the boilerplate or copy-and-paste code associated with writing your own decorators, while also handling the function signatures, the metadata, and a history of which functions decorate others.

I Don’t Read Documentation

Typical usage looks like this:

from dectools import *   # <-- Don't do this

@make_call_once
def register_callback(function):
      gui.callback_create(function.__name__, function)

@make_call_before
def require_login(function, args, kwargs, page_name):
     while not current_user_id():
        ...

@log()
@register()
@require_login("Summary of Items")
def view_summary():
    ...

Thanks

Thanks to Michele Simionato for exposing utility functions in Decorator Decorator. Thanks to David Mertz for his excellent IBM Developer Works article “Charming Python: Decorators make magic easy”, http://www.ibm.com/developerworks/linux/library/l-cpdecor.html

Supported Versions

Currently, only version Python 2.6.x is guaranteed to work.

Contact

You can contact the author, Charles Merriam, at charles.merriam@gmail.com.

Sources

  • The source and bugs repository is git://github.com/merriam/dectools
  • The package is also available from the cheeseshop, http://pypi.python.org/pypi/dectools
  • The presentation from PyCon 2010, of decorators and introducing the library, is in the docs/ directory.
  • The video from the PyCon 2010 presentation is available at http://blip.tv/file/3257278/