Simple Decorators

decorate(*decorators)

Apply decorators to the subsequent function definition or assignment statement, thereby allowing you to conviently use standard decorators with Python 2.3 and up (i.e., no @ syntax required), as shown in the following table of examples:

Python 2.4+               DecoratorTools
------------              --------------
@classmethod              decorate(classmethod)
def blah(cls):            def blah(cls):
    pass                      pass

@foo
@bar(baz)                 decorate(foo, bar(baz))
def spam(bing):           def spam(bing):
    """whee"""                """whee"""

decorate_class(decorator [, depth=2, frame=None])

Set up decorator to be passed the containing class after its creation.

This function is designed to be called by a decorator factory function executed in a class suite. It is not used directly; instead you simply give your users a "magic function" to call in the body of the appropriate class. Your "magic function" (i.e. a decorator factory function) then calls decorate_class to register the decorator to be called when the class is created. Multiple decorators may be used within a single class, although they must all appear after the __metaclass__ declaration, if there is one.

The registered decorator will be given one argument: the newly created containing class. The return value of the decorator will be used in place of the original class, so the decorator should return the input class if it does not wish to replace it. Example:

>>> from peak.util.decorators import decorate_class

>>> def demo_class_decorator():
...     def decorator(cls):
...         print "decorating", cls
...         return cls
...     decorate_class(decorator)

>>> class Demo:
...     demo_class_decorator()
decorating __builtin__.Demo

In the above example, demo_class_decorator() is the decorator factory function, and its inner function decorator is what gets called to actually decorate the class. Notice that the factory function has to be called within the class body, even if it doesn't take any arguments.

If you are just creating simple class decorators, you don't need to worry about the depth or frame arguments here. However, if you are creating routines that are intended to be used within other class or method decorators, you will need to pay attention to these arguments to ensure that decorate_class() can find the frame where the class is being defined. In general, the simplest way to do this is for the function that's called in the class body to get its caller's frame with sys._getframe(1), and then pass that frame down to whatever code will be calling decorate_class(). Alternately, you can specify the depth that decorate_class() should call sys._getframe() with, but this can be a bit trickier to compute correctly.

Note, by the way that decorate_class() ignores duplicate callbacks:

>>> def hello(cls):
...     print "decorating", cls
...     return cls

>>> def do_hello():
...     decorate_class(hello)

>>> class Demo:
...     do_hello()
...     do_hello()
decorating __builtin__.Demo

Unless the allow_duplicates argument is set to a true value:

>>> def do_hello():
...     decorate_class(hello, allow_duplicates=True)

>>> class Demo:
...     do_hello()
...     do_hello()
decorating __builtin__.Demo
decorating __builtin__.Demo

The struct() Decorator

The struct() decorator creates a tuple subclass with the same name and docstring as the decorated function. The class will have read-only properties with the same names as the function's arguments, and the repr() of its instances will look like a call to the original function:

>>> from peak.util.decorators import struct

>>> def X(a,b,c):
...     """Demo type"""
...     return a,b,c

>>> X = struct()(X)    # can't use decorators above functions in doctests

>>> v = X(1,2,3)
>>> v
X(1, 2, 3)
>>> v.a
1
>>> v.b
2
>>> v.c
3

>>> help(X) # doctest: +NORMALIZE_WHITESPACE
Help on class X:
<BLANKLINE>
class X(__builtin__.tuple)
 |  Demo type
 |
 |  Method resolution order:
 |      X
 |      __builtin__.tuple
 |      __builtin__.object
 |
 |  Methods defined here:
 |
 |  __repr__(self)
 |
 |  ----------------------------------------------------------------------
 |  Static methods defined here:
 |
 |  __new__(cls, *args, **kw)
 |
 |  ----------------------------------------------------------------------
 |  ...s defined here:
 |
 |  a...
 |
 |  b...
 |
 |  c...
 |
 |  ----------------------------------------------------------------------
 |  Data and other attributes defined here:
 |
 |  __args__ = ['a', 'b', 'c']...
 |
 |  __star__ = None
 |
 |  ...

