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/

