diff options
| author | Michele Simionato <michele.simionato@gmail.com> | 2015-03-16 11:13:06 +0100 |
|---|---|---|
| committer | Michele Simionato <michele.simionato@gmail.com> | 2015-03-16 11:13:06 +0100 |
| commit | 5d0a05302b850386b2b71ff281c58db333ac7e78 (patch) | |
| tree | e8ccc92a2336ee1a5bed53a503776888a3929e91 | |
| parent | 3e2bd43069fa1837d77f8ab2079044a44aaedd66 (diff) | |
| download | python-decorator-git-5d0a05302b850386b2b71ff281c58db333ac7e78.tar.gz | |
Initial changes for decorator 3.4.1
| -rw-r--r-- | Makefile | 10 | ||||
| -rw-r--r-- | README.rst (renamed from README.txt) | 10 | ||||
| -rw-r--r-- | documentation.html | 1102 | ||||
| -rw-r--r-- | documentation.py | 211 | ||||
| -rw-r--r-- | documentation.rst | 1037 | ||||
| -rw-r--r-- | documentation3.html | 1102 | ||||
| -rw-r--r-- | documentation3.py | 219 | ||||
| -rw-r--r-- | documentation3.rst | 1056 | ||||
| -rw-r--r-- | setup.py | 7 | ||||
| -rw-r--r-- | src/decorator.py | 88 |
10 files changed, 2412 insertions, 2430 deletions
@@ -1,18 +1,18 @@ RST=python $(S)/ms/tools/rst.py rst: documentation.py documentation3.py - python $(S)/ms/tools/minidoc.py -d documentation.py - python3.3 $(S)/minidoc3.py -d documentation3.py + PYTHONPATH=src:$(S) python $(S)/ms/tools/minidoc.py -d documentation.py + python3 $(S)/minidoc3.py -d documentation3.py + cp /tmp/documentation.rst /tmp/documentation3.rst . html: /tmp/documentation.rst /tmp/documentation3.rst $(RST) /tmp/documentation.rst $(RST) /tmp/documentation3.rst - rst2html README.txt index.html + rst2html README.rst index.html pdf: /tmp/documentation.rst /tmp/documentation3.rst rst2pdf /tmp/documentation.rst -o documentation.pdf rst2pdf /tmp/documentation3.rst -o documentation3.pdf - cp /tmp/documentation.html /tmp/documentation3.html . upload: documentation.pdf documentation3.pdf - python3.3 setup.py register sdist upload + python3 setup.py register sdist upload @@ -14,10 +14,9 @@ Installation If you are lazy, just perform
-$ easy_install decorator
+$ pip install decorator
-which will install just the module on your system. Notice that
-Python 3 requires the easy_install version of the distribute_ project.
+which will install just the module on your system.
If you prefer to install the full distribution from source, including
the documentation, download the tarball_, unpack it and run
@@ -74,7 +73,6 @@ There are various versions of the documentation: Repository
---------------
-The project is hosted on GoogleCode as a Mercurial repository. You
-can look at the source here:
+The project is hosted on GitHub. You can look at the source here:
- http://code.google.com/p/micheles/source/browse/#hg%2Fdecorator
+ https://github.com/micheles/decorator
diff --git a/documentation.html b/documentation.html deleted file mode 100644 index 25a5709..0000000 --- a/documentation.html +++ /dev/null @@ -1,1102 +0,0 @@ -<?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.8.1: http://docutils.sourceforge.net/" /> -<title>The decorator module</title> -<meta name="author" content="Michele Simionato" /> -<style type="text/css"> - -.highlight { background: #f8f8f8; } -.highlight .c { color: #408080; font-style: italic } /* Comment */ -.highlight .err { border: 1px solid #FF0000 } /* Error */ -.highlight .k { color: #008000; font-weight: bold } /* Keyword */ -.highlight .o { color: #666666 } /* Operator */ -.highlight .cm { color: #408080; font-style: italic } /* Comment.Multiline */ -.highlight .cp { color: #BC7A00 } /* Comment.Preproc */ -.highlight .c1 { color: #408080; font-style: italic } /* Comment.Single */ -.highlight .cs { color: #408080; font-style: italic } /* Comment.Special */ -.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: #008000; font-weight: bold } /* Keyword.Constant */ -.highlight .kd { color: #008000; font-weight: bold } /* Keyword.Declaration */ -.highlight .kp { color: #008000 } /* Keyword.Pseudo */ -.highlight .kr { color: #008000; font-weight: bold } /* Keyword.Reserved */ -.highlight .kt { color: #008000; font-weight: bold } /* Keyword.Type */ -.highlight .m { color: #666666 } /* Literal.Number */ -.highlight .s { color: #BA2121 } /* Literal.String */ -.highlight .na { color: #7D9029 } /* Name.Attribute */ -.highlight .nb { color: #008000 } /* Name.Builtin */ -.highlight .nc { color: #0000FF; font-weight: bold } /* 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: #0000FF } /* 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: #19177C } /* Name.Variable */ -.highlight .ow { color: #AA22FF; font-weight: bold } /* Operator.Word */ -.highlight .w { color: #bbbbbb } /* Text.Whitespace */ -.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: #BA2121 } /* Literal.String.Backtick */ -.highlight .sc { color: #BA2121 } /* Literal.String.Char */ -.highlight .sd { color: #BA2121; font-style: italic } /* Literal.String.Doc */ -.highlight .s2 { color: #BA2121 } /* Literal.String.Double */ -.highlight .se { color: #BB6622; font-weight: bold } /* Literal.String.Escape */ -.highlight .sh { color: #BA2121 } /* 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: #BA2121 } /* Literal.String.Single */ -.highlight .ss { color: #19177C } /* Literal.String.Symbol */ -.highlight .bp { color: #008000 } /* Name.Builtin.Pseudo */ -.highlight .vc { color: #19177C } /* Name.Variable.Class */ -.highlight .vg { color: #19177C } /* Name.Variable.Global */ -.highlight .vi { color: #19177C } /* 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">decorator</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 external" href="mailto:michele.simionato@gmail.com">michele.simionato@gmail.com</a></td> -</tr> -<tr><th class="docinfo-name">Version:</th> -<td>3.4.0 (2012-10-18)</td></tr> -<tr class="field"><th class="docinfo-name">Requires:</th><td class="field-body">Python 2.4+</td> -</tr> -<tr class="field"><th class="docinfo-name">Download page:</th><td class="field-body"><a class="reference external" href="http://pypi.python.org/pypi/decorator/3.4.0">http://pypi.python.org/pypi/decorator/3.4.0</a></td> -</tr> -<tr class="field"><th class="docinfo-name">Installation:</th><td class="field-body"><tt class="docutils literal">easy_install decorator</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" id="contents"> -<p class="topic-title first">Contents</p> -<ul class="simple"> -<li><a class="reference internal" href="#introduction" id="id3">Introduction</a></li> -<li><a class="reference internal" href="#definitions" id="id4">Definitions</a></li> -<li><a class="reference internal" href="#statement-of-the-problem" id="id5">Statement of the problem</a></li> -<li><a class="reference internal" href="#the-solution" id="id6">The solution</a></li> -<li><a class="reference internal" href="#a-trace-decorator" id="id7">A <tt class="docutils literal">trace</tt> decorator</a></li> -<li><a class="reference internal" href="#decorator-is-a-decorator" id="id8"><tt class="docutils literal">decorator</tt> is a decorator</a></li> -<li><a class="reference internal" href="#blocking" id="id9"><tt class="docutils literal">blocking</tt></a></li> -<li><a class="reference internal" href="#async" id="id10"><tt class="docutils literal">async</tt></a></li> -<li><a class="reference internal" href="#contextmanager" id="id11">contextmanager</a></li> -<li><a class="reference internal" href="#the-functionmaker-class" id="id12">The <tt class="docutils literal">FunctionMaker</tt> class</a></li> -<li><a class="reference internal" href="#getting-the-source-code" id="id13">Getting the source code</a></li> -<li><a class="reference internal" href="#dealing-with-third-party-decorators" id="id14">Dealing with third party decorators</a></li> -<li><a class="reference internal" href="#caveats-and-limitations" id="id15">Caveats and limitations</a></li> -<li><a class="reference internal" href="#compatibility-notes" id="id16">Compatibility notes</a></li> -<li><a class="reference internal" href="#licence" id="id17">LICENCE</a></li> -</ul> -</div> -<div class="section" id="introduction"> -<h1><a class="toc-backref" href="#id3">Introduction</a></h1> -<p>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 -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 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">decorator</tt> 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.</p> -<p>You may find the source code for all the examples -discussed here in the <tt class="docutils literal">documentation.py</tt> file, which contains -this documentation in the form of doctests.</p> -</div> -<div class="section" id="definitions"> -<h1><a class="toc-backref" href="#id4">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 subclasses:</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">staticmethod</tt> and <tt class="docutils literal">classmethod</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.</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" id="statement-of-the-problem"> -<h1><a class="toc-backref" href="#id5">Statement of the problem</a></h1> -<p>A very common use case for decorators is the memoization of functions. -A <tt class="docutils literal">memoize</tt> 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 -<tt class="docutils literal">memoize</tt> in <a class="reference external" href="http://www.python.org/moin/PythonDecoratorLibrary">http://www.python.org/moin/PythonDecoratorLibrary</a>, -but they do not preserve the signature. -A simple implementation could be the following (notice -that in general it is impossible to memoize correctly something -that depends on non-hashable arguments):</p> -<div class="codeblock python"> -<div class="highlight"><pre><span class="k">def</span> <span class="nf">memoize_uw</span><span class="p">(</span><span class="n">func</span><span class="p">):</span> - <span class="n">func</span><span class="o">.</span><span class="n">cache</span> <span class="o">=</span> <span class="p">{}</span> - <span class="k">def</span> <span class="nf">memoize</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="n">kw</span><span class="p">:</span> <span class="c"># frozenset is used to ensure hashability</span> - <span class="n">key</span> <span class="o">=</span> <span class="n">args</span><span class="p">,</span> <span class="nb">frozenset</span><span class="p">(</span><span class="n">kw</span><span class="o">.</span><span class="n">iteritems</span><span class="p">())</span> - <span class="k">else</span><span class="p">:</span> - <span class="n">key</span> <span class="o">=</span> <span class="n">args</span> - <span class="n">cache</span> <span class="o">=</span> <span class="n">func</span><span class="o">.</span><span class="n">cache</span> - <span class="k">if</span> <span class="n">key</span> <span class="ow">in</span> <span class="n">cache</span><span class="p">:</span> - <span class="k">return</span> <span class="n">cache</span><span class="p">[</span><span class="n">key</span><span class="p">]</span> - <span class="k">else</span><span class="p">:</span> - <span class="n">cache</span><span class="p">[</span><span class="n">key</span><span class="p">]</span> <span class="o">=</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">return</span> <span class="n">result</span> - <span class="k">return</span> <span class="n">functools</span><span class="o">.</span><span class="n">update_wrapper</span><span class="p">(</span><span class="n">memoize</span><span class="p">,</span> <span class="n">func</span><span class="p">)</span> -</pre></div> - -</div> -<p>Here we used the <a class="reference external" href="http://www.python.org/doc/2.5.2/lib/module-functools.html">functools.update_wrapper</a> 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 -<tt class="docutils literal">__name__</tt>, <tt class="docutils literal">__doc__</tt>, <tt class="docutils literal">__module__</tt> and <tt class="docutils literal">__dict__</tt> -from the original function to the decorated function by hand).</p> -<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">memoize_uw</tt> returns a function with a -<em>different signature</em> from the original function.</p> -<p>Consider for instance the following case:</p> -<div class="codeblock python"> -<div class="highlight"><pre><span class="o">>>></span> <span class="nd">@memoize_uw</span> -<span class="o">...</span> <span class="k">def</span> <span class="nf">f1</span><span class="p">(</span><span class="n">x</span><span class="p">):</span> -<span class="o">...</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="c"># simulate some long computation</span> -<span class="o">...</span> <span class="k">return</span> <span class="n">x</span> -</pre></div> - -</div> -<p>Here the original function takes a single argument named <tt class="docutils literal">x</tt>, -but the decorated function takes any number of arguments and -keyword arguments:</p> -<div class="codeblock python"> -<div class="highlight"><pre><span class="o">>>></span> <span class="kn">from</span> <span class="nn">inspect</span> <span class="kn">import</span> <span class="n">getargspec</span> -<span class="o">>>></span> <span class="k">print</span> <span class="n">getargspec</span><span class="p">(</span><span class="n">f1</span><span class="p">)</span> <span class="c"># I am using Python 2.6+ here</span> -<span class="n">ArgSpec</span><span class="p">(</span><span class="n">args</span><span class="o">=</span><span class="p">[],</span> <span class="n">varargs</span><span class="o">=</span><span class="s">'args'</span><span class="p">,</span> <span class="n">keywords</span><span class="o">=</span><span class="s">'kw'</span><span class="p">,</span> <span class="n">defaults</span><span class="o">=</span><span class="bp">None</span><span class="p">)</span> -</pre></div> - -</div> -<p>This means that introspection tools such as pydoc will give -wrong informations about the signature of <tt class="docutils literal">f1</tt>. This is pretty bad: -pydoc will tell you that the function accepts a generic signature -<tt class="docutils literal">*args</tt>, <tt class="docutils literal">**kw</tt>, but when you try to call the function with more than an -argument, you will get an error:</p> -<div class="codeblock python"> -<div class="highlight"><pre><span class="o">>>></span> <span class="n">f1</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">)</span> -<span class="n">Traceback</span> <span class="p">(</span><span class="n">most</span> <span class="n">recent</span> <span class="n">call</span> <span class="n">last</span><span class="p">):</span> - <span class="o">...</span> -<span class="ne">TypeError</span><span class="p">:</span> <span class="n">f1</span><span class="p">()</span> <span class="n">takes</span> <span class="n">exactly</span> <span class="mi">1</span> <span class="n">argument</span> <span class="p">(</span><span class="mi">2</span> <span class="n">given</span><span class="p">)</span> -</pre></div> - -</div> -</div> -<div class="section" id="the-solution"> -<h1><a class="toc-backref" href="#id6">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">decorator</tt> function in -the <tt class="docutils literal">decorator</tt> module is such a factory:</p> -<div class="codeblock python"> -<div class="highlight"><pre><span class="o">>>></span> <span class="kn">from</span> <span class="nn">decorator</span> <span class="kn">import</span> <span class="n">decorator</span> -</pre></div> - -</div> -<p><tt class="docutils literal">decorator</tt> 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 <tt class="docutils literal">(f, *args, **kw)</tt> and it must call the original function <tt class="docutils literal">f</tt> -with arguments <tt class="docutils literal">args</tt> and <tt class="docutils literal">kw</tt>, implementing the wanted capability, -i.e. memoization in this case:</p> -<div class="codeblock python"> -<div class="highlight"><pre><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="o">**</span><span class="n">kw</span><span class="p">):</span> - <span class="k">if</span> <span class="n">kw</span><span class="p">:</span> <span class="c"># frozenset is used to ensure hashability</span> - <span class="n">key</span> <span class="o">=</span> <span class="n">args</span><span class="p">,</span> <span class="nb">frozenset</span><span class="p">(</span><span class="n">kw</span><span class="o">.</span><span class="n">iteritems</span><span class="p">())</span> - <span class="k">else</span><span class="p">:</span> - <span class="n">key</span> <span class="o">=</span> <span class="n">args</span> - <span class="n">cache</span> <span class="o">=</span> <span class="n">func</span><span class="o">.</span><span class="n">cache</span> <span class="c"># attributed added by memoize</span> - <span class="k">if</span> <span class="n">key</span> <span class="ow">in</span> <span class="n">cache</span><span class="p">:</span> - <span class="k">return</span> <span class="n">cache</span><span class="p">[</span><span class="n">key</span><span class="p">]</span> - <span class="k">else</span><span class="p">:</span> - <span class="n">cache</span><span class="p">[</span><span class="n">key</span><span class="p">]</span> <span class="o">=</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">return</span> <span class="n">result</span> -</pre></div> - -</div> -<p>At this point you can define your decorator as follows:</p> -<div class="codeblock python"> -<div class="highlight"><pre><span class="k">def</span> <span class="nf">memoize</span><span class="p">(</span><span class="n">f</span><span class="p">):</span> - <span class="n">f</span><span class="o">.</span><span class="n">cache</span> <span class="o">=</span> <span class="p">{}</span> - <span class="k">return</span> <span class="n">decorator</span><span class="p">(</span><span class="n">_memoize</span><span class="p">,</span> <span class="n">f</span><span class="p">)</span> -</pre></div> - -</div> -<p>The difference with respect to the <tt class="docutils literal">memoize_uw</tt> approach, which is based -on nested functions, is that the decorator module forces you to lift -the inner function at the outer level (<em>flat is better than nested</em>). -Moreover, you are forced to pass explicitly the function you want to -decorate to the caller function.</p> -<p>Here is a test of usage:</p> -<div class="codeblock python"> -<div class="highlight"><pre><span class="o">>>></span> <span class="nd">@memoize</span> -<span class="o">...</span> <span class="k">def</span> <span class="nf">heavy_computation</span><span class="p">():</span> -<span class="o">...</span> <span class="n">time</span><span class="o">.</span><span class="n">sleep</span><span class="p">(</span><span class="mi">2</span><span class="p">)</span> -<span class="o">...</span> <span class="k">return</span> <span class="s">"done"</span> - -<span class="o">>>></span> <span class="k">print</span> <span class="n">heavy_computation</span><span class="p">()</span> <span class="c"># the first time it will take 2 seconds</span> -<span class="n">done</span> - -<span class="o">>>></span> <span class="k">print</span> <span class="n">heavy_computation</span><span class="p">()</span> <span class="c"># the second time it will be instantaneous</span> -<span class="n">done</span> -</pre></div> - -</div> -<p>The signature of <tt class="docutils literal">heavy_computation</tt> is the one you would expect:</p> -<div class="codeblock python"> -<div class="highlight"><pre><span class="o">>>></span> <span class="k">print</span> <span class="n">getargspec</span><span class="p">(</span><span class="n">heavy_computation</span><span class="p">)</span> -<span class="n">ArgSpec</span><span class="p">(</span><span class="n">args</span><span class="o">=</span><span class="p">[],</span> <span class="n">varargs</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span> <span class="n">keywords</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span> <span class="n">defaults</span><span class="o">=</span><span class="bp">None</span><span class="p">)</span> -</pre></div> - -</div> -</div> -<div class="section" id="a-trace-decorator"> -<h1><a class="toc-backref" href="#id7">A <tt class="docutils literal">trace</tt> decorator</a></h1> -<p>As an additional example, here is how you can define a trivial -<tt class="docutils literal">trace</tt> decorator, which prints a message everytime the traced -function is called:</p> -<div class="codeblock python"> -<div class="highlight"><pre><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">"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">"</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> -</pre></div> - -</div> -<div class="codeblock python"> -<div class="highlight"><pre><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="k">return</span> <span class="n">decorator</span><span class="p">(</span><span class="n">_trace</span><span class="p">,</span> <span class="n">f</span><span class="p">)</span> -</pre></div> - -</div> -<p>Here is an example of usage:</p> -<div class="codeblock python"> -<div class="highlight"><pre><span class="o">>>></span> <span class="nd">@trace</span> -<span class="o">...</span> <span class="k">def</span> <span class="nf">f1</span><span class="p">(</span><span class="n">x</span><span class="p">):</span> -<span class="o">...</span> <span class="k">pass</span> -</pre></div> - -</div> -<p>It is immediate to verify that <tt class="docutils literal">f1</tt> works</p> -<div class="codeblock python"> -<div class="highlight"><pre><span class="o">>>></span> <span class="n">f1</span><span class="p">(</span><span class="mi">0</span><span class="p">)</span> -<span class="n">calling</span> <span class="n">f1</span> <span class="k">with</span> <span class="n">args</span> <span class="p">(</span><span class="mi">0</span><span class="p">,),</span> <span class="p">{}</span> -</pre></div> - -</div> -<p>and it that it has the correct signature:</p> -<div class="codeblock python"> -<div class="highlight"><pre><span class="o">>>></span> <span class="k">print</span> <span class="n">getargspec</span><span class="p">(</span><span class="n">f1</span><span class="p">)</span> -<span class="n">ArgSpec</span><span class="p">(</span><span class="n">args</span><span class="o">=</span><span class="p">[</span><span class="s">'x'</span><span class="p">],</span> <span class="n">varargs</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span> <span class="n">keywords</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span> <span class="n">defaults</span><span class="o">=</span><span class="bp">None</span><span class="p">)</span> -</pre></div> - -</div> -<p>The same decorator works with functions of any signature:</p> -<div class="codeblock python"> -<div class="highlight"><pre><span class="o">>>></span> <span class="nd">@trace</span> -<span class="o">...</span> <span class="k">def</span> <span class="nf">f</span><span class="p">(</span><span class="n">x</span><span class="p">,</span> <span class="n">y</span><span class="o">=</span><span class="mi">1</span><span class="p">,</span> <span class="n">z</span><span class="o">=</span><span class="mi">2</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="o">...</span> <span class="k">pass</span> - -<span class="o">>>></span> <span class="n">f</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">3</span><span class="p">)</span> -<span class="n">calling</span> <span class="n">f</span> <span class="k">with</span> <span class="n">args</span> <span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">2</span><span class="p">),</span> <span class="p">{}</span> - -<span class="o">>>></span> <span class="k">print</span> <span class="n">getargspec</span><span class="p">(</span><span class="n">f</span><span class="p">)</span> -<span class="n">ArgSpec</span><span class="p">(</span><span class="n">args</span><span class="o">=</span><span class="p">[</span><span class="s">'x'</span><span class="p">,</span> <span class="s">'y'</span><span class="p">,</span> <span class="s">'z'</span><span class="p">],</span> <span class="n">varargs</span><span class="o">=</span><span class="s">'args'</span><span class="p">,</span> <span class="n">keywords</span><span class="o">=</span><span class="s">'kw'</span><span class="p">,</span> <span class="n">defaults</span><span class="o">=</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">))</span> -</pre></div> - -</div> -<p>That includes even functions with exotic signatures like the following:</p> -<div class="codeblock python"> -<div class="highlight"><pre><span class="o">>>></span> <span class="nd">@trace</span> -<span class="o">...</span> <span class="k">def</span> <span class="nf">exotic_signature</span><span class="p">((</span><span class="n">x</span><span class="p">,</span> <span class="n">y</span><span class="p">)</span><span class="o">=</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">)):</span> <span class="k">return</span> <span class="n">x</span><span class="o">+</span><span class="n">y</span> - -<span class="o">>>></span> <span class="k">print</span> <span class="n">getargspec</span><span class="p">(</span><span class="n">exotic_signature</span><span class="p">)</span> -<span class="n">ArgSpec</span><span class="p">(</span><span class="n">args</span><span class="o">=</span><span class="p">[[</span><span class="s">'x'</span><span class="p">,</span> <span class="s">'y'</span><span class="p">]],</span> <span class="n">varargs</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span> <span class="n">keywords</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span> <span class="n">defaults</span><span class="o">=</span><span class="p">((</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">),))</span> -<span class="o">>>></span> <span class="n">exotic_signature</span><span class="p">()</span> -<span class="n">calling</span> <span class="n">exotic_signature</span> <span class="k">with</span> <span class="n">args</span> <span class="p">((</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">),),</span> <span class="p">{}</span> -<span class="mi">3</span> -</pre></div> - -</div> -<p>Notice that the support for exotic signatures has been deprecated -in Python 2.6 and removed in Python 3.0.</p> -</div> -<div class="section" id="decorator-is-a-decorator"> -<h1><a class="toc-backref" href="#id8"><tt class="docutils literal">decorator</tt> is a decorator</a></h1> -<p>It may be annoying to write a caller function (like the <tt class="docutils literal">_trace</tt> -function above) and then a trivial wrapper -(<tt class="docutils literal">def trace(f): return decorator(_trace, f)</tt>) every time. For this reason, -the <tt class="docutils literal">decorator</tt> module provides an easy shortcut to convert -the caller function into a signature-preserving decorator: -you can just call <tt class="docutils literal">decorator</tt> with a single argument. -In our example you can just write <tt class="docutils literal">trace = decorator(_trace)</tt>. -The <tt class="docutils literal">decorator</tt> function can also be used as a signature-changing -decorator, just as <tt class="docutils literal">classmethod</tt> and <tt class="docutils literal">staticmethod</tt>. -However, <tt class="docutils literal">classmethod</tt> and <tt class="docutils literal">staticmethod</tt> return generic -objects which are not callable, while <tt class="docutils literal">decorator</tt> returns -signature-preserving decorators, i.e. functions of a single argument. -For instance, you can write directly</p> -<div class="codeblock python"> -<div class="highlight"><pre><span class="o">>>></span> <span class="nd">@decorator</span> -<span class="o">...</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="o">...</span> <span class="k">print</span> <span class="s">"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">"</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="o">...</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> -</pre></div> - -</div> -<p>and now <tt class="docutils literal">trace</tt> will be a decorator. Actually <tt class="docutils literal">trace</tt> is a <tt class="docutils literal">partial</tt> -object which can be used as a decorator:</p> -<div class="codeblock python"> -<div class="highlight"><pre><span class="o">>>></span> <span class="n">trace</span> -<span class="o"><</span><span class="n">function</span> <span class="n">trace</span> <span class="n">at</span> <span class="mi">0</span><span class="n">x</span><span class="o">...></span> -</pre></div> - -</div> -<p>Here is an example of usage:</p> -<div class="codeblock python"> -<div class="highlight"><pre><span class="o">>>></span> <span class="nd">@trace</span> -<span class="o">...</span> <span class="k">def</span> <span class="nf">func</span><span class="p">():</span> <span class="k">pass</span> - -<span class="o">>>></span> <span class="n">func</span><span class="p">()</span> -<span class="n">calling</span> <span class="n">func</span> <span class="k">with</span> <span class="n">args</span> <span class="p">(),</span> <span class="p">{}</span> -</pre></div> - -</div> -<p>If you are using an old Python version (Python 2.4) the -<tt class="docutils literal">decorator</tt> module provides a poor man replacement for -<tt class="docutils literal">functools.partial</tt>.</p> -</div> -<div class="section" id="blocking"> -<h1><a class="toc-backref" href="#id9"><tt class="docutils literal">blocking</tt></a></h1> -<p>Sometimes one has to deal with blocking resources, such as <tt class="docutils literal">stdin</tt>, and -sometimes it is best to have back a "busy" message than to block everything. -This behavior can be implemented with a suitable family of decorators, -where the parameter is the busy message:</p> -<div class="codeblock python"> -<div class="highlight"><pre><span class="k">def</span> <span class="nf">blocking</span><span class="p">(</span><span class="n">not_avail</span><span class="p">):</span> - <span class="k">def</span> <span class="nf">blocking</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">"thread"</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">blocking</span><span class="p">)</span> -</pre></div> - -</div> -<p>Functions decorated with <tt class="docutils literal">blocking</tt> will return a busy message if -the resource is unavailable, and the intended result if the resource is -available. For instance:</p> -<div class="codeblock python"> -<div class="highlight"><pre><span class="o">>>></span> <span class="nd">@blocking</span><span class="p">(</span><span class="s">"Please wait ..."</span><span class="p">)</span> -<span class="o">...</span> <span class="k">def</span> <span class="nf">read_data</span><span class="p">():</span> -<span class="o">...</span> <span class="n">time</span><span class="o">.</span><span class="n">sleep</span><span class="p">(</span><span class="mi">3</span><span class="p">)</span> <span class="c"># simulate a blocking resource</span> -<span class="o">...</span> <span class="k">return</span> <span class="s">"some data"</span> - -<span class="o">>>></span> <span class="k">print</span> <span class="n">read_data</span><span class="p">()</span> <span class="c"># data is not available yet</span> -<span class="n">Please</span> <span class="n">wait</span> <span class="o">...</span> - -<span class="o">>>></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="o">>>></span> <span class="k">print</span> <span class="n">read_data</span><span class="p">()</span> <span class="c"># data is not available yet</span> -<span class="n">Please</span> <span class="n">wait</span> <span class="o">...</span> - -<span class="o">>>></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="o">>>></span> <span class="k">print</span> <span class="n">read_data</span><span class="p">()</span> <span class="c"># data is not available yet</span> -<span class="n">Please</span> <span class="n">wait</span> <span class="o">...</span> - -<span class="o">>>></span> <span class="n">time</span><span class="o">.</span><span class="n">sleep</span><span class="p">(</span><span class="mf">1.1</span><span class="p">)</span> <span class="c"># after 3.1 seconds, data is available</span> -<span class="o">>>></span> <span class="k">print</span> <span class="n">read_data</span><span class="p">()</span> -<span class="n">some</span> <span class="n">data</span> -</pre></div> - -</div> -</div> -<div class="section" id="async"> -<h1><a class="toc-backref" href="#id10"><tt class="docutils literal">async</tt></a></h1> -<p>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 converted into decorators.</p> -<p>As an example, here will 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 <tt class="docutils literal">on_success</tt>, <tt class="docutils literal">on_failure</tt> and <tt class="docutils literal">on_closing</tt>, -to specify how to manage the function call (of course the code here -is just an example, it is not a recommended way of doing multi-threaded -programming). The implementation is the following:</p> -<div class="codeblock python"> -<div class="highlight"><pre><span class="k">def</span> <span class="nf">on_success</span><span class="p">(</span><span class="n">result</span><span class="p">):</span> <span class="c"># default implementation</span> - <span class="s">"Called on the result of the function"</span> - <span class="k">return</span> <span class="n">result</span> -</pre></div> - -</div> -<div class="codeblock python"> -<div class="highlight"><pre><span class="k">def</span> <span class="nf">on_failure</span><span class="p">(</span><span class="n">exc_info</span><span class="p">):</span> <span class="c"># default implementation</span> - <span class="s">"Called if the function fails"</span> - <span class="k">pass</span> -</pre></div> - -</div> -<div class="codeblock python"> -<div class="highlight"><pre><span class="k">def</span> <span class="nf">on_closing</span><span class="p">():</span> <span class="c"># default implementation</span> - <span class="s">"Called at the end, both in case of success and failure"</span> - <span class="k">pass</span> -</pre></div> - -</div> -<div class="codeblock python"> -<div class="highlight"><pre><span class="k">class</span> <span class="nc">Async</span><span class="p">(</span><span class="nb">object</span><span class="p">):</span> - <span class="sd">"""</span> -<span class="sd"> A decorator converting blocking functions into asynchronous</span> -<span class="sd"> functions, by using threads or processes. Examples:</span> - -<span class="sd"> async_with_threads = Async(threading.Thread)</span> -<span class="sd"> async_with_processes = Async(multiprocessing.Process)</span> -<span class="sd"> """</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">threadfactory</span><span class="p">,</span> <span class="n">on_success</span><span class="o">=</span><span class="n">on_success</span><span class="p">,</span> - <span class="n">on_failure</span><span class="o">=</span><span class="n">on_failure</span><span class="p">,</span> <span class="n">on_closing</span><span class="o">=</span><span class="n">on_closing</span><span class="p">):</span> - <span class="bp">self</span><span class="o">.</span><span class="n">threadfactory</span> <span class="o">=</span> <span class="n">threadfactory</span> - <span class="bp">self</span><span class="o">.</span><span class="n">on_success</span> <span class="o">=</span> <span class="n">on_success</span> - <span class="bp">self</span><span class="o">.</span><span class="n">on_failure</span> <span class="o">=</span> <span class="n">on_failure</span> - <span class="bp">self</span><span class="o">.</span><span class="n">on_closing</span> <span class="o">=</span> <span class="n">on_closing</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="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">try</span><span class="p">:</span> - <span class="n">counter</span> <span class="o">=</span> <span class="n">func</span><span class="o">.</span><span class="n">counter</span> - <span class="k">except</span> <span class="ne">AttributeError</span><span class="p">:</span> <span class="c"># instantiate the counter at the first call</span> - <span class="n">counter</span> <span class="o">=</span> <span class="n">func</span><span class="o">.</span><span class="n">counter</span> <span class="o">=</span> <span class="n">itertools</span><span class="o">.</span><span class="n">count</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span> - <span class="n">name</span> <span class="o">=</span> <span class="s">'</span><span class="si">%s</span><span class="s">-</span><span class="si">%s</span><span class="s">'</span> <span class="o">%</span> <span class="p">(</span><span class="n">func</span><span class="o">.</span><span class="n">__name__</span><span class="p">,</span> <span class="n">counter</span><span class="o">.</span><span class="n">next</span><span class="p">())</span> - <span class="k">def</span> <span class="nf">func_wrapper</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">except</span><span class="p">:</span> - <span class="bp">self</span><span class="o">.</span><span class="n">on_failure</span><span class="p">(</span><span class="n">sys</span><span class="o">.</span><span class="n">exc_info</span><span class="p">())</span> - <span class="k">else</span><span class="p">:</span> - <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">on_success</span><span class="p">(</span><span class="n">result</span><span class="p">)</span> - <span class="k">finally</span><span class="p">:</span> - <span class="bp">self</span><span class="o">.</span><span class="n">on_closing</span><span class="p">()</span> - <span class="n">thread</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">threadfactory</span><span class="p">(</span><span class="bp">None</span><span class="p">,</span> <span class="n">func_wrapper</span><span class="p">,</span> <span class="n">name</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> -</pre></div> - -</div> -<p>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">.isAlive()</tt>.</p> -<p>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:</p> -<div class="codeblock python"> -<div class="highlight"><pre><span class="o">>>></span> <span class="n">async</span> <span class="o">=</span> <span class="n">decorator</span><span class="p">(</span><span class="n">Async</span><span class="p">(</span><span class="n">threading</span><span class="o">.</span><span class="n">Thread</span><span class="p">))</span> - -<span class="o">>>></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="o">>>></span> <span class="nd">@async</span> -<span class="o">...</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="o">...</span> <span class="c"># append data to the datalist by locking</span> -<span class="o">...</span> <span class="k">with</span> <span class="n">threading</span><span class="o">.</span><span class="n">Lock</span><span class="p">():</span> -<span class="o">...</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="c"># emulate some long running operation</span> -<span class="o">...</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="o">...</span> <span class="c"># other operations not requiring a lock here</span> -</pre></div> - -</div> -<p>Each call to <tt class="docutils literal">write</tt> will create a new writer thread, but there will -be no synchronization problems since <tt class="docutils literal">write</tt> is locked.</p> -<div class="codeblock python"> -<div class="highlight"><pre><span class="o">>>></span> <span class="n">write</span><span class="p">(</span><span class="s">"data1"</span><span class="p">)</span> -<span class="o"><</span><span class="n">Thread</span><span class="p">(</span><span class="n">write</span><span class="o">-</span><span class="mi">1</span><span class="p">,</span> <span class="n">started</span><span class="o">...</span><span class="p">)</span><span class="o">></span> - -<span class="o">>>></span> <span class="n">time</span><span class="o">.</span><span class="n">sleep</span><span class="p">(</span><span class="o">.</span><span class="mi">1</span><span class="p">)</span> <span class="c"># wait a bit, so we are sure data2 is written after data1</span> - -<span class="o">>>></span> <span class="n">write</span><span class="p">(</span><span class="s">"data2"</span><span class="p">)</span> -<span class="o"><</span><span class="n">Thread</span><span class="p">(</span><span class="n">write</span><span class="o">-</span><span class="mi">2</span><span class="p">,</span> <span class="n">started</span><span class="o">...</span><span class="p">)</span><span class="o">></span> - -<span class="o">>>></span> <span class="n">time</span><span class="o">.</span><span class="n">sleep</span><span class="p">(</span><span class="mi">2</span><span class="p">)</span> <span class="c"># wait for the writers to complete</span> - -<span class="o">>>></span> <span class="k">print</span> <span class="n">datalist</span> -<span class="p">[</span><span class="s">'data1'</span><span class="p">,</span> <span class="s">'data2'</span><span class="p">]</span> -</pre></div> - -</div> -</div> -<div class="section" id="contextmanager"> -<h1><a class="toc-backref" href="#id11">contextmanager</a></h1> -<p>For a long time Python had in its standard library a <tt class="docutils literal">contextmanager</tt> -decorator, able to convert generator functions into <tt class="docutils literal">GeneratorContextManager</tt> -factories. For instance if you write</p> -<div class="codeblock python"> -<div class="highlight"><pre><span class="o">>>></span> <span class="kn">from</span> <span class="nn">contextlib</span> <span class="kn">import</span> <span class="n">contextmanager</span> -<span class="o">>>></span> <span class="nd">@contextmanager</span> -<span class="o">...</span> <span class="k">def</span> <span class="nf">before_after</span><span class="p">(</span><span class="n">before</span><span class="p">,</span> <span class="n">after</span><span class="p">):</span> -<span class="o">...</span> <span class="k">print</span><span class="p">(</span><span class="n">before</span><span class="p">)</span> -<span class="o">...</span> <span class="k">yield</span> -<span class="o">...</span> <span class="k">print</span><span class="p">(</span><span class="n">after</span><span class="p">)</span> -</pre></div> - -</div> -<p>then <tt class="docutils literal">before_after</tt> is a factory function returning -<tt class="docutils literal">GeneratorContextManager</tt> objects which can be used with -the <tt class="docutils literal">with</tt> statement:</p> -<div class="codeblock python"> -<div class="highlight"><pre><span class="o">>>></span> <span class="n">ba</span> <span class="o">=</span> <span class="n">before_after</span><span class="p">(</span><span class="s">'BEFORE'</span><span class="p">,</span> <span class="s">'AFTER'</span><span class="p">)</span> -<span class="o">>>></span> <span class="nb">type</span><span class="p">(</span><span class="n">ba</span><span class="p">)</span> -<span class="o"><</span><span class="k">class</span> <span class="err">'</span><span class="nc">contextlib</span><span class="o">.</span><span class="n">GeneratorContextManager</span><span class="s">'></span> -<span class="o">>>></span> <span class="k">with</span> <span class="n">ba</span><span class="p">:</span> -<span class="o">...</span> <span class="k">print</span> <span class="s">'hello'</span> -<span class="n">BEFORE</span> -<span class="n">hello</span> -<span class="n">AFTER</span> -</pre></div> - -</div> -<p>Basically, it is as if the content of the <tt class="docutils literal">with</tt> block was executed -in the place of the <tt class="docutils literal">yield</tt> expression in the generator function. -In Python 3.2 <tt class="docutils literal">GeneratorContextManager</tt> -objects were enhanced with a <tt class="docutils literal">__call__</tt> -method, so that they can be used as decorators as in this example:</p> -<div class="codeblock python"> -<div class="highlight"><pre><span class="o">>>></span> <span class="nd">@ba</span> -<span class="o">...</span> <span class="k">def</span> <span class="nf">hello</span><span class="p">():</span> -<span class="o">...</span> <span class="k">print</span> <span class="s">'hello'</span> -<span class="o">...</span> -<span class="o">>>></span> <span class="n">hello</span><span class="p">()</span> -<span class="n">BEFORE</span> -<span class="n">hello</span> -<span class="n">AFTER</span> -</pre></div> - -</div> -<p>The <tt class="docutils literal">ba</tt> decorator is basically inserting a <tt class="docutils literal">with ba:</tt> -block inside the function. -However there two issues: the first is that <tt class="docutils literal">GeneratorContextManager</tt> -objects are callable only in Python 3.2, so the previous example will break -in older versions of Python; the second is that -<tt class="docutils literal">GeneratorContextManager</tt> objects do not preserve the signature -of the decorated functions: the decorated <tt class="docutils literal">hello</tt> function here will have -a generic signature <tt class="docutils literal"><span class="pre">hello(*args,</span> **kwargs)</tt> but will break when -called with more than zero arguments. For such reasons the decorator -module, starting with release 3.4, offers a <tt class="docutils literal">decorator.contextmanager</tt> -decorator that solves both problems and works even in Python 2.5. -The usage is the same and factories decorated with <tt class="docutils literal">decorator.contextmanager</tt> -will returns instances of <tt class="docutils literal">ContextManager</tt>, a subclass of -<tt class="docutils literal">contextlib.GeneratorContextManager</tt> with a <tt class="docutils literal">__call__</tt> method -acting as a signature-preserving decorator.</p> -</div> -<div class="section" id="the-functionmaker-class"> -<h1><a class="toc-backref" href="#id12">The <tt class="docutils literal">FunctionMaker</tt> class</a></h1> -<p>You may wonder about how the functionality of the <tt class="docutils literal">decorator</tt> module -is implemented. The basic building block is -a <tt class="docutils literal">FunctionMaker</tt> class which is able to generate on the fly -functions with a given name and signature from a function template -passed as a string. Generally speaking, you should not need to -resort to <tt class="docutils literal">FunctionMaker</tt> when writing ordinary decorators, but -it is handy in some circumstances. You will see an example shortly, in -the implementation of a cool decorator utility (<tt class="docutils literal">decorator_apply</tt>).</p> -<p><tt class="docutils literal">FunctionMaker</tt> provides a <tt class="docutils literal">.create</tt> classmethod which -takes as input the name, signature, and body of the function -we want to generate as well as the execution environment -were the function is generated by <tt class="docutils literal">exec</tt>. Here is an example:</p> -<div class="codeblock python"> -<div class="highlight"><pre><span class="o">>>></span> <span class="k">def</span> <span class="nf">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"># a function with a generic signature</span> -<span class="o">...</span> <span class="k">print</span> <span class="n">args</span><span class="p">,</span> <span class="n">kw</span> - -<span class="o">>>></span> <span class="n">f1</span> <span class="o">=</span> <span class="n">FunctionMaker</span><span class="o">.</span><span class="n">create</span><span class="p">(</span><span class="s">'f1(a, b)'</span><span class="p">,</span> <span class="s">'f(a, b)'</span><span class="p">,</span> <span class="nb">dict</span><span class="p">(</span><span class="n">f</span><span class="o">=</span><span class="n">f</span><span class="p">))</span> -<span class="o">>>></span> <span class="n">f1</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">)</span> -<span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">)</span> <span class="p">{}</span> -</pre></div> - -</div> -<p>It is important to notice that the function body is interpolated -before being executed, so be careful with the <tt class="docutils literal">%</tt> sign!</p> -<p><tt class="docutils literal">FunctionMaker.create</tt> 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 <tt class="docutils literal">__doc__</tt>.</p> -<p>For debugging/introspection purposes it may be useful to see -the source code of the generated function; to do that, just -pass the flag <tt class="docutils literal">addsource=True</tt> and a <tt class="docutils literal">__source__</tt> attribute will -be added to the generated function:</p> -<div class="codeblock python"> -<div class="highlight"><pre><span class="o">>>></span> <span class="n">f1</span> <span class="o">=</span> <span class="n">FunctionMaker</span><span class="o">.</span><span class="n">create</span><span class="p">(</span> -<span class="o">...</span> <span class="s">'f1(a, b)'</span><span class="p">,</span> <span class="s">'f(a, b)'</span><span class="p">,</span> <span class="nb">dict</span><span class="p">(</span><span class="n">f</span><span class="o">=</span><span class="n">f</span><span class="p">),</span> <span class="n">addsource</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span> -<span class="o">>>></span> <span class="k">print</span> <span class="n">f1</span><span class="o">.</span><span class="n">__source__</span> -<span class="k">def</span> <span class="nf">f1</span><span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="n">b</span><span class="p">):</span> - <span class="n">f</span><span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="n">b</span><span class="p">)</span> -<span class="o"><</span><span class="n">BLANKLINE</span><span class="o">></span> -</pre></div> - -</div> -<p><tt class="docutils literal">FunctionMaker.create</tt> can take as first argument a string, -as in the examples before, or a function. This is the most common -usage, since typically you want to decorate a pre-existing -function. A framework author may want to use directly <tt class="docutils literal">FunctionMaker.create</tt> -instead of <tt class="docutils literal">decorator</tt>, since it gives you direct access to the body -of the generated function. For instance, suppose you want to instrument -the <tt class="docutils literal">__init__</tt> methods of a set of classes, by preserving their -signature (such use case is not made up; this is done in SQAlchemy -and in other frameworks). When the first argument of <tt class="docutils literal">FunctionMaker.create</tt> -is a function, a <tt class="docutils literal">FunctionMaker</tt> object is instantiated internally, -with attributes <tt class="docutils literal">args</tt>, <tt class="docutils literal">varargs</tt>, -<tt class="docutils literal">keywords</tt> and <tt class="docutils literal">defaults</tt> which are the -the return values of the standard library function <tt class="docutils literal">inspect.getargspec</tt>. -For each argument in the <tt class="docutils literal">args</tt> (which is a list of strings containing -the names of the mandatory arguments) an attribute <tt class="docutils literal">arg0</tt>, <tt class="docutils literal">arg1</tt>, -..., <tt class="docutils literal">argN</tt> is also generated. Finally, there is a <tt class="docutils literal">signature</tt> -attribute, a string with the signature of the original function.</p> -<p>Notice that while I do not have plans -to change or remove the functionality provided in the -<tt class="docutils literal">FunctionMaker</tt> class, I do not guarantee that it will stay -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 -<tt class="docutils literal">decorator</tt> has been there from version 0.1 and it is guaranteed to -stay there forever.</p> -</div> -<div class="section" id="getting-the-source-code"> -<h1><a class="toc-backref" href="#id13">Getting the source code</a></h1> -<p>Internally <tt class="docutils literal">FunctionMaker.create</tt> uses <tt class="docutils literal">exec</tt> to generate the -decorated function. Therefore -<tt class="docutils literal">inspect.getsource</tt> will not work for decorated functions. That -means that the usual '??' trick in IPython will give you the (right on -the spot) message <tt class="docutils literal">Dynamically generated function. No source code -available</tt>. In the past I have considered this acceptable, since -<tt class="docutils literal">inspect.getsource</tt> does not really work even with regular -decorators. In that case <tt class="docutils literal">inspect.getsource</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="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> -</pre></div> - -</div> -<div class="codeblock python"> -<div class="highlight"><pre><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="o">>>></span> <span class="k">print</span> <span class="n">inspect</span><span class="o">.</span><span class="n">getsource</span><span class="p">(</span><span class="n">example</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="o"><</span><span class="n">BLANKLINE</span><span class="o">></span> -</pre></div> - -</div> -<p>(see bug report <a class="reference external" href="http://bugs.python.org/issue1764286">1764286</a> for an explanation of what is happening). -Unfortunately the bug is still there, even in Python 2.7 and 3.1. -There is however a workaround. The decorator module adds an -attribute <tt class="docutils literal">.__wrapped__</tt> to the decorated function, containing -a reference to the original function. The easy way to get -the source code is to call <tt class="docutils literal">inspect.getsource</tt> on the -undecorated function:</p> -<div class="codeblock python"> -<div class="highlight"><pre><span class="o">>>></span> <span class="k">print</span> <span class="n">inspect</span><span class="o">.</span><span class="n">getsource</span><span class="p">(</span><span class="n">factorial</span><span class="o">.</span><span class="n">__wrapped__</span><span class="p">)</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">"The good old factorial"</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="o"><</span><span class="n">BLANKLINE</span><span class="o">></span> -</pre></div> - -</div> -</div> -<div class="section" id="dealing-with-third-party-decorators"> -<h1><a class="toc-backref" href="#id14">Dealing with third party decorators</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">decorator</tt>. You can use a -<tt class="docutils literal">FunctionMaker</tt> to implement that functionality as follows:</p> -<div class="codeblock python"> -<div class="highlight"><pre><span class="k">def</span> <span class="nf">decorator_apply</span><span class="p">(</span><span class="n">dec</span><span class="p">,</span> <span class="n">func</span><span class="p">):</span> - <span class="sd">"""</span> -<span class="sd"> Decorate a function by preserving the signature even if dec</span> -<span class="sd"> is not a signature-preserving decorator.</span> -<span class="sd"> """</span> - <span class="k">return</span> <span class="n">FunctionMaker</span><span class="o">.</span><span class="n">create</span><span class="p">(</span> - <span class="n">func</span><span class="p">,</span> <span class="s">'return decorated(</span><span class="si">%(signature)s</span><span class="s">)'</span><span class="p">,</span> - <span class="nb">dict</span><span class="p">(</span><span class="n">decorated</span><span class="o">=</span><span class="n">dec</span><span class="p">(</span><span class="n">func</span><span class="p">)),</span> <span class="n">__wrapped__</span><span class="o">=</span><span class="n">func</span><span class="p">)</span> -</pre></div> - -</div> -<p><tt class="docutils literal">decorator_apply</tt> sets the attribute <tt class="docutils literal">.__wrapped__</tt> of the generated -function to the original function, so that you can get the right -source code.</p> -<p>Notice that I am not providing this functionality in the <tt class="docutils literal">decorator</tt> -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 <tt class="docutils literal">decorator_apply</tt> to your toolbox and -use it if you need to.</p> -<p>In order to give an example of usage of <tt class="docutils literal">decorator_apply</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 external" 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="k">class</span> <span class="nc">TailRecursive</span><span class="p">(</span><span class="nb">object</span><span class="p">):</span> - <span class="sd">"""</span> -<span class="sd"> tail_recursive decorator based on Kay Schluehr's recipe</span> -<span class="sd"> http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/496691</span> -<span class="sd"> with improvements by me and George Sakkis.</span> -<span class="sd"> """</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="bp">self</span><span class="o">.</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">__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="n">CONTINUE</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">CONTINUE</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="n">func</span> <span class="o">=</span> <span class="bp">self</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">False</span> - <span class="k">try</span><span class="p">:</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="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="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">return</span> <span class="n">result</span> - <span class="k">finally</span><span class="p">:</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">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="n">CONTINUE</span> -</pre></div> - -</div> -<p>Here the decorator is implemented as a class returning callable -objects.</p> -<div class="codeblock python"> -<div class="highlight"><pre><span class="k">def</span> <span class="nf">tail_recursive</span><span class="p">(</span><span class="n">func</span><span class="p">):</span> - <span class="k">return</span> <span class="n">decorator_apply</span><span class="p">(</span><span class="n">TailRecursive</span><span class="p">,</span> <span class="n">func</span><span class="p">)</span> -</pre></div> - -</div> -<p>Here is how you apply the upgraded decorator to the good old factorial:</p> -<div class="codeblock python"> -<div class="highlight"><pre><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">"The good old factorial"</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> -</pre></div> - -</div> -<div class="codeblock python"> -<div class="highlight"><pre><span class="o">>>></span> <span class="k">print</span> <span class="n">factorial</span><span class="p">(</span><span class="mi">4</span><span class="p">)</span> -<span class="mi">24</span> -</pre></div> - -</div> -<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">factorial(1001)</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 the following</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>(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).</p> -</div> -<div class="section" id="caveats-and-limitations"> -<h1><a class="toc-backref" href="#id15">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 " -from decorator import decorator - -@decorator -def do_nothing(func, *args, **kw): - return func(*args, **kw) - -@do_nothing -def f(): - pass -" "f()" - -python -m timeit -s " -def f(): - pass -" "f()" -</pre> -<p>On my MacBook, using the <tt class="docutils literal">do_nothing</tt> decorator instead of the -plain function is more than three times slower:</p> -<pre class="literal-block"> -$ bash performance.sh -1000000 loops, best of 3: 0.995 usec per loop -1000000 loops, best of 3: 0.273 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">f</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> -<div class="codeblock python"> -<div class="highlight"><pre><span class="o">>>></span> <span class="nd">@trace</span> -<span class="o">...</span> <span class="k">def</span> <span class="nf">f</span><span class="p">():</span> -<span class="o">...</span> <span class="mi">1</span><span class="o">/</span><span class="mi">0</span> -</pre></div> - -</div> -<p>Calling <tt class="docutils literal">f()</tt> will give you a <tt class="docutils literal">ZeroDivisionError</tt>, but since the -function is decorated the traceback will be longer:</p> -<div class="codeblock python"> -<div class="highlight"><pre><span class="o">>>></span> <span class="n">f</span><span class="p">()</span> -<span class="n">Traceback</span> <span class="p">(</span><span class="n">most</span> <span class="n">recent</span> <span class="n">call</span> <span class="n">last</span><span class="p">):</span> - <span class="o">...</span> - <span class="n">File</span> <span class="s">"<string>"</span><span class="p">,</span> <span class="n">line</span> <span class="mi">2</span><span class="p">,</span> <span class="ow">in</span> <span class="n">f</span> - <span class="n">File</span> <span class="s">"<doctest __main__[18]>"</span><span class="p">,</span> <span class="n">line</span> <span class="mi">4</span><span class="p">,</span> <span class="ow">in</span> <span class="n">trace</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">File</span> <span class="s">"<doctest __main__[47]>"</span><span class="p">,</span> <span class="n">line</span> <span class="mi">3</span><span class="p">,</span> <span class="ow">in</span> <span class="n">f</span> - <span class="mi">1</span><span class="o">/</span><span class="mi">0</span> -<span class="ne">ZeroDivisionError</span><span class="p">:</span> <span class="n">integer</span> <span class="n">division</span> <span class="ow">or</span> <span class="n">modulo</span> <span class="n">by</span> <span class="n">zero</span> -</pre></div> - -</div> -<p>You see here the inner call to the decorator <tt class="docutils literal">trace</tt>, which calls -<tt class="docutils literal"><span class="pre">f(*args,</span> **kw)</tt>, and a reference to <tt class="docutils literal">File <span class="pre">"<string>",</span> line 2, in f</tt>. -This latter reference is due to the fact that internally the decorator -module uses <tt class="docutils literal">exec</tt> to generate the decorated function. Notice that -<tt class="docutils literal">exec</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>At present, there is no clean way to avoid <tt class="docutils literal">exec</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. -That could happen in future versions of Python (see PEP <a class="reference external" href="http://www.python.org/dev/peps/pep-0362">362</a>) and -then the decorator module would become obsolete. However, at present, -even in Python 3.1 it is impossible to change the function signature -directly, therefore the <tt class="docutils literal">decorator</tt> module is still useful. -Actually, this is one of the main reasons why I keep maintaining -the module and releasing new versions.</p> -<p>In the present implementation, decorators generated by <tt class="docutils literal">decorator</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">inspect</tt> module in the standard library. Moreover, notice -that you can decorate a method, but only before if becomes a bound or unbound -method, i.e. inside the class. -Here is an example of valid decoration:</p> -<div class="codeblock python"> -<div class="highlight"><pre><span class="o">>>></span> <span class="k">class</span> <span class="nc">C</span><span class="p">(</span><span class="nb">object</span><span class="p">):</span> -<span class="o">...</span> <span class="nd">@trace</span> -<span class="o">...</span> <span class="k">def</span> <span class="nf">meth</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span> -<span class="o">...</span> <span class="k">pass</span> -</pre></div> - -</div> -<p>Here is an example of invalid decoration, when the decorator in -called too late:</p> -<div class="codeblock python"> -<div class="highlight"><pre><span class="o">>>></span> <span class="k">class</span> <span class="nc">C</span><span class="p">(</span><span class="nb">object</span><span class="p">):</span> -<span class="o">...</span> <span class="k">def</span> <span class="nf">meth</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span> -<span class="o">...</span> <span class="k">pass</span> -<span class="o">...</span> -<span class="o">>>></span> <span class="n">trace</span><span class="p">(</span><span class="n">C</span><span class="o">.</span><span class="n">meth</span><span class="p">)</span> -<span class="n">Traceback</span> <span class="p">(</span><span class="n">most</span> <span class="n">recent</span> <span class="n">call</span> <span class="n">last</span><span class="p">):</span> - <span class="o">...</span> -<span class="ne">TypeError</span><span class="p">:</span> <span class="n">You</span> <span class="n">are</span> <span class="n">decorating</span> <span class="n">a</span> <span class="n">non</span> <span class="n">function</span><span class="p">:</span> <span class="o"><</span><span class="n">unbound</span> <span class="n">method</span> <span class="n">C</span><span class="o">.</span><span class="n">meth</span><span class="o">></span> -</pre></div> - -</div> -<p>The solution is to extract the inner function from the unbound method:</p> -<div class="codeblock python"> -<div class="highlight"><pre><span class="o">>>></span> <span class="n">trace</span><span class="p">(</span><span class="n">C</span><span class="o">.</span><span class="n">meth</span><span class="o">.</span><span class="n">im_func</span><span class="p">)</span> -<span class="o"><</span><span class="n">function</span> <span class="n">meth</span> <span class="n">at</span> <span class="mi">0</span><span class="n">x</span><span class="o">...></span> -</pre></div> - -</div> -<p>There is a restriction on the names of the arguments: for instance, -if try to call an argument <tt class="docutils literal">_call_</tt> or <tt class="docutils literal">_func_</tt> -you will get a <tt class="docutils literal">NameError</tt>:</p> -<div class="codeblock python"> -<div class="highlight"><pre><span class="o">>>></span> <span class="nd">@trace</span> -<span class="o">...</span> <span class="k">def</span> <span class="nf">f</span><span class="p">(</span><span class="n">_func_</span><span class="p">):</span> <span class="k">print</span> <span class="n">f</span> -<span class="o">...</span> -<span class="n">Traceback</span> <span class="p">(</span><span class="n">most</span> <span class="n">recent</span> <span class="n">call</span> <span class="n">last</span><span class="p">):</span> - <span class="o">...</span> -<span class="ne">NameError</span><span class="p">:</span> <span class="n">_func_</span> <span class="ow">is</span> <span class="n">overridden</span> <span class="ow">in</span> -<span class="k">def</span> <span class="nf">f</span><span class="p">(</span><span class="n">_func_</span><span class="p">):</span> - <span class="k">return</span> <span class="n">_call_</span><span class="p">(</span><span class="n">_func_</span><span class="p">,</span> <span class="n">_func_</span><span class="p">)</span> -</pre></div> - -</div> -<p>Finally, the implementation is such that the decorated function -attribute <tt class="docutils literal">.func_globals</tt> is a <em>copy</em> of the original function -attribute. Moreover the decorated function contains -a <em>copy</em> of the original function dictionary -(<tt class="docutils literal">vars(decorated_f) is not vars(f)</tt>):</p> -<div class="codeblock python"> -<div class="highlight"><pre><span class="o">>>></span> <span class="k">def</span> <span class="nf">f</span><span class="p">():</span> <span class="k">pass</span> <span class="c"># the original function</span> -<span class="o">>>></span> <span class="n">f</span><span class="o">.</span><span class="n">attr1</span> <span class="o">=</span> <span class="s">"something"</span> <span class="c"># setting an attribute</span> -<span class="o">>>></span> <span class="n">f</span><span class="o">.</span><span class="n">attr2</span> <span class="o">=</span> <span class="s">"something else"</span> <span class="c"># setting another attribute</span> - -<span class="o">>>></span> <span class="n">traced_f</span> <span class="o">=</span> <span class="n">trace</span><span class="p">(</span><span class="n">f</span><span class="p">)</span> <span class="c"># the decorated function</span> - -<span class="o">>>></span> <span class="n">traced_f</span><span class="o">.</span><span class="n">attr1</span> -<span class="s">'something'</span> -<span class="o">>>></span> <span class="n">traced_f</span><span class="o">.</span><span class="n">attr2</span> <span class="o">=</span> <span class="s">"something different"</span> <span class="c"># setting attr</span> -<span class="o">>>></span> <span class="n">f</span><span class="o">.</span><span class="n">attr2</span> <span class="c"># the original attribute did not change</span> -<span class="s">'something else'</span> -</pre></div> - -</div> -</div> -<div class="section" id="compatibility-notes"> -<h1><a class="toc-backref" href="#id16">Compatibility notes</a></h1> -<p>Version 3.3 is the first version of the <tt class="docutils literal">decorator</tt> module to fully -support Python 3, including <a class="reference external" href="http://www.python.org/dev/peps/pep-3107/">function annotations</a>. Version 3.2 was the -first version to support Python 3 via the <tt class="docutils literal">2to3</tt> conversion tool -invoked in the build process by the <a class="reference external" href="http://packages.python.org/distribute/">distribute</a> project, the Python -3-compatible replacement of easy_install. The hard work (for me) has -been converting the documentation and the doctests. This has been -possible only after that <a class="reference external" href="http://docutils.sourceforge.net/">docutils</a> and <a class="reference external" href="http://pygments.org/">pygments</a> have been ported to -Python 3.</p> -<p>Version 3 of the <tt class="docutils literal">decorator</tt> module do not contain any backward -incompatible change, apart from the removal of the functions -<tt class="docutils literal">get_info</tt> and <tt class="docutils literal">new_wrapper</tt>, which have been deprecated for -years. <tt class="docutils literal">get_info</tt> has been removed since it was little used and -since it had to be changed anyway to work with Python 3.0; -<tt class="docutils literal">new_wrapper</tt> has been removed since it was useless: its major use -case (converting signature changing decorators to signature preserving -decorators) has been subsumed by <tt class="docutils literal">decorator_apply</tt>, whereas the other use -case can be managed with the <tt class="docutils literal">FunctionMaker</tt>.</p> -<p>There are a few changes in the documentation: I removed the -<tt class="docutils literal">decorator_factory</tt> example, which was confusing some of my users, -and I removed the part about exotic signatures in the Python 3 -documentation, since Python 3 does not support them.</p> -<p>Finally <tt class="docutils literal">decorator</tt> cannot be used as a class decorator and the -<a class="reference external" href="http://www.phyast.pitt.edu/~micheles/python/documentation.html#class-decorators-and-decorator-factories">functionality introduced in version 2.3</a> has been removed. That -means that in order to define decorator factories with classes you -need to define the <tt class="docutils literal">__call__</tt> method explicitly (no magic anymore). -All these changes should not cause any trouble, since they were -all rarely used features. Should you have any trouble, you can always -downgrade to the 2.3 version.</p> -<p>The examples shown here have been tested with Python 2.6. Python 2.4 -is also supported - of course the examples requiring the <tt class="docutils literal">with</tt> -statement will not work there. Python 2.5 works fine, but if you -run the examples in the interactive interpreter -you will notice a few differences since -<tt class="docutils literal">getargspec</tt> returns an <tt class="docutils literal">ArgSpec</tt> namedtuple instead of a regular -tuple. That means that running the file -<tt class="docutils literal">documentation.py</tt> under Python 2.5 will print a few errors, but -they are not serious.</p> -</div> -<div class="section" id="licence"> -<h1><a class="toc-backref" href="#id17">LICENCE</a></h1> -<p>Copyright (c) 2005-2012, Michele Simionato -All rights reserved.</p> -<p>Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are -met:</p> -<blockquote> -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.</blockquote> -<p>THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -"AS IS" 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.</p> -<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> diff --git a/documentation.py b/documentation.py index 17de544..86ba66f 100644 --- a/documentation.py +++ b/documentation.py @@ -24,7 +24,7 @@ believe the change is for the best, and that decorators are a great idea since: * decorators help reducing boilerplate code; -* decorators help separation of concerns; +* decorators help separation of concerns; * decorators enhance readability and maintenability; * decorators are explicit. @@ -47,8 +47,8 @@ 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 +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 subclasses: + *signature-preserving* decorators, i.e. callable objects taking a @@ -61,7 +61,7 @@ decorators in two subclasses: Signature-changing decorators have their use: for instance the builtin classes ``staticmethod`` and ``classmethod`` are in this -group, since they take functions and return descriptor objects which +group, since they take functions and return descriptor objects which are not functions, nor callables. However, signature-preserving decorators are more common and easier to @@ -69,8 +69,8 @@ reason about; in particular signature-preserving decorators can be 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 -can accept functions with any signature. A simple example will clarify +obvious, especially if one wants to define proper decorators that +can accept functions with any signature. A simple example will clarify the issue. Statement of the problem @@ -80,8 +80,8 @@ 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, +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 could be the following (notice that in general it is impossible to memoize correctly something @@ -95,9 +95,9 @@ been added in Python 2.5 expressly to simplify the definition of decorators ``__name__``, ``__doc__``, ``__module__`` and ``__dict__`` from the original function to the decorated function by hand). -.. _functools.update_wrapper: http://www.python.org/doc/2.5.2/lib/module-functools.html +.. _functools.update_wrapper: https://docs.python.org/2/library/functools.html#functools.update_wrapper -The implementation above works in the sense that the decorator +The implementation above works in the sense that the decorator can accept functions with generic signatures; unfortunately this implementation does *not* define a signature-preserving decorator, since in general ``memoize_uw`` returns a function with a @@ -118,14 +118,14 @@ keyword arguments: .. code-block:: python - >>> from inspect import getargspec + >>> from inspect import getargspec >>> print getargspec(f1) # I am using Python 2.6+ here ArgSpec(args=[], varargs='args', keywords='kw', defaults=None) This means that introspection tools such as pydoc will give wrong informations about the signature of ``f1``. This is pretty bad: -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 +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: .. code-block:: python @@ -185,7 +185,7 @@ The signature of ``heavy_computation`` is the one you would expect: .. code-block:: python - >>> print getargspec(heavy_computation) + >>> print getargspec(heavy_computation) ArgSpec(args=[], varargs=None, keywords=None, defaults=None) A ``trace`` decorator @@ -218,33 +218,33 @@ and it that it has the correct signature: .. code-block:: python - >>> print getargspec(f1) + >>> print getargspec(f1) ArgSpec(args=['x'], varargs=None, keywords=None, defaults=None) The same decorator works with functions of any signature: .. code-block:: python - + >>> @trace ... def f(x, y=1, z=2, *args, **kw): ... pass >>> f(0, 3) calling f with args (0, 3, 2), {} - - >>> print getargspec(f) + + >>> print getargspec(f) ArgSpec(args=['x', 'y', 'z'], varargs='args', keywords='kw', defaults=(1, 2)) That includes even functions with exotic signatures like the following: .. code-block:: python - + >>> @trace ... def exotic_signature((x, y)=(1,2)): return x+y - + >>> print getargspec(exotic_signature) ArgSpec(args=[['x', 'y']], varargs=None, keywords=None, defaults=((1, 2),)) - >>> exotic_signature() + >>> exotic_signature() calling exotic_signature with args ((1, 2),), {} 3 @@ -301,14 +301,14 @@ If you are using an old Python version (Python 2.4) the ------------------------------------------- Sometimes one has to deal with blocking resources, such as ``stdin``, and -sometimes it is best to have back a "busy" message than to block everything. +sometimes it is best to have back a "busy" message than to block everything. This behavior can be implemented with a suitable family of decorators, where the parameter is the busy message: $$blocking - + Functions decorated with ``blocking`` will return a busy message if -the resource is unavailable, and the intended result if the resource is +the resource is unavailable, and the intended result if the resource is available. For instance: .. code-block:: python @@ -321,7 +321,7 @@ available. For instance: >>> print read_data() # data is not available yet Please wait ... - >>> time.sleep(1) + >>> time.sleep(1) >>> print read_data() # data is not available yet Please wait ... @@ -340,11 +340,11 @@ 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 converted into decorators. +callable objects that can be converted into decorators. As an example, here will I show a decorator which is able to convert a blocking function into an asynchronous -function. The function, when called, +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 (of course the code here @@ -356,13 +356,13 @@ $$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()``. +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 +(for instance a printer). Then the access to the writing function must be locked. Here is a minimalistic example: .. code-block:: python @@ -379,7 +379,7 @@ be locked. Here is a minimalistic example: ... datalist.append(data) ... # other operations not requiring a lock here -Each call to ``write`` will create a new writer thread, but there will +Each call to ``write`` will create a new writer thread, but there will be no synchronization problems since ``write`` is locked. .. code-block:: python @@ -415,7 +415,7 @@ factories. For instance if you write then ``before_after`` is a factory function returning -``GeneratorContextManager`` objects which can be used with +``GeneratorContextManager`` objects which can be used with the ``with`` statement: .. code-block:: python @@ -431,7 +431,7 @@ the ``with`` statement: Basically, it is as if the content of the ``with`` block was executed in the place of the ``yield`` expression in the generator function. -In Python 3.2 ``GeneratorContextManager`` +In Python 3.2 ``GeneratorContextManager`` objects were enhanced with a ``__call__`` method, so that they can be used as decorators as in this example: @@ -446,11 +446,11 @@ method, so that they can be used as decorators as in this example: hello AFTER -The ``ba`` decorator is basically inserting a ``with ba:`` +The ``ba`` decorator is basically inserting a ``with ba:`` block inside the function. -However there two issues: the first is that ``GeneratorContextManager`` +However there two issues: the first is that ``GeneratorContextManager`` objects are callable only in Python 3.2, so the previous example will break -in older versions of Python; the second is that +in older versions of Python; the second is that ``GeneratorContextManager`` objects do not preserve the signature of the decorated functions: the decorated ``hello`` function here will have a generic signature ``hello(*args, **kwargs)`` but will break when @@ -458,7 +458,7 @@ called with more than zero arguments. For such reasons the decorator module, starting with release 3.4, offers a ``decorator.contextmanager`` decorator that solves both problems and works even in Python 2.5. The usage is the same and factories decorated with ``decorator.contextmanager`` -will returns instances of ``ContextManager``, a subclass of +will returns instances of ``ContextManager``, a subclass of ``contextlib.GeneratorContextManager`` with a ``__call__`` method acting as a signature-preserving decorator. @@ -529,7 +529,7 @@ with attributes ``args``, ``varargs``, the return values of the standard library function ``inspect.getargspec``. For each argument in the ``args`` (which is a list of strings containing the names of the mandatory arguments) an attribute ``arg0``, ``arg1``, -..., ``argN`` is also generated. Finally, there is a ``signature`` +..., ``argN`` is also generated. Finally, there is a ``signature`` attribute, a string with the signature of the original function. Notice that while I do not have plans @@ -582,7 +582,8 @@ undecorated function: @tail_recursive def factorial(n, acc=1): "The good old factorial" - if n == 0: return acc + if n == 0: + return acc return factorial(n-1, n*acc) <BLANKLINE> @@ -592,8 +593,8 @@ 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 +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 ``decorator``. You can use a ``FunctionMaker`` to implement that functionality as follows: @@ -610,10 +611,10 @@ 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. -In order to give an example of usage of ``decorator_apply``, I will show a +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 -in the Python Cookbook, +in the Python Cookbook, http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/496691. $$TailRecursive @@ -629,11 +630,11 @@ $$factorial .. code-block:: python - >>> print factorial(4) + >>> print factorial(4) 24 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 +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 the following @@ -647,8 +648,8 @@ call). Caveats and limitations ------------------------------------------- -The first thing you should be aware of, it the fact that decorators -have a performance penalty. +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:: $ cat performance.sh @@ -657,7 +658,7 @@ The worse case is shown by the following example:: @decorator def do_nothing(func, *args, **kw): - return func(*args, **kw) + return func(*args, **kw) @do_nothing def f(): @@ -676,10 +677,10 @@ plain function is more than three times slower:: 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 +It should be noted that a real life function would probably do something more useful than ``f`` here, and therefore in real life the performance penalty could be completely negligible. As always, the -only way to know if there is +only way to know if there is a penalty in your specific use case is to measure it. You should be aware that decorators will make your tracebacks @@ -706,8 +707,8 @@ function is decorated the traceback will be longer: 1/0 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``. +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``. This latter reference is due to the fact that internally the decorator module uses ``exec`` to generate the decorated function. Notice that ``exec`` is *not* responsibile for the performance penalty, since is the @@ -716,8 +717,8 @@ the decorated function is called. At present, there is no clean way to avoid ``exec``. 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. -That could happen in future versions of Python (see PEP 362_) and +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.1 it is impossible to change the function signature directly, therefore the ``decorator`` module is still useful. @@ -727,7 +728,7 @@ the module and releasing new versions. .. _362: http://www.python.org/dev/peps/pep-0362 In the present implementation, decorators generated by ``decorator`` -can only be used on user-defined Python functions or methods, not on generic +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, notice that you can decorate a method, but only before if becomes a bound or unbound @@ -736,7 +737,7 @@ Here is an example of valid decoration: .. code-block:: python - >>> class C(object): + >>> class C(object): ... @trace ... def meth(self): ... pass @@ -793,8 +794,8 @@ original function dictionary, i.e. ``vars(decorated_f) is vars(f)``: >>> traced_f.attr1 'something' - >>> traced_f.attr2 = "something different" # setting attr - >>> f.attr2 # the original attribute did change + >>> traced_f.attr2 = "something different" # setting attr + >>> f.attr2 # the original attribute did change 'something different' Compatibility notes @@ -809,7 +810,7 @@ dictionary is now the same of the original function dictionary, wheread in past versions they were different objects. -The examples shown here have been tested with Python 2.7 and 3.3. Python 2.4 +The examples shown here have been tested with Python 2.7 and 3.4. Python 2.4 is also supported - of course the examples requiring the ``with`` statement will not work there. Python 2.5 works fine, but if you run the examples in the interactive interpreter @@ -817,7 +818,7 @@ you will notice a few differences since ``getargspec`` returns an ``ArgSpec`` namedtuple instead of a regular tuple. That means that running the file ``documentation.py`` under Python 2.5 will print a few errors, but -they are not serious. +they are not serious. .. _function annotations: http://www.python.org/dev/peps/pep-3107/ .. _distribute: http://packages.python.org/distribute/ @@ -827,19 +828,19 @@ they are not serious. LICENCE --------------------------------------------- -Copyright (c) 2005-2012, Michele Simionato +Copyright (c) 2005-2015, Michele Simionato All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: - Redistributions of source code must retain the above copyright + 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. + distribution. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT @@ -854,12 +855,17 @@ 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. -If you use this software and you are happy with it, consider sending me a +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! """ from __future__ import with_statement -import sys, threading, time, functools, inspect, itertools +import sys +import threading +import time +import functools +import inspect +import itertools from decorator import * from functools import partial from setup import VERSION @@ -868,34 +874,41 @@ today = time.strftime('%Y-%m-%d') __doc__ = __doc__.replace('$VERSION', VERSION).replace('$DATE', today) + def decorator_apply(dec, func): """ - Decorate a function by preserving the signature even if dec + Decorate a function by preserving the signature even if dec is not a signature-preserving decorator. """ return FunctionMaker.create( func, 'return decorated(%(signature)s)', dict(decorated=dec(func)), __wrapped__=func) + def _trace(f, *args, **kw): print "calling %s with args %s, %s" % (f.__name__, args, kw) return f(*args, **kw) + def trace(f): return decorator(_trace, f) -def on_success(result): # default implementation + +def on_success(result): # default implementation "Called on the result of the function" return result -def on_failure(exc_info): # default implementation + +def on_failure(exc_info): # default implementation "Called if the function fails" pass -def on_closing(): # default implementation + +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 @@ -915,9 +928,10 @@ class Async(object): def __call__(self, func, *args, **kw): try: counter = func.counter - except AttributeError: # instantiate the counter at the first call + except AttributeError: # instantiate the counter at the first call counter = func.counter = itertools.count(1) name = '%s-%s' % (func.__name__, counter.next()) + def func_wrapper(): try: result = func(*args, **kw) @@ -931,18 +945,22 @@ class Async(object): thread.start() return thread + def identity_dec(func): def wrapper(*args, **kw): return func(*args, **kw) return wrapper + @identity_dec def example(): pass + def memoize_uw(func): func.cache = {} + def memoize(*args, **kw): - if kw: # frozenset is used to ensure hashability + if kw: # frozenset is used to ensure hashability key = args, frozenset(kw.iteritems()) else: key = args @@ -954,51 +972,61 @@ def memoize_uw(func): return result return functools.update_wrapper(memoize, func) + def _memoize(func, *args, **kw): - if kw: # frozenset is used to ensure hashability + if kw: # frozenset is used to ensure hashability key = args, frozenset(kw.iteritems()) else: key = args - cache = func.cache # attributed added by memoize + cache = func.cache # attributed added by memoize if key in cache: return cache[key] else: cache[key] = result = func(*args, **kw) return result + def memoize(f): f.cache = {} return decorator(_memoize, f) + def blocking(not_avail): def blocking(f, *args, **kw): - if not hasattr(f, "thread"): # no thread running - def set_result(): f.result = f(*args, **kw) + if not hasattr(f, "thread"): # no thread running + def set_result(): + f.result = f(*args, **kw) f.thread = threading.Thread(None, set_result) f.thread.start() return not_avail elif f.thread.isAlive(): return not_avail - else: # the thread is ended, return the stored result + else: # the thread is ended, return the stored result del f.thread return f.result return decorator(blocking) + class User(object): "Will just be able to see a page" + class PowerUser(User): "Will be able to add new pages too" + class Admin(PowerUser): "Will be able to delete pages too" + def get_userclass(): return User + class PermissionError(Exception): pass + def restricted(user_class): def restricted(func, *args, **kw): "Restrict access to a given class of users" @@ -1011,6 +1039,7 @@ def restricted(user_class): % (userclass.__name__, func.__name__)) return decorator(restricted) + class Action(object): """ >>> a = Action() @@ -1033,6 +1062,7 @@ class Action(object): def delete(self): pass + class TailRecursive(object): """ tail_recursive decorator based on Kay Schluehr's recipe @@ -1043,7 +1073,7 @@ class TailRecursive(object): def __init__(self, func): self.func = func self.firstcall = True - self.CONTINUE = object() # sentinel + self.CONTINUE = object() # sentinel def __call__(self, *args, **kwd): CONTINUE = self.CONTINUE @@ -1053,29 +1083,35 @@ class TailRecursive(object): try: while True: result = func(*args, **kwd) - if result is CONTINUE: # update arguments + if result is CONTINUE: # update arguments args, kwd = self.argskwd - else: # last call + else: # last call return result finally: self.firstcall = True - else: # return the arguments of the tail call + else: # return the arguments of the tail call self.argskwd = args, kwd return CONTINUE + def tail_recursive(func): return decorator_apply(TailRecursive, func) + @tail_recursive def factorial(n, acc=1): "The good old factorial" - if n == 0: return acc + if n == 0: + return acc return factorial(n-1, n*acc) -def fact(n): # this is not tail-recursive - if n == 0: return 1 + +def fact(n): # this is not tail-recursive + if n == 0: + return 1 return n * fact(n-1) + def a_test_for_pylons(): """ In version 3.1.0 decorator(caller) returned a nameless partial @@ -1090,13 +1126,15 @@ def a_test_for_pylons(): 'The good old factorial' """ + @contextmanager def before_after(before, after): print(before) yield print(after) -ba = before_after('BEFORE', 'AFTER') # ContextManager instance +ba = before_after('BEFORE', 'AFTER') # ContextManager instance + @ba def hello(user): @@ -1111,4 +1149,5 @@ def hello(user): print('hello %s' % user) if __name__ == '__main__': - import doctest; doctest.testmod() + import doctest + doctest.testmod() diff --git a/documentation.rst b/documentation.rst new file mode 100644 index 0000000..3c10cae --- /dev/null +++ b/documentation.rst @@ -0,0 +1,1037 @@ + +The ``decorator`` module +============================================================= + +:Author: Michele Simionato +:E-mail: michele.simionato@gmail.com +:Version: 3.4.1 (2015-03-16) +:Requires: Python 2.4+ +:Download page: http://pypi.python.org/pypi/decorator/3.4.1 +:Installation: ``easy_install decorator`` +:License: BSD license + +.. contents:: + +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 +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: + +* decorators help reducing boilerplate code; +* decorators help separation of concerns; +* decorators enhance readability and maintenability; +* 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 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. + +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 +------------------------------------ + +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 subclasses: + ++ *signature-preserving* decorators, i.e. callable objects taking a + function as input and returning a function *with the same + signature* as output; + ++ *signature-changing* decorators, i.e. decorators that change + the signature of their input function, or decorators returning + non-callable objects. + +Signature-changing decorators have their use: for instance the +builtin classes ``staticmethod`` and ``classmethod`` are in this +group, since they take functions and return descriptor objects which +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. + +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. + +Statement of the problem +------------------------------ + +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 could be the following (notice +that in general it is impossible to memoize correctly something +that depends on non-hashable arguments): + +.. code-block:: python + + def memoize_uw(func): + func.cache = {} + + def memoize(*args, **kw): + if kw: # frozenset is used to ensure hashability + key = args, frozenset(kw.iteritems()) + else: + key = args + cache = func.cache + if key in cache: + return cache[key] + else: + cache[key] = result = func(*args, **kw) + return result + return functools.update_wrapper(memoize, func) + + +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). + +.. _functools.update_wrapper: https://docs.python.org/2/library/functools.html#functools.update_wrapper + +The implementation above works in the sense that the decorator +can accept functions with generic signatures; unfortunately this +implementation does *not* define a signature-preserving decorator, since in +general ``memoize_uw`` returns a function with a +*different signature* from the original function. + +Consider for instance the following case: + +.. code-block:: python + + >>> @memoize_uw + ... 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: + +.. code-block:: python + + >>> from inspect import getargspec + >>> print getargspec(f1) # I am using Python 2.6+ here + ArgSpec(args=[], varargs='args', keywords='kw', defaults=None) + +This means that introspection tools such as pydoc will give +wrong informations about the signature of ``f1``. This is pretty bad: +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: + +.. 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`` function in +the ``decorator`` module is such a factory: + +.. code-block:: python + + >>> from decorator import decorator + +``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: + +.. code-block:: python + + def _memoize(func, *args, **kw): + if kw: # frozenset is used to ensure hashability + key = args, frozenset(kw.iteritems()) + else: + key = args + cache = func.cache # attributed added by memoize + if key in cache: + return cache[key] + else: + cache[key] = result = func(*args, **kw) + return result + + +At this point you can define your decorator as follows: + +.. code-block:: python + + def memoize(f): + f.cache = {} + return decorator(_memoize, f) + + +The difference with respect to the ``memoize_uw`` 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 to the caller function. + +Here is a test of usage: + +.. 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 second time it will be instantaneous + done + +The signature of ``heavy_computation`` is the one you would expect: + +.. code-block:: python + + >>> print getargspec(heavy_computation) + ArgSpec(args=[], varargs=None, keywords=None, defaults=None) + +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: + +.. code-block:: python + + def _trace(f, *args, **kw): + print "calling %s with args %s, %s" % (f.__name__, args, kw) + return f(*args, **kw) + + +.. code-block:: python + + def trace(f): + return decorator(_trace, f) + + +Here is an example of usage: + +.. code-block:: python + + >>> @trace + ... def f1(x): + ... pass + +It is immediate to verify that ``f1`` works + +.. code-block:: python + + >>> f1(0) + calling f1 with args (0,), {} + +and it that it has the correct signature: + +.. code-block:: python + + >>> print getargspec(f1) + ArgSpec(args=['x'], varargs=None, keywords=None, defaults=None) + +The same decorator works with functions of any signature: + +.. code-block:: python + + >>> @trace + ... def f(x, y=1, z=2, *args, **kw): + ... pass + + >>> f(0, 3) + calling f with args (0, 3, 2), {} + + >>> print getargspec(f) + ArgSpec(args=['x', 'y', 'z'], varargs='args', keywords='kw', defaults=(1, 2)) + +That includes even functions with exotic signatures like the following: + +.. code-block:: python + + >>> @trace + ... def exotic_signature((x, y)=(1,2)): return x+y + + >>> print getargspec(exotic_signature) + ArgSpec(args=[['x', 'y']], varargs=None, keywords=None, defaults=((1, 2),)) + >>> exotic_signature() + calling exotic_signature with args ((1, 2),), {} + 3 + +Notice that the support for exotic signatures has been deprecated +in Python 2.6 and removed in Python 3.0. + +``decorator`` is a decorator +--------------------------------------------- + +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 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 + +.. 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. Actually ``trace`` is a ``partial`` +object which can be used as a decorator: + +.. code-block:: python + + >>> trace + <function trace at 0x...> + +Here is an example of usage: + +.. code-block:: python + + >>> @trace + ... def func(): pass + + >>> func() + calling func with args (), {} + +If you are using an old Python version (Python 2.4) the +``decorator`` module provides a poor man replacement for +``functools.partial``. + +``blocking`` +------------------------------------------- + +Sometimes one has to deal with blocking resources, such as ``stdin``, and +sometimes it is best to have back a "busy" message than to block everything. +This behavior can be implemented with a suitable family of decorators, +where the parameter is the busy message: + +.. code-block:: python + + def blocking(not_avail): + def blocking(f, *args, **kw): + if not hasattr(f, "thread"): # no thread running + def set_result(): + f.result = f(*args, **kw) + f.thread = threading.Thread(None, set_result) + f.thread.start() + return not_avail + elif f.thread.isAlive(): + return not_avail + else: # the thread is ended, return the stored result + del f.thread + return f.result + return decorator(blocking) + + +Functions decorated with ``blocking`` will return a busy message if +the resource is unavailable, and the intended result if the resource is +available. For instance: + +.. code-block:: python + + >>> @blocking("Please wait ...") + ... def read_data(): + ... time.sleep(3) # simulate a blocking resource + ... return "some data" + + >>> print read_data() # data is not available yet + Please wait ... + + >>> time.sleep(1) + >>> print read_data() # data is not available yet + Please wait ... + + >>> time.sleep(1) + >>> print read_data() # data is not available yet + Please wait ... + + >>> time.sleep(1.1) # after 3.1 seconds, data is available + >>> print read_data() + some data + +``async`` +-------------------------------------------- + +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 converted into decorators. + +As an example, here will 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 (of course the code here +is just an example, it is not a recommended way of doing multi-threaded +programming). The implementation is the following: + +.. code-block:: python + + def on_success(result): # default implementation + "Called on the result of the function" + return result + +.. code-block:: python + + def on_failure(exc_info): # default implementation + "Called if the function fails" + pass + +.. code-block:: python + + def on_closing(): # default implementation + "Called at the end, both in case of success and failure" + pass + +.. code-block:: python + + 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, on_success=on_success, + on_failure=on_failure, on_closing=on_closing): + self.threadfactory = threadfactory + self.on_success = on_success + self.on_failure = on_failure + self.on_closing = on_closing + + def __call__(self, func, *args, **kw): + try: + counter = func.counter + except AttributeError: # instantiate the counter at the first call + counter = func.counter = itertools.count(1) + name = '%s-%s' % (func.__name__, counter.next()) + + def func_wrapper(): + try: + result = func(*args, **kw) + except: + self.on_failure(sys.exc_info()) + else: + return self.on_success(result) + finally: + self.on_closing() + thread = self.threadfactory(None, func_wrapper, name) + thread.start() + return thread + + +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: + +.. code-block:: python + + >>> async = decorator(Async(threading.Thread)) + + >>> 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. + +.. code-block:: python + + >>> 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'] + +contextmanager +------------------------------------- + +For a long time Python had in its standard library a ``contextmanager`` +decorator, able to convert generator functions into ``GeneratorContextManager`` +factories. For instance if you write + +.. code-block:: python + + >>> from contextlib import contextmanager + >>> @contextmanager + ... def before_after(before, after): + ... print(before) + ... yield + ... print(after) + + +then ``before_after`` is a factory function returning +``GeneratorContextManager`` objects which can be used with +the ``with`` statement: + +.. code-block:: python + + >>> ba = before_after('BEFORE', 'AFTER') + >>> type(ba) + <class 'contextlib.GeneratorContextManager'> + >>> with ba: + ... print 'hello' + BEFORE + hello + AFTER + +Basically, it is as if the content of the ``with`` block was executed +in the place of the ``yield`` expression in the generator function. +In Python 3.2 ``GeneratorContextManager`` +objects were enhanced with a ``__call__`` +method, so that they can be used as decorators as in this example: + +.. code-block:: python + + >>> @ba + ... def hello(): + ... print 'hello' + ... + >>> hello() + BEFORE + hello + AFTER + +The ``ba`` decorator is basically inserting a ``with ba:`` +block inside the function. +However there two issues: the first is that ``GeneratorContextManager`` +objects are callable only in Python 3.2, so the previous example will break +in older versions of Python; the second is that +``GeneratorContextManager`` objects do not preserve the signature +of the decorated functions: the decorated ``hello`` function here will have +a generic signature ``hello(*args, **kwargs)`` but will break when +called with more than zero arguments. For such reasons the decorator +module, starting with release 3.4, offers a ``decorator.contextmanager`` +decorator that solves both problems and works even in Python 2.5. +The usage is the same and factories decorated with ``decorator.contextmanager`` +will returns instances of ``ContextManager``, a subclass of +``contextlib.GeneratorContextManager`` with a ``__call__`` method +acting as a signature-preserving decorator. + +**Disclaimer**: the ``contextmanager`` decorator is an *experimental* feature: +it may go away in future versions of the decorator module. Use it at your +own risk. + +The ``FunctionMaker`` class +--------------------------------------------------------------- + +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 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. You will see an example shortly, in +the implementation of a cool decorator utility (``decorator_apply``). + +``FunctionMaker`` provides a ``.create`` classmethod which +takes as input the name, signature, and body of the function +we want to generate as well as the execution environment +were the function is generated by ``exec``. Here is an example: + +.. code-block:: python + + >>> def f(*args, **kw): # a function with a generic signature + ... print args, kw + + >>> f1 = FunctionMaker.create('f1(a, b)', 'f(a, b)', dict(f=f)) + >>> f1(1,2) + (1, 2) {} + +It is important to notice that the function body is interpolated +before being executed, so be careful with the ``%`` sign! + +``FunctionMaker.create`` 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 generated function: + +.. code-block:: python + + >>> f1 = FunctionMaker.create( + ... 'f1(a, b)', 'f(a, b)', dict(f=f), addsource=True) + >>> print f1.__source__ + def f1(a, b): + f(a, b) + <BLANKLINE> + +``FunctionMaker.create`` can take as first argument a string, +as in the examples before, or a function. This is the most common +usage, since typically you want to decorate a pre-existing +function. A framework author may want to use directly ``FunctionMaker.create`` +instead of ``decorator``, since it gives you direct access to the body +of the generated function. For instance, suppose you want to instrument +the ``__init__`` methods of a set of classes, by preserving their +signature (such use case is not made up; this is done in SQAlchemy +and in other frameworks). When the first argument of ``FunctionMaker.create`` +is a function, a ``FunctionMaker`` object is instantiated internally, +with attributes ``args``, ``varargs``, +``keywords`` and ``defaults`` which are the +the return values of the standard library function ``inspect.getargspec``. +For each argument in the ``args`` (which is a list of strings containing +the names of the mandatory arguments) an attribute ``arg0``, ``arg1``, +..., ``argN`` is also generated. Finally, there is a ``signature`` +attribute, a string with the signature of the original function. + +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. 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. + +Getting the source code +--------------------------------------------------- + +Internally ``FunctionMaker.create`` 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: + +.. code-block:: python + + def identity_dec(func): + def wrapper(*args, **kw): + return func(*args, **kw) + return wrapper + + +.. code-block:: python + + @identity_dec + def example(): pass + + >>> 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.7 and 3.1. +There is however a workaround. The decorator module adds an +attribute ``.__wrapped__`` 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 inspect.getsource(factorial.__wrapped__) + @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 +upgrade third party decorators to signature-preserving decorators without +having to rewrite them in terms of ``decorator``. You can use a +``FunctionMaker`` to implement that functionality as follows: + +.. code-block:: python + + def decorator_apply(dec, func): + """ + Decorate a function by preserving the signature even if dec + is not a signature-preserving decorator. + """ + return FunctionMaker.create( + func, 'return decorated(%(signature)s)', + dict(decorated=dec(func)), __wrapped__=func) + + +``decorator_apply`` sets the attribute ``.__wrapped__`` 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 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. + +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 +in the Python Cookbook, +http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/496691. + +.. code-block:: python + + class TailRecursive(object): + """ + tail_recursive decorator based on Kay Schluehr's recipe + http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/496691 + with improvements by me and George Sakkis. + """ + + def __init__(self, func): + self.func = func + self.firstcall = True + self.CONTINUE = object() # sentinel + + def __call__(self, *args, **kwd): + CONTINUE = self.CONTINUE + if self.firstcall: + func = self.func + self.firstcall = False + try: + while True: + result = func(*args, **kwd) + if result is CONTINUE: # update arguments + args, kwd = self.argskwd + else: # last call + return result + finally: + self.firstcall = True + else: # return the arguments of the tail call + self.argskwd = args, kwd + return CONTINUE + + +Here the decorator is implemented as a class returning callable +objects. + +.. code-block:: python + + def tail_recursive(func): + return decorator_apply(TailRecursive, func) + + +Here is how you apply the upgraded decorator to the good old factorial: + +.. code-block:: python + + @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 + +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 the following + +.. code-block:: python + + def fact(n): # this is not tail-recursive + if n == 0: + return 1 + return n * fact(n-1) + + +(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). + +Caveats and limitations +------------------------------------------- + +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:: + + $ cat performance.sh + python -m timeit -s " + from decorator import decorator + + @decorator + def do_nothing(func, *args, **kw): + return func(*args, **kw) + + @do_nothing + def f(): + pass + " "f()" + + python -m timeit -s " + def f(): + pass + " "f()" + +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: 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 +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. + +You should be aware that decorators will make your tracebacks +longer and more difficult to understand. Consider this example: + +.. 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: + +.. code-block:: python + + >>> f() + Traceback (most recent call last): + ... + File "<string>", line 2, in f + File "<doctest __main__[18]>", line 4, in trace + return f(*args, **kw) + File "<doctest __main__[47]>", line 3, in f + 1/0 + 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``. +This latter reference is due to the fact that internally the decorator +module uses ``exec`` to generate the decorated function. Notice that +``exec`` is *not* responsibile for the performance penalty, since is the +called *only once* at function decoration time, and not every time +the decorated function is called. + +At present, there is no clean way to avoid ``exec``. 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. +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.1 it is impossible to change the function signature +directly, therefore the ``decorator`` module is still useful. +Actually, this is one of the main reasons why I keep maintaining +the module and releasing new versions. + +.. _362: http://www.python.org/dev/peps/pep-0362 + +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, notice +that you can decorate a method, but only before if becomes a bound or unbound +method, i.e. inside the class. +Here is an example of valid decoration: + +.. code-block:: python + + >>> class C(object): + ... @trace + ... def meth(self): + ... pass + +Here is an example of invalid decoration, when the decorator in +called too late: + +.. code-block:: python + + >>> class C(object): + ... def meth(self): + ... pass + ... + >>> trace(C.meth) + Traceback (most recent call last): + ... + TypeError: You are decorating a non function: <unbound method C.meth> + +The solution is to extract the inner function from the unbound method: + +.. code-block:: python + + >>> trace(C.meth.im_func) + <function meth at 0x...> + +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``: + +.. 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 +attribute ``.func_globals`` is a *copy* of the original function +attribute. On the other hand the function attribute dictionary +of the decorated function is just a reference to the +original function dictionary, i.e. ``vars(decorated_f) is vars(f)``: + +.. code-block:: python + + >>> def f(): pass # the original function + >>> f.attr1 = "something" # setting an attribute + >>> f.attr2 = "something else" # setting another attribute + + >>> traced_f = trace(f) # the decorated function + + >>> traced_f.attr1 + 'something' + >>> traced_f.attr2 = "something different" # setting attr + >>> f.attr2 # the original attribute did change + 'something different' + +Compatibility notes +--------------------------------------------------------------- + +This version fully supports Python 3, including `function +annotations`_. Moreover it is the first version to support +generic callers, i.e. callable objects with the right +signature, not necessarily functions. ``contextmanager`` +will not work in Python 2.4. The decorated function +dictionary is now the same of the original function +dictionary, wheread in past versions they were +different objects. + +The examples shown here have been tested with Python 2.7 and 3.4. Python 2.4 +is also supported - of course the examples requiring the ``with`` +statement will not work there. Python 2.5 works fine, but if you +run the examples in the interactive interpreter +you will notice a few differences since +``getargspec`` returns an ``ArgSpec`` namedtuple instead of a regular +tuple. That means that running the file +``documentation.py`` under Python 2.5 will print a few errors, but +they are not serious. + +.. _function annotations: http://www.python.org/dev/peps/pep-3107/ +.. _distribute: http://packages.python.org/distribute/ +.. _docutils: http://docutils.sourceforge.net/ +.. _pygments: http://pygments.org/ + +LICENCE +--------------------------------------------- + +Copyright (c) 2005-2015, Michele Simionato +All rights reserved. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are +met: + + 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 +"AS IS" 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. + +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! diff --git a/documentation3.html b/documentation3.html deleted file mode 100644 index c5e2fac..0000000 --- a/documentation3.html +++ /dev/null @@ -1,1102 +0,0 @@ -<?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.8.1: http://docutils.sourceforge.net/" /> -<title>The decorator module</title> -<meta name="author" content="Michele Simionato" /> -<style type="text/css"> - -.highlight { background: #f8f8f8; } -.highlight .c { color: #408080; font-style: italic } /* Comment */ -.highlight .err { border: 1px solid #FF0000 } /* Error */ -.highlight .k { color: #008000; font-weight: bold } /* Keyword */ -.highlight .o { color: #666666 } /* Operator */ -.highlight .cm { color: #408080; font-style: italic } /* Comment.Multiline */ -.highlight .cp { color: #BC7A00 } /* Comment.Preproc */ -.highlight .c1 { color: #408080; font-style: italic } /* Comment.Single */ -.highlight .cs { color: #408080; font-style: italic } /* Comment.Special */ -.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: #008000; font-weight: bold } /* Keyword.Constant */ -.highlight .kd { color: #008000; font-weight: bold } /* Keyword.Declaration */ -.highlight .kp { color: #008000 } /* Keyword.Pseudo */ -.highlight .kr { color: #008000; font-weight: bold } /* Keyword.Reserved */ -.highlight .kt { color: #008000; font-weight: bold } /* Keyword.Type */ -.highlight .m { color: #666666 } /* Literal.Number */ -.highlight .s { color: #BA2121 } /* Literal.String */ -.highlight .na { color: #7D9029 } /* Name.Attribute */ -.highlight .nb { color: #008000 } /* Name.Builtin */ -.highlight .nc { color: #0000FF; font-weight: bold } /* 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: #0000FF } /* 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: #19177C } /* Name.Variable */ -.highlight .ow { color: #AA22FF; font-weight: bold } /* Operator.Word */ -.highlight .w { color: #bbbbbb } /* Text.Whitespace */ -.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: #BA2121 } /* Literal.String.Backtick */ -.highlight .sc { color: #BA2121 } /* Literal.String.Char */ -.highlight .sd { color: #BA2121; font-style: italic } /* Literal.String.Doc */ -.highlight .s2 { color: #BA2121 } /* Literal.String.Double */ -.highlight .se { color: #BB6622; font-weight: bold } /* Literal.String.Escape */ -.highlight .sh { color: #BA2121 } /* 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: #BA2121 } /* Literal.String.Single */ -.highlight .ss { color: #19177C } /* Literal.String.Symbol */ -.highlight .bp { color: #008000 } /* Name.Builtin.Pseudo */ -.highlight .vc { color: #19177C } /* Name.Variable.Class */ -.highlight .vg { color: #19177C } /* Name.Variable.Global */ -.highlight .vi { color: #19177C } /* 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">decorator</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 external" href="mailto:michele.simionato@gmail.com">michele.simionato@gmail.com</a></td> -</tr> -<tr><th class="docinfo-name">Version:</th> -<td>3.4.0 (2012-10-18)</td></tr> -<tr class="field"><th class="docinfo-name">Requires:</th><td class="field-body">Python 2.4+</td> -</tr> -<tr class="field"><th class="docinfo-name">Download page:</th><td class="field-body"><a class="reference external" href="http://pypi.python.org/pypi/decorator/3.4.0">http://pypi.python.org/pypi/decorator/3.4.0</a></td> -</tr> -<tr class="field"><th class="docinfo-name">Installation:</th><td class="field-body"><tt class="docutils literal">easy_install decorator</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" id="contents"> -<p class="topic-title first">Contents</p> -<ul class="simple"> -<li><a class="reference internal" href="#introduction" id="id4">Introduction</a></li> -<li><a class="reference internal" href="#definitions" id="id5">Definitions</a></li> -<li><a class="reference internal" href="#statement-of-the-problem" id="id6">Statement of the problem</a></li> -<li><a class="reference internal" href="#the-solution" id="id7">The solution</a></li> -<li><a class="reference internal" href="#a-trace-decorator" id="id8">A <tt class="docutils literal">trace</tt> decorator</a></li> -<li><a class="reference internal" href="#function-annotations" id="id9">Function annotations</a></li> -<li><a class="reference internal" href="#decorator-is-a-decorator" id="id10"><tt class="docutils literal">decorator</tt> is a decorator</a></li> -<li><a class="reference internal" href="#blocking" id="id11"><tt class="docutils literal">blocking</tt></a></li> -<li><a class="reference internal" href="#async" id="id12"><tt class="docutils literal">async</tt></a></li> -<li><a class="reference internal" href="#contextmanager" id="id13">contextmanager</a></li> -<li><a class="reference internal" href="#the-functionmaker-class" id="id14">The <tt class="docutils literal">FunctionMaker</tt> class</a></li> -<li><a class="reference internal" href="#getting-the-source-code" id="id15">Getting the source code</a></li> -<li><a class="reference internal" href="#dealing-with-third-party-decorators" id="id16">Dealing with third party decorators</a></li> -<li><a class="reference internal" href="#caveats-and-limitations" id="id17">Caveats and limitations</a></li> -<li><a class="reference internal" href="#compatibility-notes" id="id18">Compatibility notes</a></li> -<li><a class="reference internal" href="#licence" id="id19">LICENCE</a></li> -</ul> -</div> -<div class="section" id="introduction"> -<h1><a class="toc-backref" href="#id4">Introduction</a></h1> -<p>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 -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 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">decorator</tt> 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.</p> -<p>You may find the source code for all the examples -discussed here in the <tt class="docutils literal">documentation.py</tt> file, which contains -this documentation in the form of doctests.</p> -</div> -<div class="section" id="definitions"> -<h1><a class="toc-backref" href="#id5">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 subclasses:</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">staticmethod</tt> and <tt class="docutils literal">classmethod</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.</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" id="statement-of-the-problem"> -<h1><a class="toc-backref" href="#id6">Statement of the problem</a></h1> -<p>A very common use case for decorators is the memoization of functions. -A <tt class="docutils literal">memoize</tt> 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 -<tt class="docutils literal">memoize</tt> in <a class="reference external" href="http://www.python.org/moin/PythonDecoratorLibrary">http://www.python.org/moin/PythonDecoratorLibrary</a>, -but they do not preserve the signature. -A simple implementation could be the following (notice -that in general it is impossible to memoize correctly something -that depends on non-hashable arguments):</p> -<div class="codeblock python"> -<div class="highlight"><pre><span class="k">def</span> <span class="nf">memoize_uw</span><span class="p">(</span><span class="n">func</span><span class="p">):</span> - <span class="n">func</span><span class="o">.</span><span class="n">cache</span> <span class="o">=</span> <span class="p">{}</span> - <span class="k">def</span> <span class="nf">memoize</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="n">kw</span><span class="p">:</span> <span class="c"># frozenset is used to ensure hashability</span> - <span class="n">key</span> <span class="o">=</span> <span class="n">args</span><span class="p">,</span> <span class="nb">frozenset</span><span class="p">(</span><span class="n">kw</span><span class="o">.</span><span class="n">iteritems</span><span class="p">())</span> - <span class="k">else</span><span class="p">:</span> - <span class="n">key</span> <span class="o">=</span> <span class="n">args</span> - <span class="n">cache</span> <span class="o">=</span> <span class="n">func</span><span class="o">.</span><span class="n">cache</span> - <span class="k">if</span> <span class="n">key</span> <span class="ow">in</span> <span class="n">cache</span><span class="p">:</span> - <span class="k">return</span> <span class="n">cache</span><span class="p">[</span><span class="n">key</span><span class="p">]</span> - <span class="k">else</span><span class="p">:</span> - <span class="n">cache</span><span class="p">[</span><span class="n">key</span><span class="p">]</span> <span class="o">=</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">return</span> <span class="n">result</span> - <span class="k">return</span> <span class="n">functools</span><span class="o">.</span><span class="n">update_wrapper</span><span class="p">(</span><span class="n">memoize</span><span class="p">,</span> <span class="n">func</span><span class="p">)</span> -</pre></div> - -</div> -<p>Here we used the <a class="reference external" href="http://www.python.org/doc/2.5.2/lib/module-functools.html">functools.update_wrapper</a> 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 -<tt class="docutils literal">__name__</tt>, <tt class="docutils literal">__doc__</tt>, <tt class="docutils literal">__module__</tt> and <tt class="docutils literal">__dict__</tt> -from the original function to the decorated function by hand).</p> -<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">memoize_uw</tt> returns a function with a -<em>different signature</em> from the original function.</p> -<p>Consider for instance the following case:</p> -<div class="codeblock python"> -<div class="highlight"><pre><span class="o">>>></span> <span class="nd">@memoize_uw</span> -<span class="o">...</span> <span class="k">def</span> <span class="nf">f1</span><span class="p">(</span><span class="n">x</span><span class="p">):</span> -<span class="o">...</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="c"># simulate some long computation</span> -<span class="o">...</span> <span class="k">return</span> <span class="n">x</span> -</pre></div> - -</div> -<p>Here the original function takes a single argument named <tt class="docutils literal">x</tt>, -but the decorated function takes any number of arguments and -keyword arguments:</p> -<div class="codeblock python"> -<div class="highlight"><pre><span class="o">>>></span> <span class="kn">from</span> <span class="nn">inspect</span> <span class="kn">import</span> <span class="n">getargspec</span> -<span class="o">>>></span> <span class="k">print</span><span class="p">(</span><span class="n">getargspec</span><span class="p">(</span><span class="n">f1</span><span class="p">))</span> -<span class="n">ArgSpec</span><span class="p">(</span><span class="n">args</span><span class="o">=</span><span class="p">[],</span> <span class="n">varargs</span><span class="o">=</span><span class="s">'args'</span><span class="p">,</span> <span class="n">keywords</span><span class="o">=</span><span class="s">'kw'</span><span class="p">,</span> <span class="n">defaults</span><span class="o">=</span><span class="bp">None</span><span class="p">)</span> -</pre></div> - -</div> -<p>This means that introspection tools such as pydoc will give -wrong informations about the signature of <tt class="docutils literal">f1</tt>. This is pretty bad: -pydoc will tell you that the function accepts a generic signature -<tt class="docutils literal">*args</tt>, <tt class="docutils literal">**kw</tt>, but when you try to call the function with more than an -argument, you will get an error:</p> -<div class="codeblock python"> -<div class="highlight"><pre><span class="o">>>></span> <span class="n">f1</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">)</span> -<span class="n">Traceback</span> <span class="p">(</span><span class="n">most</span> <span class="n">recent</span> <span class="n">call</span> <span class="n">last</span><span class="p">):</span> - <span class="o">...</span> -<span class="ne">TypeError</span><span class="p">:</span> <span class="n">f1</span><span class="p">()</span> <span class="n">takes</span> <span class="n">exactly</span> <span class="mi">1</span> <span class="n">positional</span> <span class="n">argument</span> <span class="p">(</span><span class="mi">2</span> <span class="n">given</span><span class="p">)</span> -</pre></div> - -</div> -</div> -<div class="section" id="the-solution"> -<h1><a class="toc-backref" href="#id7">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">decorator</tt> function in -the <tt class="docutils literal">decorator</tt> module is such a factory:</p> -<div class="codeblock python"> -<div class="highlight"><pre><span class="o">>>></span> <span class="kn">from</span> <span class="nn">decorator</span> <span class="kn">import</span> <span class="n">decorator</span> -</pre></div> - -</div> -<p><tt class="docutils literal">decorator</tt> 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 <tt class="docutils literal">(f, *args, **kw)</tt> and it must call the original function <tt class="docutils literal">f</tt> -with arguments <tt class="docutils literal">args</tt> and <tt class="docutils literal">kw</tt>, implementing the wanted capability, -i.e. memoization in this case:</p> -<div class="codeblock python"> -<div class="highlight"><pre><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="o">**</span><span class="n">kw</span><span class="p">):</span> - <span class="k">if</span> <span class="n">kw</span><span class="p">:</span> <span class="c"># frozenset is used to ensure hashability</span> - <span class="n">key</span> <span class="o">=</span> <span class="n">args</span><span class="p">,</span> <span class="nb">frozenset</span><span class="p">(</span><span class="n">kw</span><span class="o">.</span><span class="n">iteritems</span><span class="p">())</span> - <span class="k">else</span><span class="p">:</span> - <span class="n">key</span> <span class="o">=</span> <span class="n">args</span> - <span class="n">cache</span> <span class="o">=</span> <span class="n">func</span><span class="o">.</span><span class="n">cache</span> <span class="c"># attributed added by memoize</span> - <span class="k">if</span> <span class="n">key</span> <span class="ow">in</span> <span class="n">cache</span><span class="p">:</span> - <span class="k">return</span> <span class="n">cache</span><span class="p">[</span><span class="n">key</span><span class="p">]</span> - <span class="k">else</span><span class="p">:</span> - <span class="n">cache</span><span class="p">[</span><span class="n">key</span><span class="p">]</span> <span class="o">=</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">return</span> <span class="n">result</span> -</pre></div> - -</div> -<p>At this point you can define your decorator as follows:</p> -<div class="codeblock python"> -<div class="highlight"><pre><span class="k">def</span> <span class="nf">memoize</span><span class="p">(</span><span class="n">f</span><span class="p">):</span> - <span class="n">f</span><span class="o">.</span><span class="n">cache</span> <span class="o">=</span> <span class="p">{}</span> - <span class="k">return</span> <span class="n">decorator</span><span class="p">(</span><span class="n">_memoize</span><span class="p">,</span> <span class="n">f</span><span class="p">)</span> -</pre></div> - -</div> -<p>The difference with respect to the <tt class="docutils literal">memoize_uw</tt> approach, which is based -on nested functions, is that the decorator module forces you to lift -the inner function at the outer level (<em>flat is better than nested</em>). -Moreover, you are forced to pass explicitly the function you want to -decorate to the caller function.</p> -<p>Here is a test of usage:</p> -<div class="codeblock python"> -<div class="highlight"><pre><span class="o">>>></span> <span class="nd">@memoize</span> -<span class="o">...</span> <span class="k">def</span> <span class="nf">heavy_computation</span><span class="p">():</span> -<span class="o">...</span> <span class="n">time</span><span class="o">.</span><span class="n">sleep</span><span class="p">(</span><span class="mi">2</span><span class="p">)</span> -<span class="o">...</span> <span class="k">return</span> <span class="s">"done"</span> - -<span class="o">>>></span> <span class="k">print</span><span class="p">(</span><span class="n">heavy_computation</span><span class="p">())</span> <span class="c"># the first time it will take 2 seconds</span> -<span class="n">done</span> - -<span class="o">>>></span> <span class="k">print</span><span class="p">(</span><span class="n">heavy_computation</span><span class="p">())</span> <span class="c"># the second time it will be instantaneous</span> -<span class="n">done</span> -</pre></div> - -</div> -<p>The signature of <tt class="docutils literal">heavy_computation</tt> is the one you would expect:</p> -<div class="codeblock python"> -<div class="highlight"><pre><span class="o">>>></span> <span class="k">print</span><span class="p">(</span><span class="n">getargspec</span><span class="p">(</span><span class="n">heavy_computation</span><span class="p">))</span> -<span class="n">ArgSpec</span><span class="p">(</span><span class="n">args</span><span class="o">=</span><span class="p">[],</span> <span class="n">varargs</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span> <span class="n">keywords</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span> <span class="n">defaults</span><span class="o">=</span><span class="bp">None</span><span class="p">)</span> -</pre></div> - -</div> -</div> -<div class="section" id="a-trace-decorator"> -<h1><a class="toc-backref" href="#id8">A <tt class="docutils literal">trace</tt> decorator</a></h1> -<p>As an additional example, here is how you can define a trivial -<tt class="docutils literal">trace</tt> decorator, which prints a message everytime the traced -function is called:</p> -<div class="codeblock python"> -<div class="highlight"><pre><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="n">kwstr</span> <span class="o">=</span> <span class="s">', '</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="s">'</span><span class="si">%r</span><span class="s">: </span><span class="si">%r</span><span class="s">'</span> <span class="o">%</span> <span class="p">(</span><span class="n">k</span><span class="p">,</span> <span class="n">kw</span><span class="p">[</span><span class="n">k</span><span class="p">])</span> <span class="k">for</span> <span class="n">k</span> <span class="ow">in</span> <span class="nb">sorted</span><span class="p">(</span><span class="n">kw</span><span class="p">))</span> - <span class="k">print</span><span class="p">(</span><span class="s">"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">}"</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">kwstr</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> -</pre></div> - -</div> -<div class="codeblock python"> -<div class="highlight"><pre><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="k">return</span> <span class="n">decorator</span><span class="p">(</span><span class="n">_trace</span><span class="p">,</span> <span class="n">f</span><span class="p">)</span> -</pre></div> - -</div> -<p>Here is an example of usage:</p> -<div class="codeblock python"> -<div class="highlight"><pre><span class="o">>>></span> <span class="nd">@trace</span> -<span class="o">...</span> <span class="k">def</span> <span class="nf">f1</span><span class="p">(</span><span class="n">x</span><span class="p">):</span> -<span class="o">...</span> <span class="k">pass</span> -</pre></div> - -</div> -<p>It is immediate to verify that <tt class="docutils literal">f1</tt> works</p> -<div class="codeblock python"> -<div class="highlight"><pre><span class="o">>>></span> <span class="n">f1</span><span class="p">(</span><span class="mi">0</span><span class="p">)</span> -<span class="n">calling</span> <span class="n">f1</span> <span class="k">with</span> <span class="n">args</span> <span class="p">(</span><span class="mi">0</span><span class="p">,),</span> <span class="p">{}</span> -</pre></div> - -</div> -<p>and it that it has the correct signature:</p> -<div class="codeblock python"> -<div class="highlight"><pre><span class="o">>>></span> <span class="k">print</span><span class="p">(</span><span class="n">getargspec</span><span class="p">(</span><span class="n">f1</span><span class="p">))</span> -<span class="n">ArgSpec</span><span class="p">(</span><span class="n">args</span><span class="o">=</span><span class="p">[</span><span class="s">'x'</span><span class="p">],</span> <span class="n">varargs</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span> <span class="n">keywords</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span> <span class="n">defaults</span><span class="o">=</span><span class="bp">None</span><span class="p">)</span> -</pre></div> - -</div> -<p>The same decorator works with functions of any signature:</p> -<div class="codeblock python"> -<div class="highlight"><pre><span class="o">>>></span> <span class="nd">@trace</span> -<span class="o">...</span> <span class="k">def</span> <span class="nf">f</span><span class="p">(</span><span class="n">x</span><span class="p">,</span> <span class="n">y</span><span class="o">=</span><span class="mi">1</span><span class="p">,</span> <span class="n">z</span><span class="o">=</span><span class="mi">2</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="o">...</span> <span class="k">pass</span> - -<span class="o">>>></span> <span class="n">f</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">3</span><span class="p">)</span> -<span class="n">calling</span> <span class="n">f</span> <span class="k">with</span> <span class="n">args</span> <span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">2</span><span class="p">),</span> <span class="p">{}</span> - -<span class="o">>>></span> <span class="k">print</span><span class="p">(</span><span class="n">getargspec</span><span class="p">(</span><span class="n">f</span><span class="p">))</span> -<span class="n">ArgSpec</span><span class="p">(</span><span class="n">args</span><span class="o">=</span><span class="p">[</span><span class="s">'x'</span><span class="p">,</span> <span class="s">'y'</span><span class="p">,</span> <span class="s">'z'</span><span class="p">],</span> <span class="n">varargs</span><span class="o">=</span><span class="s">'args'</span><span class="p">,</span> <span class="n">keywords</span><span class="o">=</span><span class="s">'kw'</span><span class="p">,</span> <span class="n">defaults</span><span class="o">=</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">))</span> -</pre></div> - -</div> -</div> -<div class="section" id="function-annotations"> -<h1><a class="toc-backref" href="#id9">Function annotations</a></h1> -<p>Python 3 introduced the concept of <a class="reference external" href="http://www.python.org/dev/peps/pep-3107/">function annotations</a>,i.e. the ability -to annotate the signature of a function with additional information, -stored in a dictionary named <tt class="docutils literal">__annotations__</tt>. The decorator module, -starting from release 3.3, is able to understand and to preserve the -annotations. Here is an example:</p> -<div class="codeblock python"> -<div class="highlight"><pre><span class="o">>>></span> <span class="nd">@trace</span> -<span class="o">...</span> <span class="k">def</span> <span class="nf">f</span><span class="p">(</span><span class="n">x</span><span class="p">:</span> <span class="s">'the first argument'</span><span class="p">,</span> <span class="n">y</span><span class="p">:</span> <span class="s">'default argument'</span><span class="o">=</span><span class="mi">1</span><span class="p">,</span> <span class="n">z</span><span class="o">=</span><span class="mi">2</span><span class="p">,</span> -<span class="o">...</span> <span class="o">*</span><span class="n">args</span><span class="p">:</span> <span class="s">'varargs'</span><span class="p">,</span> <span class="o">**</span><span class="n">kw</span><span class="p">:</span> <span class="s">'kwargs'</span><span class="p">):</span> -<span class="o">...</span> <span class="k">pass</span> -</pre></div> - -</div> -<p>In order to introspect functions with annotations, one needs the -utility <tt class="docutils literal">inspect.getfullargspec</tt>, new in Python 3:</p> -<div class="codeblock python"> -<div class="highlight"><pre><span class="o">>>></span> <span class="kn">from</span> <span class="nn">inspect</span> <span class="kn">import</span> <span class="n">getfullargspec</span> -<span class="o">>>></span> <span class="n">argspec</span> <span class="o">=</span> <span class="n">getfullargspec</span><span class="p">(</span><span class="n">f</span><span class="p">)</span> -<span class="o">>>></span> <span class="n">argspec</span><span class="o">.</span><span class="n">args</span> -<span class="p">[</span><span class="s">'x'</span><span class="p">,</span> <span class="s">'y'</span><span class="p">,</span> <span class="s">'z'</span><span class="p">]</span> -<span class="o">>>></span> <span class="n">argspec</span><span class="o">.</span><span class="n">varargs</span> -<span class="s">'args'</span> -<span class="o">>>></span> <span class="n">argspec</span><span class="o">.</span><span class="n">varkw</span> -<span class="s">'kw'</span> -<span class="o">>>></span> <span class="n">argspec</span><span class="o">.</span><span class="n">defaults</span> -<span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">)</span> -<span class="o">>>></span> <span class="n">argspec</span><span class="o">.</span><span class="n">kwonlyargs</span> -<span class="p">[]</span> -<span class="o">>>></span> <span class="n">argspec</span><span class="o">.</span><span class="n">kwonlydefaults</span> -</pre></div> - -</div> -<p>You can also check that the <tt class="docutils literal">__annotations__</tt> dictionary is preserved:</p> -<div class="codeblock python"> -<div class="highlight"><pre><span class="o">>>></span> <span class="n">f</span><span class="o">.</span><span class="n">__annotations__</span> <span class="o">==</span> <span class="n">f</span><span class="o">.</span><span class="n">__wrapped__</span><span class="o">.</span><span class="n">__annotations__</span> -<span class="bp">True</span> -</pre></div> - -</div> -<p>Depending on the version of the decorator module, the two dictionaries can -be the same object or not: you cannot rely on object identity, but you can -rely on the content being the same.</p> -</div> -<div class="section" id="decorator-is-a-decorator"> -<h1><a class="toc-backref" href="#id10"><tt class="docutils literal">decorator</tt> is a decorator</a></h1> -<p>It may be annoying to write a caller function (like the <tt class="docutils literal">_trace</tt> -function above) and then a trivial wrapper -(<tt class="docutils literal">def trace(f): return decorator(_trace, f)</tt>) every time. For this reason, -the <tt class="docutils literal">decorator</tt> module provides an easy shortcut to convert -the caller function into a signature-preserving decorator: -you can just call <tt class="docutils literal">decorator</tt> with a single argument. -In our example you can just write <tt class="docutils literal">trace = decorator(_trace)</tt>. -The <tt class="docutils literal">decorator</tt> function can also be used as a signature-changing -decorator, just as <tt class="docutils literal">classmethod</tt> and <tt class="docutils literal">staticmethod</tt>. -However, <tt class="docutils literal">classmethod</tt> and <tt class="docutils literal">staticmethod</tt> return generic -objects which are not callable, while <tt class="docutils literal">decorator</tt> returns -signature-preserving decorators, i.e. functions of a single argument. -For instance, you can write directly</p> -<div class="codeblock python"> -<div class="highlight"><pre><span class="o">>>></span> <span class="nd">@decorator</span> -<span class="o">...</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="o">...</span> <span class="n">kwstr</span> <span class="o">=</span> <span class="s">', '</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="s">'</span><span class="si">%r</span><span class="s">: </span><span class="si">%r</span><span class="s">'</span> <span class="o">%</span> <span class="p">(</span><span class="n">k</span><span class="p">,</span> <span class="n">kw</span><span class="p">[</span><span class="n">k</span><span class="p">])</span> <span class="k">for</span> <span class="n">k</span> <span class="ow">in</span> <span class="nb">sorted</span><span class="p">(</span><span class="n">kw</span><span class="p">))</span> -<span class="o">...</span> <span class="k">print</span><span class="p">(</span><span class="s">"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">}"</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">kwstr</span><span class="p">))</span> -<span class="o">...</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> -</pre></div> - -</div> -<p>and now <tt class="docutils literal">trace</tt> will be a decorator. Actually <tt class="docutils literal">trace</tt> is a <tt class="docutils literal">partial</tt> -object which can be used as a decorator:</p> -<div class="codeblock python"> -<div class="highlight"><pre><span class="o">>>></span> <span class="n">trace</span> -<span class="o"><</span><span class="n">function</span> <span class="n">trace</span> <span class="n">at</span> <span class="mi">0</span><span class="n">x</span><span class="o">...></span> -</pre></div> - -</div> -<p>Here is an example of usage:</p> -<div class="codeblock python"> -<div class="highlight"><pre><span class="o">>>></span> <span class="nd">@trace</span> -<span class="o">...</span> <span class="k">def</span> <span class="nf">func</span><span class="p">():</span> <span class="k">pass</span> - -<span class="o">>>></span> <span class="n">func</span><span class="p">()</span> -<span class="n">calling</span> <span class="n">func</span> <span class="k">with</span> <span class="n">args</span> <span class="p">(),</span> <span class="p">{}</span> -</pre></div> - -</div> -<p>If you are using an old Python version (Python 2.4) the -<tt class="docutils literal">decorator</tt> module provides a poor man replacement for -<tt class="docutils literal">functools.partial</tt>.</p> -</div> -<div class="section" id="blocking"> -<h1><a class="toc-backref" href="#id11"><tt class="docutils literal">blocking</tt></a></h1> -<p>Sometimes one has to deal with blocking resources, such as <tt class="docutils literal">stdin</tt>, and -sometimes it is best to have back a "busy" message than to block everything. -This behavior can be implemented with a suitable family of decorators, -where the parameter is the busy message:</p> -<div class="codeblock python"> -<div class="highlight"><pre><span class="k">def</span> <span class="nf">blocking</span><span class="p">(</span><span class="n">not_avail</span><span class="p">):</span> - <span class="k">def</span> <span class="nf">blocking</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">"thread"</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">blocking</span><span class="p">)</span> -</pre></div> - -</div> -<p>Functions decorated with <tt class="docutils literal">blocking</tt> will return a busy message if -the resource is unavailable, and the intended result if the resource is -available. For instance:</p> -<div class="codeblock python"> -<div class="highlight"><pre><span class="o">>>></span> <span class="nd">@blocking</span><span class="p">(</span><span class="s">"Please wait ..."</span><span class="p">)</span> -<span class="o">...</span> <span class="k">def</span> <span class="nf">read_data</span><span class="p">():</span> -<span class="o">...</span> <span class="n">time</span><span class="o">.</span><span class="n">sleep</span><span class="p">(</span><span class="mi">3</span><span class="p">)</span> <span class="c"># simulate a blocking resource</span> -<span class="o">...</span> <span class="k">return</span> <span class="s">"some data"</span> - -<span class="o">>>></span> <span class="k">print</span><span class="p">(</span><span class="n">read_data</span><span class="p">())</span> <span class="c"># data is not available yet</span> -<span class="n">Please</span> <span class="n">wait</span> <span class="o">...</span> - -<span class="o">>>></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="o">>>></span> <span class="k">print</span><span class="p">(</span><span class="n">read_data</span><span class="p">())</span> <span class="c"># data is not available yet</span> -<span class="n">Please</span> <span class="n">wait</span> <span class="o">...</span> - -<span class="o">>>></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="o">>>></span> <span class="k">print</span><span class="p">(</span><span class="n">read_data</span><span class="p">())</span> <span class="c"># data is not available yet</span> -<span class="n">Please</span> <span class="n">wait</span> <span class="o">...</span> - -<span class="o">>>></span> <span class="n">time</span><span class="o">.</span><span class="n">sleep</span><span class="p">(</span><span class="mf">1.1</span><span class="p">)</span> <span class="c"># after 3.1 seconds, data is available</span> -<span class="o">>>></span> <span class="k">print</span><span class="p">(</span><span class="n">read_data</span><span class="p">())</span> -<span class="n">some</span> <span class="n">data</span> -</pre></div> - -</div> -</div> -<div class="section" id="async"> -<h1><a class="toc-backref" href="#id12"><tt class="docutils literal">async</tt></a></h1> -<p>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 converted into decorators.</p> -<p>As an example, here will 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 <tt class="docutils literal">on_success</tt>, <tt class="docutils literal">on_failure</tt> and <tt class="docutils literal">on_closing</tt>, -to specify how to manage the function call (of course the code here -is just an example, it is not a recommended way of doing multi-threaded -programming). The implementation is the following:</p> -<div class="codeblock python"> -<div class="highlight"><pre><span class="k">def</span> <span class="nf">on_success</span><span class="p">(</span><span class="n">result</span><span class="p">):</span> <span class="c"># default implementation</span> - <span class="s">"Called on the result of the function"</span> - <span class="k">return</span> <span class="n">result</span> -</pre></div> - -</div> -<div class="codeblock python"> -<div class="highlight"><pre><span class="k">def</span> <span class="nf">on_failure</span><span class="p">(</span><span class="n">exc_info</span><span class="p">):</span> <span class="c"># default implementation</span> - <span class="s">"Called if the function fails"</span> - <span class="k">pass</span> -</pre></div> - -</div> -<div class="codeblock python"> -<div class="highlight"><pre><span class="k">def</span> <span class="nf">on_closing</span><span class="p">():</span> <span class="c"># default implementation</span> - <span class="s">"Called at the end, both in case of success and failure"</span> - <span class="k">pass</span> -</pre></div> - -</div> -<div class="codeblock python"> -<div class="highlight"><pre><span class="k">class</span> <span class="nc">Async</span><span class="p">(</span><span class="nb">object</span><span class="p">):</span> - <span class="sd">"""</span> -<span class="sd"> A decorator converting blocking functions into asynchronous</span> -<span class="sd"> functions, by using threads or processes. Examples:</span> - -<span class="sd"> async_with_threads = Async(threading.Thread)</span> -<span class="sd"> async_with_processes = Async(multiprocessing.Process)</span> -<span class="sd"> """</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">threadfactory</span><span class="p">,</span> <span class="n">on_success</span><span class="o">=</span><span class="n">on_success</span><span class="p">,</span> - <span class="n">on_failure</span><span class="o">=</span><span class="n">on_failure</span><span class="p">,</span> <span class="n">on_closing</span><span class="o">=</span><span class="n">on_closing</span><span class="p">):</span> - <span class="bp">self</span><span class="o">.</span><span class="n">threadfactory</span> <span class="o">=</span> <span class="n">threadfactory</span> - <span class="bp">self</span><span class="o">.</span><span class="n">on_success</span> <span class="o">=</span> <span class="n">on_success</span> - <span class="bp">self</span><span class="o">.</span><span class="n">on_failure</span> <span class="o">=</span> <span class="n">on_failure</span> - <span class="bp">self</span><span class="o">.</span><span class="n">on_closing</span> <span class="o">=</span> <span class="n">on_closing</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="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">try</span><span class="p">:</span> - <span class="n">counter</span> <span class="o">=</span> <span class="n">func</span><span class="o">.</span><span class="n">counter</span> - <span class="k">except</span> <span class="ne">AttributeError</span><span class="p">:</span> <span class="c"># instantiate the counter at the first call</span> - <span class="n">counter</span> <span class="o">=</span> <span class="n">func</span><span class="o">.</span><span class="n">counter</span> <span class="o">=</span> <span class="n">itertools</span><span class="o">.</span><span class="n">count</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span> - <span class="n">name</span> <span class="o">=</span> <span class="s">'</span><span class="si">%s</span><span class="s">-</span><span class="si">%s</span><span class="s">'</span> <span class="o">%</span> <span class="p">(</span><span class="n">func</span><span class="o">.</span><span class="n">__name__</span><span class="p">,</span> <span class="nb">next</span><span class="p">(</span><span class="n">counter</span><span class="p">))</span> - <span class="k">def</span> <span class="nf">func_wrapper</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">except</span><span class="p">:</span> - <span class="bp">self</span><span class="o">.</span><span class="n">on_failure</span><span class="p">(</span><span class="n">sys</span><span class="o">.</span><span class="n">exc_info</span><span class="p">())</span> - <span class="k">else</span><span class="p">:</span> - <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">on_success</span><span class="p">(</span><span class="n">result</span><span class="p">)</span> - <span class="k">finally</span><span class="p">:</span> - <span class="bp">self</span><span class="o">.</span><span class="n">on_closing</span><span class="p">()</span> - <span class="n">thread</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">threadfactory</span><span class="p">(</span><span class="bp">None</span><span class="p">,</span> <span class="n">func_wrapper</span><span class="p">,</span> <span class="n">name</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> -</pre></div> - -</div> -<p>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">.isAlive()</tt>.</p> -<p>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:</p> -<div class="codeblock python"> -<div class="highlight"><pre><span class="o">>>></span> <span class="n">async</span> <span class="o">=</span> <span class="n">decorator</span><span class="p">(</span><span class="n">Async</span><span class="p">(</span><span class="n">threading</span><span class="o">.</span><span class="n">Thread</span><span class="p">))</span> - -<span class="o">>>></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="o">>>></span> <span class="nd">@async</span> -<span class="o">...</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="o">...</span> <span class="c"># append data to the datalist by locking</span> -<span class="o">...</span> <span class="k">with</span> <span class="n">threading</span><span class="o">.</span><span class="n">Lock</span><span class="p">():</span> -<span class="o">...</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="c"># emulate some long running operation</span> -<span class="o">...</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="o">...</span> <span class="c"># other operations not requiring a lock here</span> -</pre></div> - -</div> -<p>Each call to <tt class="docutils literal">write</tt> will create a new writer thread, but there will -be no synchronization problems since <tt class="docutils literal">write</tt> is locked.</p> -<div class="codeblock python"> -<div class="highlight"><pre><span class="o">>>></span> <span class="n">write</span><span class="p">(</span><span class="s">"data1"</span><span class="p">)</span> -<span class="o"><</span><span class="n">Thread</span><span class="p">(</span><span class="n">write</span><span class="o">-</span><span class="mi">1</span><span class="p">,</span> <span class="n">started</span><span class="o">...</span><span class="p">)</span><span class="o">></span> - -<span class="o">>>></span> <span class="n">time</span><span class="o">.</span><span class="n">sleep</span><span class="p">(</span><span class="o">.</span><span class="mi">1</span><span class="p">)</span> <span class="c"># wait a bit, so we are sure data2 is written after data1</span> - -<span class="o">>>></span> <span class="n">write</span><span class="p">(</span><span class="s">"data2"</span><span class="p">)</span> -<span class="o"><</span><span class="n">Thread</span><span class="p">(</span><span class="n">write</span><span class="o">-</span><span class="mi">2</span><span class="p">,</span> <span class="n">started</span><span class="o">...</span><span class="p">)</span><span class="o">></span> - -<span class="o">>>></span> <span class="n">time</span><span class="o">.</span><span class="n">sleep</span><span class="p">(</span><span class="mi">2</span><span class="p">)</span> <span class="c"># wait for the writers to complete</span> - -<span class="o">>>></span> <span class="k">print</span><span class="p">(</span><span class="n">datalist</span><span class="p">)</span> -<span class="p">[</span><span class="s">'data1'</span><span class="p">,</span> <span class="s">'data2'</span><span class="p">]</span> -</pre></div> - -</div> -</div> -<div class="section" id="contextmanager"> -<h1><a class="toc-backref" href="#id13">contextmanager</a></h1> -<p>For a long time Python had in its standard library a <tt class="docutils literal">contextmanager</tt> -decorator, able to convert generator functions into -<tt class="docutils literal">_GeneratorContextManager</tt> -factories. For instance if you write</p> -<div class="codeblock python"> -<div class="highlight"><pre><span class="o">>>></span> <span class="kn">from</span> <span class="nn">contextlib</span> <span class="kn">import</span> <span class="n">contextmanager</span> -<span class="o">>>></span> <span class="nd">@contextmanager</span> -<span class="o">...</span> <span class="k">def</span> <span class="nf">before_after</span><span class="p">(</span><span class="n">before</span><span class="p">,</span> <span class="n">after</span><span class="p">):</span> -<span class="o">...</span> <span class="k">print</span><span class="p">(</span><span class="n">before</span><span class="p">)</span> -<span class="o">...</span> <span class="k">yield</span> -<span class="o">...</span> <span class="k">print</span><span class="p">(</span><span class="n">after</span><span class="p">)</span> -</pre></div> - -</div> -<p>then <tt class="docutils literal">before_after</tt> is a factory function returning -<tt class="docutils literal">_GeneratorContextManager</tt> objects which can be used with -the <tt class="docutils literal">with</tt> statement:</p> -<div class="codeblock python"> -<div class="highlight"><pre><span class="o">>>></span> <span class="n">ba</span> <span class="o">=</span> <span class="n">before_after</span><span class="p">(</span><span class="s">'BEFORE'</span><span class="p">,</span> <span class="s">'AFTER'</span><span class="p">)</span> -<span class="o">>>></span> <span class="nb">type</span><span class="p">(</span><span class="n">ba</span><span class="p">)</span> -<span class="o"><</span><span class="k">class</span> <span class="err">'</span><span class="nc">contextlib</span><span class="o">.</span><span class="n">_GeneratorContextManager</span><span class="s">'></span> -<span class="o">>>></span> <span class="k">with</span> <span class="n">ba</span><span class="p">:</span> -<span class="o">...</span> <span class="k">print</span><span class="p">(</span><span class="s">'hello'</span><span class="p">)</span> -<span class="n">BEFORE</span> -<span class="n">hello</span> -<span class="n">AFTER</span> -</pre></div> - -</div> -<p>Basically, it is as if the content of the <tt class="docutils literal">with</tt> block was executed -in the place of the <tt class="docutils literal">yield</tt> expression in the generator function. -In Python 3.2 <tt class="docutils literal">_GeneratorContextManager</tt> -objects were enhanced with a <tt class="docutils literal">__call__</tt> -method, so that they can be used as decorators as in this example:</p> -<div class="codeblock python"> -<div class="highlight"><pre><span class="o">>>></span> <span class="nd">@ba</span> -<span class="o">...</span> <span class="k">def</span> <span class="nf">hello</span><span class="p">():</span> -<span class="o">...</span> <span class="k">print</span><span class="p">(</span><span class="s">'hello'</span><span class="p">)</span> -<span class="o">...</span> -<span class="o">>>></span> <span class="n">hello</span><span class="p">()</span> -<span class="n">BEFORE</span> -<span class="n">hello</span> -<span class="n">AFTER</span> -</pre></div> - -</div> -<p>The <tt class="docutils literal">ba</tt> decorator is basically inserting a <tt class="docutils literal">with ba:</tt> -block inside the function. -However there two issues: the first is that <tt class="docutils literal">_GeneratorContextManager</tt> -objects are callable only in Python 3.2, so the previous example will break -in older versions of Python; the second is that -<tt class="docutils literal">_GeneratorContextManager</tt> objects do not preserve the signature -of the decorated functions: the decorated <tt class="docutils literal">hello</tt> function here will have -a generic signature <tt class="docutils literal"><span class="pre">hello(*args,</span> **kwargs)</tt> but will break when -called with more than zero arguments. For such reasons the decorator -module, starting with release 3.4, offers a <tt class="docutils literal">decorator.contextmanager</tt> -decorator that solves both problems and works even in Python 2.5. -The usage is the same and factories decorated with <tt class="docutils literal">decorator.contextmanager</tt> -will returns instances of <tt class="docutils literal">ContextManager</tt>, a subclass of -<tt class="docutils literal">contextlib._GeneratorContextManager</tt> with a <tt class="docutils literal">__call__</tt> method -acting as a signature-preserving decorator.</p> -</div> -<div class="section" id="the-functionmaker-class"> -<h1><a class="toc-backref" href="#id14">The <tt class="docutils literal">FunctionMaker</tt> class</a></h1> -<p>You may wonder about how the functionality of the <tt class="docutils literal">decorator</tt> module -is implemented. The basic building block is -a <tt class="docutils literal">FunctionMaker</tt> class which is able to generate on the fly -functions with a given name and signature from a function template -passed as a string. Generally speaking, you should not need to -resort to <tt class="docutils literal">FunctionMaker</tt> when writing ordinary decorators, but -it is handy in some circumstances. You will see an example shortly, in -the implementation of a cool decorator utility (<tt class="docutils literal">decorator_apply</tt>).</p> -<p><tt class="docutils literal">FunctionMaker</tt> provides a <tt class="docutils literal">.create</tt> classmethod which -takes as input the name, signature, and body of the function -we want to generate as well as the execution environment -were the function is generated by <tt class="docutils literal">exec</tt>. Here is an example:</p> -<div class="codeblock python"> -<div class="highlight"><pre><span class="o">>>></span> <span class="k">def</span> <span class="nf">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"># a function with a generic signature</span> -<span class="o">...</span> <span class="k">print</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="o">>>></span> <span class="n">f1</span> <span class="o">=</span> <span class="n">FunctionMaker</span><span class="o">.</span><span class="n">create</span><span class="p">(</span><span class="s">'f1(a, b)'</span><span class="p">,</span> <span class="s">'f(a, b)'</span><span class="p">,</span> <span class="nb">dict</span><span class="p">(</span><span class="n">f</span><span class="o">=</span><span class="n">f</span><span class="p">))</span> -<span class="o">>>></span> <span class="n">f1</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">)</span> -<span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">)</span> <span class="p">{}</span> -</pre></div> - -</div> -<p>It is important to notice that the function body is interpolated -before being executed, so be careful with the <tt class="docutils literal">%</tt> sign!</p> -<p><tt class="docutils literal">FunctionMaker.create</tt> 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 <tt class="docutils literal">__doc__</tt>.</p> -<p>For debugging/introspection purposes it may be useful to see -the source code of the generated function; to do that, just -pass the flag <tt class="docutils literal">addsource=True</tt> and a <tt class="docutils literal">__source__</tt> attribute will -be added to the generated function:</p> -<div class="codeblock python"> -<div class="highlight"><pre><span class="o">>>></span> <span class="n">f1</span> <span class="o">=</span> <span class="n">FunctionMaker</span><span class="o">.</span><span class="n">create</span><span class="p">(</span> -<span class="o">...</span> <span class="s">'f1(a, b)'</span><span class="p">,</span> <span class="s">'f(a, b)'</span><span class="p">,</span> <span class="nb">dict</span><span class="p">(</span><span class="n">f</span><span class="o">=</span><span class="n">f</span><span class="p">),</span> <span class="n">addsource</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span> -<span class="o">>>></span> <span class="k">print</span><span class="p">(</span><span class="n">f1</span><span class="o">.</span><span class="n">__source__</span><span class="p">)</span> -<span class="k">def</span> <span class="nf">f1</span><span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="n">b</span><span class="p">):</span> - <span class="n">f</span><span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="n">b</span><span class="p">)</span> -<span class="o"><</span><span class="n">BLANKLINE</span><span class="o">></span> -</pre></div> - -</div> -<p><tt class="docutils literal">FunctionMaker.create</tt> can take as first argument a string, -as in the examples before, or a function. This is the most common -usage, since typically you want to decorate a pre-existing -function. A framework author may want to use directly <tt class="docutils literal">FunctionMaker.create</tt> -instead of <tt class="docutils literal">decorator</tt>, since it gives you direct access to the body -of the generated function. For instance, suppose you want to instrument -the <tt class="docutils literal">__init__</tt> methods of a set of classes, by preserving their -signature (such use case is not made up; this is done in SQAlchemy -and in other frameworks). When the first argument of <tt class="docutils literal">FunctionMaker.create</tt> -is a function, a <tt class="docutils literal">FunctionMaker</tt> object is instantiated internally, -with attributes <tt class="docutils literal">args</tt>, <tt class="docutils literal">varargs</tt>, -<tt class="docutils literal">keywords</tt> and <tt class="docutils literal">defaults</tt> which are the -the return values of the standard library function <tt class="docutils literal">inspect.getargspec</tt>. -For each argument in the <tt class="docutils literal">args</tt> (which is a list of strings containing -the names of the mandatory arguments) an attribute <tt class="docutils literal">arg0</tt>, <tt class="docutils literal">arg1</tt>, -..., <tt class="docutils literal">argN</tt> is also generated. Finally, there is a <tt class="docutils literal">signature</tt> -attribute, a string with the signature of the original function.</p> -<p>Notice that while I do not have plans -to change or remove the functionality provided in the -<tt class="docutils literal">FunctionMaker</tt> class, I do not guarantee that it will stay -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 -<tt class="docutils literal">decorator</tt> has been there from version 0.1 and it is guaranteed to -stay there forever.</p> -</div> -<div class="section" id="getting-the-source-code"> -<h1><a class="toc-backref" href="#id15">Getting the source code</a></h1> -<p>Internally <tt class="docutils literal">FunctionMaker.create</tt> uses <tt class="docutils literal">exec</tt> to generate the -decorated function. Therefore -<tt class="docutils literal">inspect.getsource</tt> will not work for decorated functions. That -means that the usual '??' trick in IPython will give you the (right on -the spot) message <tt class="docutils literal">Dynamically generated function. No source code -available</tt>. In the past I have considered this acceptable, since -<tt class="docutils literal">inspect.getsource</tt> does not really work even with regular -decorators. In that case <tt class="docutils literal">inspect.getsource</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="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> -</pre></div> - -</div> -<div class="codeblock python"> -<div class="highlight"><pre><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="o">>>></span> <span class="k">print</span><span class="p">(</span><span class="n">inspect</span><span class="o">.</span><span class="n">getsource</span><span class="p">(</span><span class="n">example</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="o"><</span><span class="n">BLANKLINE</span><span class="o">></span> -</pre></div> - -</div> -<p>(see bug report <a class="reference external" href="http://bugs.python.org/issue1764286">1764286</a> for an explanation of what is happening). -Unfortunately the bug is still there, even in Python 2.7 and 3.1. -There is however a workaround. The decorator module adds an -attribute <tt class="docutils literal">.__wrapped__</tt> to the decorated function, containing -a reference to the original function. The easy way to get -the source code is to call <tt class="docutils literal">inspect.getsource</tt> on the -undecorated function:</p> -<div class="codeblock python"> -<div class="highlight"><pre><span class="o">>>></span> <span class="k">print</span><span class="p">(</span><span class="n">inspect</span><span class="o">.</span><span class="n">getsource</span><span class="p">(</span><span class="n">factorial</span><span class="o">.</span><span class="n">__wrapped__</span><span class="p">))</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">"The good old factorial"</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="o"><</span><span class="n">BLANKLINE</span><span class="o">></span> -</pre></div> - -</div> -</div> -<div class="section" id="dealing-with-third-party-decorators"> -<h1><a class="toc-backref" href="#id16">Dealing with third party decorators</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">decorator</tt>. You can use a -<tt class="docutils literal">FunctionMaker</tt> to implement that functionality as follows:</p> -<div class="codeblock python"> -<div class="highlight"><pre><span class="k">def</span> <span class="nf">decorator_apply</span><span class="p">(</span><span class="n">dec</span><span class="p">,</span> <span class="n">func</span><span class="p">):</span> - <span class="sd">"""</span> -<span class="sd"> Decorate a function by preserving the signature even if dec</span> -<span class="sd"> is not a signature-preserving decorator.</span> -<span class="sd"> """</span> - <span class="k">return</span> <span class="n">FunctionMaker</span><span class="o">.</span><span class="n">create</span><span class="p">(</span> - <span class="n">func</span><span class="p">,</span> <span class="s">'return decorated(</span><span class="si">%(signature)s</span><span class="s">)'</span><span class="p">,</span> - <span class="nb">dict</span><span class="p">(</span><span class="n">decorated</span><span class="o">=</span><span class="n">dec</span><span class="p">(</span><span class="n">func</span><span class="p">)),</span> <span class="n">__wrapped__</span><span class="o">=</span><span class="n">func</span><span class="p">)</span> -</pre></div> - -</div> -<p><tt class="docutils literal">decorator_apply</tt> sets the attribute <tt class="docutils literal">.__wrapped__</tt> of the generated -function to the original function, so that you can get the right -source code.</p> -<p>Notice that I am not providing this functionality in the <tt class="docutils literal">decorator</tt> -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 <tt class="docutils literal">decorator_apply</tt> to your toolbox and -use it if you need to.</p> -<p>In order to give an example of usage of <tt class="docutils literal">decorator_apply</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 external" 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="k">class</span> <span class="nc">TailRecursive</span><span class="p">(</span><span class="nb">object</span><span class="p">):</span> - <span class="sd">"""</span> -<span class="sd"> tail_recursive decorator based on Kay Schluehr's recipe</span> -<span class="sd"> http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/496691</span> -<span class="sd"> with improvements by me and George Sakkis.</span> -<span class="sd"> """</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="bp">self</span><span class="o">.</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">__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="n">CONTINUE</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">CONTINUE</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="n">func</span> <span class="o">=</span> <span class="bp">self</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">False</span> - <span class="k">try</span><span class="p">:</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="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="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">return</span> <span class="n">result</span> - <span class="k">finally</span><span class="p">:</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">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="n">CONTINUE</span> -</pre></div> - -</div> -<p>Here the decorator is implemented as a class returning callable -objects.</p> -<div class="codeblock python"> -<div class="highlight"><pre><span class="k">def</span> <span class="nf">tail_recursive</span><span class="p">(</span><span class="n">func</span><span class="p">):</span> - <span class="k">return</span> <span class="n">decorator_apply</span><span class="p">(</span><span class="n">TailRecursive</span><span class="p">,</span> <span class="n">func</span><span class="p">)</span> -</pre></div> - -</div> -<p>Here is how you apply the upgraded decorator to the good old factorial:</p> -<div class="codeblock python"> -<div class="highlight"><pre><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">"The good old factorial"</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> -</pre></div> - -</div> -<div class="codeblock python"> -<div class="highlight"><pre><span class="o">>>></span> <span class="k">print</span><span class="p">(</span><span class="n">factorial</span><span class="p">(</span><span class="mi">4</span><span class="p">))</span> -<span class="mi">24</span> -</pre></div> - -</div> -<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">factorial(1001)</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 the following</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>(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).</p> -</div> -<div class="section" id="caveats-and-limitations"> -<h1><a class="toc-backref" href="#id17">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 -python3 -m timeit -s " -from decorator import decorator - -@decorator -def do_nothing(func, *args, **kw): - return func(*args, **kw) - -@do_nothing -def f(): - pass -" "f()" - -python3 -m timeit -s " -def f(): - pass -" "f()" -</pre> -<p>On my MacBook, using the <tt class="docutils literal">do_nothing</tt> decorator instead of the -plain function is more than three times slower:</p> -<pre class="literal-block"> -$ bash performance.sh -1000000 loops, best of 3: 0.669 usec per loop -1000000 loops, best of 3: 0.181 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">f</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> -<div class="codeblock python"> -<div class="highlight"><pre><span class="o">>>></span> <span class="nd">@trace</span> -<span class="o">...</span> <span class="k">def</span> <span class="nf">f</span><span class="p">():</span> -<span class="o">...</span> <span class="mi">1</span><span class="o">/</span><span class="mi">0</span> -</pre></div> - -</div> -<p>Calling <tt class="docutils literal">f()</tt> will give you a <tt class="docutils literal">ZeroDivisionError</tt>, but since the -function is decorated the traceback will be longer:</p> -<div class="codeblock python"> -<div class="highlight"><pre><span class="o">>>></span> <span class="n">f</span><span class="p">()</span> -<span class="n">Traceback</span> <span class="p">(</span><span class="n">most</span> <span class="n">recent</span> <span class="n">call</span> <span class="n">last</span><span class="p">):</span> - <span class="o">...</span> - <span class="n">File</span> <span class="s">"<string>"</span><span class="p">,</span> <span class="n">line</span> <span class="mi">2</span><span class="p">,</span> <span class="ow">in</span> <span class="n">f</span> - <span class="n">File</span> <span class="s">"<doctest __main__[22]>"</span><span class="p">,</span> <span class="n">line</span> <span class="mi">4</span><span class="p">,</span> <span class="ow">in</span> <span class="n">trace</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">File</span> <span class="s">"<doctest __main__[51]>"</span><span class="p">,</span> <span class="n">line</span> <span class="mi">3</span><span class="p">,</span> <span class="ow">in</span> <span class="n">f</span> - <span class="mi">1</span><span class="o">/</span><span class="mi">0</span> -<span class="ne">ZeroDivisionError</span><span class="p">:</span> <span class="o">...</span> -</pre></div> - -</div> -<p>You see here the inner call to the decorator <tt class="docutils literal">trace</tt>, which calls -<tt class="docutils literal"><span class="pre">f(*args,</span> **kw)</tt>, and a reference to <tt class="docutils literal">File <span class="pre">"<string>",</span> line 2, in f</tt>. -This latter reference is due to the fact that internally the decorator -module uses <tt class="docutils literal">exec</tt> to generate the decorated function. Notice that -<tt class="docutils literal">exec</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>At present, there is no clean way to avoid <tt class="docutils literal">exec</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. -That could happen in future versions of Python (see PEP <a class="reference external" href="http://www.python.org/dev/peps/pep-0362">362</a>) and -then the decorator module would become obsolete. However, at present, -even in Python 3.2 it is impossible to change the function signature -directly, therefore the <tt class="docutils literal">decorator</tt> module is still useful. -Actually, this is one of the main reasons why I keep maintaining -the module and releasing new versions.</p> -<p>In the present implementation, decorators generated by <tt class="docutils literal">decorator</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">inspect</tt> module in the standard library.</p> -<p>There is a restriction on the names of the arguments: for instance, -if try to call an argument <tt class="docutils literal">_call_</tt> or <tt class="docutils literal">_func_</tt> -you will get a <tt class="docutils literal">NameError</tt>:</p> -<div class="codeblock python"> -<div class="highlight"><pre><span class="o">>>></span> <span class="nd">@trace</span> -<span class="o">...</span> <span class="k">def</span> <span class="nf">f</span><span class="p">(</span><span class="n">_func_</span><span class="p">):</span> <span class="k">print</span><span class="p">(</span><span class="n">f</span><span class="p">)</span> -<span class="o">...</span> -<span class="n">Traceback</span> <span class="p">(</span><span class="n">most</span> <span class="n">recent</span> <span class="n">call</span> <span class="n">last</span><span class="p">):</span> - <span class="o">...</span> -<span class="ne">NameError</span><span class="p">:</span> <span class="n">_func_</span> <span class="ow">is</span> <span class="n">overridden</span> <span class="ow">in</span> -<span class="k">def</span> <span class="nf">f</span><span class="p">(</span><span class="n">_func_</span><span class="p">):</span> - <span class="k">return</span> <span class="n">_call_</span><span class="p">(</span><span class="n">_func_</span><span class="p">,</span> <span class="n">_func_</span><span class="p">)</span> -</pre></div> - -</div> -<p>Finally, the implementation is such that the decorated function contains -a <em>copy</em> of the original function dictionary -(<tt class="docutils literal">vars(decorated_f) is not vars(f)</tt>):</p> -<div class="codeblock python"> -<div class="highlight"><pre><span class="o">>>></span> <span class="k">def</span> <span class="nf">f</span><span class="p">():</span> <span class="k">pass</span> <span class="c"># the original function</span> -<span class="o">>>></span> <span class="n">f</span><span class="o">.</span><span class="n">attr1</span> <span class="o">=</span> <span class="s">"something"</span> <span class="c"># setting an attribute</span> -<span class="o">>>></span> <span class="n">f</span><span class="o">.</span><span class="n">attr2</span> <span class="o">=</span> <span class="s">"something else"</span> <span class="c"># setting another attribute</span> - -<span class="o">>>></span> <span class="n">traced_f</span> <span class="o">=</span> <span class="n">trace</span><span class="p">(</span><span class="n">f</span><span class="p">)</span> <span class="c"># the decorated function</span> - -<span class="o">>>></span> <span class="n">traced_f</span><span class="o">.</span><span class="n">attr1</span> -<span class="s">'something'</span> -<span class="o">>>></span> <span class="n">traced_f</span><span class="o">.</span><span class="n">attr2</span> <span class="o">=</span> <span class="s">"something different"</span> <span class="c"># setting attr</span> -<span class="o">>>></span> <span class="n">f</span><span class="o">.</span><span class="n">attr2</span> <span class="c"># the original attribute did not change</span> -<span class="s">'something else'</span> -</pre></div> - -</div> -</div> -<div class="section" id="compatibility-notes"> -<h1><a class="toc-backref" href="#id18">Compatibility notes</a></h1> -<p>Version 3.3 is the first version of the <tt class="docutils literal">decorator</tt> module to fully -support Python 3, including <a class="reference external" href="http://www.python.org/dev/peps/pep-3107/">function annotations</a>. Version 3.2 was the -first version to support Python 3 via the <tt class="docutils literal">2to3</tt> conversion tool -invoked in the build process by the <a class="reference external" href="http://packages.python.org/distribute/">distribute</a> project, the Python -3-compatible replacement of easy_install. The hard work (for me) has -been converting the documentation and the doctests. This has been -possible only after that <a class="reference external" href="http://docutils.sourceforge.net/">docutils</a> and <a class="reference external" href="http://pygments.org/">pygments</a> have been ported to -Python 3.</p> -<p>Version 3 of the <tt class="docutils literal">decorator</tt> module do not contain any backward -incompatible change, apart from the removal of the functions -<tt class="docutils literal">get_info</tt> and <tt class="docutils literal">new_wrapper</tt>, which have been deprecated for -years. <tt class="docutils literal">get_info</tt> has been removed since it was little used and -since it had to be changed anyway to work with Python 3.0; -<tt class="docutils literal">new_wrapper</tt> has been removed since it was useless: its major use -case (converting signature changing decorators to signature preserving -decorators) has been subsumed by <tt class="docutils literal">decorator_apply</tt>, whereas the other use -case can be managed with the <tt class="docutils literal">FunctionMaker</tt>.</p> -<p>There are a few changes in the documentation: I removed the -<tt class="docutils literal">decorator_factory</tt> example, which was confusing some of my users, -and I removed the part about exotic signatures in the Python 3 -documentation, since Python 3 does not support them.</p> -<p>Finally <tt class="docutils literal">decorator</tt> cannot be used as a class decorator and the -<a class="reference external" href="http://www.phyast.pitt.edu/~micheles/python/documentation.html#class-decorators-and-decorator-factories">functionality introduced in version 2.3</a> has been removed. That -means that in order to define decorator factories with classes you -need to define the <tt class="docutils literal">__call__</tt> method explicitly (no magic anymore). -All these changes should not cause any trouble, since they were -all rarely used features. Should you have any trouble, you can always -downgrade to the 2.3 version.</p> -<p>The examples shown here have been tested with Python 2.6. Python 2.4 -is also supported - of course the examples requiring the <tt class="docutils literal">with</tt> -statement will not work there. Python 2.5 works fine, but if you -run the examples in the interactive interpreter -you will notice a few differences since -<tt class="docutils literal">getargspec</tt> returns an <tt class="docutils literal">ArgSpec</tt> namedtuple instead of a regular -tuple. That means that running the file -<tt class="docutils literal">documentation.py</tt> under Python 2.5 will print a few errors, but -they are not serious.</p> -</div> -<div class="section" id="licence"> -<h1><a class="toc-backref" href="#id19">LICENCE</a></h1> -<p>Copyright (c) 2005-2012, Michele Simionato -All rights reserved.</p> -<p>Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are -met:</p> -<blockquote> -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.</blockquote> -<p>THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -"AS IS" 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.</p> -<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> diff --git a/documentation3.py b/documentation3.py index bd86cc6..0fc2c0c 100644 --- a/documentation3.py +++ b/documentation3.py @@ -24,7 +24,7 @@ believe the change is for the best, and that decorators are a great idea since: * decorators help reducing boilerplate code; -* decorators help separation of concerns; +* decorators help separation of concerns; * decorators enhance readability and maintenability; * decorators are explicit. @@ -47,8 +47,8 @@ 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 +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 subclasses: + *signature-preserving* decorators, i.e. callable objects taking a @@ -61,7 +61,7 @@ decorators in two subclasses: Signature-changing decorators have their use: for instance the builtin classes ``staticmethod`` and ``classmethod`` are in this -group, since they take functions and return descriptor objects which +group, since they take functions and return descriptor objects which are not functions, nor callables. However, signature-preserving decorators are more common and easier to @@ -69,8 +69,8 @@ reason about; in particular signature-preserving decorators can be 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 -can accept functions with any signature. A simple example will clarify +obvious, especially if one wants to define proper decorators that +can accept functions with any signature. A simple example will clarify the issue. Statement of the problem @@ -80,8 +80,8 @@ 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, +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 could be the following (notice that in general it is impossible to memoize correctly something @@ -95,9 +95,9 @@ been added in Python 2.5 expressly to simplify the definition of decorators ``__name__``, ``__doc__``, ``__module__`` and ``__dict__`` from the original function to the decorated function by hand). -.. _functools.update_wrapper: http://www.python.org/doc/2.5.2/lib/module-functools.html +.. _functools.update_wrapper: https://docs.python.org/3/library/functools.html#functools.update_wrapper -The implementation above works in the sense that the decorator +The implementation above works in the sense that the decorator can accept functions with generic signatures; unfortunately this implementation does *not* define a signature-preserving decorator, since in general ``memoize_uw`` returns a function with a @@ -118,14 +118,14 @@ keyword arguments: .. code-block:: python - >>> from inspect import getargspec + >>> from inspect import getargspec >>> print(getargspec(f1)) ArgSpec(args=[], varargs='args', keywords='kw', defaults=None) This means that introspection tools such as pydoc will give wrong informations about the signature of ``f1``. This is pretty bad: -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 +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: .. code-block:: python @@ -185,7 +185,7 @@ The signature of ``heavy_computation`` is the one you would expect: .. code-block:: python - >>> print(getargspec(heavy_computation)) + >>> print(getargspec(heavy_computation)) ArgSpec(args=[], varargs=None, keywords=None, defaults=None) A ``trace`` decorator @@ -218,21 +218,21 @@ and it that it has the correct signature: .. code-block:: python - >>> print(getargspec(f1)) + >>> print(getargspec(f1)) ArgSpec(args=['x'], varargs=None, keywords=None, defaults=None) The same decorator works with functions of any signature: .. code-block:: python - + >>> @trace ... def f(x, y=1, z=2, *args, **kw): ... pass >>> f(0, 3) calling f with args (0, 3, 2), {} - - >>> print(getargspec(f)) + + >>> print(getargspec(f)) ArgSpec(args=['x', 'y', 'z'], varargs='args', keywords='kw', defaults=(1, 2)) Function annotations @@ -241,7 +241,7 @@ Function annotations Python 3 introduced the concept of `function annotations`_,i.e. the ability to annotate the signature of a function with additional information, stored in a dictionary named ``__annotations__``. The decorator module, -starting from release 3.3, is able to understand and to preserve the +starting from release 3.3, is able to understand and to preserve the annotations. Here is an example: .. code-block:: python @@ -256,7 +256,7 @@ utility ``inspect.getfullargspec``, new in Python 3: .. code-block:: python - >>> from inspect import getfullargspec + >>> from inspect import getfullargspec >>> argspec = getfullargspec(f) >>> argspec.args ['x', 'y', 'z'] @@ -332,14 +332,14 @@ If you are using an old Python version (Python 2.4) the ------------------------------------------- Sometimes one has to deal with blocking resources, such as ``stdin``, and -sometimes it is best to have back a "busy" message than to block everything. +sometimes it is best to have back a "busy" message than to block everything. This behavior can be implemented with a suitable family of decorators, where the parameter is the busy message: $$blocking Functions decorated with ``blocking`` will return a busy message if -the resource is unavailable, and the intended result if the resource is +the resource is unavailable, and the intended result if the resource is available. For instance: .. code-block:: python @@ -349,18 +349,18 @@ available. For instance: ... time.sleep(3) # simulate a blocking resource ... return "some data" - >>> print(read_data()) # data is not available yet + >>> print(read_data()) # data is not available yet Please wait ... - >>> time.sleep(1) - >>> print(read_data()) # data is not available yet + >>> time.sleep(1) + >>> print(read_data()) # data is not available yet Please wait ... >>> time.sleep(1) - >>> print(read_data()) # data is not available yet + >>> print(read_data()) # data is not available yet Please wait ... - >>> time.sleep(1.1) # after 3.1 seconds, data is available + >>> time.sleep(1.1) # after 3.1 seconds, data is available >>> print(read_data()) some data @@ -371,11 +371,11 @@ 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 converted into decorators. +callable objects that can be converted into decorators. As an example, here will I show a decorator which is able to convert a blocking function into an asynchronous -function. The function, when called, +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 (of course the code here @@ -387,13 +387,13 @@ $$on_failure $$on_closing $$Async -The decorated function returns -the current execution thread, which can be stored and checked later, for +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 +(for instance a printer). Then the access to the writing function must be locked. Here is a minimalistic example: .. code-block:: python @@ -410,7 +410,7 @@ be locked. Here is a minimalistic example: ... datalist.append(data) ... # other operations not requiring a lock here -Each call to ``write`` will create a new writer thread, but there will +Each call to ``write`` will create a new writer thread, but there will be no synchronization problems since ``write`` is locked. .. code-block:: python @@ -432,8 +432,8 @@ contextmanager ------------------------------------- For a long time Python had in its standard library a ``contextmanager`` -decorator, able to convert generator functions into ``_GeneratorContextManager`` -factories. For instance if you write +decorator, able to convert generator functions into +``_GeneratorContextManager`` factories. For instance if you write .. code-block:: python @@ -446,7 +446,7 @@ factories. For instance if you write then ``before_after`` is a factory function returning -``_GeneratorContextManager`` objects which can be used with +``_GeneratorContextManager`` objects which can be used with the ``with`` statement: .. code-block:: python @@ -462,7 +462,7 @@ the ``with`` statement: Basically, it is as if the content of the ``with`` block was executed in the place of the ``yield`` expression in the generator function. -In Python 3.2 ``_GeneratorContextManager`` +In Python 3.2 ``_GeneratorContextManager`` objects were enhanced with a ``__call__`` method, so that they can be used as decorators as in this example: @@ -477,11 +477,11 @@ method, so that they can be used as decorators as in this example: hello AFTER -The ``ba`` decorator is basically inserting a ``with ba:`` +The ``ba`` decorator is basically inserting a ``with ba:`` block inside the function. -However there two issues: the first is that ``_GeneratorContextManager`` +However there two issues: the first is that ``_GeneratorContextManager`` objects are callable only in Python 3.2, so the previous example will break -in older versions of Python; the second is that +in older versions of Python; the second is that ``_GeneratorContextManager`` objects do not preserve the signature of the decorated functions: the decorated ``hello`` function here will have a generic signature ``hello(*args, **kwargs)`` but will break when @@ -489,7 +489,7 @@ called with more than zero arguments. For such reasons the decorator module, starting with release 3.4, offers a ``decorator.contextmanager`` decorator that solves both problems and works even in Python 2.5. The usage is the same and factories decorated with ``decorator.contextmanager`` -will returns instances of ``ContextManager``, a subclass of +will returns instances of ``ContextManager``, a subclass of ``contextlib._GeneratorContextManager`` with a ``__call__`` method acting as a signature-preserving decorator. @@ -556,7 +556,7 @@ with attributes ``args``, ``varargs``, the return values of the standard library function ``inspect.getargspec``. For each argument in the ``args`` (which is a list of strings containing the names of the mandatory arguments) an attribute ``arg0``, ``arg1``, -..., ``argN`` is also generated. Finally, there is a ``signature`` +..., ``argN`` is also generated. Finally, there is a ``signature`` attribute, a string with the signature of the original function. Notice that while I do not have plans @@ -619,8 +619,8 @@ 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 +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 ``decorator``. You can use a ``FunctionMaker`` to implement that functionality as follows: @@ -637,10 +637,10 @@ 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. -In order to give an example of usage of ``decorator_apply``, I will show a +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 -in the Python Cookbook, +in the Python Cookbook, http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/496691. $$TailRecursive @@ -660,7 +660,7 @@ $$factorial 24 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 +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 the following @@ -674,8 +674,8 @@ call). Caveats and limitations ------------------------------------------- -The first thing you should be aware of, it the fact that decorators -have a performance penalty. +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:: $ cat performance.sh @@ -684,7 +684,7 @@ The worse case is shown by the following example:: @decorator def do_nothing(func, *args, **kw): - return func(*args, **kw) + return func(*args, **kw) @do_nothing def f(): @@ -703,10 +703,10 @@ plain function is more than three times slower:: 1000000 loops, best of 3: 0.669 usec per loop 1000000 loops, best of 3: 0.181 usec per loop -It should be noted that a real life function would probably do +It should be noted that a real life function would probably do something more useful than ``f`` here, and therefore in real life the performance penalty could be completely negligible. As always, the -only way to know if there is +only way to know if there is a penalty in your specific use case is to measure it. You should be aware that decorators will make your tracebacks @@ -733,8 +733,8 @@ function is decorated the traceback will be longer: 1/0 ZeroDivisionError: ... -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``. +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``. This latter reference is due to the fact that internally the decorator module uses ``exec`` to generate the decorated function. Notice that ``exec`` is *not* responsibile for the performance penalty, since is the @@ -743,8 +743,8 @@ the decorated function is called. At present, there is no clean way to avoid ``exec``. 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. -That could happen in future versions of Python (see PEP 362_) and +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.2 it is impossible to change the function signature directly, therefore the ``decorator`` module is still useful. @@ -754,7 +754,7 @@ the module and releasing new versions. .. _362: http://www.python.org/dev/peps/pep-0362 In the present implementation, decorators generated by ``decorator`` -can only be used on user-defined Python functions or methods, not on generic +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. @@ -794,7 +794,8 @@ a *copy* of the original function dictionary Compatibility notes --------------------------------------------------------------- -Version 3.3 is the first version of the ``decorator`` module to fully +Version 3.4 fixes some bugs in the support of recent versions of Python 3. +Version 3.3 was the first version of the ``decorator`` module to fully support Python 3, including `function annotations`_. Version 3.2 was the first version to support Python 3 via the ``2to3`` conversion tool invoked in the build process by the distribute_ project, the Python @@ -813,7 +814,7 @@ case (converting signature changing decorators to signature preserving decorators) has been subsumed by ``decorator_apply``, whereas the other use case can be managed with the ``FunctionMaker``. -There are a few changes in the documentation: I removed the +There are a few changes in the documentation: I removed the ``decorator_factory`` example, which was confusing some of my users, and I removed the part about exotic signatures in the Python 3 documentation, since Python 3 does not support them. @@ -834,7 +835,7 @@ you will notice a few differences since ``getargspec`` returns an ``ArgSpec`` namedtuple instead of a regular tuple. That means that running the file ``documentation.py`` under Python 2.5 will print a few errors, but -they are not serious. +they are not serious. .. _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/ @@ -845,19 +846,19 @@ they are not serious. LICENCE --------------------------------------------- -Copyright (c) 2005-2012, Michele Simionato +Copyright (c) 2005-2015, Michele Simionato All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: - Redistributions of source code must retain the above copyright + 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. + distribution. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT @@ -872,12 +873,17 @@ 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. -If you use this software and you are happy with it, consider sending me a +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! """ from __future__ import with_statement -import sys, threading, time, functools, inspect, itertools +import sys +import threading +import time +import functools +import inspect +import itertools from decorator import * from functools import partial from setup import VERSION @@ -886,35 +892,42 @@ today = time.strftime('%Y-%m-%d') __doc__ = __doc__.replace('$VERSION', VERSION).replace('$DATE', today) + def decorator_apply(dec, func): """ - Decorate a function by preserving the signature even if dec + Decorate a function by preserving the signature even if dec is not a signature-preserving decorator. """ return FunctionMaker.create( func, 'return decorated(%(signature)s)', dict(decorated=dec(func)), __wrapped__=func) + def _trace(f, *args, **kw): kwstr = ', '.join('%r: %r' % (k, kw[k]) for k in sorted(kw)) print("calling %s with args %s, {%s}" % (f.__name__, args, kwstr)) return f(*args, **kw) + def trace(f): return decorator(_trace, f) -def on_success(result): # default implementation + +def on_success(result): # default implementation "Called on the result of the function" return result -def on_failure(exc_info): # default implementation + +def on_failure(exc_info): # default implementation "Called if the function fails" pass -def on_closing(): # default implementation + +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 @@ -934,9 +947,10 @@ class Async(object): def __call__(self, func, *args, **kw): try: counter = func.counter - except AttributeError: # instantiate the counter at the first call + except AttributeError: # instantiate the counter at the first call counter = func.counter = itertools.count(1) name = '%s-%s' % (func.__name__, next(counter)) + def func_wrapper(): try: result = func(*args, **kw) @@ -950,18 +964,23 @@ class Async(object): thread.start() return thread + def identity_dec(func): def wrapper(*args, **kw): return func(*args, **kw) return wrapper + @identity_dec -def example(): pass +def example(): + pass + def memoize_uw(func): func.cache = {} + def memoize(*args, **kw): - if kw: # frozenset is used to ensure hashability + if kw: # frozenset is used to ensure hashability key = args, frozenset(kw.iteritems()) else: key = args @@ -973,51 +992,61 @@ def memoize_uw(func): return result return functools.update_wrapper(memoize, func) + def _memoize(func, *args, **kw): - if kw: # frozenset is used to ensure hashability + if kw: # frozenset is used to ensure hashability key = args, frozenset(kw.iteritems()) else: key = args - cache = func.cache # attributed added by memoize + cache = func.cache # attributed added by memoize if key in cache: return cache[key] else: cache[key] = result = func(*args, **kw) return result + def memoize(f): f.cache = {} return decorator(_memoize, f) + def blocking(not_avail): def blocking(f, *args, **kw): - if not hasattr(f, "thread"): # no thread running - def set_result(): f.result = f(*args, **kw) + if not hasattr(f, "thread"): # no thread running + def set_result(): + f.result = f(*args, **kw) f.thread = threading.Thread(None, set_result) f.thread.start() return not_avail elif f.thread.isAlive(): return not_avail - else: # the thread is ended, return the stored result + else: # the thread is ended, return the stored result del f.thread return f.result return decorator(blocking) + class User(object): "Will just be able to see a page" + class PowerUser(User): "Will be able to add new pages too" + class Admin(PowerUser): "Will be able to delete pages too" + def get_userclass(): return User + class PermissionError(Exception): pass + def restricted(user_class): def restricted(func, *args, **kw): "Restrict access to a given class of users" @@ -1030,6 +1059,7 @@ def restricted(user_class): % (userclass.__name__, func.__name__)) return decorator(restricted) + class Action(object): """ >>> a = Action() @@ -1052,6 +1082,7 @@ class Action(object): def delete(self): pass + class TailRecursive(object): """ tail_recursive decorator based on Kay Schluehr's recipe @@ -1062,7 +1093,7 @@ class TailRecursive(object): def __init__(self, func): self.func = func self.firstcall = True - self.CONTINUE = object() # sentinel + self.CONTINUE = object() # sentinel def __call__(self, *args, **kwd): CONTINUE = self.CONTINUE @@ -1072,29 +1103,35 @@ class TailRecursive(object): try: while True: result = func(*args, **kwd) - if result is CONTINUE: # update arguments + if result is CONTINUE: # update arguments args, kwd = self.argskwd - else: # last call + else: # last call return result finally: self.firstcall = True - else: # return the arguments of the tail call + else: # return the arguments of the tail call self.argskwd = args, kwd return CONTINUE + def tail_recursive(func): return decorator_apply(TailRecursive, func) + @tail_recursive def factorial(n, acc=1): "The good old factorial" - if n == 0: return acc + if n == 0: + return acc return factorial(n-1, n*acc) -def fact(n): # this is not tail-recursive - if n == 0: return 1 + +def fact(n): # this is not tail-recursive + if n == 0: + return 1 return n * fact(n-1) + def a_test_for_pylons(): """ In version 3.1.0 decorator(caller) returned a nameless partial @@ -1109,15 +1146,17 @@ def a_test_for_pylons(): 'The good old factorial' """ + def test_kwonlydefaults(): """ >>> @trace ... def f(arg, defarg=1, *args, kwonly=2): pass ... - >>> f.__kwdefaults__ + >>> f.__kwdefaults__ {'kwonly': 2} """ + def test_kwonlyargs(): """ >>> @trace @@ -1129,6 +1168,7 @@ def test_kwonlyargs(): ('y', 'z') """ + def test_kwonly_no_args(): """# this was broken with decorator 3.3.3 >>> @trace @@ -1137,6 +1177,8 @@ def test_kwonly_no_args(): >>> f() calling f with args (), {} """ + + def test_kwonly_star_notation(): """ >>> @trace @@ -1146,13 +1188,15 @@ def test_kwonly_star_notation(): FullArgSpec(args=[], varargs=None, varkw='kw', defaults=None, kwonlyargs=['a'], kwonlydefaults={'a': 1}, annotations={}) """ + @contextmanager def before_after(before, after): print(before) yield print(after) -ba = before_after('BEFORE', 'AFTER') # ContextManager instance +ba = before_after('BEFORE', 'AFTER') # ContextManager instance + @ba def hello(user): @@ -1167,4 +1211,5 @@ def hello(user): print('hello %s' % user) if __name__ == '__main__': - import doctest; doctest.testmod() + import doctest + doctest.testmod() diff --git a/documentation3.rst b/documentation3.rst new file mode 100644 index 0000000..8cf41fe --- /dev/null +++ b/documentation3.rst @@ -0,0 +1,1056 @@ + +The ``decorator`` module +============================================================= + +:Author: Michele Simionato +:E-mail: michele.simionato@gmail.com +:Version: 3.4.1 (2015-03-16) +:Requires: Python 2.4+ +:Download page: http://pypi.python.org/pypi/decorator/3.4.1 +:Installation: ``easy_install decorator`` +:License: BSD license + +.. contents:: + +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 +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: + +* decorators help reducing boilerplate code; +* decorators help separation of concerns; +* decorators enhance readability and maintenability; +* 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 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. + +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 +------------------------------------ + +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 subclasses: + ++ *signature-preserving* decorators, i.e. callable objects taking a + function as input and returning a function *with the same + signature* as output; + ++ *signature-changing* decorators, i.e. decorators that change + the signature of their input function, or decorators returning + non-callable objects. + +Signature-changing decorators have their use: for instance the +builtin classes ``staticmethod`` and ``classmethod`` are in this +group, since they take functions and return descriptor objects which +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. + +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. + +Statement of the problem +------------------------------ + +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 could be the following (notice +that in general it is impossible to memoize correctly something +that depends on non-hashable arguments): + +.. code-block:: python + + def memoize_uw(func): + func.cache = {} + + def memoize(*args, **kw): + if kw: # frozenset is used to ensure hashability + key = args, frozenset(kw.iteritems()) + else: + key = args + cache = func.cache + if key in cache: + return cache[key] + else: + cache[key] = result = func(*args, **kw) + return result + return functools.update_wrapper(memoize, func) + + +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). + +.. _functools.update_wrapper: https://docs.python.org/3/library/functools.html#functools.update_wrapper + +The implementation above works in the sense that the decorator +can accept functions with generic signatures; unfortunately this +implementation does *not* define a signature-preserving decorator, since in +general ``memoize_uw`` returns a function with a +*different signature* from the original function. + +Consider for instance the following case: + +.. code-block:: python + + >>> @memoize_uw + ... 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: + +.. code-block:: python + + >>> from inspect import getargspec + >>> print(getargspec(f1)) + ArgSpec(args=[], varargs='args', keywords='kw', defaults=None) + +This means that introspection tools such as pydoc will give +wrong informations about the signature of ``f1``. This is pretty bad: +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: + +.. code-block:: python + + >>> f1(0, 1) + Traceback (most recent call last): + ... + TypeError: f1() takes exactly 1 positional 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`` function in +the ``decorator`` module is such a factory: + +.. code-block:: python + + >>> from decorator import decorator + +``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: + +.. code-block:: python + + def _memoize(func, *args, **kw): + if kw: # frozenset is used to ensure hashability + key = args, frozenset(kw.iteritems()) + else: + key = args + cache = func.cache # attributed added by memoize + if key in cache: + return cache[key] + else: + cache[key] = result = func(*args, **kw) + return result + + +At this point you can define your decorator as follows: + +.. code-block:: python + + def memoize(f): + f.cache = {} + return decorator(_memoize, f) + + +The difference with respect to the ``memoize_uw`` 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 to the caller function. + +Here is a test of usage: + +.. 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 second time it will be instantaneous + done + +The signature of ``heavy_computation`` is the one you would expect: + +.. code-block:: python + + >>> print(getargspec(heavy_computation)) + ArgSpec(args=[], varargs=None, keywords=None, defaults=None) + +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: + +.. code-block:: python + + def _trace(f, *args, **kw): + kwstr = ', '.join('%r: %r' % (k, kw[k]) for k in sorted(kw)) + print("calling %s with args %s, {%s}" % (f.__name__, args, kwstr)) + return f(*args, **kw) + + +.. code-block:: python + + def trace(f): + return decorator(_trace, f) + + +Here is an example of usage: + +.. code-block:: python + + >>> @trace + ... def f1(x): + ... pass + +It is immediate to verify that ``f1`` works + +.. code-block:: python + + >>> f1(0) + calling f1 with args (0,), {} + +and it that it has the correct signature: + +.. code-block:: python + + >>> print(getargspec(f1)) + ArgSpec(args=['x'], varargs=None, keywords=None, defaults=None) + +The same decorator works with functions of any signature: + +.. code-block:: python + + >>> @trace + ... def f(x, y=1, z=2, *args, **kw): + ... pass + + >>> f(0, 3) + calling f with args (0, 3, 2), {} + + >>> print(getargspec(f)) + ArgSpec(args=['x', 'y', 'z'], varargs='args', keywords='kw', defaults=(1, 2)) + +Function annotations +--------------------------------------------- + +Python 3 introduced the concept of `function annotations`_,i.e. the ability +to annotate the signature of a function with additional information, +stored in a dictionary named ``__annotations__``. The decorator module, +starting from release 3.3, is able to understand and to preserve the +annotations. Here is an example: + +.. code-block:: python + + >>> @trace + ... def f(x: 'the first argument', y: 'default argument'=1, z=2, + ... *args: 'varargs', **kw: 'kwargs'): + ... pass + +In order to introspect functions with annotations, one needs the +utility ``inspect.getfullargspec``, new in Python 3: + +.. code-block:: python + + >>> from inspect import getfullargspec + >>> argspec = getfullargspec(f) + >>> argspec.args + ['x', 'y', 'z'] + >>> argspec.varargs + 'args' + >>> argspec.varkw + 'kw' + >>> argspec.defaults + (1, 2) + >>> argspec.kwonlyargs + [] + >>> argspec.kwonlydefaults + +You can also check that the ``__annotations__`` dictionary is preserved: + +.. code-block:: python + + >>> f.__annotations__ == f.__wrapped__.__annotations__ + True + +Depending on the version of the decorator module, the two dictionaries can +be the same object or not: you cannot rely on object identity, but you can +rely on the content being the same. + +``decorator`` is a decorator +--------------------------------------------- + +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 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 + +.. code-block:: python + + >>> @decorator + ... def trace(f, *args, **kw): + ... kwstr = ', '.join('%r: %r' % (k, kw[k]) for k in sorted(kw)) + ... print("calling %s with args %s, {%s}" % (f.__name__, args, kwstr)) + ... return f(*args, **kw) + +and now ``trace`` will be a decorator. Actually ``trace`` is a ``partial`` +object which can be used as a decorator: + +.. code-block:: python + + >>> trace + <function trace at 0x...> + +Here is an example of usage: + +.. code-block:: python + + >>> @trace + ... def func(): pass + + >>> func() + calling func with args (), {} + +If you are using an old Python version (Python 2.4) the +``decorator`` module provides a poor man replacement for +``functools.partial``. + +``blocking`` +------------------------------------------- + +Sometimes one has to deal with blocking resources, such as ``stdin``, and +sometimes it is best to have back a "busy" message than to block everything. +This behavior can be implemented with a suitable family of decorators, +where the parameter is the busy message: + +.. code-block:: python + + def blocking(not_avail): + def blocking(f, *args, **kw): + if not hasattr(f, "thread"): # no thread running + def set_result(): + f.result = f(*args, **kw) + f.thread = threading.Thread(None, set_result) + f.thread.start() + return not_avail + elif f.thread.isAlive(): + return not_avail + else: # the thread is ended, return the stored result + del f.thread + return f.result + return decorator(blocking) + + +Functions decorated with ``blocking`` will return a busy message if +the resource is unavailable, and the intended result if the resource is +available. For instance: + +.. code-block:: python + + >>> @blocking("Please wait ...") + ... def read_data(): + ... time.sleep(3) # simulate a blocking resource + ... return "some data" + + >>> print(read_data()) # data is not available yet + Please wait ... + + >>> time.sleep(1) + >>> print(read_data()) # data is not available yet + Please wait ... + + >>> time.sleep(1) + >>> print(read_data()) # data is not available yet + Please wait ... + + >>> time.sleep(1.1) # after 3.1 seconds, data is available + >>> print(read_data()) + some data + +``async`` +-------------------------------------------- + +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 converted into decorators. + +As an example, here will 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 (of course the code here +is just an example, it is not a recommended way of doing multi-threaded +programming). The implementation is the following: + +.. code-block:: python + + def on_success(result): # default implementation + "Called on the result of the function" + return result + +.. code-block:: python + + def on_failure(exc_info): # default implementation + "Called if the function fails" + pass + +.. code-block:: python + + def on_closing(): # default implementation + "Called at the end, both in case of success and failure" + pass + +.. code-block:: python + + 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, on_success=on_success, + on_failure=on_failure, on_closing=on_closing): + self.threadfactory = threadfactory + self.on_success = on_success + self.on_failure = on_failure + self.on_closing = on_closing + + def __call__(self, func, *args, **kw): + try: + counter = func.counter + except AttributeError: # instantiate the counter at the first call + counter = func.counter = itertools.count(1) + name = '%s-%s' % (func.__name__, next(counter)) + + def func_wrapper(): + try: + result = func(*args, **kw) + except: + self.on_failure(sys.exc_info()) + else: + return self.on_success(result) + finally: + self.on_closing() + thread = self.threadfactory(None, func_wrapper, name) + thread.start() + return thread + + +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: + +.. code-block:: python + + >>> async = decorator(Async(threading.Thread)) + + >>> 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. + +.. code-block:: python + + >>> 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'] + +contextmanager +------------------------------------- + +For a long time Python had in its standard library a ``contextmanager`` +decorator, able to convert generator functions into +``_GeneratorContextManager`` factories. For instance if you write + +.. code-block:: python + + >>> from contextlib import contextmanager + >>> @contextmanager + ... def before_after(before, after): + ... print(before) + ... yield + ... print(after) + + +then ``before_after`` is a factory function returning +``_GeneratorContextManager`` objects which can be used with +the ``with`` statement: + +.. code-block:: python + + >>> ba = before_after('BEFORE', 'AFTER') + >>> type(ba) + <class 'contextlib._GeneratorContextManager'> + >>> with ba: + ... print('hello') + BEFORE + hello + AFTER + +Basically, it is as if the content of the ``with`` block was executed +in the place of the ``yield`` expression in the generator function. +In Python 3.2 ``_GeneratorContextManager`` +objects were enhanced with a ``__call__`` +method, so that they can be used as decorators as in this example: + +.. code-block:: python + + >>> @ba + ... def hello(): + ... print('hello') + ... + >>> hello() + BEFORE + hello + AFTER + +The ``ba`` decorator is basically inserting a ``with ba:`` +block inside the function. +However there two issues: the first is that ``_GeneratorContextManager`` +objects are callable only in Python 3.2, so the previous example will break +in older versions of Python; the second is that +``_GeneratorContextManager`` objects do not preserve the signature +of the decorated functions: the decorated ``hello`` function here will have +a generic signature ``hello(*args, **kwargs)`` but will break when +called with more than zero arguments. For such reasons the decorator +module, starting with release 3.4, offers a ``decorator.contextmanager`` +decorator that solves both problems and works even in Python 2.5. +The usage is the same and factories decorated with ``decorator.contextmanager`` +will returns instances of ``ContextManager``, a subclass of +``contextlib._GeneratorContextManager`` with a ``__call__`` method +acting as a signature-preserving decorator. + +The ``FunctionMaker`` class +--------------------------------------------------------------- + +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 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. You will see an example shortly, in +the implementation of a cool decorator utility (``decorator_apply``). + +``FunctionMaker`` provides a ``.create`` classmethod which +takes as input the name, signature, and body of the function +we want to generate as well as the execution environment +were the function is generated by ``exec``. Here is an example: + +.. code-block:: python + + >>> def f(*args, **kw): # a function with a generic signature + ... print(args, kw) + + >>> f1 = FunctionMaker.create('f1(a, b)', 'f(a, b)', dict(f=f)) + >>> f1(1,2) + (1, 2) {} + +It is important to notice that the function body is interpolated +before being executed, so be careful with the ``%`` sign! + +``FunctionMaker.create`` 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 generated function: + +.. code-block:: python + + >>> f1 = FunctionMaker.create( + ... 'f1(a, b)', 'f(a, b)', dict(f=f), addsource=True) + >>> print(f1.__source__) + def f1(a, b): + f(a, b) + <BLANKLINE> + +``FunctionMaker.create`` can take as first argument a string, +as in the examples before, or a function. This is the most common +usage, since typically you want to decorate a pre-existing +function. A framework author may want to use directly ``FunctionMaker.create`` +instead of ``decorator``, since it gives you direct access to the body +of the generated function. For instance, suppose you want to instrument +the ``__init__`` methods of a set of classes, by preserving their +signature (such use case is not made up; this is done in SQAlchemy +and in other frameworks). When the first argument of ``FunctionMaker.create`` +is a function, a ``FunctionMaker`` object is instantiated internally, +with attributes ``args``, ``varargs``, +``keywords`` and ``defaults`` which are the +the return values of the standard library function ``inspect.getargspec``. +For each argument in the ``args`` (which is a list of strings containing +the names of the mandatory arguments) an attribute ``arg0``, ``arg1``, +..., ``argN`` is also generated. Finally, there is a ``signature`` +attribute, a string with the signature of the original function. + +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. 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. + +Getting the source code +--------------------------------------------------- + +Internally ``FunctionMaker.create`` 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: + +.. code-block:: python + + def identity_dec(func): + def wrapper(*args, **kw): + return func(*args, **kw) + return wrapper + + +.. code-block:: python + + @identity_dec + def example(): pass + + >>> 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.7 and 3.1. +There is however a workaround. The decorator module adds an +attribute ``.__wrapped__`` 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(inspect.getsource(factorial.__wrapped__)) + @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 +upgrade third party decorators to signature-preserving decorators without +having to rewrite them in terms of ``decorator``. You can use a +``FunctionMaker`` to implement that functionality as follows: + +.. code-block:: python + + def decorator_apply(dec, func): + """ + Decorate a function by preserving the signature even if dec + is not a signature-preserving decorator. + """ + return FunctionMaker.create( + func, 'return decorated(%(signature)s)', + dict(decorated=dec(func)), __wrapped__=func) + + +``decorator_apply`` sets the attribute ``.__wrapped__`` 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 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. + +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 +in the Python Cookbook, +http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/496691. + +.. code-block:: python + + class TailRecursive(object): + """ + tail_recursive decorator based on Kay Schluehr's recipe + http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/496691 + with improvements by me and George Sakkis. + """ + + def __init__(self, func): + self.func = func + self.firstcall = True + self.CONTINUE = object() # sentinel + + def __call__(self, *args, **kwd): + CONTINUE = self.CONTINUE + if self.firstcall: + func = self.func + self.firstcall = False + try: + while True: + result = func(*args, **kwd) + if result is CONTINUE: # update arguments + args, kwd = self.argskwd + else: # last call + return result + finally: + self.firstcall = True + else: # return the arguments of the tail call + self.argskwd = args, kwd + return CONTINUE + + +Here the decorator is implemented as a class returning callable +objects. + +.. code-block:: python + + def tail_recursive(func): + return decorator_apply(TailRecursive, func) + + +Here is how you apply the upgraded decorator to the good old factorial: + +.. code-block:: python + + @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 + +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 the following + +.. code-block:: python + + def fact(n): # this is not tail-recursive + if n == 0: + return 1 + return n * fact(n-1) + + +(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). + +Caveats and limitations +------------------------------------------- + +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:: + + $ cat performance.sh + python3 -m timeit -s " + from decorator import decorator + + @decorator + def do_nothing(func, *args, **kw): + return func(*args, **kw) + + @do_nothing + def f(): + pass + " "f()" + + python3 -m timeit -s " + def f(): + pass + " "f()" + +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: 0.669 usec per loop + 1000000 loops, best of 3: 0.181 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 +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. + +You should be aware that decorators will make your tracebacks +longer and more difficult to understand. Consider this example: + +.. 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: + +.. code-block:: python + + >>> f() + Traceback (most recent call last): + ... + File "<string>", line 2, in f + File "<doctest __main__[22]>", line 4, in trace + return f(*args, **kw) + File "<doctest __main__[51]>", line 3, in f + 1/0 + ZeroDivisionError: ... + +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``. +This latter reference is due to the fact that internally the decorator +module uses ``exec`` to generate the decorated function. Notice that +``exec`` is *not* responsibile for the performance penalty, since is the +called *only once* at function decoration time, and not every time +the decorated function is called. + +At present, there is no clean way to avoid ``exec``. 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. +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.2 it is impossible to change the function signature +directly, therefore the ``decorator`` module is still useful. +Actually, this is one of the main reasons why I keep maintaining +the module and releasing new versions. + +.. _362: http://www.python.org/dev/peps/pep-0362 + +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. + +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``: + +.. 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 dictionary +(``vars(decorated_f) is not vars(f)``): + +.. code-block:: python + + >>> def f(): pass # the original function + >>> f.attr1 = "something" # setting an attribute + >>> f.attr2 = "something else" # setting another attribute + + >>> traced_f = trace(f) # the decorated function + + >>> 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.4 fixes some bugs in the support of recent versions of Python 3. +Version 3.3 was the first version of the ``decorator`` module to fully +support Python 3, including `function annotations`_. Version 3.2 was the +first version to support Python 3 via the ``2to3`` conversion tool +invoked in the build process by the distribute_ project, the Python +3-compatible replacement of easy_install. The hard work (for me) has +been converting the documentation and the doctests. This has been +possible only after that docutils_ and pygments_ have been ported to +Python 3. + +Version 3 of the ``decorator`` module do not contain any backward +incompatible change, apart from the removal of the functions +``get_info`` and ``new_wrapper``, which have been deprecated for +years. ``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 signature changing decorators to signature preserving +decorators) has been subsumed by ``decorator_apply``, whereas the other use +case can be managed with the ``FunctionMaker``. + +There are a few changes in the documentation: I removed the +``decorator_factory`` example, which was confusing some of my users, +and I removed the part about exotic signatures in the Python 3 +documentation, since Python 3 does not support them. + +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 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 any trouble, you can always +downgrade to the 2.3 version. + +The examples shown here have been tested with Python 2.6. Python 2.4 +is also supported - of course the examples requiring the ``with`` +statement will not work there. Python 2.5 works fine, but if you +run the examples in the interactive interpreter +you will notice a few differences since +``getargspec`` returns an ``ArgSpec`` namedtuple instead of a regular +tuple. That means that running the file +``documentation.py`` under Python 2.5 will print a few errors, but +they are not serious. + +.. _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/ +.. _distribute: http://packages.python.org/distribute/ +.. _docutils: http://docutils.sourceforge.net/ +.. _pygments: http://pygments.org/ + +LICENCE +--------------------------------------------- + +Copyright (c) 2005-2015, Michele Simionato +All rights reserved. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are +met: + + 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 +"AS IS" 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. + +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! @@ -4,6 +4,7 @@ except ImportError: from distutils.core import setup import os.path + def getversion(fname): """Get the __version__ reading the file: works both in Python 2.X and 3.X, whereas direct importing would break in Python 3.X with a syntax error""" @@ -19,13 +20,13 @@ if __name__ == '__main__': setup(name='decorator', version=VERSION, description='Better living through Python with decorators', - long_description=open('README.txt').read(), + long_description=open('README.rst').read(), author='Michele Simionato', author_email='michele.simionato@gmail.com', url='http://pypi.python.org/pypi/decorator', license="BSD License", - package_dir = {'': 'src'}, - py_modules = ['decorator'], + package_dir={'': 'src'}, + py_modules=['decorator'], keywords="decorators generic utility", platforms=["All"], classifiers=['Development Status :: 5 - Production/Stable', diff --git a/src/decorator.py b/src/decorator.py index e1187bd..07d99cb 100644 --- a/src/decorator.py +++ b/src/decorator.py @@ -1,4 +1,4 @@ -########################## LICENCE ############################### +# ######################### LICENCE ############################ # # Copyright (c) 2005-2012, Michele Simionato # All rights reserved. @@ -7,12 +7,12 @@ # modification, are permitted provided that the following conditions are # met: -# Redistributions of source code must retain the above copyright +# 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. +# distribution. # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS # "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT @@ -36,9 +36,13 @@ __version__ = '3.4.1' __all__ = ["decorator", "FunctionMaker", "contextmanager"] -import sys, re, inspect +import re +import sys +import inspect + if sys.version >= '3': from inspect import getfullargspec + def get_init(cls): return cls.__init__ else: @@ -49,16 +53,19 @@ else: inspect.getargspec(f) self.kwonlyargs = [] self.kwonlydefaults = None + def __iter__(self): yield self.args yield self.varargs yield self.varkw yield self.defaults + def get_init(cls): return cls.__init__.im_func DEF = re.compile('\s*def\s*([_\w][_\w\d]*)\s*\(') + # basic functionality class FunctionMaker(object): """ @@ -72,8 +79,8 @@ class FunctionMaker(object): if func: # func can be a class or a callable, but not an instance method self.name = func.__name__ - if self.name == '<lambda>': # small hack for lambda functions - self.name = '_lambda_' + if self.name == '<lambda>': # small hack for lambda functions + self.name = '_lambda_' self.doc = func.__doc__ self.module = func.__module__ if inspect.isfunction(func): @@ -84,18 +91,18 @@ class FunctionMaker(object): setattr(self, a, getattr(argspec, a)) for i, arg in enumerate(self.args): setattr(self, 'arg%d' % i, arg) - if sys.version < '3': # easy way - self.shortsignature = self.signature = \ + if sys.version < '3': # easy way + self.shortsignature = self.signature = ( inspect.formatargspec( - formatvalue=lambda val: "", *argspec)[1:-1] - else: # Python 3 way + formatvalue=lambda val: "", *argspec)[1:-1]) + else: # Python 3 way allargs = list(self.args) allshortargs = list(self.args) if self.varargs: allargs.append('*' + self.varargs) allshortargs.append('*' + self.varargs) elif self.kwonlyargs: - allargs.append('*') # single star syntax + allargs.append('*') # single star syntax for a in self.kwonlyargs: allargs.append('%s=None' % a) allshortargs.append('%s=%s' % (a, a)) @@ -137,19 +144,19 @@ class FunctionMaker(object): def make(self, src_templ, evaldict=None, addsource=False, **attrs): "Make a new function from a given template and update the signature" - src = src_templ % vars(self) # expand name and signature + src = src_templ % vars(self) # expand name and signature evaldict = evaldict or {} mo = DEF.match(src) if mo is None: raise SyntaxError('not a valid function template\n%s' % src) - name = mo.group(1) # extract the function name - names = set([name] + [arg.strip(' *') for arg in - self.shortsignature.split(',')]) + name = mo.group(1) # extract the function name + names = set([name] + [arg.strip(' *') for arg in + self.shortsignature.split(',')]) for n in names: if n in ('_func_', '_call_'): raise NameError('%s is overridden in\n%s' % (n, src)) - if not src.endswith('\n'): # add a newline just for safety - src += '\n' # this is needed in old versions of Python + if not src.endswith('\n'): # add a newline just for safety + src += '\n' # this is needed in old versions of Python try: code = compile(src, '<string>', 'single') # print >> sys.stderr, 'Compiling %s' % src @@ -169,42 +176,43 @@ class FunctionMaker(object): doc=None, module=None, addsource=True, **attrs): """ Create a function from the strings name, signature and body. - evaldict is the evaluation dictionary. If addsource is true an attribute - __source__ is added to the result. The attributes attrs are added, - if any. + evaldict is the evaluation dictionary. If addsource is true an + attribute __source__ is added to the result. The attributes attrs + are added, if any. """ - if isinstance(obj, str): # "name(signature)" + if isinstance(obj, str): # "name(signature)" name, rest = obj.strip().split('(', 1) - signature = rest[:-1] #strip a right parens + signature = rest[:-1] # strip a right parens func = None - else: # a function + else: # a function name = None signature = None func = obj self = cls(func, name, signature, defaults, doc, module) ibody = '\n'.join(' ' + line for line in body.splitlines()) - return self.make('def %(name)s(%(signature)s):\n' + ibody, - evaldict, addsource, **attrs) - + return self.make('def %(name)s(%(signature)s):\n' + ibody, + evaldict, addsource, **attrs) + + def decorator(caller, func=None): """ decorator(caller) converts a caller function into a decorator; decorator(caller, func) decorates a function using a caller. """ - if func is not None: # returns a decorated function + if func is not None: # returns a decorated function evaldict = func.func_globals.copy() evaldict['_call_'] = caller evaldict['_func_'] = func return FunctionMaker.create( func, "return _call_(_func_, %(shortsignature)s)", evaldict, __wrapped__=func) - else: # returns a decorator + else: # returns a decorator if inspect.isclass(caller): name = caller.__name__.lower() callerfunc = get_init(caller) doc = 'decorator(%s) converts functions/generators into ' \ 'factories of %s objects' % (caller.__name__, caller.__name__) - fun = getfullargspec(callerfunc).args[1] # second arg + fun = getfullargspec(callerfunc).args[1] # second arg elif inspect.isfunction(caller): if caller.__name__ == '<lambda>': name = '_lambda_' @@ -212,21 +220,22 @@ def decorator(caller, func=None): name = caller.__name__ callerfunc = caller doc = caller.__doc__ - fun = getfullargspec(callerfunc).args[0] # first arg - else: # assume caller is an object with a __call__ method + fun = getfullargspec(callerfunc).args[0] # first arg + else: # assume caller is an object with a __call__ method name = caller.__class__.__name__.lower() callerfunc = caller.__call__.im_func doc = caller.__call__.__doc__ - fun = getfullargspec(callerfunc).args[1] # second arg + fun = getfullargspec(callerfunc).args[1] # second arg evaldict = callerfunc.func_globals.copy() evaldict['_call_'] = caller evaldict['decorator'] = decorator return FunctionMaker.create( - '%s(%s)' % (name, fun), + '%s(%s)' % (name, fun), 'return decorator(_call_, %s)' % fun, evaldict, call=caller, doc=doc, module=caller.__module__) -######################### contextmanager ######################## + +# ####################### contextmanager ####################### # def __call__(self, func): 'Context manager decorator' @@ -234,17 +243,18 @@ def __call__(self, func): func, "with _self_: return _func_(%(shortsignature)s)", dict(_self_=self, _func_=func), __wrapped__=func) -try: # Python >= 3.2 +try: # Python >= 3.2 + + from contextlib import _GeneratorContextManager - from contextlib import _GeneratorContextManager class ContextManager(_GeneratorContextManager): - __call__=__call__ + __call__ = __call__ -except ImportError: # Python >= 2.5 +except ImportError: # Python >= 2.5 try: from contextlib import GeneratorContextManager - except ImportError: # Python 2.4 + except ImportError: # Python 2.4 class ContextManager(object): def __init__(self, g, *a, **k): raise RuntimeError( |