The function should return a tuple of values in the same order as its argument names, as it will be used by the class' constructor. The function can perform validation, add defaults, and/or do type conversions on the values.

If the function takes a *, argument, it should flatten this argument into the result tuple, e.g.:

>>> def pair(first, *rest):
...     return (first,) + rest
>>> pair = struct()(pair)

>>> p = pair(1,2,3,4)
>>> p
pair(1, 2, 3, 4)
>>> p.first
1
>>> p.rest
(2, 3, 4)

Internally, struct types are actually tuples:

>>> print tuple.__repr__(X(1,2,3))
(<class 'X'>, 1, 2, 3)

The internal representation contains the struct's type object, so that structs of different types will not compare equal to each other:

>>> def Y(a,b,c):
...     return a,b,c
>>> Y = struct()(Y)

>>> X(1,2,3) == X(1,2,3)
True
>>> Y(1,2,3) == Y(1,2,3)
True
>>> X(1,2,3) == Y(1,2,3)
False

Note, however, that this means that if you want to unpack them or otherwise access members directly, you must include the type entry, or use a slice:

>>> a, b, c = X(1,2,3)  # wrong
Traceback (most recent call last):
  ...
ValueError: too many values to unpack

>>> t, a, b, c = X(1,2,3)       # right
>>> a, b, c    = X(1,2,3)[1:]   # ok, if perhaps a bit unintuitive

The struct() decorator takes optional mixin classes (as positional arguments), and dictionary entries (as keyword arguments). The mixin classes will be placed before tuple in the resulting class' bases, and the dictionary entries will be placed in the class' dictionary. These entries take precedence over any default entries (e.g. methods, properties, docstring, etc.) that are created by the struct() decorator:

>>> class Mixin(object):
...     __slots__ = []
...     def foo(self): print "bar"

>>> def demo(a, b):
...     return a, b

>>> demo = struct(Mixin, reversed=property(lambda self: self[:0:-1]))(demo)
>>> demo(1,2).foo()
bar
>>> demo(3,4).reversed
(4, 3)
>>> demo.__mro__
(<class 'demo'>, <class ...Mixin...>, <type 'tuple'>, <type 'object'>)

Note that using mixin classes will result in your new class' instances having a __dict__ attribute, unless they are new-style classes that set __slots__ to an empty list. And if they have any slots other than __weakref__ or __dict__, this will cause a type error due to layout conflicts. In general, it's best to use mixins only for adding methods, not data.

Finally, note that if your function returns a non-tuple result, it will be returned from the class' constructor. This is sometimes useful:

>>> def And(a, b):
...     if a is None: return b
...     return a, b
>>> And = struct()(And)

>>> And(1,2)
And(1, 2)

>>> And(None, 27)
27

Signature Matching

One of the drawbacks to using function decorators is that using help() or other documentation tools on a decorated function usually produces unhelpful results:

>>> def before_and_after(message):
...     def decorator(func):
...         def decorated(*args, **kw):
...             print "before", message
...             try:
...                 return func(*args, **kw)
...             finally:
...                 print "after", message
...         return decorated
...     return decorator

>>> def foo(bar, baz):
...     """Here's some doc"""

>>> foo(1,2)
>>> help(foo)               # doctest: -NORMALIZE_WHITESPACE
Help on function foo:
...
foo(bar, baz)
    Here's some doc
...

>>> decorated_foo = before_and_after("hello")(foo)
>>> decorated_foo(1,2)
before hello
after hello

>>> help(decorated_foo)     # doctest: -NORMALIZE_WHITESPACE
Help on function decorated:
...
decorated(*args, **kw)
...

So DecoratorTools provides you with two tools to improve this situation. First, the rewrap() function provides a simple way to match the signature, module, and other characteristics of the original function:

