diff options
Diffstat (limited to 'documentation.py')
| -rw-r--r-- | documentation.py | 718 |
1 files changed, 393 insertions, 325 deletions
diff --git a/documentation.py b/documentation.py index 10879aa..cdc0685 100644 --- a/documentation.py +++ b/documentation.py @@ -1,11 +1,11 @@ -"""\ +r""" The ``decorator`` module ============================================================= -:author: Michele Simionato +:Author: Michele Simionato :E-mail: michele.simionato@gmail.com -:version: $VERSION ($DATE) -:Requirements: Python 2.4+ +:Version: $VERSION ($DATE) +:Requires: Python 2.4+ :Download page: http://pypi.python.org/pypi/decorator :Installation: ``easy_install decorator`` :License: BSD license @@ -18,7 +18,7 @@ Introduction Python decorators are an interesting example of why syntactic sugar matters. In principle, their introduction in Python 2.4 changed nothing, since they do not provide any new functionality which was not -already present in the language; in practice, their introduction has +already present in the language. In practice, their introduction has significantly changed the way we structure our programs in Python. I believe the change is for the best, and that decorators are a great idea since: @@ -26,22 +26,22 @@ idea since: * decorators help reducing boilerplate code; * decorators help separation of concerns; * decorators enhance readability and maintenability; -* decorators are very explicit. +* decorators are explicit. Still, as of now, writing custom decorators correctly requires some experience and it is not as easy as it could be. For instance, typical implementations of decorators involve nested functions, and we all know that flat is better than nested. -The aim of the ``decorator`` module it to simplify the usage of -decorators for the average programmer, and to popularize decorators -usage giving examples of useful decorators, such as ``memoize``, -``tracing``, etc. +The aim of the ``decorator`` module it to simplify the usage of +decorators for the average programmer, and to popularize decorators by +showing various non-trivial examples. Of course, as all techniques, +decorators can be abused (I have seen that) and you should not try to +solve every problem with a decorator, just because you can. -The core of this module is a decorator factory called ``decorator``. -All decorators discussed here are built as simple recipes on top -of ``decorator``. You may find their source code in the ``documentation.py`` -file. If you execute it, all the examples contained will be doctested. +You may find the source code for all the examples +discussed here in the ``documentation.py`` file, which contains +this documentation in the form of doctests. Definitions ------------------------------------ @@ -49,7 +49,7 @@ Definitions Technically speaking, any Python object which can be called with one argument can be used as a decorator. However, this definition is somewhat too large to be really useful. It is more convenient to split the generic class of -decorators in two groups: +decorators in two subclasses: + *signature-preserving* decorators, i.e. callable objects taking a function as input and returning a function *with the same @@ -66,9 +66,7 @@ are not functions, nor callables. However, signature-preserving decorators are more common and easier to reason about; in particular signature-preserving decorators can be -composed together whereas other -decorators in general cannot (for instance you cannot -meaningfully compose a staticmethod with a classmethod or viceversa). +composed together whereas other decorators in general cannot. Writing signature-preserving decorators from scratch is not that obvious, especially if one wants to define proper decorators that @@ -78,22 +76,26 @@ the issue. Statement of the problem ------------------------------ -A typical decorator is a decorator to memoize functions. -Such a decorator works by caching -the result of a function call in a dictionary, so that the next time +A very common use case for decorators is the memoization of functions. +A ``memoize`` decorator works by caching +the result of the function call in a dictionary, so that the next time the function is called with the same input parameters the result is retrieved from the cache and not recomputed. There are many implementations of ``memoize`` in http://www.python.org/moin/PythonDecoratorLibrary, but they do not preserve the signature. -A simple implementation for Python 2.5 could be the following: +A simple implementation for Python 2.5 could be the following (notice +that in general it is impossible to memoize correctly something +that depends on non-hashable arguments): $$memoize25 -Notice that in general it is impossible to memoize correctly something -that depends on non-hashable arguments. +Here we used the functools.update_wrapper_ utility, which has +been added in Python 2.5 expressly to simplify the definition of decorators +(in older versions of Python you need to copy the function attributes +``__name__``, ``__doc__``, ``__module__`` and ``__dict__`` +from the original function to the decorated function by hand). -Here we used the ``functools.update_wrapper`` utility, which has -been added in Python 2.5 to simplify the definition of decorators. +.. _functools.update_wrapper: http://www.python.org/doc/2.5.2/lib/module-functools.html The implementation above works in the sense that the decorator can accept functions with generic signatures; unfortunately this @@ -103,18 +105,22 @@ general ``memoize25`` returns a function with a Consider for instance the following case: ->>> @memoize25 -... def f1(x): -... time.sleep(1) -... return x +.. code-block:: python + + >>> @memoize25 + ... def f1(x): + ... time.sleep(1) # simulate some long computation + ... return x Here the original function takes a single argument named ``x``, but the decorated function takes any number of arguments and keyword arguments: ->>> from inspect import getargspec ->>> print getargspec(f1) -([], 'args', 'kw', None) +.. code-block:: python + + >>> from inspect import getargspec + >>> print getargspec(f1) + ([], 'args', 'kw', None) This means that introspection tools such as pydoc will give wrong informations about the signature of ``f1``. This is pretty bad: @@ -122,30 +128,35 @@ pydoc will tell you that the function accepts a generic signature ``*args``, ``**kw``, but when you try to call the function with more than an argument, you will get an error: ->>> f1(0, 1) -Traceback (most recent call last): - ... -TypeError: f1() takes exactly 1 argument (2 given) +.. code-block:: python + + >>> f1(0, 1) + Traceback (most recent call last): + ... + TypeError: f1() takes exactly 1 argument (2 given) The solution ----------------------------------------- The solution is to provide a generic factory of generators, which hides the complexity of making signature-preserving decorators -from the application programmer. The ``decorator`` factory -allows to define decorators without the need to use nested functions -or classes. -First of all, you must import ``decorator``: +from the application programmer. The ``decorator`` function in +the ``decorator`` module is such a factory: ->>> from decorator import decorator +.. code-block:: python + + >>> from decorator import decorator -Then you must define a helper function with signature ``(f, *args, **kw)`` -which calls the original function ``f`` with arguments ``args`` and ``kw`` -and implements the tracing capability: +``decorator`` takes two arguments, a caller function describing the +functionality of the decorator and a function to be decorated; it +returns the decorated function. The caller function must have +signature ``(f, *args, **kw)`` and it must call the original function ``f`` +with arguments ``args`` and ``kw``, implementing the wanted capability, +i.e. memoization in this case: $$_memoize -At this point you can define your decorator by means of ``decorator``: +At this point you can define your decorator as follows: $$memoize @@ -153,38 +164,42 @@ The difference with respect to the Python 2.5 approach, which is based on nested functions, is that the decorator module forces you to lift the inner function at the outer level (*flat is better than nested*). Moreover, you are forced to pass explicitly the function you want to -decorate as first argument of the helper function, also know as -the *caller* function, since it calls the original function with the -given arguments. +decorate to the caller function. Here is a test of usage: ->>> @memoize -... def heavy_computation(): -... time.sleep(2) -... return "done" +.. code-block:: python + + >>> @memoize + ... def heavy_computation(): + ... time.sleep(2) + ... return "done" ->>> print heavy_computation() # the first time it will take 2 seconds -done + >>> print heavy_computation() # the first time it will take 2 seconds + done ->>> print heavy_computation() # the second time it will be instantaneous -done + >>> print heavy_computation() # the second time it will be instantaneous + done The signature of ``heavy_computation`` is the one you would expect: ->>> print getargspec(heavy_computation) -([], None, None, None) +.. code-block:: python + + >>> print getargspec(heavy_computation) + ([], None, None, None) A ``trace`` decorator ------------------------------------------------------ -As an additional example, here is how you can define a ``trace`` decorator. +As an additional example, here is how you can define a trivial +``trace`` decorator, which prints a message everytime the traced +function is called: $$_trace $$trace -Then, you can write the following: +Here is an example of usage: .. code-block:: python @@ -194,13 +209,17 @@ Then, you can write the following: It is immediate to verify that ``f1`` works ->>> f1(0) -calling f1 with args (0,), {} +.. code-block:: python + + >>> f1(0) + calling f1 with args (0,), {} and it that it has the correct signature: ->>> print getargspec(f1) -(['x'], None, None, None) +.. code-block:: python + + >>> print getargspec(f1) + (['x'], None, None, None) The same decorator works with functions of any signature: @@ -235,91 +254,49 @@ in Python 2.6 and removed in Python 3.0. ``decorator`` is a decorator --------------------------------------------- -It may be annoying to be forced to write a caller function (like the ``_trace`` +It may be annoying to write a caller function (like the ``_trace`` function above) and then a trivial wrapper (``def trace(f): return decorator(_trace, f)``) every time. For this reason, the ``decorator`` module provides an easy shortcut to convert the caller function into a signature-preserving decorator: -you can call ``decorator`` with a single argument and you will get out -your decorator: ``trace = decorator(_trace)``. -That means that the ``decorator`` function can be used as a signature-changing +you can just call ``decorator`` with a single argument. +In our example you can just write ``trace = decorator(_trace)``. +The ``decorator`` function can also be used as a signature-changing decorator, just as ``classmethod`` and ``staticmethod``. However, ``classmethod`` and ``staticmethod`` return generic objects which are not callable, while ``decorator`` returns signature-preserving decorators, i.e. functions of a single argument. For instance, you can write directly ->>> @decorator -... def trace(f, *args, **kw): -... print "calling %s with args %s, %s" % (f.func_name, args, kw) -... return f(*args, **kw) +.. code-block:: python + + >>> @decorator + ... def trace(f, *args, **kw): + ... print "calling %s with args %s, %s" % (f.func_name, args, kw) + ... return f(*args, **kw) and now ``trace`` will be a decorator. You can easily check that the signature has changed: ->>> print getargspec(trace) -(['f'], None, None, None) +.. code-block:: python + + >>> print getargspec(trace) + (['f'], None, None, None) Therefore now ``trace`` can be used as a decorator and the following will work: ->>> @trace -... def func(): pass +.. code-block:: python + + >>> @trace + ... def func(): pass ->>> func() -calling func with args (), {} + >>> func() + calling func with args (), {} For the rest of this document, I will discuss examples of useful decorators built on top of ``decorator``. -``async`` --------------------------------------------- - -Here I show a decorator -which is able to convert a blocking procedure into an asynchronous -procedure. The procedure, when called, -is executed in a separate thread. The implementation is not difficult: - -$$_async -$$async - -``async`` as intended to be used on procedures, i.e. -on functions returning ``None``, since the return value of the original -function is discarded by this implementation. The decorated function returns -the current execution thread, which can be stored and checked later, for -instance to verify that the thread ``.isAlive()``. - -Here is an example of usage. Suppose one wants to write some data to -an external resource which can be accessed by a single user at once -(for instance a printer). Then the access to the writing function must -be locked. Here is a minimalistic example: - ->>> datalist = [] # for simplicity the written data are stored into a list. - ->>> @async -... def write(data): -... # append data to the datalist by locking -... with threading.Lock(): -... time.sleep(1) # emulate some long running operation -... datalist.append(data) -... # other operations not requiring a lock here - -Each call to ``write`` will create a new writer thread, but there will -be no synchronization problems since ``write`` is locked. - ->>> write("data1") -<Thread(write-1, started)> - ->>> time.sleep(.1) # wait a bit, so we are sure data2 is written after data1 - ->>> write("data2") -<Thread(write-2, started)> - ->>> time.sleep(2) # wait for the writers to complete - ->>> print datalist -['data1', 'data2'] - ``blocking`` ------------------------------------------- @@ -331,8 +308,7 @@ $$blocking (notice that without the help of ``decorator``, an additional level of nesting would have been needed). This is actually an example -of a one-parameter family of decorators where the -"busy message" is the parameter. +of a one-parameter family of decorators. Functions decorated with ``blocking`` will return a busy message if the resource is unavailable, and the intended result if the resource is @@ -360,101 +336,189 @@ available. For instance: >>> print read_data() some data -decorator factories --------------------------------------------------------------------- - -We have just seen an example -of a simple decorator factories, implemented as a function returning a -decorator. For more complex situations, it is more convenient to -implement decorator factories as classes returning callable objects -that can be used as signature-preserving decorators. +``async`` +-------------------------------------------- -To give an example of usage, let me -show a (simplistic) permission system based on classes. -Suppose we have a (Web) framework with the following user classes: +We have just seen an examples of a simple decorator factory, +implemented as a function returning a decorator. +For more complex situations, it is more +convenient to implement decorator factories as classes returning +callable objects that can be used as signature-preserving +decorators. The suggested pattern to do that is to introduce +a helper method ``call(self, func, *args, **kw)`` and to call +it in the ``__call__(self, func)`` method. + +As an example, here I show a decorator +which is able to convert a blocking function into an asynchronous +function. The function, when called, +is executed in a separate thread. Moreover, it is possible to set +three callbacks ``on_success``, ``on_failure`` and ``on_closing``, +to specify how to manage the function call. +The implementation is the following: + +$$on_success +$$on_failure +$$on_closing +$$Async + +The decorated function returns +the current execution thread, which can be stored and checked later, for +instance to verify that the thread ``.isAlive()``. -$$User -$$PowerUser -$$Admin +Here is an example of usage. Suppose one wants to write some data to +an external resource which can be accessed by a single user at once +(for instance a printer). Then the access to the writing function must +be locked. Here is a minimalistic example: -Suppose we have a function ``get_userclass`` returning the class of -the user logged in our system: in a Web framework ``get_userclass`` -will read the current user from the environment (i.e. from REMOTE_USER) -and will compare it with a database table to determine her user class. -For the sake of the example, let us use a trivial function: +.. code-block:: python -$$get_userclass - -We can implement the ``Restricted`` decorator factory as follows: + >>> async = Async(threading.Thread) -$$Restricted -$$PermissionError + >>> datalist = [] # for simplicity the written data are stored into a list. -An user can perform different actions according to her class: + >>> @async + ... def write(data): + ... # append data to the datalist by locking + ... with threading.Lock(): + ... time.sleep(1) # emulate some long running operation + ... datalist.append(data) + ... # other operations not requiring a lock here -$$Action +Each call to ``write`` will create a new writer thread, but there will +be no synchronization problems since ``write`` is locked. -Here is an example of usage:: +>>> write("data1") +<Thread(write-1, started)> - >>> a = Action() - >>> a.view() - >>> a.insert() - Traceback (most recent call last): - ... - PermissionError: User does not have the permission to run insert! - >>> a.delete() - Traceback (most recent call last): - ... - PermissionError: User does not have the permission to run delete! +>>> time.sleep(.1) # wait a bit, so we are sure data2 is written after data1 -A ``PowerUser`` could call ``.insert`` but not ``.delete``, whereas -and ``Admin`` can call all the methods. +>>> write("data2") +<Thread(write-2, started)> -I could have provided the same functionality by means of a mixin class -(say ``DecoratorMixin``) providing a ``__call__`` method. Within -that design an user should have derived his decorator class from -``DecoratorMixin``. However, `I generally dislike inheritance`_ -and I do not want to force my users to inherit from a class of my -choice. Using the class decorator approach my user is free to use -any class she wants, inheriting from any class she wants, provided -the class provide a proper ``.call`` method and does not provide -a custom ``__call__`` method. In other words, I am trading (less stringent) -interface requirements for (more stringent) inheritance requirements. +>>> time.sleep(2) # wait for the writers to complete -.. _I generally dislike inheritance: http://stacktrace.it/articoli/2008/06/i-pericoli-della-programmazione-con-i-mixin1 +>>> print datalist +['data1', 'data2'] The ``FunctionMaker`` class --------------------------------------------------------------- -The public API of the ``decorator`` module consists in the -``decorator`` function and its two attributes ``decorator`` and -``decorator_apply``. Internally, the functionality is implemented via +You may wonder about how the functionality of the ``decorator`` module +is implemented. The basic building block is a ``FunctionMaker`` class which is able to generate on the fly -functions with a given name and signature. You should not need to -resort to ``FunctionMaker`` when writing ordinary decorators, but it -is interesting to know how the module works internally, so I have -decided to add this paragraph. Notice that while I do not have plan +functions with a given name and signature from a function template +passed as a string. Generally speaking, you should not need to +resort to ``FunctionMaker`` when writing ordinary decorators, but +it is handy in some circumstances. We will see an example in two +paragraphs, when implementing a custom decorator factory +(``decorator_apply``). + +Notice that while I do not have plans to change or remove the functionality provided in the ``FunctionMaker`` class, I do not guarantee that it will stay -unchanged forever. On the other hand, the functionality provided by +unchanged forever. For instance, right now I am using the traditional +string interpolation syntax for function templates, but Python 2.6 +and Python 3.0 provide a newer interpolation syntax and I may use +the new syntax in the future. +On the other hand, the functionality provided by ``decorator`` has been there from version 0.1 and it is guaranteed to stay there forever. -``FunctionMaker`` takes the name and the signature of a function in -input, or a whole function. Here is an example of how to -restrict the signature of a function: + +``FunctionMaker`` takes the name and the signature (as a string) of a +function in input, or a whole function. Then, it creates a new +function (actually a closure) from a function template (the function +template must begin with ``def`` with no comments before and you cannot +use a ``lambda``) via its +``.make`` method: the name and the signature of the resulting function +are determinated by the specified name and signature. For instance, +here is an example of how to restrict the signature of a function: .. code-block:: python - >>> def f(*args, **kw): + >>> def f(*args, **kw): # a function with a generic signature ... print args, kw - >>> f1 = FunctionMaker(name="f1", signature="a,b").make(''' + >>> fun = FunctionMaker(name="f1", signature="a,b") + >>> f1 = fun.make('''\ ... def %(name)s(%(signature)s): ... f(%(signature)s)''', dict(f=f)) - + ... >>> f1(1,2) (1, 2) {} +The dictionary passed in this example (``dict(f=f)``) is the +execution environment: ``FunctionMaker.make`` actually returns a +closure, and the original function ``f`` is a variable in the +closure environment. +``FunctionMaker.make`` also accepts keyword arguments and such +arguments are attached to the resulting function. This is useful +if you want to set some function attributes, for instance the +docstring ``__doc__``. + +For debugging/introspection purposes it may be useful to see +the source code of the generated function; to do that, just +pass the flag ``addsource=True`` and a ``__source__`` attribute will +be added to the decorated function: + +.. code-block:: python + + >>> f1 = fun.make('''\ + ... def %(name)s(%(signature)s): + ... f(%(signature)s)''', dict(f=f), addsource=True) + ... + >>> print f1.__source__ + def f1(a,b): + f(a,b) + <BLANKLINE> + +Getting the source code +--------------------------------------------------- + +Internally ``FunctionMaker.make`` uses ``exec`` to generate the +decorated function. Therefore +``inspect.getsource`` will not work for decorated functions. That +means that the usual '??' trick in IPython will give you the (right on +the spot) message ``Dynamically generated function. No source code +available``. In the past I have considered this acceptable, since +``inspect.getsource`` does not really work even with regular +decorators. In that case ``inspect.getsource`` gives you the wrapper +source code which is probably not what you want: + +$$identity_dec + +.. code-block:: python + + @identity_dec + def example(): pass + + >>> print getsource(example) + def wrapper(*args, **kw): + return func(*args, **kw) + <BLANKLINE> + +(see bug report 1764286_ for an explanation of what is happening). +Unfortunately the bug is still there, even in Python 2.6 and 3.0. +There is however a workaround. The decorator module adds an +attribute ``.undecorated`` to the decorated function, containing +a reference to the original function. The easy way to get +the source code is to call ``inspect.getsource`` on the +undecorated function: + +.. code-block:: python + + >>> print getsource(factorial.undecorated) + @tail_recursive + def factorial(n, acc=1): + "The good old factorial" + if n == 0: return acc + return factorial(n-1, n*acc) + <BLANKLINE> + +.. _1764286: http://bugs.python.org/issue1764286 + +Dealing with third party decorators +----------------------------------------------------------------- + Sometimes you find on the net some cool decorator that you would like to include in your code. However, more often than not the cool decorator is not signature-preserving. Therefore you may want an easy way to @@ -464,15 +528,16 @@ having to rewrite them in terms of ``decorator``. You can use a $$decorator_apply +``decorator_apply`` sets the attribute ``.undecorated`` of the generated +function to the original function, so that you can get the right +source code. + Notice that I am not providing this functionality in the ``decorator`` -module directly since I think it is best to rewrite a decorator rather +module directly since I think it is best to rewrite the decorator rather than adding an additional level of indirection. However, practicality beats purity, so you can add ``decorator_apply`` to your toolbox and use it if you need to. -``tail-recursive`` ------------------------------------------------------------- - In order to give an example of usage of ``decorator_apply``, I will show a pretty slick decorator that converts a tail-recursive function in an iterative function. I have shamelessly stolen the basic idea from Kay Schluehr's recipe @@ -488,13 +553,9 @@ $$tail_recursive Here is how you apply the upgraded decorator to the good old factorial: -.. code-block:: python +$$factorial - @tail_recursive - def factorial(n, acc=1): - "The good old factorial" - if n == 0: return acc - return factorial(n-1, n*acc) +.. code-block:: python >>> print factorial(4) 24 @@ -503,63 +564,14 @@ This decorator is pretty impressive, and should give you some food for your mind ;) Notice that there is no recursion limit now, and you can easily compute ``factorial(1001)`` or larger without filling the stack frame. Notice also that the decorator will not work on functions which -are not tail recursive, such as +are not tail recursive, such as the following $$fact -(a function is tail recursive if it either returns a value without +(reminder: a function is tail recursive if it either returns a value without making a recursive call, or returns directly the result of a recursive call). -Getting the source code ---------------------------------------------------- - -Iinternally the decorator module uses ``exec`` to generate the decorated -function with the right signature. Therefore the ordinary -``inspect.getsource`` will not work for decorated -functions. This means that the usual '??' trick in IPython will give you -the (right on the spot) message -``Dynamically generated function. No source code available.``. -In the past I have considered this acceptable, since ``inspect.getsource`` -does not really work even with regular decorators. In that case -``inspect.getsource`` gives you the wrapper source code which is probably -not what you want: - -$$identity_dec -$$example - ->>> import inspect ->>> print inspect.getsource(example) - def wrapper(*args, **kw): - return func(*args, **kw) -<BLANKLINE> - -(see bug report 1764286_ for an explanation of what is happening). -Unfortunately the bug is still there, even in Python 2.6 and 3.0. -There is however a workaround. The decorator module adds an -attribute ``.undecorated`` to the decorated function, containing -a reference to the original function. The easy way to get -the source code is to call ``inspect.getsource`` on the -undecorated function: - ->>> print inspect.getsource(factorial.undecorated) -@tail_recursive -def factorial(n, acc=1): - "The good old factorial" - if n == 0: return acc - return factorial(n-1, n*acc) -<BLANKLINE> - -.. _1764286: http://bugs.python.org/issue1764286 - -Starting from release 3.0, the decorator module also adds -a ``__source__`` attribute to the decorated function. - -The generated function is a closure depending on the the caller -``_call_`` and the original function ``_func_``. For debugging convenience -you get the names of the moduled where they are defined in a comment: -in this example they are defined in the ``__main__`` module. - Caveats and limitations ------------------------------------------- @@ -585,12 +597,12 @@ The worse case is shown by the following example:: pass " "f()" -On my Linux system, using the ``do_nothing`` decorator instead of the -plain function is more than four times slower:: +On my MacBook, using the ``do_nothing`` decorator instead of the +plain function is more than three times slower:: - $ bash performance.sh - 1000000 loops, best of 3: 1.68 usec per loop - 1000000 loops, best of 3: 0.397 usec per loop + $ bash performance.sh + 1000000 loops, best of 3: 0.995 usec per loop + 1000000 loops, best of 3: 0.273 usec per loop It should be noted that a real life function would probably do something more useful than ``f`` here, and therefore in real life the @@ -601,23 +613,26 @@ a penalty in your specific use case is to measure it. You should be aware that decorators will make your tracebacks longer and more difficult to understand. Consider this example: ->>> @trace -... def f(): -... 1/0 +.. code-block:: python + + >>> @trace + ... def f(): + ... 1/0 Calling ``f()`` will give you a ``ZeroDivisionError``, but since the function is decorated the traceback will be longer: ->>> f() -Traceback (most recent call last): - File "<stdin>", line 1, in ? - f() - File "<string>", line 2, in f - File "<stdin>", line 4, in trace - return f(*args, **kw) - File "<stdin>", line 3, in f - 1/0 -ZeroDivisionError: integer division or modulo by zero +.. code-block:: python + + >>> f() + calling f with args (), {} + Traceback (most recent call last): + File "<stdin>", line 1, in <module> + File "<string>", line 2, in f + File "documentation.py", line 799, in _trace + return f(*args, **kw) + File "<stdin>", line 3, in f + ZeroDivisionError: integer division or modulo by zero You see here the inner call to the decorator ``trace``, which calls ``f(*args, **kw)``, and a reference to ``File "<string>", line 2, in f``. @@ -633,8 +648,8 @@ add an hook to make it possible to change their signature directly. That could happen in future versions of Python (see PEP 362_) and then the decorator module would become obsolete. However, at present, even in Python 3.0 it is impossible to change the function signature -directly, therefore the ``decorator`` module is still useful (this is -the reason why I am releasing version 3.0). +directly, therefore the ``decorator`` module is still useful. +Actually, this is one of the main reasons why I am releasing version 3.0. .. _362: http://www.python.org/dev/peps/pep-0362 @@ -642,49 +657,54 @@ In the present implementation, decorators generated by ``decorator`` can only be used on user-defined Python functions or methods, not on generic callable objects, nor on built-in functions, due to limitations of the ``inspect`` module in the standard library. - -Moreover, you can decorate anonymous functions: - ->>> trace(lambda : None)() -calling <lambda> with args (), {} There is a restriction on the names of the arguments: for instance, if try to call an argument ``_call_`` or ``_func_`` you will get a ``NameError``: ->>> @trace -... def f(_func_): print f -... -Traceback (most recent call last): - ... -NameError: _func_ is overridden in -def f(_func_): - return _call_(_func_, _func_) +.. code-block:: python + + >>> @trace + ... def f(_func_): print f + ... + Traceback (most recent call last): + ... + NameError: _func_ is overridden in + def f(_func_): + return _call_(_func_, _func_) Finally, the implementation is such that the decorated function contains -a copy of the original function attributes: +a *copy* of the original function dictionary +(``vars(decorated_f) is not vars(f)``): ->>> def f(): pass # the original function ->>> f.attr1 = "something" # setting an attribute ->>> f.attr2 = "something else" # setting another attribute +.. code-block:: python ->>> traced_f = trace(f) # the decorated function + >>> def f(): pass # the original function + >>> f.attr1 = "something" # setting an attribute + >>> f.attr2 = "something else" # setting another attribute ->>> traced_f.attr1 -'something' ->>> traced_f.attr2 = "something different" # setting attr ->>> f.attr2 # the original attribute did not change -'something else' + >>> traced_f = trace(f) # the decorated function -Backward compatibility notes + >>> traced_f.attr1 + 'something' + >>> traced_f.attr2 = "something different" # setting attr + >>> f.attr2 # the original attribute did not change + 'something else' + +Compatibility notes --------------------------------------------------------------- Version 3.0 is a complete rewrite of the original implementation. It is mostly compatible with the past, a part for a few differences. -The utilites ``get_info`` and ``new_wrapper``, available +First of all, the utilites ``get_info`` and ``new_wrapper``, available in the 2.X versions, have been deprecated and they will be removed in the future. For the moment, using them raises a ``DeprecationWarning``. +Incidentally, the functionality has been implemented through a +decorator which makes a good example for this documentation: + +$$deprecated + ``get_info`` has been removed since it was little used and since it had to be changed anyway to work with Python 3.0; ``new_wrapper`` has been removed since it was useless: its major use case (converting @@ -695,24 +715,32 @@ and the other use case can be managed with the ``FunctionMaker``. Finally ``decorator`` cannot be used as a class decorator and the `functionality introduced in version 2.3`_ has been removed. That means that in order to define decorator factories with classes you -need to override the ``__call__`` method explicitly (no magic anymore). +need to define the ``__call__`` method explicitly (no magic anymore). All these changes should not cause any trouble, since they were -all rarely used features. Should you have trouble, you are invited to +all rarely used features. Should you have any trouble, you can always downgrade to the 2.3 version. -.. _functionality introduced in version 2.3: http://www.phyast.pitt.edu/~micheles/python/documentation.html#class-decorators-and-decorator-factories - -Python 3.0 support ------------------------------------------------------------- - The examples shown here have been tested with Python 2.5. Python 2.4 is also supported - of course the examples requiring the ``with`` -statement will not work there - as well as Python 2.5. Python 3.0 -is supported too. Simply run the script ``2to3`` on the module +statement will not work there. Python 2.6 works fine, but if you +run the examples here in the interactive interpreter +you will notice a couple of minor differences since +``getargspec`` returns an ``ArgSpec`` namedtuple instead of a regular +tuple, and the string representation of a thread object returns a +thread identifier number. That means that running the file +``documentation.py`` under Python 2.5 will a few errors, but +they are not serious. Python 3.0 is kind of supported too. +Simply run the script ``2to3`` on the module ``decorator.py`` and you will get a version of the code running -with Python 3.0. Notice however that the decorator module is little -tested with Python 3.0, since I mostly use Python 2.5. +with Python 3.0 (at least, I did some simple checks and it seemed +to work). However there is no support for `function annotations`_ yet +since it seems premature at this moment (most people are +still using Python 2.5). + +.. _functionality introduced in version 2.3: http://www.phyast.pitt.edu/~micheles/python/documentation.html#class-decorators-and-decorator-factories +.. _function annotations: http://www.python.org/dev/peps/pep-3107/ + LICENCE --------------------------------------------- @@ -746,7 +774,11 @@ note, just to gratify my ego. On the other hand, if you use this software and you are unhappy with it, send me a patch! """ from __future__ import with_statement -import sys, threading, time, functools, inspect, itertools +import sys, threading, time, functools, inspect, itertools +try: + import multiprocessing +except ImportError: + import processing as multiprocessing from decorator import * from setup import VERSION @@ -768,17 +800,54 @@ def _trace(f, *args, **kw): def trace(f): return decorator(_trace, f) -def _async(proc, *args, **kw): - name = '%s-%s' % (proc.__name__, proc.counter.next()) - thread = threading.Thread(None, proc, name, args, kw) - thread.start() - return thread +def on_success(result): # default implementation + "Called on the result of the function" + return result + +def on_failure(exc_info): # default implementation + "Called if the function fails" + pass + +def on_closing(): # default implementation + "Called at the end, both in case of success and failure" + pass + +class Async(object): + """ + A decorator converting blocking functions into asynchronous + functions, by using threads or processes. Examples: + + async_with_threads = Async(threading.Thread) + async_with_processes = Async(multiprocessing.Process) + """ + + def __init__(self, threadfactory): + self.threadfactory = threadfactory + + def __call__(self, func, on_success=on_success, + on_failure=on_failure, on_closing=on_closing): + # every decorated function has its own independent thread counter + func.counter = itertools.count(1) + func.on_success = on_success + func.on_failure = on_failure + func.on_closing = on_closing + return decorator(self.call, func) + + def call(self, func, *args, **kw): + def func_wrapper(): + try: + result = func(*args, **kw) + except: + func.on_failure(sys.exc_info()) + else: + return func.on_success(result) + finally: + func.on_closing() + name = '%s-%s' % (func.__name__, func.counter.next()) + thread = self.threadfactory(None, func_wrapper, name) + thread.start() + return thread -def async(proc): - # every decorated procedure has its own independent thread counter - proc.counter = itertools.count(1) - return decorator(_async, proc) - def identity_dec(func): def wrapper(*args, **kw): return func(*args, **kw) @@ -790,7 +859,7 @@ def example(): pass def memoize25(func): func.cache = {} def memoize(*args, **kw): - if kw: + if kw: # frozenset is used to ensure hashability key = args, frozenset(kw.iteritems()) else: key = args @@ -803,12 +872,11 @@ def memoize25(func): return functools.update_wrapper(memoize, func) def _memoize(func, *args, **kw): - # args and kw must be hashable - if kw: + if kw: # frozenset is used to ensure hashability key = args, frozenset(kw.iteritems()) else: key = args - cache = func.cache + cache = func.cache # attributed added by memoize if key in cache: return cache[key] else: |