File: documentation.html

package info (click to toggle)
python-decorator 2.2.0-2
links: PTS, VCS
area: main
in suites: lenny
size: 280 kB
ctags: 58
sloc: python: 129; makefile: 46; sh: 13
file content (949 lines) | stat: -rw-r--r-- 63,398 bytes
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.4.1: http://docutils.sourceforge.net/" />
<title>The decorator module</title>
<meta name="author" content="Michele Simionato" />
<style type="text/css">

.highlight{ background: #f2f2f2; }
.highlight .c { color: #008800; font-style: italic } /* Comment */
.highlight .err { border: 1px solid #FF0000 } /* Error */
.highlight .k { color: #AA22FF; font-weight: bold } /* Keyword */
.highlight .o { color: #666666 } /* Operator */
.highlight .cm { color: #008800; font-style: italic } /* Comment.Multiline */
.highlight .cp { color: #008800 } /* Comment.Preproc */
.highlight .c1 { color: #008800; font-style: italic } /* Comment.Single */
.highlight .gd { color: #A00000 } /* Generic.Deleted */
.highlight .ge { font-style: italic } /* Generic.Emph */
.highlight .gr { color: #FF0000 } /* Generic.Error */
.highlight .gh { color: #000080; font-weight: bold } /* Generic.Heading */
.highlight .gi { color: #00A000 } /* Generic.Inserted */
.highlight .go { color: #808080 } /* Generic.Output */
.highlight .gp { color: #000080; font-weight: bold } /* Generic.Prompt */
.highlight .gs { font-weight: bold } /* Generic.Strong */
.highlight .gu { color: #800080; font-weight: bold } /* Generic.Subheading */
.highlight .gt { color: #0040D0 } /* Generic.Traceback */
.highlight .kc { color: #AA22FF; font-weight: bold } /* Keyword.Constant */
.highlight .kd { color: #AA22FF; font-weight: bold } /* Keyword.Declaration */
.highlight .kp { color: #AA22FF } /* Keyword.Pseudo */
.highlight .kr { color: #AA22FF; font-weight: bold } /* Keyword.Reserved */
.highlight .kt { color: #AA22FF; font-weight: bold } /* Keyword.Type */
.highlight .m { color: #666666 } /* Literal.Number */
.highlight .s { color: #BB4444 } /* Literal.String */
.highlight .na { color: #BB4444 } /* Name.Attribute */
.highlight .nb { color: #AA22FF } /* Name.Builtin */
.highlight .nc { color: #0000FF } /* Name.Class */
.highlight .no { color: #880000 } /* Name.Constant */
.highlight .nd { color: #AA22FF } /* Name.Decorator */
.highlight .ni { color: #999999; font-weight: bold } /* Name.Entity */
.highlight .ne { color: #D2413A; font-weight: bold } /* Name.Exception */
.highlight .nf { color: #00A000 } /* Name.Function */
.highlight .nl { color: #A0A000 } /* Name.Label */
.highlight .nn { color: #0000FF; font-weight: bold } /* Name.Namespace */
.highlight .nt { color: #008000; font-weight: bold } /* Name.Tag */
.highlight .nv { color: #B8860B } /* Name.Variable */
.highlight .ow { color: #AA22FF; font-weight: bold } /* Operator.Word */
.highlight .mf { color: #666666 } /* Literal.Number.Float */
.highlight .mh { color: #666666 } /* Literal.Number.Hex */
.highlight .mi { color: #666666 } /* Literal.Number.Integer */
.highlight .mo { color: #666666 } /* Literal.Number.Oct */
.highlight .sb { color: #BB4444 } /* Literal.String.Backtick */
.highlight .sc { color: #BB4444 } /* Literal.String.Char */
.highlight .sd { color: #BB4444; font-style: italic } /* Literal.String.Doc */
.highlight .s2 { color: #BB4444 } /* Literal.String.Double */
.highlight .se { color: #BB6622; font-weight: bold } /* Literal.String.Escape */
.highlight .sh { color: #BB4444 } /* Literal.String.Heredoc */
.highlight .si { color: #BB6688; font-weight: bold } /* Literal.String.Interpol */
.highlight .sx { color: #008000 } /* Literal.String.Other */
.highlight .sr { color: #BB6688 } /* Literal.String.Regex */
.highlight .s1 { color: #BB4444 } /* Literal.String.Single */
.highlight .ss { color: #B8860B } /* Literal.String.Symbol */
.highlight .bp { color: #AA22FF } /* Name.Builtin.Pseudo */
.highlight .vc { color: #B8860B } /* Name.Variable.Class */
.highlight .vg { color: #B8860B } /* Name.Variable.Global */
.highlight .vi { color: #B8860B } /* Name.Variable.Instance */
.highlight .il { color: #666666 } /* Literal.Number.Integer.Long */

</style>
</head>
<body>
<div class="document" id="the-decorator-module">
<h1 class="title">The <tt class="docutils literal"><span class="pre">decorator</span></tt> module</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<col class="docinfo-content" />
<tbody valign="top">
<tr><th class="docinfo-name">Author:</th>
<td>Michele Simionato</td></tr>
<tr class="field"><th class="docinfo-name">E-mail:</th><td class="field-body"><a class="reference" href="mailto:michele.simionato&#64;gmail.com">michele.simionato&#64;gmail.com</a></td>
</tr>
<tr><th class="docinfo-name">Version:</th>
<td>2.2.0 (31 July 2007)</td></tr>
<tr class="field"><th class="docinfo-name">Download page:</th><td class="field-body"><a class="reference" href="http://www.phyast.pitt.edu/~micheles/python/decorator-2.2.0.zip">http://www.phyast.pitt.edu/~micheles/python/decorator-2.2.0.zip</a></td>
</tr>
<tr class="field"><th class="docinfo-name">Installation:</th><td class="field-body"><tt class="docutils literal"><span class="pre">easy_install</span> <span class="pre">decorator</span></tt></td>
</tr>
<tr class="field"><th class="docinfo-name">License:</th><td class="field-body">BSD license</td>
</tr>
</tbody>
</table>
<div class="contents topic">
<p class="topic-title first"><a id="contents" name="contents">Contents</a></p>
<ul class="simple">
<li><a class="reference" href="#introduction" id="id5" name="id5">Introduction</a></li>
<li><a class="reference" href="#definitions" id="id6" name="id6">Definitions</a></li>
<li><a class="reference" href="#statement-of-the-problem" id="id7" name="id7">Statement of the problem</a></li>
<li><a class="reference" href="#the-solution" id="id8" name="id8">The solution</a></li>
<li><a class="reference" href="#decorator-is-a-decorator" id="id9" name="id9"><tt class="docutils literal"><span class="pre">decorator</span></tt> is a decorator</a></li>
<li><a class="reference" href="#memoize" id="id10" name="id10"><tt class="docutils literal"><span class="pre">memoize</span></tt></a></li>
<li><a class="reference" href="#locked" id="id11" name="id11"><tt class="docutils literal"><span class="pre">locked</span></tt></a></li>
<li><a class="reference" href="#delayed-and-threaded" id="id12" name="id12"><tt class="docutils literal"><span class="pre">delayed</span></tt> and <tt class="docutils literal"><span class="pre">threaded</span></tt></a></li>
<li><a class="reference" href="#blocking" id="id13" name="id13"><tt class="docutils literal"><span class="pre">blocking</span></tt></a></li>
<li><a class="reference" href="#redirecting-stdout" id="id14" name="id14"><tt class="docutils literal"><span class="pre">redirecting_stdout</span></tt></a></li>
<li><a class="reference" href="#dealing-with-third-party-decorators-new-wrapper" id="id15" name="id15">Dealing with third party decorators: <tt class="docutils literal"><span class="pre">new_wrapper</span></tt></a></li>
<li><a class="reference" href="#tail-recursive" id="id16" name="id16"><tt class="docutils literal"><span class="pre">tail_recursive</span></tt></a></li>
<li><a class="reference" href="#caveats-and-limitations" id="id17" name="id17">Caveats and limitations</a></li>
<li><a class="reference" href="#licence" id="id18" name="id18">LICENCE</a></li>
</ul>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id5" id="introduction" name="introduction">Introduction</a></h1>
<p>Python 2.4 decorators are an interesting example of why syntactic sugar
matters: in principle, their introduction changed nothing, since they do
not provide any new functionality which was not 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:</p>
<ul class="simple">
<li>decorators help reducing boilerplate code;</li>
<li>decorators help separation of concerns;</li>
<li>decorators enhance readability and maintenability;</li>
<li>decorators are very explicit.</li>
</ul>
<p>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.</p>
<p>The aim of the <tt class="docutils literal"><span class="pre">decorator</span></tt> module it to simplify the usage of
decorators for the average programmer, and to popularize decorators
usage giving examples of useful decorators, such as <tt class="docutils literal"><span class="pre">memoize</span></tt>,
<tt class="docutils literal"><span class="pre">tracing</span></tt>, <tt class="docutils literal"><span class="pre">redirecting_stdout</span></tt>, <tt class="docutils literal"><span class="pre">locked</span></tt>, etc.</p>
<p>The core of this module is a decorator factory called <tt class="docutils literal"><span class="pre">decorator</span></tt>.
All decorators discussed here are built as simple recipes on top
of  <tt class="docutils literal"><span class="pre">decorator</span></tt>. You may find their source code in the <tt class="docutils literal"><span class="pre">_main.py</span></tt>
file, which is generated automatically when you run the doctester
(included into the decorator package) on this documentation:</p>
<pre class="literal-block">
$ python doctester.py documentation.txt
</pre>
<p>At the same time the doctester runs all the examples contained here as
test cases.</p>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id6" id="definitions" name="definitions">Definitions</a></h1>
<p>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:</p>
<ul class="simple">
<li><em>signature-preserving</em> decorators, i.e. callable objects taking a
function as input and returning a function <em>with the same
signature</em> as output;</li>
<li><em>signature-changing</em> decorators, i.e. decorators that change
the signature of their input function, or decorators returning
non-callable objects.</li>
</ul>
<p>Signature-changing decorators have their use: for instance the
builtin classes <tt class="docutils literal"><span class="pre">staticmethod</span></tt> and <tt class="docutils literal"><span class="pre">classmethod</span></tt> are in this
group, since they take functions and return descriptor objects which
are not functions, nor callables.</p>
<p>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).</p>
<p>Writing signature-preserving decorators from scratch is not that
obvious, especially if one wants to define proper decorators that
can accept functions with any signature. A simple example will clarify
the issue.</p>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id7" id="statement-of-the-problem" name="statement-of-the-problem">Statement of the problem</a></h1>
<p>Suppose you want to trace a function: this is a typical use case
for a decorator and you can find in many places code like this:</p>
<div class="codeblock python">
<div class="highlight" ><pre><span class="c">#&lt;_main.py&gt;</span>

<span class="k">try</span><span class="p">:</span>
    <span class="k">from</span> <span class="nn">functools</span> <span class="k">import</span> <span class="n">update_wrapper</span>
<span class="k">except</span> <span class="ne">ImportError</span><span class="p">:</span> <span class="c"># using Python version &lt; 2.5</span>
    <span class="k">def</span> <span class="nf">decorator_trace</span><span class="p">(</span><span class="n">f</span><span class="p">):</span>
        <span class="k">def</span> <span class="nf">newf</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kw</span><span class="p">):</span>
           <span class="k">print</span> <span class="s">&quot;calling </span><span class="si">%s</span><span class="s"> with args </span><span class="si">%s</span><span class="s">, </span><span class="si">%s</span><span class="s">&quot;</span> <span class="o">%</span> <span class="p">(</span><span class="n">f</span><span class="o">.</span><span class="n">__name__</span><span class="p">,</span> <span class="n">args</span><span class="p">,</span> <span class="n">kw</span><span class="p">)</span>
           <span class="k">return</span> <span class="n">f</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kw</span><span class="p">)</span>
        <span class="n">newf</span><span class="o">.</span><span class="n">__name__</span> <span class="o">=</span> <span class="n">f</span><span class="o">.</span><span class="n">__name__</span>
        <span class="n">newf</span><span class="o">.</span><span class="n">__dict__</span><span class="o">.</span><span class="n">update</span><span class="p">(</span><span class="n">f</span><span class="o">.</span><span class="n">__dict__</span><span class="p">)</span>
        <span class="n">newf</span><span class="o">.</span><span class="n">__doc__</span> <span class="o">=</span> <span class="n">f</span><span class="o">.</span><span class="n">__doc__</span>
        <span class="n">newf</span><span class="o">.</span><span class="n">__module__</span> <span class="o">=</span> <span class="n">f</span><span class="o">.</span><span class="n">__module__</span>
        <span class="k">return</span> <span class="n">newf</span>
<span class="k">else</span><span class="p">:</span> <span class="c"># using Python 2.5+</span>
    <span class="k">def</span> <span class="nf">decorator_trace</span><span class="p">(</span><span class="n">f</span><span class="p">):</span>
        <span class="k">def</span> <span class="nf">newf</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kw</span><span class="p">):</span>
            <span class="k">print</span> <span class="s">&quot;calling </span><span class="si">%s</span><span class="s"> with args </span><span class="si">%s</span><span class="s">, </span><span class="si">%s</span><span class="s">&quot;</span> <span class="o">%</span> <span class="p">(</span><span class="n">f</span><span class="o">.</span><span class="n">__name__</span><span class="p">,</span> <span class="n">args</span><span class="p">,</span> <span class="n">kw</span><span class="p">)</span>
            <span class="k">return</span> <span class="n">f</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kw</span><span class="p">)</span>
        <span class="k">return</span> <span class="n">update_wrapper</span><span class="p">(</span><span class="n">newf</span><span class="p">,</span> <span class="n">f</span><span class="p">)</span>

<span class="c">#&lt;/_main.py&gt;</span>
</pre></div>

</div>
<p>The implementation above works in the sense that the decorator
can accept functions with generic signatures; unfortunately this
implementation does <em>not</em> define a signature-preserving decorator, since in
general <tt class="docutils literal"><span class="pre">decorator_trace</span></tt> returns a function with a
<em>different signature</em> from the original function.</p>
<p>Consider for instance the following case:</p>
<pre class="doctest-block">
&gt;&gt;&gt; &#64;decorator_trace
... def f1(x):
...     pass
</pre>
<p>Here the original function takes a single argument named <tt class="docutils literal"><span class="pre">x</span></tt>,
but the decorated function takes any number of arguments and
keyword arguments:</p>
<pre class="doctest-block">
&gt;&gt;&gt; from inspect import getargspec
&gt;&gt;&gt; print getargspec(f1)
([], 'args', 'kw', None)
</pre>
<p>This means that introspection tools such as pydoc will give
wrong informations about the signature of <tt class="docutils literal"><span class="pre">f1</span></tt>. This is pretty bad:
pydoc will tell you that the function accepts a generic signature
<tt class="docutils literal"><span class="pre">*args</span></tt>, <tt class="docutils literal"><span class="pre">**kw</span></tt>, but when you try to call the function with more than an
argument, you will get an error:</p>
<pre class="doctest-block">
&gt;&gt;&gt; f1(0, 1)
Traceback (most recent call last):
   ...
TypeError: f1() takes exactly 1 argument (2 given)
</pre>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id8" id="the-solution" name="the-solution">The solution</a></h1>
<p>The solution is to provide a generic factory of generators, which
hides the complexity of making signature-preserving decorators
from the application programmer. The <tt class="docutils literal"><span class="pre">decorator</span></tt> factory
allows to define decorators without the need to use nested functions
or classes. As an example, here is how you can define
<tt class="docutils literal"><span class="pre">decorator_trace</span></tt>.</p>
<p>First of all, you must import <tt class="docutils literal"><span class="pre">decorator</span></tt>:</p>
<pre class="doctest-block">
&gt;&gt;&gt; from decorator import decorator
</pre>
<p>Then you must define an helper function with signature <tt class="docutils literal"><span class="pre">(f,</span> <span class="pre">*args,</span> <span class="pre">**kw)</span></tt>
which calls the original function <tt class="docutils literal"><span class="pre">f</span></tt> with arguments <tt class="docutils literal"><span class="pre">args</span></tt> and <tt class="docutils literal"><span class="pre">kw</span></tt>
and implements the tracing capability:</p>
<div class="codeblock python">
<div class="highlight" ><pre><span class="c">#&lt;_main.py&gt;</span>

<span class="k">def</span> <span class="nf">trace</span><span class="p">(</span><span class="n">f</span><span class="p">,</span> <span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kw</span><span class="p">):</span>
    <span class="k">print</span> <span class="s">&quot;calling </span><span class="si">%s</span><span class="s"> with args </span><span class="si">%s</span><span class="s">, </span><span class="si">%s</span><span class="s">&quot;</span> <span class="o">%</span> <span class="p">(</span><span class="n">f</span><span class="o">.</span><span class="n">func_name</span><span class="p">,</span> <span class="n">args</span><span class="p">,</span> <span class="n">kw</span><span class="p">)</span>
    <span class="k">return</span> <span class="n">f</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kw</span><span class="p">)</span>

<span class="c">#&lt;/_main.py&gt;</span>
</pre></div>

</div>
<p><tt class="docutils literal"><span class="pre">decorator</span></tt> is able to convert the helper function into a
signature-preserving decorator
object, i.e  is a callable object that takes a function and returns a
decorated function with the same signature of the original function.
Therefore, you can write the following:</p>
<pre class="doctest-block">
&gt;&gt;&gt; &#64;decorator(trace)
... def f1(x):
...     pass
</pre>
<p>It is immediate to verify that <tt class="docutils literal"><span class="pre">f1</span></tt> works</p>
<pre class="doctest-block">
&gt;&gt;&gt; f1(0)
calling f1 with args (0,), {}
</pre>
<p>and it that it has the correct signature:</p>
<pre class="doctest-block">
&gt;&gt;&gt; print getargspec(f1)
(['x'], None, None, None)
</pre>
<p>The same decorator works with functions of any signature:</p>
<pre class="doctest-block">
&gt;&gt;&gt; &#64;decorator(trace)
... def f(x, y=1, z=2, *args, **kw):
...     pass
</pre>
<pre class="doctest-block">
&gt;&gt;&gt; f(0, 3)
calling f with args (0, 3, 2), {}
</pre>
<pre class="doctest-block">
&gt;&gt;&gt; print getargspec(f)
(['x', 'y', 'z'], 'args', 'kw', (1, 2))
</pre>
<p>That includes even functions with exotic signatures like the following:</p>
<pre class="doctest-block">
&gt;&gt;&gt; &#64;decorator(trace)
... def exotic_signature((x, y)=(1,2)): return x+y
</pre>
<pre class="doctest-block">
&gt;&gt;&gt; print getargspec(exotic_signature)
([['x', 'y']], None, None, ((1, 2),))
&gt;&gt;&gt; exotic_signature()
calling exotic_signature with args ((1, 2),), {}
3
</pre>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id9" id="decorator-is-a-decorator" name="decorator-is-a-decorator"><tt class="docutils literal"><span class="pre">decorator</span></tt> is a decorator</a></h1>
<p>The <tt class="docutils literal"><span class="pre">decorator</span></tt> factory itself can be considered as a signature-changing
decorator, just as <tt class="docutils literal"><span class="pre">classmethod</span></tt> and <tt class="docutils literal"><span class="pre">staticmethod</span></tt>.
However, <tt class="docutils literal"><span class="pre">classmethod</span></tt> and <tt class="docutils literal"><span class="pre">staticmethod</span></tt> return generic
objects which are not callable, while <tt class="docutils literal"><span class="pre">decorator</span></tt> returns
signature-preserving decorators, i.e. functions of a single argument.
Therefore, you can write</p>
<pre class="doctest-block">
&gt;&gt;&gt; &#64;decorator
... def tracing(f, *args, **kw):
...     print &quot;calling %s with args %s, %s&quot; % (f.func_name, args, kw)
...     return f(*args, **kw)
</pre>
<p>and this idiom is actually redefining <tt class="docutils literal"><span class="pre">tracing</span></tt> to be a decorator.
We can easily check that the signature has changed:</p>
<pre class="doctest-block">
&gt;&gt;&gt; print getargspec(tracing)
(['func'], None, None, None)
</pre>
<p>Therefore now <tt class="docutils literal"><span class="pre">tracing</span></tt> can be used as a decorator and
the following will work:</p>
<pre class="doctest-block">
&gt;&gt;&gt; &#64;tracing
... def func(): pass
</pre>
<pre class="doctest-block">
&gt;&gt;&gt; func()
calling func with args (), {}
</pre>
<p>BTW, you may use the decorator on lambda functions too:</p>
<pre class="doctest-block">
&gt;&gt;&gt; tracing(lambda : None)()
calling &lt;lambda&gt; with args (), {}
</pre>
<p>For the rest of this document, I will discuss examples of useful
decorators built on top of <tt class="docutils literal"><span class="pre">decorator</span></tt>.</p>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id10" id="memoize" name="memoize"><tt class="docutils literal"><span class="pre">memoize</span></tt></a></h1>
<p>This decorator implements the <tt class="docutils literal"><span class="pre">memoize</span></tt> pattern, i.e. it caches
the result of a function 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.</p>
<div class="codeblock python">
<div class="highlight" ><pre><span class="c">#&lt;_main.py&gt;</span>

<span class="k">from</span> <span class="nn">decorator</span> <span class="k">import</span> <span class="o">*</span>

<span class="k">def</span> <span class="nf">getattr_</span><span class="p">(</span><span class="n">obj</span><span class="p">,</span> <span class="n">name</span><span class="p">,</span> <span class="n">default_thunk</span><span class="p">):</span>
    <span class="s">&quot;Similar to .setdefault in dictionaries.&quot;</span>
    <span class="k">try</span><span class="p">:</span>
        <span class="k">return</span> <span class="nb">getattr</span><span class="p">(</span><span class="n">obj</span><span class="p">,</span> <span class="n">name</span><span class="p">)</span>
    <span class="k">except</span> <span class="ne">AttributeError</span><span class="p">:</span>
        <span class="n">default</span> <span class="o">=</span> <span class="n">default_thunk</span><span class="p">()</span>
        <span class="nb">setattr</span><span class="p">(</span><span class="n">obj</span><span class="p">,</span> <span class="n">name</span><span class="p">,</span> <span class="n">default</span><span class="p">)</span>
        <span class="k">return</span> <span class="n">default</span>

<span class="nd">@decorator</span>
<span class="k">def</span> <span class="nf">memoize</span><span class="p">(</span><span class="n">func</span><span class="p">,</span> <span class="o">*</span><span class="n">args</span><span class="p">):</span>
    <span class="n">dic</span> <span class="o">=</span> <span class="n">getattr_</span><span class="p">(</span><span class="n">func</span><span class="p">,</span> <span class="s">&quot;memoize_dic&quot;</span><span class="p">,</span> <span class="nb">dict</span><span class="p">)</span>
    <span class="c"># memoize_dic is created at the first call</span>
    <span class="k">if</span> <span class="n">args</span> <span class="ow">in</span> <span class="n">dic</span><span class="p">:</span>
        <span class="k">return</span> <span class="n">dic</span><span class="p">[</span><span class="n">args</span><span class="p">]</span>
    <span class="k">else</span><span class="p">:</span>
        <span class="n">result</span> <span class="o">=</span> <span class="n">func</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">)</span>
        <span class="n">dic</span><span class="p">[</span><span class="n">args</span><span class="p">]</span> <span class="o">=</span> <span class="n">result</span>
        <span class="k">return</span> <span class="n">result</span>

<span class="c">#&lt;/_main.py&gt;</span>
</pre></div>

</div>
<p>Here is a test of usage:</p>
<pre class="doctest-block">
&gt;&gt;&gt; &#64;memoize
... def heavy_computation():
...     time.sleep(2)
...     return &quot;done&quot;
</pre>
<pre class="doctest-block">
&gt;&gt;&gt; print heavy_computation() # the first time it will take 2 seconds
done
</pre>
<pre class="doctest-block">
&gt;&gt;&gt; print heavy_computation() # the second time it will be instantaneous
done
</pre>
<p>As an exercise, try to implement <tt class="docutils literal"><span class="pre">memoize</span></tt> <em>properly</em> without the
<tt class="docutils literal"><span class="pre">decorator</span></tt> factory.</p>
<p>Notice that this <tt class="docutils literal"><span class="pre">memoize</span></tt> only works for functions with no keyword
arguments, since it is impossible to memoize correctly something that
depends on mutable arguments. One can relax this requirement, and
allow keyword arguments in the signature: however, if keyword
arguments are passed, the result should not be cached. For an
example see <a class="reference" href="http://www.python.org/moin/PythonDecoratorLibrary">http://www.python.org/moin/PythonDecoratorLibrary</a></p>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id11" id="locked" name="locked"><tt class="docutils literal"><span class="pre">locked</span></tt></a></h1>
<p>There are good use cases for decorators is in multithreaded programming.
For instance, a <tt class="docutils literal"><span class="pre">locked</span></tt> decorator can remove the boilerplate
for acquiring/releasing locks <a class="footnote-reference" href="#id2" id="id1" name="id1">[1]</a>.</p>
<div class="codeblock python">
<div class="highlight" ><pre><span class="c">#&lt;_main.py&gt;</span>

<span class="k">import</span> <span class="nn">threading</span>

<span class="nd">@decorator</span>
<span class="k">def</span> <span class="nf">locked</span><span class="p">(</span><span class="n">func</span><span class="p">,</span> <span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kw</span><span class="p">):</span>
    <span class="n">lock</span> <span class="o">=</span> <span class="n">getattr_</span><span class="p">(</span><span class="n">func</span><span class="p">,</span> <span class="s">&quot;lock&quot;</span><span class="p">,</span> <span class="n">threading</span><span class="o">.</span><span class="n">Lock</span><span class="p">)</span>
    <span class="n">lock</span><span class="o">.</span><span class="n">acquire</span><span class="p">()</span>
    <span class="k">try</span><span class="p">:</span>
        <span class="n">result</span> <span class="o">=</span> <span class="n">func</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kw</span><span class="p">)</span>
    <span class="k">finally</span><span class="p">:</span>
        <span class="n">lock</span><span class="o">.</span><span class="n">release</span><span class="p">()</span>
    <span class="k">return</span> <span class="n">result</span>

<span class="c">#&lt;/_main.py&gt;</span>
</pre></div>

</div>
<table class="docutils footnote" frame="void" id="id2" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id1" name="id2">[1]</a></td><td>In Python 2.5, the preferred way to manage locking is via
the <tt class="docutils literal"><span class="pre">with</span></tt> statement: <a class="reference" href="http://docs.python.org/dev/lib/with-locks.html">http://docs.python.org/dev/lib/with-locks.html</a></td></tr>
</tbody>
</table>
<p>To show 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:</p>
<div class="codeblock python">
<div class="highlight" ><pre><span class="c">#&lt;_main.py&gt;</span>

<span class="k">import</span> <span class="nn">time</span>

<span class="n">datalist</span> <span class="o">=</span> <span class="p">[]</span> <span class="c"># for simplicity the written data are stored into a list.</span>

<span class="nd">@locked</span>
<span class="k">def</span> <span class="nf">write</span><span class="p">(</span><span class="n">data</span><span class="p">):</span>
    <span class="s">&quot;Writing to a sigle-access resource&quot;</span>
    <span class="n">time</span><span class="o">.</span><span class="n">sleep</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span>
    <span class="n">datalist</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">data</span><span class="p">)</span>

<span class="c">#&lt;/_main.py&gt;</span>
</pre></div>

</div>
<p>Since the writing function is locked, we are guaranteed that at any given time
there is at most one writer. An example multithreaded program that invokes
<tt class="docutils literal"><span class="pre">write</span></tt> and prints the datalist is shown in the next section.</p>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id12" id="delayed-and-threaded" name="delayed-and-threaded"><tt class="docutils literal"><span class="pre">delayed</span></tt> and <tt class="docutils literal"><span class="pre">threaded</span></tt></a></h1>
<p>Often, one wants to define families of decorators, i.e. decorators depending
on one or more parameters.</p>
<p>Here I will consider the example of a one-parameter family of <tt class="docutils literal"><span class="pre">delayed</span></tt>
decorators taking a procedure and converting it into a delayed procedure.
In this case the time delay is the parameter.</p>
<p>A delayed procedure is a procedure that, when called,
is executed in a separate thread after a certain time
delay. The implementation is not difficult:</p>
<div class="codeblock python">
<div class="highlight" ><pre><span class="c">#&lt;_main.py&gt;</span>

<span class="k">def</span> <span class="nf">delayed</span><span class="p">(</span><span class="n">nsec</span><span class="p">):</span>
    <span class="k">def</span> <span class="nf">call</span><span class="p">(</span><span class="n">proc</span><span class="p">,</span> <span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kw</span><span class="p">):</span>
        <span class="n">thread</span> <span class="o">=</span> <span class="n">threading</span><span class="o">.</span><span class="n">Timer</span><span class="p">(</span><span class="n">nsec</span><span class="p">,</span> <span class="n">proc</span><span class="p">,</span> <span class="n">args</span><span class="p">,</span> <span class="n">kw</span><span class="p">)</span>
        <span class="n">thread</span><span class="o">.</span><span class="n">start</span><span class="p">()</span>
        <span class="k">return</span> <span class="n">thread</span>
    <span class="k">return</span> <span class="n">decorator</span><span class="p">(</span><span class="n">call</span><span class="p">)</span>

<span class="c">#&lt;/_main.py&gt;</span>
</pre></div>

</div>
<p>Notice that without the help of <tt class="docutils literal"><span class="pre">decorator</span></tt>, an additional level of
nesting would have been needed.</p>
<p>Delayed decorators as intended to be used on procedures, i.e.
on functions returning <tt class="docutils literal"><span class="pre">None</span></tt>, 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 <tt class="docutils literal"><span class="pre">.isAlive()</span></tt>.</p>
<p>Delayed procedures can be useful in many situations. For instance, I have used
this pattern to start a web browser <em>after</em> the web server started,
in code such as</p>
<pre class="doctest-block">
&gt;&gt;&gt; &#64;delayed(2)
... def start_browser():
...     &quot;code to open an external browser window here&quot;
</pre>
<pre class="doctest-block">
&gt;&gt;&gt; #start_browser() # will open the browser in 2 seconds
&gt;&gt;&gt; #server.serve_forever() # enter the server mainloop
</pre>
<p>The particular case in which there is no delay is important enough
to deserve a name:</p>
<div class="codeblock python">
<div class="highlight" ><pre><span class="c">#&lt;_main.py&gt;</span>

<span class="n">threaded</span> <span class="o">=</span> <span class="n">delayed</span><span class="p">(</span><span class="mi">0</span><span class="p">)</span> <span class="c"># no-delay decorator</span>

<span class="c">#&lt;/_main.py&gt;</span>
</pre></div>

</div>
<p>Threaded procedures will be executed in a separated thread as soon
as they are called. Here is an example using the <tt class="docutils literal"><span class="pre">write</span></tt>
routine defined before:</p>
<pre class="doctest-block">
&gt;&gt;&gt; &#64;threaded
... def writedata(data):
...     write(data)
</pre>
<p>Each call to <tt class="docutils literal"><span class="pre">writedata</span></tt> will create a new writer thread, but there will
be no synchronization problems since <tt class="docutils literal"><span class="pre">write</span></tt> is locked.</p>
<pre class="doctest-block">
&gt;&gt;&gt; writedata(&quot;data1&quot;)
&lt;_Timer(Thread-1, started)&gt;
</pre>
<pre class="doctest-block">
&gt;&gt;&gt; time.sleep(.1) # wait a bit, so we are sure data2 is written after data1
</pre>
<pre class="doctest-block">
&gt;&gt;&gt; writedata(&quot;data2&quot;)
&lt;_Timer(Thread-2, started)&gt;
</pre>
<pre class="doctest-block">
&gt;&gt;&gt; time.sleep(2) # wait for the writers to complete
</pre>
<pre class="doctest-block">
&gt;&gt;&gt; print datalist
['data1', 'data2']
</pre>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id13" id="blocking" name="blocking"><tt class="docutils literal"><span class="pre">blocking</span></tt></a></h1>
<p>Sometimes one has to deal with blocking resources, such as <tt class="docutils literal"><span class="pre">stdin</span></tt>, and
sometimes it is best to have back a &quot;busy&quot; message than to block everything.
This behavior can be implemented with a suitable decorator:</p>
<div class="codeblock python">
<div class="highlight" ><pre><span class="c">#&lt;_main.py&gt;</span>

<span class="k">def</span> <span class="nf">blocking</span><span class="p">(</span><span class="n">not_avail</span><span class="o">=</span><span class="s">&quot;Not Available&quot;</span><span class="p">):</span>
    <span class="k">def</span> <span class="nf">call</span><span class="p">(</span><span class="n">f</span><span class="p">,</span> <span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kw</span><span class="p">):</span>
        <span class="k">if</span> <span class="ow">not</span> <span class="nb">hasattr</span><span class="p">(</span><span class="n">f</span><span class="p">,</span> <span class="s">&quot;thread&quot;</span><span class="p">):</span> <span class="c"># no thread running</span>
            <span class="k">def</span> <span class="nf">set_result</span><span class="p">():</span> <span class="n">f</span><span class="o">.</span><span class="n">result</span> <span class="o">=</span> <span class="n">f</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kw</span><span class="p">)</span>
            <span class="n">f</span><span class="o">.</span><span class="n">thread</span> <span class="o">=</span> <span class="n">threading</span><span class="o">.</span><span class="n">Thread</span><span class="p">(</span><span class="bp">None</span><span class="p">,</span> <span class="n">set_result</span><span class="p">)</span>
            <span class="n">f</span><span class="o">.</span><span class="n">thread</span><span class="o">.</span><span class="n">start</span><span class="p">()</span>
            <span class="k">return</span> <span class="n">not_avail</span>
        <span class="k">elif</span> <span class="n">f</span><span class="o">.</span><span class="n">thread</span><span class="o">.</span><span class="n">isAlive</span><span class="p">():</span>
            <span class="k">return</span> <span class="n">not_avail</span>
        <span class="k">else</span><span class="p">:</span> <span class="c"># the thread is ended, return the stored result</span>
            <span class="k">del</span> <span class="n">f</span><span class="o">.</span><span class="n">thread</span>
            <span class="k">return</span> <span class="n">f</span><span class="o">.</span><span class="n">result</span>
    <span class="k">return</span> <span class="n">decorator</span><span class="p">(</span><span class="n">call</span><span class="p">)</span>

<span class="c">#&lt;/_main.py&gt;</span>
</pre></div>

</div>
<p>Functions decorated with <tt class="docutils literal"><span class="pre">blocking</span></tt> will return a busy message if
the resource is unavailable, and the intended result if the resource is
available. For instance:</p>
<pre class="doctest-block">
&gt;&gt;&gt; &#64;blocking(&quot;Please wait ...&quot;)
... def read_data():
...     time.sleep(3) # simulate a blocking resource
...     return &quot;some data&quot;
</pre>
<pre class="doctest-block">
&gt;&gt;&gt; print read_data() # data is not available yet
Please wait ...
</pre>
<pre class="doctest-block">
&gt;&gt;&gt; time.sleep(1)
&gt;&gt;&gt; print read_data() # data is not available yet
Please wait ...
</pre>
<pre class="doctest-block">
&gt;&gt;&gt; time.sleep(1)
&gt;&gt;&gt; print read_data() # data is not available yet
Please wait ...
</pre>
<pre class="doctest-block">
&gt;&gt;&gt; time.sleep(1.1) # after 3.1 seconds, data is available
&gt;&gt;&gt; print read_data()
some data
</pre>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id14" id="redirecting-stdout" name="redirecting-stdout"><tt class="docutils literal"><span class="pre">redirecting_stdout</span></tt></a></h1>
<p>Decorators help in removing the boilerplate associated to <tt class="docutils literal"><span class="pre">try</span> <span class="pre">..</span> <span class="pre">finally</span></tt>
blocks. We saw the case of <tt class="docutils literal"><span class="pre">locked</span></tt>; here is another example:</p>
<div class="codeblock python">
<div class="highlight" ><pre><span class="c">#&lt;_main.py&gt;</span>

<span class="k">import</span> <span class="nn">sys</span>

<span class="k">def</span> <span class="nf">redirecting_stdout</span><span class="p">(</span><span class="n">new_stdout</span><span class="p">):</span>
    <span class="k">def</span> <span class="nf">call</span><span class="p">(</span><span class="n">func</span><span class="p">,</span> <span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kw</span><span class="p">):</span>
        <span class="n">save_stdout</span> <span class="o">=</span> <span class="n">sys</span><span class="o">.</span><span class="n">stdout</span>
        <span class="n">sys</span><span class="o">.</span><span class="n">stdout</span> <span class="o">=</span> <span class="n">new_stdout</span>
        <span class="k">try</span><span class="p">:</span>
            <span class="n">result</span> <span class="o">=</span> <span class="n">func</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kw</span><span class="p">)</span>
        <span class="k">finally</span><span class="p">:</span>
            <span class="n">sys</span><span class="o">.</span><span class="n">stdout</span> <span class="o">=</span> <span class="n">save_stdout</span>
        <span class="k">return</span> <span class="n">result</span>
    <span class="k">return</span> <span class="n">decorator</span><span class="p">(</span><span class="n">call</span><span class="p">)</span>

<span class="c">#&lt;/_main.py&gt;</span>
</pre></div>

</div>
<p>Here is an example of usage:</p>
<pre class="doctest-block">
&gt;&gt;&gt; from StringIO import StringIO
</pre>
<pre class="doctest-block">
&gt;&gt;&gt; out = StringIO()
</pre>
<pre class="doctest-block">
&gt;&gt;&gt; &#64;redirecting_stdout(out)
... def helloworld():
...     print &quot;hello, world!&quot;
</pre>
<pre class="doctest-block">
&gt;&gt;&gt; helloworld()
</pre>
<pre class="doctest-block">
&gt;&gt;&gt; out.getvalue()
'hello, world!\n'
</pre>
<p>Similar tricks can be used to remove the boilerplate associate with
transactional databases. I think you got the idea, so I will leave
the transactional example as an exercise for the reader. Of course
in Python 2.5 these use cases can also be addressed with the <tt class="docutils literal"><span class="pre">with</span></tt>
statement.</p>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id15" id="dealing-with-third-party-decorators-new-wrapper" name="dealing-with-third-party-decorators-new-wrapper">Dealing with third party decorators: <tt class="docutils literal"><span class="pre">new_wrapper</span></tt></a></h1>
<p>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
upgrade third party decorators to signature-preserving decorators without
having to rewrite them in terms of <tt class="docutils literal"><span class="pre">decorator</span></tt>. To this aim the
<tt class="docutils literal"><span class="pre">decorator</span></tt> module provides an utility function called <tt class="docutils literal"><span class="pre">new_wrapper</span></tt>.
<tt class="docutils literal"><span class="pre">new_wrapper</span></tt> takes a wrapper function with a generic signature and returns
a copy of it with the right signature.
For instance, suppose you have a wrapper function <tt class="docutils literal"><span class="pre">wrapper</span></tt> (or generically
a callable object) with a &quot;permissive&quot; signature (say <tt class="docutils literal"><span class="pre">wrapper(*args,</span> <span class="pre">**kw)</span></tt>)
returned by a third party non signature-preserving decorator; let <tt class="docutils literal"><span class="pre">model</span></tt>
be the original function, with a stricter signature; then
<tt class="docutils literal"><span class="pre">new_wrapper(wrapper,</span> <span class="pre">model)</span></tt>
returns a copy of <tt class="docutils literal"><span class="pre">wrapper</span></tt> with signature copied from <tt class="docutils literal"><span class="pre">model</span></tt>.
Notice that it is your responsability to make sure that the original
function and the model function have compatibile signature, i.e. that
the signature of the model is stricter (or equivalent) than the signature
of the original function. If not, you will get an error at calling
time, not at decoration time.</p>
<p>With <tt class="docutils literal"><span class="pre">new_wrapper</span></tt> at your disposal, it is a breeze to define an utility
to upgrade old-style decorators to signature-preserving decorators:</p>
<div class="codeblock python">
<div class="highlight" ><pre><span class="c">#&lt;_main.py&gt;</span>

<span class="k">def</span> <span class="nf">upgrade_dec</span><span class="p">(</span><span class="n">dec</span><span class="p">):</span>
    <span class="k">return</span> <span class="k">lambda</span> <span class="n">f</span> <span class="p">:</span> <span class="n">new_wrapper</span><span class="p">(</span><span class="n">dec</span><span class="p">(</span><span class="n">f</span><span class="p">),</span> <span class="n">f</span><span class="p">)</span>

<span class="c">#&lt;/_main.py&gt;</span>
</pre></div>

</div>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id16" id="tail-recursive" name="tail-recursive"><tt class="docutils literal"><span class="pre">tail_recursive</span></tt></a></h1>
<p>In order to give an example of usage for <tt class="docutils literal"><span class="pre">new_wrapper</span></tt>, 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
in the Python Cookbook,
<a class="reference" href="http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/496691">http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/496691</a>.</p>
<div class="codeblock python">
<div class="highlight" ><pre><span class="c">#&lt;_main.py&gt;</span>

<span class="k">from</span> <span class="nn">decorator</span> <span class="k">import</span> <span class="n">new_wrapper</span>

<span class="k">class</span> <span class="nc">TailRecursive</span><span class="p">(</span><span class="nb">object</span><span class="p">):</span>
    <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">    tail_recursive decorator based on Kay Schluehr&#39;s recipe</span>
<span class="sd">    http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/496691</span>
<span class="sd">    &quot;&quot;&quot;</span>
    <span class="n">CONTINUE</span> <span class="o">=</span> <span class="nb">object</span><span class="p">()</span> <span class="c"># sentinel</span>

    <span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">func</span><span class="p">):</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">func</span> <span class="o">=</span> <span class="n">func</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">firstcall</span> <span class="o">=</span> <span class="bp">True</span>

    <span class="k">def</span> <span class="nf">__call__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kwd</span><span class="p">):</span>
        <span class="k">try</span><span class="p">:</span>
            <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">firstcall</span><span class="p">:</span> <span class="c"># start looping</span>
                <span class="bp">self</span><span class="o">.</span><span class="n">firstcall</span> <span class="o">=</span> <span class="bp">False</span>
                <span class="k">while</span> <span class="bp">True</span><span class="p">:</span>
                    <span class="n">result</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">func</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kwd</span><span class="p">)</span>
                    <span class="k">if</span> <span class="n">result</span> <span class="ow">is</span> <span class="bp">self</span><span class="o">.</span><span class="n">CONTINUE</span><span class="p">:</span> <span class="c"># update arguments</span>
                        <span class="n">args</span><span class="p">,</span> <span class="n">kwd</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">argskwd</span>
                    <span class="k">else</span><span class="p">:</span> <span class="c"># last call</span>
                        <span class="k">break</span>
            <span class="k">else</span><span class="p">:</span> <span class="c"># return the arguments of the tail call</span>
                <span class="bp">self</span><span class="o">.</span><span class="n">argskwd</span> <span class="o">=</span> <span class="n">args</span><span class="p">,</span> <span class="n">kwd</span>
                <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">CONTINUE</span>
        <span class="k">except</span><span class="p">:</span> <span class="c"># reset and re-raise</span>
            <span class="bp">self</span><span class="o">.</span><span class="n">firstcall</span> <span class="o">=</span> <span class="bp">True</span>
            <span class="k">raise</span>
        <span class="k">else</span><span class="p">:</span> <span class="c"># reset and exit</span>
            <span class="bp">self</span><span class="o">.</span><span class="n">firstcall</span> <span class="o">=</span> <span class="bp">True</span>
            <span class="k">return</span> <span class="n">result</span>

<span class="n">tail_recursive</span> <span class="o">=</span> <span class="n">upgrade_dec</span><span class="p">(</span><span class="n">TailRecursive</span><span class="p">)</span>

<span class="c">#&lt;/_main.py&gt;</span>
</pre></div>

</div>
<p>Here the decorator is implemented as a class returning callable
objects. <tt class="docutils literal"><span class="pre">upgrade_dec</span></tt> converts that class in a factory function
returning functions.
Here is how you apply the upgraded decorator to the good old factorial:</p>
<div class="codeblock python">
<div class="highlight" ><pre><span class="c">#&lt;_main.py&gt;</span>

<span class="nd">@tail_recursive</span>
<span class="k">def</span> <span class="nf">factorial</span><span class="p">(</span><span class="n">n</span><span class="p">,</span> <span class="n">acc</span><span class="o">=</span><span class="mi">1</span><span class="p">):</span>
    <span class="s">&quot;The good old factorial&quot;</span>
    <span class="k">if</span> <span class="n">n</span> <span class="o">==</span> <span class="mi">0</span><span class="p">:</span> <span class="k">return</span> <span class="n">acc</span>
    <span class="k">return</span> <span class="n">factorial</span><span class="p">(</span><span class="n">n</span><span class="o">-</span><span class="mi">1</span><span class="p">,</span> <span class="n">n</span><span class="o">*</span><span class="n">acc</span><span class="p">)</span>

<span class="c">#&lt;/_main.py&gt;</span>
</pre></div>

</div>
<pre class="doctest-block">
&gt;&gt;&gt; print factorial(4)
24
</pre>
<p>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 <tt class="docutils literal"><span class="pre">factorial(1001)</span></tt> or larger without filling the stack
frame. Notice also that the decorator will not work on functions which
are not tail recursive, such as</p>
<div class="codeblock python">
<div class="highlight" ><pre><span class="k">def</span> <span class="nf">fact</span><span class="p">(</span><span class="n">n</span><span class="p">):</span> <span class="c"># this is not tail-recursive</span>
    <span class="k">if</span> <span class="n">n</span> <span class="o">==</span> <span class="mi">0</span><span class="p">:</span> <span class="k">return</span> <span class="mi">1</span>
    <span class="k">return</span> <span class="n">n</span> <span class="o">*</span> <span class="n">fact</span><span class="p">(</span><span class="n">n</span><span class="o">-</span><span class="mi">1</span><span class="p">)</span>
</pre></div>

</div>
<p>(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).</p>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id17" id="caveats-and-limitations" name="caveats-and-limitations">Caveats and limitations</a></h1>
<p>The first thing you should be aware of, it the fact that decorators
have a performance penalty.
The worse case is shown by the following example:</p>
<pre class="literal-block">
$ cat performance.sh
python -m timeit -s &quot;
from decorator import decorator

&#64;decorator
def do_nothing(func, *args, **kw):
    return func(*args, **kw)

&#64;do_nothing
def f():
    pass
&quot; &quot;f()&quot;

python -m timeit -s &quot;
def f():
    pass
&quot; &quot;f()&quot;
</pre>
<p>On my Linux system, using the <tt class="docutils literal"><span class="pre">do_nothing</span></tt> decorator instead of the
plain function is more than four times slower:</p>
<pre class="literal-block">
$ bash performance.sh
1000000 loops, best of 3: 1.68 usec per loop
1000000 loops, best of 3: 0.397 usec per loop
</pre>
<p>It should be noted that a real life function would probably do
something more useful than <tt class="docutils literal"><span class="pre">f</span></tt> here, and therefore in real life the
performance penalty could be completely negligible.  As always, the
only way to know if there is
a penalty in your specific use case is to measure it.</p>
<p>You should be aware that decorators will make your tracebacks
longer and more difficult to understand. Consider this example:</p>
<pre class="doctest-block">
&gt;&gt;&gt; &#64;tracing
... def f():
...     1/0
</pre>
<p>Calling <tt class="docutils literal"><span class="pre">f()</span></tt> will give you a <tt class="docutils literal"><span class="pre">ZeroDivisionError</span></tt>, but since the
function is decorated the traceback will be longer:</p>
<pre class="doctest-block">
&gt;&gt;&gt; f()
Traceback (most recent call last):
  File &quot;&lt;stdin&gt;&quot;, line 1, in ?
    f()
  File &quot;&lt;string&gt;&quot;, line 2, in f
  File &quot;&lt;stdin&gt;&quot;, line 4, in tracing
    return f(*args, **kw)
  File &quot;&lt;stdin&gt;&quot;, line 3, in f
    1/0
ZeroDivisionError: integer division or modulo by zero
</pre>
<p>You see here the inner call to the decorator <tt class="docutils literal"><span class="pre">tracing</span></tt>, which calls
<tt class="docutils literal"><span class="pre">f(*args,</span> <span class="pre">**kw)</span></tt>, and a reference to  <tt class="docutils literal"><span class="pre">File</span> <span class="pre">&quot;&lt;string&gt;&quot;,</span> <span class="pre">line</span> <span class="pre">2,</span> <span class="pre">in</span> <span class="pre">f</span></tt>.
This latter reference is due to the fact that internally the decorator
module uses <tt class="docutils literal"><span class="pre">eval</span></tt> to generate the decorated function. Notice that
<tt class="docutils literal"><span class="pre">eval</span></tt> is <em>not</em> responsibile for the performance penalty, since is the
called <em>only once</em> at function decoration time, and not every time
the decorated function is called.</p>
<p>Using <tt class="docutils literal"><span class="pre">eval</span></tt> means that <tt class="docutils literal"><span class="pre">inspect.getsource</span></tt> will not work for decorated
functions. This means that the usual '??' trick in IPython will give you
the (right on the spot) message
<tt class="docutils literal"><span class="pre">Dynamically</span> <span class="pre">generated</span> <span class="pre">function.</span> <span class="pre">No</span> <span class="pre">source</span> <span class="pre">code</span> <span class="pre">available.</span></tt>. This
however is preferable to the situation with regular decorators, where
<tt class="docutils literal"><span class="pre">inspect.getsource</span></tt> gives you the wrapper source code which is probably
not what you want:</p>
<div class="codeblock python">
<div class="highlight" ><pre><span class="c">#&lt;_main.py&gt;</span>

<span class="k">def</span> <span class="nf">identity_dec</span><span class="p">(</span><span class="n">func</span><span class="p">):</span>
    <span class="k">def</span> <span class="nf">wrapper</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kw</span><span class="p">):</span>
        <span class="k">return</span> <span class="n">func</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kw</span><span class="p">)</span>
    <span class="k">return</span> <span class="n">wrapper</span>

<span class="nd">@identity_dec</span>
<span class="k">def</span> <span class="nf">example</span><span class="p">():</span> <span class="k">pass</span>

<span class="c">#&lt;/_main.py&gt;</span>
</pre></div>

</div>
<pre class="doctest-block">
&gt;&gt;&gt; import inspect
&gt;&gt;&gt; print inspect.getsource(example)
    def wrapper(*args, **kw):
        return func(*args, **kw)
&lt;BLANKLINE&gt;
</pre>
<p>(see bug report <a class="reference" href="http://sourceforge.net/tracker/index.php?func=detail&amp;aid=1764286&amp;group_id=5470&amp;atid=105470">1764286</a> for an explanation of what is happening).</p>
<p>At present, there is no clean way to avoid <tt class="docutils literal"><span class="pre">eval</span></tt>. A clean solution
would require to change the CPython implementation of functions and
add an hook to make it possible to change their signature directly.
This will happen in future versions of Python (see PEP <a class="reference" href="http://www.python.org/dev/peps/pep-0362">362</a>) and
then the decorator module will become obsolete.</p>
<p>For debugging purposes, it may be useful to know that the decorator
module also provides a <tt class="docutils literal"><span class="pre">getinfo</span></tt> utility function which returns a
dictionary containing information about a function.
For instance, for the factorial function we will get</p>
<pre class="doctest-block">
&gt;&gt;&gt; d = getinfo(factorial)
&gt;&gt;&gt; d['name']
'factorial'
&gt;&gt;&gt; d['argnames']
['n', 'acc']
&gt;&gt;&gt; d['signature']
'n, acc'
&gt;&gt;&gt; d['defaults']
(1,)
&gt;&gt;&gt; d['doc']
'The good old factorial'
</pre>
<p>In the present implementation, decorators generated by <tt class="docutils literal"><span class="pre">decorator</span></tt>
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
<tt class="docutils literal"><span class="pre">inspect</span></tt> module in the standard library.
Also, there is a restriction on the names of the arguments: if try to
call an argument <tt class="docutils literal"><span class="pre">_call_</span></tt> or <tt class="docutils literal"><span class="pre">_func_</span></tt> you will get an AssertionError:</p>
<pre class="doctest-block">
&gt;&gt;&gt; &#64;tracing
... def f(_func_): print f
...
Traceback (most recent call last):
  ...
AssertionError: You cannot use _call_ or _func_ as argument names!
</pre>
<p>(the existence of these two reserved names is an implementation detail).</p>
<p>Moreover, the implementation is such that the decorated function contains
a copy of the original function attributes:</p>
<pre class="doctest-block">
&gt;&gt;&gt; def f(): pass # the original function
&gt;&gt;&gt; f.attr1 = &quot;something&quot; # setting an attribute
&gt;&gt;&gt; f.attr2 = &quot;something else&quot; # setting another attribute
</pre>
<pre class="doctest-block">
&gt;&gt;&gt; traced_f = tracing(f) # the decorated function
</pre>
<pre class="doctest-block">
&gt;&gt;&gt; traced_f.attr1
'something'
&gt;&gt;&gt; traced_f.attr2 = &quot;something different&quot; # setting attr
&gt;&gt;&gt; f.attr2 # the original attribute did not change
'something else'
</pre>
<p>That's all folks, enjoy!</p>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id18" id="licence" name="licence">LICENCE</a></h1>
<p>Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:</p>
<pre class="literal-block">
Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
Redistributions in bytecode form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in
the documentation and/or other materials provided with the
distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
&quot;AS IS&quot; AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
DAMAGE.
</pre>
<p>If you use this software and you are happy with it, consider sending me a
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!</p>
</div>
</div>
</body>
</html>