>>> from peak.util.decorators import rewrap

>>> def before_and_after(message):
...     def decorator(func):
...         def before_and_after(*args, **kw):
...             print "before", message
...             try:
...                 return func(*args, **kw)
...             finally:
...                 print "after", message
...         return rewrap(func, before_and_after)
...     return decorator

>>> decorated_foo = before_and_after("hello")(foo)
>>> decorated_foo(1,2)
before hello
after hello

>>> help(decorated_foo)     # doctest: -NORMALIZE_WHITESPACE
Help on function foo:
...
foo(bar, baz)
    Here's some doc
...

The rewrap() function returns you a new function object with the same attributes (including __doc__, __dict__, __name__, __module__, etc.) as the original function, but which calls the decorated function.

If you want the same signature but don't want the overhead of another calling level at runtime, you can use the @template_function decorator instead. The downside to this approach, however, is that it is more complex to use. So, this approach is only recommended for more performance-intensive decorators, that you've already debugged using the rewrap() approach. But if you need to use it, the appropriate usage looks something like this:

>>> from peak.util.decorators import template_function

>>> def before_and_after2(message):
...     def decorator(func):
...         [template_function()]   # could also be @template_function in 2.4
...         def before_and_after2(__func, __message):
...             '''
...             print "before", __message
...             try:
...                 return __func($args)
...             finally:
...                 print "after", __message
...             '''
...         return before_and_after2(func, message)
...     return decorator

>>> decorated_foo = before_and_after2("hello")(foo)
>>> decorated_foo(1,2)
before hello
after hello

>>> help(decorated_foo)     # doctest: -NORMALIZE_WHITESPACE
Help on function foo:
...
foo(bar, baz)
    Here's some doc
...

As you can see, the process is somewhat more complex. Any values you wish the generated function to be able to access (aside from builtins) must be declared as arguments to the decorating function, and all arguments must be named so as not to conflict with the names of any of the decorated function's arguments. The docstring must either fit on one line, or begin with a newline and have its contents indented by at least two spaces. The string $args may be used one or more times in the docstring, whenever calling the original function. The first argument of the decorating function must always be the original function.

Debugging Generated Code

Both rewrap() and template_function are implemented using code generation and runtime compile/exec operations. Normally, such things are frowned on in Python because Python's debugging tools don't work on generated code. In particular, tracebacks and pdb don't show the source code of functions compiled from strings... or do they? Let's see:

>>> def raiser(x, y="blah"):
...     raise TypeError(y)

>>> def call_and_print_error(func, *args, **kw):
...     # This function is necessary because we want to test the error
...     # output, but doctest ignores a lot of exception detail, and
...     # won't show the non-errror output unless we do it this way
...     #
...     try:
...         func(*args, **kw)
...     except:
...         import sys, traceback
...         print ''.join(traceback.format_exception(*sys.exc_info()))

>>> call_and_print_error(before_and_after("error")(raiser), 99)
before error
after error
Traceback (most recent call last):
  File "<doctest README.txt[...]>", line ..., in call_and_print_error
    func(*args, **kw)
  File "<peak.util.decorators.rewrap wrapping raiser at 0x...>", line 3, in raiser
    def raiser(x, y): return __decorated(x, y)
  File ..., line ..., in before_and_after
    return func(*args, **kw)
  File "<doctest README.txt[...]>", line 2, in raiser
    raise TypeError(y)
TypeError: blah

>>> call_and_print_error(before_and_after2("error")(raiser), 99)
before error
after error
Traceback (most recent call last):
  File "<doctest README.txt[...]>", line ..., in call_and_print_error
    func(*args, **kw)
  File "<before_and_after2 wrapping raiser at 0x...>", line 6, in raiser
    return __func(x, y)
  File "<doctest README.txt[...]>", line 2, in raiser
    raise TypeError(y)
TypeError: blah

As you can see, both decorators' tracebacks include lines from the pseudo-files "<peak.util.decorators.rewrap wrapping raiser at 0x...>" and "<before_and_after2 wrapping raiser at 0x...>" (the hex id's of the corresponding objects are omitted here). This is because DecoratorTools adds information to the Python linecache module, and tracebacks and pdb both use the linecache module to get source lines. Any tools that use linecache, either directly or indirectly, will therefore be able to display this information for generated code.

If you'd like to be able to use this feature for your own code generation or non-file-based code (e.g. Python source loaded from a database, etc.), you can use the cache_source() function:

>>> from peak.util.decorators import cache_source
>>> from linecache import getline

>>> demo_source = "line 1\nline 2\nline 3"

>>> cache_source("<dummy filename 1>", demo_source)
>>> getline("<dummy filename 1>", 3)
'line 3'

The function requires a dummy filename, which must be globally unique. An easy way to ensure uniqueness is to include the id() of an object that will exist at least as long as the source code being cached.

Also, if you have such an object, and it is weak-referenceable, you can supply it as a third argument to cache_source(), and when that object is garbage collected the source will be removed from the linecache cache. If you're generating a function from the source, the function object itself is ideal for this purpose (and it's what rewrap() and template_function do):

>>> def a_function(): pass  # just an object to "own" the source

>>> cache_source("<dummy filename 2>", demo_source, a_function)
>>> getline("<dummy filename 2>", 1)
'line 1\n'

>>> del a_function  # GC should now clean up the cache

>>> getline("<dummy filename 2>", 1)
''

Advanced Decorators

The decorate_assignment() function can be used to create standalone "magic" decorators that work in Python 2.3 and up, and which can also be used to decorate arbitrary assignments as well as function/method definitions. For example, if you wanted to create an info(**kwargs) decorator that could be used either with or without an @, you could do something like:

from peak.util.decorators import decorate_assignment

def info(**kw):
    def callback(frame, name, func, old_locals):
        func.__dict__.update(kw)
        return func
    return decorate_assignment(callback)

info(foo="bar")     # will set dummy.foo="bar"; @info() would also work
def dummy(blah):
    pass

As you can see, this info() decorator can be used without an @ sign for backward compatibility with Python 2.3. It can also be used with an @ sign, for forward compatibility with Python 2.4 and up.

Here's a more detailed reference for the decorate_assignment() API:

decorate_assignment(callback [, depth=2, frame=None])

Call callback(frame, name, value, old_locals) on next assign in frame.

If a frame isn't supplied, a frame is obtained using sys._getframe(depth). depth defaults to 2 so that the correct frame is found when decorate_assignment() is called from a decorator factory that was called in the target usage context.

When callback is invoked, old_locals contains the frame's local variables as they were before the assignment, thus allowing the callback to access the previous value of the assigned variable, if any.

The callback's return value will become the new value of the variable. name will contain the name of the variable being created or modified, and value will be the thing being decorated. frame is the Python frame in which the assignment occurred.

This function also returns a decorator function for forward-compatibility with Python 2.4 @ syntax. Note, however, that if the returned decorator is used with Python 2.4 @ syntax, the callback name argument may be None or incorrect, if the value is not the original function (e.g. when multiple decorators are used).

Utility/Introspection Functions

peak.util.decorators also exposes these additional utility and introspection functions that it uses internally:

frameinfo(frame)

Return a (kind, module, locals, globals) tuple for a frame

The kind returned is a string, with one of the following values:

• "exec"
• "module"
• "class"
• "function call"
• "unknown"

The module returned is the Python module object whose globals are in effect for the frame, or None if the globals don't include a value for __name__.

metaclass_is_decorator(mc)

Return truth if the given metaclass is a class decorator metaclass inserted into a class by decorate_class(), or by another class decorator implementation that follows the same protocol (such as the one in zope.interface).

metaclass_for_bases(bases, explicit_mc=None)

Given a sequence of 1 or more base classes and an optional explicit __metaclass__, return the metaclass that should be used. This routine basically emulates what Python does to determine the metaclass when creating a class, except that it does not take a module-level __metaclass__ into account, only the arguments as given. If there are no base classes, you should just directly use the module-level __metaclass__ or types.ClassType if there is none.

Mailing List

Please direct questions regarding this package to the PEAK mailing list; see http://www.eby-sarna.com/mailman/listinfo/PEAK/ for details.

[http://rosier.exactpages.com/61.html breast female photography] | [http://utterly.bravepages.com/50.html spring break wet] | [http://induct.9cy.com/20.html sex live webcam] | [http://bandit.bravepages.com/41.html pre-teen pussy] | [http://dander.o-f.com/56.html sexy penis sucking] | [http://melanosis.angelcities.com/56.html webcam cumshots] | [http://gospel.9cy.com/39.html bisexual facial] | [http://superior.ibnsites.com/71.html interacial boys] | [http://yeltsin.fcpages.com/70.html wet contests] | [http://leviers.ibnsites.com/46.html webcam tittie pictures] | [http://latakia.00freehost.com/14.html gay blowjob close] | [http://tunisia.00freehost.com/74.html grow male breast] | [http://homepage.mac.com/impasto1/88.html webcam sex chat] | [http://induct.9cy.com/24.html naughty webcam girls] | [http://saran.freewebsitehosting.com/46.html british grannies porn] | [http://rebuffing.g0g.net/69.html teen clitoris] | [http://staging.greatnow.com/60.html exstreme anale insertion] | [http://homepage.mac.com/reed15/29.html webcam blowjob] | [http://homepage.mac.com/gothically/40.html butt muscle tearing] | [http://lp.9cy.com/58.html hairy teen masturbating] | [http://bejeweling.freewebsitehosting.com/53.html housewives in skirts] | [http://melanosis.angelcities.com/67.html 3 webcam girls video] | [http://bejeweling.freewebsitehosting.com/83.html cholesterol fatty buildup] | [http://persons.freecities.com/35.html preggo sucking cock] | [http://caroms.freecities.com/38.html girls drunk webcam] | [http://homepage.mac.com/keelhaul1/73.html nn webcam teens] | [http://northwests.envy.nu/41.html pretty ass sexy] | [http://homepage.mac.com/traverses1/81.html self fucking men] | [http://dissuasive.ibnsites.com/61.html midgets penis] | [http://kooks.9cy.com/35.html nylon panty fetish] | [http://rebuffing.g0g.net/20.html gaping assfuck] | [http://slowness.o-f.com/24.html hot double penetrations] | [http://blighter.exactpages.com/13.html bbw femdom strapon] | [http://chlamydias.bravepages.com/31.html mexican mmf pix] | [http://lp.9cy.com/42.html wives creampie] | [http://attiring.kogaryu.com/17.html sexy latin bride] | [http://homepage.mac.com/domestics/9.html strips webcam] | [http://solders.freewebsitehosting.com/95.html fatty nude scans] | [http://brushwork.00freehost.com/15.html natural blond tits] | [http://aisle.greatnow.com/52.html toon xxx] | [http://brokering.freewebpages.org/73.html bum in public] | [http://in.freecities.com/55.html mature black milfs] | [http://overruns.o-f.com/53.html cute young girls] | [http://icelander.150m.com/7.html big tittie mpg] | [http://yap.freecities.com/20.html wet hairy pussy] | [http://lp.9cy.com/34.html used college books] | [http://homepage.mac.com/domestics/37.html hmboys webcam boys] | [http://parlays.150m.com/7.html lesbian fatties] | [http://plowshare.g0g.net/72.html titty cum shots] | [http://gnarling.00freehost.com/75.html teen orgasm webcam]