Merge branch 'devel'

14 files changed, 13365 insertions, 0 deletions

diff --git a/CHANGES.txt b/CHANGES.txt
new file mode 100644
index 0000000..bb093fa
--- /dev/null
+++ b/CHANGES.txt
@@ -0,0 +1,89 @@
+HISTORY
+----------
+
+3.4.0 Added the ability to use classes and generic callables as callers and
+     implemented a signature-preserving contexmanager decorator. Fixed a bug
+     with the signature f(**kw) in Python 3 and fixed a couple of doctests
+     broken by Python 3.3, both issues pointed out by Dominic Sacré (18/10/2012)
+3.3.3 Fixed a bug with kwonlyargs for Python 3, submitted by Chris
+     Ellison (23/04/2012)
+3.3.2 Fixed a bug with __kwdefaults__ for Python 3, submitted by Chris
+     Ellison (01/09/2011)
+3.3.1 Fixed a doctest broken for Python 3.2, as noted by
+     Arfrever Frehtes Taifersar Arahesis; changed the name of
+     the attribute ``undecorated`` to ``__wrapped__`` following the
+     Python 3.2 convention, as requested by Ram Rachum; added
+     the Python 3 classifier to setup.py (22/04/2011)
+3.3. Added support for function annotations (1/1/2011)
+3.2.1. Now the .func_globals of the decorated function are the same of
+     the undecorated function, as requested by Paul Ollis (28/12/2010)
+3.2. Added __version__ (thanks to Gregg Lind), removed functionality which 
+     has been deprecated for years, removed the confusing decorator_factory
+     example and added official support for Python 3 (requested by Claus Klein).
+     Moved the documentation from PyPI to googlecode (22/05/2010)
+3.1.2. Added attributes args, varargs, keywords and arg0, ..., argN
+     to FunctionMaker objects generated from a function; fixed another
+     Pylons-breaking bug signaled by Lawrence Oluyede (25/08/2009)
+3.1.1. Fixed a bug which was breaking Pylons, signaled by
+     Gabriel de Perthuis, and added a test for it. (18/08/2009)
+3.1. Added decorator.factory, an easy way to define families of decorators
+     (requested by various users, including David Laban). Refactored the
+     FunctionMaker class and added an easier to use .create classmethod.
+     Internally, functools.partial is used for Python >= 2.5 (16/08/2009)
+3.0.1. Improved the error message in case a bound/unbound method is passed
+     instead of a function and documented this case; that should make life
+     easier for users like Gustavo Nerea (16/02/2009)
+3.0. New major version introducing ``FunctionMaker`` and the two-argument
+     syntax for ``decorator``. Moreover, added support for getting the
+     source code. This version is Python 3.0 ready.
+     Major overhaul of the documentation, now hosted on 
+     http://packages.python.org/decorator (14/12/2008)
+2.3.2. Small optimization in the code for decorator factories. First version
+       with the code uploaded to PyPI (01/12/2008)
+2.3.1. Set the zipsafe flag to False, since I want my users to have the source,
+       not a zipped egg (25/07/2008)
+2.3.0. Added support for writing decorator factories with minimal effort
+     (feature requested by Matthew Wilson); implemented it by enhancing
+     'decorator' to a Python 2.6 class decorator (10/07/2008)
+2.2.0. Added a note on 'inspect.getsource' not working for decorated
+     functions; referenced PEP 326; highlighted the snippets in the 
+     documentation with pygments; slightly simplified the code (31/07/2007)
+2.1.0. Replaced the utility 'update_wrapper' with 'new_wrapper' and
+     updated the documentation accordingly; fixed and improved the 
+     doctester argument parsing, signaled by Sam Wyse (3/07/2007)
+2.0.1. Included the licence in the source code too; fixed a versioning
+     issue by adding the version number to the zip file and fixing
+     the link to it on the web page, thanks to Philip Jenvey (17/02/2007)
+2.0. Rewritten and simplified the implementation; broken compatibility
+     with previous versions (in minor ways); added the utility function
+     'update_wrapper' instead of 'newfunc' (13/01/2007)
+1.1. 'decorator' instances now have attributes __name__, __doc__,
+     __module__ and __dict__ coming from the associated caller function; 
+     included the licence into the documentation (02/12/2006)
+1.0. Added LICENCE.txt; added a setuptools-friendly setup.py script 
+     contributed by Luke Arno (10/08/2006)
+0.8.1. Minor fixes to the documentation (21/06/2006)
+0.8. Improved the documentation, added the 'caveats' section (16/06/2006)
+0.7.1. Improved the tail_recursive example (15/05/2006)
+0.7. Renamed 'copyfunc' into 'newfunc' and added the ability to copy
+     the signature from a model function;   improved '_decorator' to
+     set the '__module__' attribute too, with the intent of improving 
+     error messages; updated the documentation (10/05/2006)
+0.6. Changed decorator.__call__ so that the module somewhat works
+     even for Python 2.3 (but the signature-preserving feature is
+     lost) (20/12/2005)
+0.5.2. Minor changes to the documentation; improved 'getattr_' and
+       shortened 'locked' (28/06/2005)
+0.5.1. Minor corrections to the documentation (20/05/2005)
+0.5. Fixed a bug with out-of-the-mind signatures, added a check for reserved
+     names in the argument list and simplified the code (thanks to Duncan 
+     Booth) (19/05/2005)
+0.4.1. Fixed a typo in the documentation (thanks to Anthon van der Neut)
+     (17/05/2005)
+0.4. Added getinfo, some tests and improved the documentation (12/05/2005)
+0.3. Simplified copyfunc, renamed deferred to delayed and added the 
+     nonblocking example (10/05/2005)
+0.2. Added copyfunc, improved the multithreading examples, improved
+     the doctester program (09/05/2005)
+0.1.1. Added the license specification and two docstrings (06/05/2005)
+0.1. Initial release  (04/05/2005)
diff --git a/MANIFEST.in b/MANIFEST.in
new file mode 100644
index 0000000..e69de29
--- /dev/null
+++ b/MANIFEST.in
diff --git a/Makefile b/Makefile
new file mode 100644
index 0000000..a5c0b86
--- /dev/null
+++ b/Makefile
@@ -0,0 +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
+
+html: /tmp/documentation.rst /tmp/documentation3.rst
+	$(RST) /tmp/documentation.rst
+	$(RST) /tmp/documentation3.rst
+	rst2html README.txt 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 
diff --git a/README.txt b/README.txt
new file mode 100644
index 0000000..50b39c1
--- /dev/null
+++ b/README.txt
@@ -0,0 +1,80 @@
+Decorator module

+=================

+

+

+:Author: Michele Simionato

+:E-mail: michele.simionato@gmail.com

+:Requires: Python 2.4+

+:Download page: http://pypi.python.org/pypi/decorator

+:Installation: ``easy_install decorator``

+:License: BSD license

+

+Installation

+-------------

+

+If you are lazy, just perform

+

+$ easy_install decorator

+

+which will install just the module on your system. Notice that

+Python 3 requires the easy_install version of the distribute_ project.

+

+If you prefer to install the full distribution from source, including

+the documentation, download the tarball_, unpack it and run

+

+$ python setup.py install

+

+in the main directory, possibly as superuser.

+

+.. _tarball: http://pypi.python.org/pypi/decorator

+.. _distribute: http://packages.python.org/distribute/

+

+Testing

+--------

+

+For Python 2.5, 2.6, 2.7 run

+

+$ python documentation.py

+

+for Python 3.X run

+

+$ python documentation3.py

+

+You will see a few innocuous errors with Python 2.5, because some

+inner details such as the introduction of the ArgSpec namedtuple and

+Thread.__repr__ changed. You may safely ignore them. 

+

+You cannot run the tests in Python 2.4, since there is a test using

+the with statement, but the decorator module is expected to work

+anyway (it has been used in production with Python 2.4 for years). My

+plan is to keep supporting all Python versions >= 2.4 in the core

+module, but I will keep the documentation and the tests updated only

+for the latest Python versions in both the 2.X and 3.X branches.

+

+Finally, notice that you may run into trouble if in your system there

+is an older version of the decorator module; in such a case remove the

+old version.

+

+Documentation

+--------------

+

+There are various versions of the documentation:

+

+-  `HTML version (Python 2)`_ 

+-  `PDF version (Python 2)`_ 

+

+-  `HTML version (Python 3)`_ 

+-  `PDF version (Python 3)`_ 

+

+.. _HTML version (Python 2): http://micheles.googlecode.com/hg/decorator/documentation.html

+.. _PDF version (Python 2): http://micheles.googlecode.com/hg/decorator/documentation.pdf

+.. _HTML version (Python 3): http://micheles.googlecode.com/hg/decorator/documentation3.html

+.. _PDF version (Python 3): http://micheles.googlecode.com/hg/decorator/documentation3.pdf

+

+Repository

+---------------

+

+The project is hosted on GoogleCode as a Mercurial repository. You

+can look at the source here:

+

+ http://code.google.com/p/micheles/source/browse/#hg%2Fdecorator

diff --git a/documentation.html b/documentation.html
new file mode 100644
index 0000000..25a5709
--- /dev/null
+++ b/documentation.html
@@ -0,0 +1,1102 @@
+<?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&#64;gmail.com">michele.simionato&#64;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">&gt;&gt;&gt;</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">&gt;&gt;&gt;</span> <span class="kn">from</span> <span class="nn">inspect</span> <span class="kn">import</span> <span class="n">getargspec</span>
+<span class="o">&gt;&gt;&gt;</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">&#39;args&#39;</span><span class="p">,</span> <span class="n">keywords</span><span class="o">=</span><span class="s">&#39;kw&#39;</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">&gt;&gt;&gt;</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">&gt;&gt;&gt;</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">&gt;&gt;&gt;</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">&quot;done&quot;</span>
+
+<span class="o">&gt;&gt;&gt;</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">&gt;&gt;&gt;</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">&gt;&gt;&gt;</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">&quot;calling </span><span class="si">%s</span><span class="s"> with args </span><span class="si">%s</span><span class="s">, </span><span class="si">%s</span><span class="s">&quot;</span> <span class="o">%</span> <span class="p">(</span><span class="n">f</span><span class="o">.</span><span class="n">__name__</span><span class="p">,</span> <span class="n">args</span><span class="p">,</span> <span class="n">kw</span><span class="p">)</span>
+    <span class="k">return</span> <span class="n">f</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kw</span><span class="p">)</span>
+</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">&gt;&gt;&gt;</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">&gt;&gt;&gt;</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">&gt;&gt;&gt;</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">&#39;x&#39;</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">&gt;&gt;&gt;</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">&gt;&gt;&gt;</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">&gt;&gt;&gt;</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">&#39;x&#39;</span><span class="p">,</span> <span class="s">&#39;y&#39;</span><span class="p">,</span> <span class="s">&#39;z&#39;</span><span class="p">],</span> <span class="n">varargs</span><span class="o">=</span><span class="s">&#39;args&#39;</span><span class="p">,</span> <span class="n">keywords</span><span class="o">=</span><span class="s">&#39;kw&#39;</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">&gt;&gt;&gt;</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">&gt;&gt;&gt;</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">&#39;x&#39;</span><span class="p">,</span> <span class="s">&#39;y&#39;</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">&gt;&gt;&gt;</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">&gt;&gt;&gt;</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">&quot;calling </span><span class="si">%s</span><span class="s"> with args </span><span class="si">%s</span><span class="s">, </span><span class="si">%s</span><span class="s">&quot;</span> <span class="o">%</span> <span class="p">(</span><span class="n">f</span><span class="o">.</span><span class="n">func_name</span><span class="p">,</span> <span class="n">args</span><span class="p">,</span> <span class="n">kw</span><span class="p">)</span>
+<span class="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">&gt;&gt;&gt;</span> <span class="n">trace</span>
+<span class="o">&lt;</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">...&gt;</span>
+</pre></div>
+
+</div>
+<p>Here is an example of usage:</p>
+<div class="codeblock python">
+<div class="highlight"><pre><span class="o">&gt;&gt;&gt;</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">&gt;&gt;&gt;</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 &quot;busy&quot; 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">&quot;thread&quot;</span><span class="p">):</span> <span class="c"># no thread running</span>
+            <span class="k">def</span> <span class="nf">set_result</span><span class="p">():</span> <span class="n">f</span><span class="o">.</span><span class="n">result</span> <span class="o">=</span> <span class="n">f</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kw</span><span class="p">)</span>
+            <span class="n">f</span><span class="o">.</span><span class="n">thread</span> <span class="o">=</span> <span class="n">threading</span><span class="o">.</span><span class="n">Thread</span><span class="p">(</span><span class="bp">None</span><span class="p">,</span> <span class="n">set_result</span><span class="p">)</span>
+            <span class="n">f</span><span class="o">.</span><span class="n">thread</span><span class="o">.</span><span class="n">start</span><span class="p">()</span>
+            <span class="k">return</span> <span class="n">not_avail</span>
+        <span class="k">elif</span> <span class="n">f</span><span class="o">.</span><span class="n">thread</span><span class="o">.</span><span class="n">isAlive</span><span class="p">():</span>
+            <span class="k">return</span> <span class="n">not_avail</span>
+        <span class="k">else</span><span class="p">:</span> <span class="c"># the thread is ended, return the stored result</span>
+            <span class="k">del</span> <span class="n">f</span><span class="o">.</span><span class="n">thread</span>
+            <span class="k">return</span> <span class="n">f</span><span class="o">.</span><span class="n">result</span>
+    <span class="k">return</span> <span class="n">decorator</span><span class="p">(</span><span class="n">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">&gt;&gt;&gt;</span> <span class="nd">@blocking</span><span class="p">(</span><span class="s">&quot;Please wait ...&quot;</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">&quot;some data&quot;</span>
+
+<span class="o">&gt;&gt;&gt;</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">&gt;&gt;&gt;</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">&gt;&gt;&gt;</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">&gt;&gt;&gt;</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">&gt;&gt;&gt;</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">&gt;&gt;&gt;</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">&gt;&gt;&gt;</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">&quot;Called on the result of the function&quot;</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">&quot;Called if the function fails&quot;</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">&quot;Called at the end, both in case of success and failure&quot;</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">&quot;&quot;&quot;</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">    &quot;&quot;&quot;</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">&#39;</span><span class="si">%s</span><span class="s">-</span><span class="si">%s</span><span class="s">&#39;</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">&gt;&gt;&gt;</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">&gt;&gt;&gt;</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">&gt;&gt;&gt;</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">&gt;&gt;&gt;</span> <span class="n">write</span><span class="p">(</span><span class="s">&quot;data1&quot;</span><span class="p">)</span>
+<span class="o">&lt;</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">&gt;</span>
+
+<span class="o">&gt;&gt;&gt;</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">&gt;&gt;&gt;</span> <span class="n">write</span><span class="p">(</span><span class="s">&quot;data2&quot;</span><span class="p">)</span>
+<span class="o">&lt;</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">&gt;</span>
+
+<span class="o">&gt;&gt;&gt;</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">&gt;&gt;&gt;</span> <span class="k">print</span> <span class="n">datalist</span>
+<span class="p">[</span><span class="s">&#39;data1&#39;</span><span class="p">,</span> <span class="s">&#39;data2&#39;</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">&gt;&gt;&gt;</span> <span class="kn">from</span> <span class="nn">contextlib</span> <span class="kn">import</span> <span class="n">contextmanager</span>
+<span class="o">&gt;&gt;&gt;</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">&gt;&gt;&gt;</span> <span class="n">ba</span> <span class="o">=</span> <span class="n">before_after</span><span class="p">(</span><span class="s">&#39;BEFORE&#39;</span><span class="p">,</span> <span class="s">&#39;AFTER&#39;</span><span class="p">)</span>
+<span class="o">&gt;&gt;&gt;</span> <span class="nb">type</span><span class="p">(</span><span class="n">ba</span><span class="p">)</span>
+<span class="o">&lt;</span><span class="k">class</span> <span class="err">&#39;</span><span class="nc">contextlib</span><span class="o">.</span><span class="n">GeneratorContextManager</span><span class="s">&#39;&gt;</span>
+<span class="o">&gt;&gt;&gt;</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">&#39;hello&#39;</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">&gt;&gt;&gt;</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">&#39;hello&#39;</span>
+<span class="o">...</span>
+<span class="o">&gt;&gt;&gt;</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">&gt;&gt;&gt;</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">&gt;&gt;&gt;</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">&#39;f1(a, b)&#39;</span><span class="p">,</span> <span class="s">&#39;f(a, b)&#39;</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">&gt;&gt;&gt;</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">&gt;&gt;&gt;</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">&#39;f1(a, b)&#39;</span><span class="p">,</span> <span class="s">&#39;f(a, b)&#39;</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">&gt;&gt;&gt;</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">&lt;</span><span class="n">BLANKLINE</span><span class="o">&gt;</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">&gt;&gt;&gt;</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">&lt;</span><span class="n">BLANKLINE</span><span class="o">&gt;</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">&gt;&gt;&gt;</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">&quot;The good old factorial&quot;</span>
+    <span class="k">if</span> <span class="n">n</span> <span class="o">==</span> <span class="mi">0</span><span class="p">:</span> <span class="k">return</span> <span class="n">acc</span>
+    <span class="k">return</span> <span class="n">factorial</span><span class="p">(</span><span class="n">n</span><span class="o">-</span><span class="mi">1</span><span class="p">,</span> <span class="n">n</span><span class="o">*</span><span class="n">acc</span><span class="p">)</span>
+<span class="o">&lt;</span><span class="n">BLANKLINE</span><span class="o">&gt;</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">&quot;&quot;&quot;</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">    &quot;&quot;&quot;</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">&#39;return decorated(</span><span class="si">%(signature)s</span><span class="s">)&#39;</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">&quot;&quot;&quot;</span>
+<span class="sd">    tail_recursive decorator based on Kay Schluehr&#39;s recipe</span>
+<span class="sd">    http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/496691</span>
+<span class="sd">    with improvements by me and George Sakkis.</span>
+<span class="sd">    &quot;&quot;&quot;</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">&quot;The good old factorial&quot;</span>
+    <span class="k">if</span> <span class="n">n</span> <span class="o">==</span> <span class="mi">0</span><span class="p">:</span> <span class="k">return</span> <span class="n">acc</span>
+    <span class="k">return</span> <span class="n">factorial</span><span class="p">(</span><span class="n">n</span><span class="o">-</span><span class="mi">1</span><span class="p">,</span> <span class="n">n</span><span class="o">*</span><span class="n">acc</span><span class="p">)</span>
+</pre></div>
+
+</div>
+<div class="codeblock python">
+<div class="highlight"><pre><span class="o">&gt;&gt;&gt;</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 &quot;
+from decorator import decorator
+
+&#64;decorator
+def do_nothing(func, *args, **kw):
+    return func(*args, **kw)
+
+&#64;do_nothing
+def f():
+    pass
+&quot; &quot;f()&quot;
+
+python -m timeit -s &quot;
+def f():
+    pass
+&quot; &quot;f()&quot;
+</pre>
+<p>On my 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">&gt;&gt;&gt;</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">&gt;&gt;&gt;</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">&quot;&lt;string&gt;&quot;</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">&quot;&lt;doctest __main__[18]&gt;&quot;</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">&quot;&lt;doctest __main__[47]&gt;&quot;</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">&quot;&lt;string&gt;&quot;,</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">&gt;&gt;&gt;</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">&gt;&gt;&gt;</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">&gt;&gt;&gt;</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">&lt;</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">&gt;</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">&gt;&gt;&gt;</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">&lt;</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">...&gt;</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">&gt;&gt;&gt;</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">&gt;&gt;&gt;</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">&gt;&gt;&gt;</span> <span class="n">f</span><span class="o">.</span><span class="n">attr1</span> <span class="o">=</span> <span class="s">&quot;something&quot;</span> <span class="c"># setting an attribute</span>
+<span class="o">&gt;&gt;&gt;</span> <span class="n">f</span><span class="o">.</span><span class="n">attr2</span> <span class="o">=</span> <span class="s">&quot;something else&quot;</span> <span class="c"># setting another attribute</span>
+
+<span class="o">&gt;&gt;&gt;</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">&gt;&gt;&gt;</span> <span class="n">traced_f</span><span class="o">.</span><span class="n">attr1</span>
+<span class="s">&#39;something&#39;</span>
+<span class="o">&gt;&gt;&gt;</span> <span class="n">traced_f</span><span class="o">.</span><span class="n">attr2</span> <span class="o">=</span> <span class="s">&quot;something different&quot;</span> <span class="c"># setting attr</span>
+<span class="o">&gt;&gt;&gt;</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">&#39;something else&#39;</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
+&quot;AS IS&quot; AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
+INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
+BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
+OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
+TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
+USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
+DAMAGE.</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.pdf b/documentation.pdf
new file mode 100644
index 0000000..611972e
--- /dev/null
+++ b/documentation.pdf
@@ -0,0 +1,3952 @@
+%PDF-1.4

+%���� ReportLab Generated PDF document http://www.reportlab.com

+% 'BasicFonts': class PDFDictionary 

+1 0 obj

+% The standard fonts dictionary

+<< /F1 2 0 R

+ /F2 3 0 R

+ /F3 4 0 R

+ /F4 7 0 R

+ /F5 39 0 R

+ /F6 41 0 R >>

+endobj

+% 'F1': class PDFType1Font 

+2 0 obj

+% Font Helvetica

+<< /BaseFont /Helvetica

+ /Encoding /WinAnsiEncoding

+ /Name /F1

+ /Subtype /Type1

+ /Type /Font >>

+endobj

+% 'F2': class PDFType1Font 

+3 0 obj

+% Font Helvetica-Bold

+<< /BaseFont /Helvetica-Bold

+ /Encoding /WinAnsiEncoding

+ /Name /F2

+ /Subtype /Type1

+ /Type /Font >>

+endobj

+% 'F3': class PDFType1Font 

+4 0 obj

+% Font Courier-Bold

+<< /BaseFont /Courier-Bold

+ /Encoding /WinAnsiEncoding

+ /Name /F3

+ /Subtype /Type1

+ /Type /Font >>

+endobj

+% 'Annot.NUMBER1': class PDFDictionary 

+5 0 obj

+<< /A << /S /URI

+ /Type /Action

+ /URI (mailto:michele.simionato@gmail.com) >>

+ /Border [ 0

+ 0

+ 0 ]

+ /Rect [ 153.7323

+ 704.7736

+ 289.4623

+ 716.7736 ]

+ /Subtype /Link

+ /Type /Annot >>

+endobj

+% 'Annot.NUMBER2': class PDFDictionary 

+6 0 obj

+<< /A << /S /URI

+ /Type /Action

+ /URI (http://pypi.python.org/pypi/decorator/3.4.0) >>

+ /Border [ 0

+ 0

+ 0 ]

+ /Rect [ 153.7323

+ 659.7736

+ 526.5827

+ 671.7736 ]

+ /Subtype /Link

+ /Type /Annot >>

+endobj

+% 'F4': class PDFType1Font 

+7 0 obj

+% Font Courier

+<< /BaseFont /Courier

+ /Encoding /WinAnsiEncoding

+ /Name /F4

+ /Subtype /Type1

+ /Type /Font >>

+endobj

+% 'Annot.NUMBER3': class LinkAnnotation 

+8 0 obj

+<< /Border [ 0

+ 0

+ 0 ]

+ /Contents ()

+ /Dest [ 38 0 R

+ /XYZ

+ 62.69291

+ 293.0236

+ 0 ]

+ /Rect [ 62.69291

+ 560.7736

+ 121.0229

+ 572.7736 ]

+ /Subtype /Link

+ /Type /Annot >>

+endobj

+% 'Annot.NUMBER4': class LinkAnnotation 

+9 0 obj

+<< /Border [ 0

+ 0

+ 0 ]

+ /Contents ()

+ /Dest [ 38 0 R

+ /XYZ

+ 62.69291

+ 293.0236

+ 0 ]

+ /Rect [ 527.0227

+ 560.7736

+ 532.5827

+ 572.7736 ]

+ /Subtype /Link

+ /Type /Annot >>

+endobj

+% 'Annot.NUMBER5': class LinkAnnotation 

+10 0 obj

+<< /Border [ 0

+ 0

+ 0 ]

+ /Contents ()

+ /Dest [ 43 0 R

+ /XYZ

+ 62.69291

+ 675.0236

+ 0 ]

+ /Rect [ 62.69291

+ 542.7736

+ 114.3629

+ 554.7736 ]

+ /Subtype /Link

+ /Type /Annot >>

+endobj

+% 'Annot.NUMBER6': class LinkAnnotation 

+11 0 obj

+<< /Border [ 0

+ 0

+ 0 ]

+ /Contents ()

+ /Dest [ 43 0 R

+ /XYZ

+ 62.69291

+ 675.0236

+ 0 ]

+ /Rect [ 527.0227

+ 542.7736

+ 532.5827

+ 554.7736 ]

+ /Subtype /Link

+ /Type /Annot >>

+endobj

+% 'Annot.NUMBER7': class LinkAnnotation 

+12 0 obj

+<< /Border [ 0

+ 0

+ 0 ]

+ /Contents ()

+ /Dest [ 43 0 R

+ /XYZ

+ 62.69291

+ 438.0236

+ 0 ]

+ /Rect [ 62.69291

+ 524.7736

+ 183.2629

+ 536.7736 ]

+ /Subtype /Link

+ /Type /Annot >>

+endobj

+% 'Annot.NUMBER8': class LinkAnnotation 

+13 0 obj

+<< /Border [ 0

+ 0

+ 0 ]

+ /Contents ()

+ /Dest [ 43 0 R

+ /XYZ

+ 62.69291

+ 438.0236

+ 0 ]

+ /Rect [ 527.0227

+ 524.7736

+ 532.5827

+ 536.7736 ]

+ /Subtype /Link

+ /Type /Annot >>

+endobj

+% 'Annot.NUMBER9': class LinkAnnotation 

+14 0 obj

+<< /Border [ 0

+ 0

+ 0 ]

+ /Contents ()

+ /Dest [ 44 0 R

+ /XYZ

+ 62.69291

+ 427.4236

+ 0 ]

+ /Rect [ 62.69291

+ 506.7736

+ 122.1429

+ 518.7736 ]

+ /Subtype /Link

+ /Type /Annot >>

+endobj

+% 'Annot.NUMBER10': class LinkAnnotation 

+15 0 obj

+<< /Border [ 0

+ 0

+ 0 ]

+ /Contents ()

+ /Dest [ 44 0 R

+ /XYZ

+ 62.69291

+ 427.4236

+ 0 ]

+ /Rect [ 527.0227

+ 506.7736

+ 532.5827

+ 518.7736 ]

+ /Subtype /Link

+ /Type /Annot >>

+endobj

+% 'Annot.NUMBER11': class LinkAnnotation 

+16 0 obj

+<< /Border [ 0

+ 0

+ 0 ]

+ /Contents ()

+ /Dest [ 45 0 R

+ /XYZ

+ 62.69291

+ 435.4236

+ 0 ]

+ /Rect [ 62.69291

+ 488.7736

+ 154.8129

+ 500.7736 ]

+ /Subtype /Link

+ /Type /Annot >>

+endobj

+% 'Annot.NUMBER12': class LinkAnnotation 

+17 0 obj

+<< /Border [ 0

+ 0

+ 0 ]

+ /Contents ()

+ /Dest [ 45 0 R

+ /XYZ

+ 62.69291

+ 435.4236

+ 0 ]

+ /Rect [ 527.0227

+ 488.7736

+ 532.5827

+ 500.7736 ]

+ /Subtype /Link

+ /Type /Annot >>

+endobj

+% 'Annot.NUMBER13': class LinkAnnotation 

+18 0 obj

+<< /Border [ 0

+ 0

+ 0 ]

+ /Contents ()

+ /Dest [ 46 0 R

+ /XYZ

+ 62.69291

+ 398.778

+ 0 ]

+ /Rect [ 62.69291

+ 470.7736

+ 188.2729

+ 482.7736 ]

+ /Subtype /Link

+ /Type /Annot >>

+endobj

+% 'Annot.NUMBER14': class LinkAnnotation 

+19 0 obj

+<< /Border [ 0

+ 0

+ 0 ]

+ /Contents ()

+ /Dest [ 46 0 R

+ /XYZ

+ 62.69291

+ 398.778

+ 0 ]

+ /Rect [ 527.0227

+ 470.7736

+ 532.5827

+ 482.7736 ]

+ /Subtype /Link

+ /Type /Annot >>

+endobj

+% 'Annot.NUMBER15': class LinkAnnotation 

+20 0 obj

+<< /Border [ 0

+ 0

+ 0 ]

+ /Contents ()

+ /Dest [ 47 0 R

+ /XYZ

+ 62.69291

+ 647.8236

+ 0 ]

+ /Rect [ 62.69291

+ 452.7736

+ 110.6929

+ 464.7736 ]

+ /Subtype /Link

+ /Type /Annot >>

+endobj

+% 'Annot.NUMBER16': class LinkAnnotation 

+21 0 obj

+<< /Border [ 0

+ 0

+ 0 ]

+ /Contents ()

+ /Dest [ 47 0 R

+ /XYZ

+ 62.69291

+ 647.8236

+ 0 ]

+ /Rect [ 527.0227

+ 452.7736

+ 532.5827

+ 464.7736 ]

+ /Subtype /Link

+ /Type /Annot >>

+endobj

+% 'Annot.NUMBER17': class LinkAnnotation 

+22 0 obj

+<< /Border [ 0

+ 0

+ 0 ]

+ /Contents ()

+ /Dest [ 48 0 R

+ /XYZ

+ 62.69291

+ 765.0236

+ 0 ]

+ /Rect [ 62.69291

+ 434.7736

+ 92.69291

+ 446.7736 ]

+ /Subtype /Link

+ /Type /Annot >>

+endobj

+% 'Annot.NUMBER18': class LinkAnnotation 

+23 0 obj

+<< /Border [ 0

+ 0

+ 0 ]

+ /Contents ()

+ /Dest [ 48 0 R

+ /XYZ

+ 62.69291

+ 765.0236

+ 0 ]

+ /Rect [ 527.0227

+ 434.7736

+ 532.5827

+ 446.7736 ]

+ /Subtype /Link

+ /Type /Annot >>

+endobj

+% 'Annot.NUMBER19': class LinkAnnotation 

+24 0 obj

+<< /Border [ 0

+ 0

+ 0 ]

+ /Contents ()

+ /Dest [ 49 0 R

+ /XYZ

+ 62.69291

+ 267.4236

+ 0 ]

+ /Rect [ 62.69291

+ 416.7736

+ 139.9329

+ 428.7736 ]

+ /Subtype /Link

+ /Type /Annot >>

+endobj

+% 'Annot.NUMBER20': class LinkAnnotation 

+25 0 obj

+<< /Border [ 0

+ 0

+ 0 ]

+ /Contents ()

+ /Dest [ 49 0 R

+ /XYZ

+ 62.69291

+ 267.4236

+ 0 ]

+ /Rect [ 527.0227

+ 416.7736

+ 532.5827

+ 428.7736 ]

+ /Subtype /Link

+ /Type /Annot >>

+endobj

+% 'Annot.NUMBER21': class LinkAnnotation 

+26 0 obj

+<< /Border [ 0

+ 0

+ 0 ]

+ /Contents ()

+ /Dest [ 50 0 R

+ /XYZ

+ 62.69291

+ 354.6236

+ 0 ]

+ /Rect [ 62.69291

+ 398.7736

+ 192.2729

+ 410.7736 ]

+ /Subtype /Link

+ /Type /Annot >>

+endobj

+% 'Annot.NUMBER22': class LinkAnnotation 

+27 0 obj

+<< /Border [ 0

+ 0

+ 0 ]

+ /Contents ()

+ /Dest [ 50 0 R

+ /XYZ

+ 62.69291

+ 354.6236

+ 0 ]

+ /Rect [ 527.0227

+ 398.7736

+ 532.5827

+ 410.7736 ]

+ /Subtype /Link

+ /Type /Annot >>

+endobj

+% 'Annot.NUMBER23': class LinkAnnotation 

+28 0 obj

+<< /Border [ 0

+ 0

+ 0 ]

+ /Contents ()

+ /Dest [ 51 0 R

+ /XYZ

+ 62.69291

+ 363.8236

+ 0 ]

+ /Rect [ 62.69291

+ 380.7736

+ 177.1629

+ 392.7736 ]

+ /Subtype /Link

+ /Type /Annot >>

+endobj

+% 'Annot.NUMBER24': class LinkAnnotation 

+29 0 obj

+<< /Border [ 0

+ 0

+ 0 ]

+ /Contents ()

+ /Dest [ 51 0 R

+ /XYZ

+ 62.69291

+ 363.8236

+ 0 ]

+ /Rect [ 521.4627

+ 380.7736

+ 532.5827

+ 392.7736 ]

+ /Subtype /Link

+ /Type /Annot >>

+endobj

+% 'Annot.NUMBER25': class LinkAnnotation 

+30 0 obj

+<< /Border [ 0

+ 0

+ 0 ]

+ /Contents ()

+ /Dest [ 54 0 R

+ /XYZ

+ 62.69291

+ 599.8236

+ 0 ]

+ /Rect [ 62.69291

+ 362.7736

+ 228.2829

+ 374.7736 ]

+ /Subtype /Link

+ /Type /Annot >>

+endobj

+% 'Annot.NUMBER26': class LinkAnnotation 

+31 0 obj

+<< /Border [ 0

+ 0

+ 0 ]

+ /Contents ()

+ /Dest [ 54 0 R

+ /XYZ

+ 62.69291

+ 599.8236

+ 0 ]

+ /Rect [ 521.4627

+ 362.7736

+ 532.5827

+ 374.7736 ]

+ /Subtype /Link

+ /Type /Annot >>

+endobj

+% 'Annot.NUMBER27': class LinkAnnotation 

+32 0 obj

+<< /Border [ 0

+ 0

+ 0 ]

+ /Contents ()

+ /Dest [ 55 0 R

+ /XYZ

+ 62.69291

+ 215.0236

+ 0 ]

+ /Rect [ 62.69291

+ 344.7736

+ 174.3929

+ 356.7736 ]

+ /Subtype /Link

+ /Type /Annot >>

+endobj

+% 'Annot.NUMBER28': class LinkAnnotation 

+33 0 obj

+<< /Border [ 0

+ 0

+ 0 ]

+ /Contents ()

+ /Dest [ 55 0 R

+ /XYZ

+ 62.69291

+ 215.0236

+ 0 ]

+ /Rect [ 521.4627

+ 344.7736

+ 532.5827

+ 356.7736 ]

+ /Subtype /Link

+ /Type /Annot >>

+endobj

+% 'Annot.NUMBER29': class LinkAnnotation 

+34 0 obj

+<< /Border [ 0

+ 0

+ 0 ]

+ /Contents ()

+ /Dest [ 65 0 R

+ /XYZ

+ 62.69291

+ 765.0236

+ 0 ]

+ /Rect [ 62.69291

+ 326.7736

+ 155.4829

+ 338.7736 ]

+ /Subtype /Link

+ /Type /Annot >>

+endobj

+% 'Annot.NUMBER30': class LinkAnnotation 

+35 0 obj

+<< /Border [ 0

+ 0

+ 0 ]

+ /Contents ()

+ /Dest [ 65 0 R

+ /XYZ

+ 62.69291

+ 765.0236

+ 0 ]

+ /Rect [ 521.4627

+ 326.7736

+ 532.5827

+ 338.7736 ]

+ /Subtype /Link

+ /Type /Annot >>

+endobj

+% 'Annot.NUMBER31': class LinkAnnotation 

+36 0 obj

+<< /Border [ 0

+ 0

+ 0 ]

+ /Contents ()

+ /Dest [ 65 0 R

+ /XYZ

+ 62.69291

+ 414.0236

+ 0 ]

+ /Rect [ 62.69291

+ 308.7736

+ 106.5829

+ 320.7736 ]

+ /Subtype /Link

+ /Type /Annot >>

+endobj

+% 'Annot.NUMBER32': class LinkAnnotation 

+37 0 obj

+<< /Border [ 0

+ 0

+ 0 ]

+ /Contents ()

+ /Dest [ 65 0 R

+ /XYZ

+ 62.69291

+ 414.0236

+ 0 ]

+ /Rect [ 521.4627

+ 308.7736

+ 532.5827

+ 320.7736 ]

+ /Subtype /Link

+ /Type /Annot >>

+endobj

+% 'Page1': class PDFPage 

+38 0 obj

+% Page dictionary

+<< /Annots [ 5 0 R

+ 6 0 R

+ 8 0 R

+ 9 0 R

+ 10 0 R

+ 11 0 R

+ 12 0 R

+ 13 0 R

+ 14 0 R

+ 15 0 R

+ 16 0 R

+ 17 0 R

+ 18 0 R

+ 19 0 R

+ 20 0 R

+ 21 0 R

+ 22 0 R

+ 23 0 R

+ 24 0 R

+ 25 0 R

+ 26 0 R

+ 27 0 R

+ 28 0 R

+ 29 0 R

+ 30 0 R

+ 31 0 R

+ 32 0 R

+ 33 0 R

+ 34 0 R

+ 35 0 R

+ 36 0 R

+ 37 0 R ]

+ /Contents 85 0 R

+ /MediaBox [ 0

+ 0

+ 595.2756

+ 841.8898 ]

+ /Parent 84 0 R

+ /Resources << /Font 1 0 R

+ /ProcSet [ /PDF

+ /Text

+ /ImageB

+ /ImageC

+ /ImageI ] >>

+ /Rotate 0

+ /Trans <<  >>

+ /Type /Page >>

+endobj

+% 'F5': class PDFType1Font 

+39 0 obj

+% Font Helvetica-Oblique

+<< /BaseFont /Helvetica-Oblique

+ /Encoding /WinAnsiEncoding

+ /Name /F5

+ /Subtype /Type1

+ /Type /Font >>

+endobj

+% 'Annot.NUMBER33': class PDFDictionary 

+40 0 obj

+<< /A << /S /URI

+ /Type /Action

+ /URI (http://www.python.org/moin/PythonDecoratorLibrary) >>

+ /Border [ 0

+ 0

+ 0 ]

+ /Rect [ 219.6428

+ 363.7736

+ 449.1728

+ 375.7736 ]

+ /Subtype /Link

+ /Type /Annot >>

+endobj

+% 'F6': class PDFType1Font 

+41 0 obj

+% Font Courier-Oblique

+<< /BaseFont /Courier-Oblique

+ /Encoding /WinAnsiEncoding

+ /Name /F6

+ /Subtype /Type1

+ /Type /Font >>

+endobj

+% 'Annot.NUMBER34': class PDFDictionary 

+42 0 obj

+<< /A << /S /URI

+ /Type /Action

+ /URI (http://www.python.org/doc/2.5.2/lib/module-functools.html) >>

+ /Border [ 0

+ 0

+ 0 ]

+ /Rect [ 151.0486

+ 130.5736

+ 270.69

+ 142.5736 ]

+ /Subtype /Link

+ /Type /Annot >>

+endobj

+% 'Page2': class PDFPage 

+43 0 obj

+% Page dictionary

+<< /Annots [ 40 0 R

+ 42 0 R ]

+ /Contents 86 0 R

+ /MediaBox [ 0

+ 0

+ 595.2756

+ 841.8898 ]

+ /Parent 84 0 R

+ /Resources << /Font 1 0 R

+ /ProcSet [ /PDF

+ /Text

+ /ImageB

+ /ImageC

+ /ImageI ] >>

+ /Rotate 0

+ /Trans <<  >>

+ /Type /Page >>

+endobj

+% 'Page3': class PDFPage 

+44 0 obj

+% Page dictionary

+<< /Contents 87 0 R

+ /MediaBox [ 0

+ 0

+ 595.2756

+ 841.8898 ]

+ /Parent 84 0 R

+ /Resources << /Font 1 0 R

+ /ProcSet [ /PDF

+ /Text

+ /ImageB

+ /ImageC

+ /ImageI ] >>

+ /Rotate 0

+ /Trans <<  >>

+ /Type /Page >>

+endobj

+% 'Page4': class PDFPage 

+45 0 obj

+% Page dictionary

+<< /Contents 88 0 R

+ /MediaBox [ 0

+ 0

+ 595.2756

+ 841.8898 ]

+ /Parent 84 0 R

+ /Resources << /Font 1 0 R

+ /ProcSet [ /PDF

+ /Text

+ /ImageB

+ /ImageC

+ /ImageI ] >>

+ /Rotate 0

+ /Trans <<  >>

+ /Type /Page >>

+endobj

+% 'Page5': class PDFPage 

+46 0 obj

+% Page dictionary

+<< /Contents 89 0 R

+ /MediaBox [ 0

+ 0

+ 595.2756

+ 841.8898 ]

+ /Parent 84 0 R

+ /Resources << /Font 1 0 R

+ /ProcSet [ /PDF

+ /Text

+ /ImageB

+ /ImageC

+ /ImageI ] >>

+ /Rotate 0

+ /Trans <<  >>

+ /Type /Page >>

+endobj

+% 'Page6': class PDFPage 

+47 0 obj

+% Page dictionary

+<< /Contents 90 0 R

+ /MediaBox [ 0

+ 0

+ 595.2756

+ 841.8898 ]

+ /Parent 84 0 R

+ /Resources << /Font 1 0 R

+ /ProcSet [ /PDF

+ /Text

+ /ImageB

+ /ImageC

+ /ImageI ] >>

+ /Rotate 0

+ /Trans <<  >>

+ /Type /Page >>

+endobj

+% 'Page7': class PDFPage 

+48 0 obj

+% Page dictionary

+<< /Contents 91 0 R

+ /MediaBox [ 0

+ 0

+ 595.2756

+ 841.8898 ]

+ /Parent 84 0 R

+ /Resources << /Font 1 0 R

+ /ProcSet [ /PDF

+ /Text

+ /ImageB

+ /ImageC

+ /ImageI ] >>

+ /Rotate 0

+ /Trans <<  >>

+ /Type /Page >>

+endobj

+% 'Page8': class PDFPage 

+49 0 obj

+% Page dictionary

+<< /Contents 92 0 R

+ /MediaBox [ 0

+ 0

+ 595.2756

+ 841.8898 ]

+ /Parent 84 0 R

+ /Resources << /Font 1 0 R

+ /ProcSet [ /PDF

+ /Text

+ /ImageB

+ /ImageC

+ /ImageI ] >>

+ /Rotate 0

+ /Trans <<  >>

+ /Type /Page >>

+endobj

+% 'Page9': class PDFPage 

+50 0 obj

+% Page dictionary

+<< /Contents 93 0 R

+ /MediaBox [ 0

+ 0

+ 595.2756

+ 841.8898 ]

+ /Parent 84 0 R

+ /Resources << /Font 1 0 R

+ /ProcSet [ /PDF

+ /Text

+ /ImageB

+ /ImageC

+ /ImageI ] >>

+ /Rotate 0

+ /Trans <<  >>

+ /Type /Page >>

+endobj

+% 'Page10': class PDFPage 

+51 0 obj

+% Page dictionary

+<< /Contents 94 0 R

+ /MediaBox [ 0

+ 0

+ 595.2756

+ 841.8898 ]

+ /Parent 84 0 R

+ /Resources << /Font 1 0 R

+ /ProcSet [ /PDF

+ /Text

+ /ImageB

+ /ImageC

+ /ImageI ] >>

+ /Rotate 0

+ /Trans <<  >>

+ /Type /Page >>

+endobj

+% 'Annot.NUMBER35': class PDFDictionary 

+52 0 obj

+<< /A << /S /URI

+ /Type /Action

+ /URI (http://bugs.python.org/issue1764286) >>

+ /Border [ 0

+ 0

+ 0 ]

+ /Rect [ 137.6966

+ 753.7736

+ 180.8679

+ 765.7736 ]

+ /Subtype /Link

+ /Type /Annot >>

+endobj

+% 'Annot.NUMBER36': class PDFDictionary 

+53 0 obj

+<< /A << /S /URI

+ /Type /Action

+ /URI (http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/496691) >>

+ /Border [ 0

+ 0

+ 0 ]

+ /Rect [ 62.69291

+ 280.3736

+ 363.4029

+ 292.3736 ]

+ /Subtype /Link

+ /Type /Annot >>

+endobj

+% 'Page11': class PDFPage 

+54 0 obj

+% Page dictionary

+<< /Annots [ 52 0 R

+ 53 0 R ]

+ /Contents 95 0 R

+ /MediaBox [ 0

+ 0

+ 595.2756

+ 841.8898 ]

+ /Parent 84 0 R

+ /Resources << /Font 1 0 R

+ /ProcSet [ /PDF

+ /Text

+ /ImageB

+ /ImageC

+ /ImageI ] >>

+ /Rotate 0

+ /Trans <<  >>

+ /Type /Page >>

+endobj

+% 'Page12': class PDFPage 

+55 0 obj

+% Page dictionary

+<< /Contents 96 0 R

+ /MediaBox [ 0

+ 0

+ 595.2756

+ 841.8898 ]

+ /Parent 84 0 R

+ /Resources << /Font 1 0 R

+ /ProcSet [ /PDF

+ /Text

+ /ImageB

+ /ImageC

+ /ImageI ] >>

+ /Rotate 0

+ /Trans <<  >>

+ /Type /Page >>

+endobj

+% 'Annot.NUMBER37': class PDFDictionary 

+56 0 obj

+<< /A << /S /URI

+ /Type /Action

+ /URI (http://www.python.org/dev/peps/pep-0362) >>

+ /Border [ 0

+ 0

+ 0 ]

+ /Rect [ 301.1597

+ 116.9736

+ 317.8397

+ 128.9736 ]

+ /Subtype /Link

+ /Type /Annot >>

+endobj

+% 'Page13': class PDFPage 

+57 0 obj

+% Page dictionary

+<< /Annots [ 56 0 R ]

+ /Contents 97 0 R

+ /MediaBox [ 0

+ 0

+ 595.2756

+ 841.8898 ]

+ /Parent 84 0 R

+ /Resources << /Font 1 0 R

+ /ProcSet [ /PDF

+ /Text

+ /ImageB

+ /ImageC

+ /ImageI ] >>

+ /Rotate 0

+ /Trans <<  >>

+ /Type /Page >>

+endobj

+% 'Page14': class PDFPage 

+58 0 obj

+% Page dictionary

+<< /Contents 98 0 R

+ /MediaBox [ 0

+ 0

+ 595.2756

+ 841.8898 ]

+ /Parent 84 0 R

+ /Resources << /Font 1 0 R

+ /ProcSet [ /PDF

+ /Text

+ /ImageB

+ /ImageC

+ /ImageI ] >>

+ /Rotate 0

+ /Trans <<  >>

+ /Type /Page >>

+endobj

+% 'Annot.NUMBER38': class PDFDictionary 

+59 0 obj

+<< /A << /S /URI

+ /Type /Action

+ /URI (http://www.python.org/dev/peps/pep-3107/) >>

+ /Border [ 0

+ 0

+ 0 ]

+ /Rect [ 497.5627

+ 726.7736

+ 531.1777

+ 738.7736 ]

+ /Subtype /Link

+ /Type /Annot >>

+endobj

+% 'Annot.NUMBER39': class PDFDictionary 

+60 0 obj

+<< /A << /S /URI

+ /Type /Action

+ /URI (http://www.python.org/dev/peps/pep-3107/) >>

+ /Border [ 0

+ 0

+ 0 ]

+ /Rect [ 62.69291

+ 714.7736

+ 114.3929

+ 726.7736 ]

+ /Subtype /Link

+ /Type /Annot >>

+endobj

+% 'Annot.NUMBER40': class PDFDictionary 

+61 0 obj

+<< /A << /S /URI

+ /Type /Action

+ /URI (http://packages.python.org/distribute/) >>

+ /Border [ 0

+ 0

+ 0 ]

+ /Rect [ 172.9507

+ 702.7736

+ 216.6742

+ 714.7736 ]

+ /Subtype /Link

+ /Type /Annot >>

+endobj

+% 'Annot.NUMBER41': class PDFDictionary 

+62 0 obj

+<< /A << /S /URI

+ /Type /Action

+ /URI (http://docutils.sourceforge.net/) >>

+ /Border [ 0

+ 0

+ 0 ]

+ /Rect [ 82.15291

+ 678.7736

+ 118.8329

+ 690.7736 ]

+ /Subtype /Link

+ /Type /Annot >>

+endobj

+% 'Annot.NUMBER42': class PDFDictionary 

+63 0 obj

+<< /A << /S /URI

+ /Type /Action

+ /URI (http://pygments.org/) >>

+ /Border [ 0

+ 0

+ 0 ]

+ /Rect [ 138.2929

+ 678.7736

+ 184.4229

+ 690.7736 ]

+ /Subtype /Link

+ /Type /Annot >>

+endobj

+% 'Annot.NUMBER43': class PDFDictionary 

+64 0 obj

+<< /A << /S /URI

+ /Type /Action

+ /URI (http://www.phyast.pitt.edu/~micheles/python/documentation.html#class-decorators-and-decorator-factories) >>

+ /Border [ 0

+ 0

+ 0 ]

+ /Rect [ 364.2921

+ 540.7736

+ 531.64

+ 552.7736 ]

+ /Subtype /Link

+ /Type /Annot >>

+endobj

+% 'Page15': class PDFPage 

+65 0 obj

+% Page dictionary

+<< /Annots [ 59 0 R

+ 60 0 R

+ 61 0 R

+ 62 0 R

+ 63 0 R

+ 64 0 R ]

+ /Contents 99 0 R

+ /MediaBox [ 0

+ 0

+ 595.2756

+ 841.8898 ]

+ /Parent 84 0 R

+ /Resources << /Font 1 0 R

+ /ProcSet [ /PDF

+ /Text

+ /ImageB

+ /ImageC

+ /ImageI ] >>

+ /Rotate 0

+ /Trans <<  >>

+ /Type /Page >>

+endobj

+% 'R66': class PDFCatalog 

+66 0 obj

+% Document Root

+<< /Outlines 68 0 R

+ /PageLabels 100 0 R

+ /PageMode /UseNone

+ /Pages 84 0 R

+ /Type /Catalog >>

+endobj

+% 'R67': class PDFInfo 

+67 0 obj

+<< /Author (Michele Simionato)

+ /CreationDate (D:20121018102559-01'00')

+ /Creator (\(unspecified\))

+ /Keywords ()

+ /Producer (ReportLab PDF Library - www.reportlab.com)

+ /Subject (\(unspecified\))

+ /Title (The decorator module) >>

+endobj

+% 'R68': class PDFOutlines 

+68 0 obj

+<< /Count 15

+ /First 69 0 R

+ /Last 83 0 R

+ /Type /Outlines >>

+endobj

+% 'Outline.0': class OutlineEntryObject 

+69 0 obj

+<< /Dest [ 38 0 R

+ /XYZ

+ 62.69291

+ 293.0236

+ 0 ]

+ /Next 70 0 R

+ /Parent 68 0 R

+ /Title (Introduction) >>

+endobj

+% 'Outline.1': class OutlineEntryObject 

+70 0 obj

+<< /Dest [ 43 0 R

+ /XYZ

+ 62.69291

+ 675.0236

+ 0 ]

+ /Next 71 0 R

+ /Parent 68 0 R

+ /Prev 69 0 R

+ /Title (Definitions) >>

+endobj

+% 'Outline.2': class OutlineEntryObject 

+71 0 obj

+<< /Dest [ 43 0 R

+ /XYZ

+ 62.69291

+ 438.0236

+ 0 ]

+ /Next 72 0 R

+ /Parent 68 0 R

+ /Prev 70 0 R

+ /Title (Statement of the problem) >>

+endobj

+% 'Outline.3': class OutlineEntryObject 

+72 0 obj

+<< /Dest [ 44 0 R

+ /XYZ

+ 62.69291

+ 427.4236

+ 0 ]

+ /Next 73 0 R

+ /Parent 68 0 R

+ /Prev 71 0 R

+ /Title (The solution) >>

+endobj

+% 'Outline.4': class OutlineEntryObject 

+73 0 obj

+<< /Dest [ 45 0 R

+ /XYZ

+ 62.69291

+ 435.4236

+ 0 ]

+ /Next 74 0 R

+ /Parent 68 0 R

+ /Prev 72 0 R

+ /Title (A trace decorator) >>

+endobj

+% 'Outline.5': class OutlineEntryObject 

+74 0 obj

+<< /Dest [ 46 0 R

+ /XYZ

+ 62.69291

+ 398.778

+ 0 ]

+ /Next 75 0 R

+ /Parent 68 0 R

+ /Prev 73 0 R

+ /Title (decorator is a decorator) >>

+endobj

+% 'Outline.6': class OutlineEntryObject 

+75 0 obj

+<< /Dest [ 47 0 R

+ /XYZ

+ 62.69291

+ 647.8236

+ 0 ]

+ /Next 76 0 R

+ /Parent 68 0 R

+ /Prev 74 0 R

+ /Title (blocking) >>

+endobj

+% 'Outline.7': class OutlineEntryObject 

+76 0 obj

+<< /Dest [ 48 0 R

+ /XYZ

+ 62.69291

+ 765.0236

+ 0 ]

+ /Next 77 0 R

+ /Parent 68 0 R

+ /Prev 75 0 R

+ /Title (async) >>

+endobj

+% 'Outline.8': class OutlineEntryObject 

+77 0 obj

+<< /Dest [ 49 0 R

+ /XYZ

+ 62.69291

+ 267.4236

+ 0 ]

+ /Next 78 0 R

+ /Parent 68 0 R

+ /Prev 76 0 R

+ /Title (contextmanager) >>

+endobj

+% 'Outline.9': class OutlineEntryObject 

+78 0 obj

+<< /Dest [ 50 0 R

+ /XYZ

+ 62.69291

+ 354.6236

+ 0 ]

+ /Next 79 0 R

+ /Parent 68 0 R

+ /Prev 77 0 R

+ /Title (The FunctionMaker class) >>

+endobj

+% 'Outline.10': class OutlineEntryObject 

+79 0 obj

+<< /Dest [ 51 0 R

+ /XYZ

+ 62.69291

+ 363.8236

+ 0 ]

+ /Next 80 0 R

+ /Parent 68 0 R

+ /Prev 78 0 R

+ /Title (Getting the source code) >>

+endobj

+% 'Outline.11': class OutlineEntryObject 

+80 0 obj

+<< /Dest [ 54 0 R

+ /XYZ

+ 62.69291

+ 599.8236

+ 0 ]

+ /Next 81 0 R

+ /Parent 68 0 R

+ /Prev 79 0 R

+ /Title (Dealing with third party decorators) >>

+endobj

+% 'Outline.12': class OutlineEntryObject 

+81 0 obj

+<< /Dest [ 55 0 R

+ /XYZ

+ 62.69291

+ 215.0236

+ 0 ]

+ /Next 82 0 R

+ /Parent 68 0 R

+ /Prev 80 0 R

+ /Title (Caveats and limitations) >>

+endobj

+% 'Outline.13': class OutlineEntryObject 

+82 0 obj

+<< /Dest [ 65 0 R

+ /XYZ

+ 62.69291

+ 765.0236

+ 0 ]

+ /Next 83 0 R

+ /Parent 68 0 R

+ /Prev 81 0 R

+ /Title (Compatibility notes) >>

+endobj

+% 'Outline.14': class OutlineEntryObject 

+83 0 obj

+<< /Dest [ 65 0 R

+ /XYZ

+ 62.69291

+ 414.0236

+ 0 ]

+ /Parent 68 0 R

+ /Prev 82 0 R

+ /Title (LICENCE) >>

+endobj

+% 'R84': class PDFPages 

+84 0 obj

+% page tree

+<< /Count 15

+ /Kids [ 38 0 R

+ 43 0 R

+ 44 0 R

+ 45 0 R

+ 46 0 R

+ 47 0 R

+ 48 0 R

+ 49 0 R

+ 50 0 R

+ 51 0 R

+ 54 0 R

+ 55 0 R

+ 57 0 R

+ 58 0 R

+ 65 0 R ]

+ /Type /Pages >>

+endobj

+% 'R85': class PDFStream 

+85 0 obj

+% page stream

+<< /Length 9046 >>

+stream

+1 0 0 1 0 0 cm  BT /F1 12 Tf 14.4 TL ET

+q

+1 0 0 1 62.69291 741.0236 cm

+q

+BT 1 0 0 1 0 4 Tm 118.8249 0 Td 24 TL /F2 20 Tf 0 0 0 rg (The ) Tj /F3 20 Tf (decorator ) Tj /F2 20 Tf (module) Tj T* -118.8249 0 Td ET

+Q

+Q

+q

+1 0 0 1 62.69291 716.0236 cm

+0 0 0 rg

+BT /F1 10 Tf 12 TL ET

+q

+1 0 0 1 6 3 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 2 Tm /F2 10 Tf 12 TL 36.93937 0 Td (Author:) Tj T* -36.93937 0 Td ET

+Q

+Q

+q

+1 0 0 1 91.03937 3 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 2 Tm /F1 10 Tf 12 TL (Michele Simionato) Tj T* ET

+Q

+Q

+q

+Q

+Q

+q

+1 0 0 1 62.69291 701.0236 cm

+0 0 0 rg

+BT /F1 10 Tf 12 TL ET

+q

+1 0 0 1 6 3 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 2 Tm /F2 10 Tf 12 TL 39.69937 0 Td (E-mail:) Tj T* -39.69937 0 Td ET

+Q

+Q

+q

+1 0 0 1 91.03937 3 cm

+q

+BT 1 0 0 1 0 2 Tm 12 TL /F1 10 Tf 0 0 .501961 rg (michele.simionato@gmail.com) Tj T* ET

+Q

+Q

+q

+Q

+Q

+q

+1 0 0 1 62.69291 686.0236 cm

+0 0 0 rg

+BT /F1 10 Tf 12 TL ET

+q

+1 0 0 1 6 3 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 2 Tm /F2 10 Tf 12 TL 33.02937 0 Td (Version:) Tj T* -33.02937 0 Td ET

+Q

+Q

+q

+1 0 0 1 91.03937 3 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 2 Tm /F1 10 Tf 12 TL (3.4.0 \(2012-10-18\)) Tj T* ET

+Q

+Q

+q

+Q

+Q

+q

+1 0 0 1 62.69291 671.0236 cm

+0 0 0 rg

+BT /F1 10 Tf 12 TL ET

+q

+1 0 0 1 6 3 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 2 Tm /F2 10 Tf 12 TL 26.91937 0 Td (Requires:) Tj T* -26.91937 0 Td ET

+Q

+Q

+q

+1 0 0 1 91.03937 3 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 2 Tm /F1 10 Tf 12 TL (Python 2.4+) Tj T* ET

+Q

+Q

+q

+Q

+Q

+q

+1 0 0 1 62.69291 644.0236 cm

+0 0 0 rg

+BT /F1 10 Tf 12 TL ET

+q

+1 0 0 1 6 3 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 14 Tm /F2 10 Tf 12 TL 25.25937 0 Td (Download) Tj T* 21.11 0 Td (page:) Tj T* -46.36937 0 Td ET

+Q

+Q

+q

+1 0 0 1 91.03937 15 cm

+q

+0 0 .501961 rg

+0 0 .501961 RG

+BT 1 0 0 1 0 2 Tm /F1 10 Tf 12 TL (http://pypi.python.org/pypi/decorator/3.4.0) Tj T* ET

+Q

+Q

+q

+Q

+Q

+q

+1 0 0 1 62.69291 629.0236 cm

+0 0 0 rg

+BT /F1 10 Tf 12 TL ET

+q

+1 0 0 1 6 3 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 2 Tm /F2 10 Tf 12 TL 16.91937 0 Td (Installation:) Tj T* -16.91937 0 Td ET

+Q

+Q

+q

+1 0 0 1 91.03937 3 cm

+q

+BT 1 0 0 1 0 2 Tm 12 TL /F4 10 Tf 0 0 0 rg (easy_install) Tj ( ) Tj (decorator) Tj T* ET

+Q

+Q

+q

+Q

+Q

+q

+1 0 0 1 62.69291 614.0236 cm

+0 0 0 rg

+BT /F1 10 Tf 12 TL ET

+q

+1 0 0 1 6 3 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 2 Tm /F2 10 Tf 12 TL 32.46937 0 Td (License:) Tj T* -32.46937 0 Td ET

+Q

+Q

+q

+1 0 0 1 91.03937 3 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 2 Tm /F1 10 Tf 12 TL (BSD license) Tj T* ET

+Q

+Q

+q

+Q

+Q

+q

+1 0 0 1 62.69291 581.0236 cm

+q

+BT 1 0 0 1 0 3.5 Tm 21 TL /F2 17.5 Tf 0 0 0 rg (Contents) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 305.0236 cm

+0 0 0 rg

+BT /F1 10 Tf 12 TL ET

+q

+1 0 0 1 0 255 cm

+q

+BT 1 0 0 1 0 2 Tm 12 TL /F2 10 Tf 0 0 .501961 rg (Introduction) Tj T* ET

+Q

+Q

+q

+1 0 0 1 397.8898 255 cm

+q

+0 0 .501961 rg

+0 0 .501961 RG

+BT 1 0 0 1 0 2 Tm /F2 10 Tf 12 TL 66.44 0 Td (1) Tj T* -66.44 0 Td ET

+Q

+Q

+q

+1 0 0 1 0 237 cm

+q

+BT 1 0 0 1 0 2 Tm 12 TL /F2 10 Tf 0 0 .501961 rg (Definitions) Tj T* ET

+Q

+Q

+q

+1 0 0 1 397.8898 237 cm

+q

+0 0 .501961 rg

+0 0 .501961 RG

+BT 1 0 0 1 0 2 Tm /F2 10 Tf 12 TL 66.44 0 Td (2) Tj T* -66.44 0 Td ET

+Q

+Q

+q

+1 0 0 1 0 219 cm

+q

+BT 1 0 0 1 0 2 Tm 12 TL /F2 10 Tf 0 0 .501961 rg (Statement of the problem) Tj T* ET

+Q

+Q

+q

+1 0 0 1 397.8898 219 cm

+q

+0 0 .501961 rg

+0 0 .501961 RG

+BT 1 0 0 1 0 2 Tm /F2 10 Tf 12 TL 66.44 0 Td (2) Tj T* -66.44 0 Td ET

+Q

+Q

+q

+1 0 0 1 0 201 cm

+q

+BT 1 0 0 1 0 2 Tm 12 TL /F2 10 Tf 0 0 .501961 rg (The solution) Tj T* ET

+Q

+Q

+q

+1 0 0 1 397.8898 201 cm

+q

+0 0 .501961 rg

+0 0 .501961 RG

+BT 1 0 0 1 0 2 Tm /F2 10 Tf 12 TL 66.44 0 Td (3) Tj T* -66.44 0 Td ET

+Q

+Q

+q

+1 0 0 1 0 183 cm

+q

+BT 1 0 0 1 0 2 Tm 12 TL /F2 10 Tf 0 0 .501961 rg (A ) Tj /F3 10 Tf (trace ) Tj /F2 10 Tf (decorator) Tj T* ET

+Q

+Q

+q

+1 0 0 1 397.8898 183 cm

+q

+0 0 .501961 rg

+0 0 .501961 RG

+BT 1 0 0 1 0 2 Tm /F2 10 Tf 12 TL 66.44 0 Td (4) Tj T* -66.44 0 Td ET

+Q

+Q

+q

+1 0 0 1 0 165 cm

+q

+BT 1 0 0 1 0 2 Tm 12 TL /F3 10 Tf 0 0 .501961 rg (decorator ) Tj /F2 10 Tf (is a decorator) Tj T* ET

+Q

+Q

+q

+1 0 0 1 397.8898 165 cm

+q

+0 0 .501961 rg

+0 0 .501961 RG

+BT 1 0 0 1 0 2 Tm /F2 10 Tf 12 TL 66.44 0 Td (5) Tj T* -66.44 0 Td ET

+Q

+Q

+q

+1 0 0 1 0 147 cm

+q

+BT 1 0 0 1 0 2 Tm 12 TL /F3 10 Tf 0 0 .501961 rg (blocking) Tj T* ET

+Q

+Q

+q

+1 0 0 1 397.8898 147 cm

+q

+0 0 .501961 rg

+0 0 .501961 RG

+BT 1 0 0 1 0 2 Tm /F2 10 Tf 12 TL 66.44 0 Td (6) Tj T* -66.44 0 Td ET

+Q

+Q

+q

+1 0 0 1 0 129 cm

+q

+BT 1 0 0 1 0 2 Tm 12 TL /F3 10 Tf 0 0 .501961 rg (async) Tj T* ET

+Q

+Q

+q

+1 0 0 1 397.8898 129 cm

+q

+0 0 .501961 rg

+0 0 .501961 RG

+BT 1 0 0 1 0 2 Tm /F2 10 Tf 12 TL 66.44 0 Td (7) Tj T* -66.44 0 Td ET

+Q

+Q

+q

+1 0 0 1 0 111 cm

+q

+BT 1 0 0 1 0 2 Tm 12 TL /F2 10 Tf 0 0 .501961 rg (contextmanager) Tj T* ET

+Q

+Q

+q

+1 0 0 1 397.8898 111 cm

+q

+0 0 .501961 rg

+0 0 .501961 RG

+BT 1 0 0 1 0 2 Tm /F2 10 Tf 12 TL 66.44 0 Td (8) Tj T* -66.44 0 Td ET

+Q

+Q

+q

+1 0 0 1 0 93 cm

+q

+BT 1 0 0 1 0 2 Tm 12 TL /F2 10 Tf 0 0 .501961 rg (The ) Tj /F3 10 Tf (FunctionMaker ) Tj /F2 10 Tf (class) Tj T* ET

+Q

+Q

+q

+1 0 0 1 397.8898 93 cm

+q

+0 0 .501961 rg

+0 0 .501961 RG

+BT 1 0 0 1 0 2 Tm /F2 10 Tf 12 TL 66.44 0 Td (9) Tj T* -66.44 0 Td ET

+Q

+Q

+q

+1 0 0 1 0 75 cm

+q

+BT 1 0 0 1 0 2 Tm 12 TL /F2 10 Tf 0 0 .501961 rg (Getting the source code) Tj T* ET

+Q

+Q

+q

+1 0 0 1 397.8898 75 cm

+q

+0 0 .501961 rg

+0 0 .501961 RG

+BT 1 0 0 1 0 2 Tm /F2 10 Tf 12 TL 60.88 0 Td (10) Tj T* -60.88 0 Td ET

+Q

+Q

+q

+1 0 0 1 0 57 cm

+q

+BT 1 0 0 1 0 2 Tm 12 TL /F2 10 Tf 0 0 .501961 rg (Dealing with third party decorators) Tj T* ET

+Q

+Q

+q

+1 0 0 1 397.8898 57 cm

+q

+0 0 .501961 rg

+0 0 .501961 RG

+BT 1 0 0 1 0 2 Tm /F2 10 Tf 12 TL 60.88 0 Td (11) Tj T* -60.88 0 Td ET

+Q

+Q

+q

+1 0 0 1 0 39 cm

+q

+BT 1 0 0 1 0 2 Tm 12 TL /F2 10 Tf 0 0 .501961 rg (Caveats and limitations) Tj T* ET

+Q

+Q

+q

+1 0 0 1 397.8898 39 cm

+q

+0 0 .501961 rg

+0 0 .501961 RG

+BT 1 0 0 1 0 2 Tm /F2 10 Tf 12 TL 60.88 0 Td (12) Tj T* -60.88 0 Td ET

+Q

+Q

+q

+1 0 0 1 0 21 cm

+q

+BT 1 0 0 1 0 2 Tm 12 TL /F2 10 Tf 0 0 .501961 rg (Compatibility notes) Tj T* ET

+Q

+Q

+q

+1 0 0 1 397.8898 21 cm

+q

+0 0 .501961 rg

+0 0 .501961 RG

+BT 1 0 0 1 0 2 Tm /F2 10 Tf 12 TL 60.88 0 Td (15) Tj T* -60.88 0 Td ET

+Q

+Q

+q

+1 0 0 1 0 3 cm

+q

+BT 1 0 0 1 0 2 Tm 12 TL /F2 10 Tf 0 0 .501961 rg (LICENCE) Tj T* ET

+Q

+Q

+q

+1 0 0 1 397.8898 3 cm

+q

+0 0 .501961 rg

+0 0 .501961 RG

+BT 1 0 0 1 0 2 Tm /F2 10 Tf 12 TL 60.88 0 Td (15) Tj T* -60.88 0 Td ET

+Q

+Q

+q

+Q

+Q

+q

+1 0 0 1 62.69291 272.0236 cm

+q

+BT 1 0 0 1 0 3.5 Tm 21 TL /F2 17.5 Tf 0 0 0 rg (Introduction) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 206.0236 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 50 Tm /F1 10 Tf 12 TL 3.995366 Tw (Python decorators are an interesting example of why syntactic sugar matters. In principle, their) Tj T* 0 Tw .151235 Tw (introduction in Python 2.4 changed nothing, since they do not provide any new functionality which was not) Tj T* 0 Tw 2.238555 Tw (already present in the language. In practice, their introduction has significantly changed the way we) Tj T* 0 Tw .098409 Tw (structure our programs in Python. I believe the change is for the best, and that decorators are a great idea) Tj T* 0 Tw (since:) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 200.0236 cm

+Q

+q

+1 0 0 1 62.69291 200.0236 cm

+Q

+q

+1 0 0 1 62.69291 188.0236 cm

+0 0 0 rg

+BT /F1 10 Tf 12 TL ET

+q

+1 0 0 1 6 -3 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 2 Tm /F1 10 Tf 12 TL 10.5 0 Td (\177) Tj T* -10.5 0 Td ET

+Q

+Q

+q

+1 0 0 1 23 -3 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 2 Tm /F1 10 Tf 12 TL (decorators help reducing boilerplate code;) Tj T* ET

+Q

+Q

+q

+Q

+Q

+q

+1 0 0 1 62.69291 182.0236 cm

+Q

+q

+1 0 0 1 62.69291 170.0236 cm

+0 0 0 rg

+BT /F1 10 Tf 12 TL ET

+q

+1 0 0 1 6 -3 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 2 Tm /F1 10 Tf 12 TL 10.5 0 Td (\177) Tj T* -10.5 0 Td ET

+Q

+Q

+q

+1 0 0 1 23 -3 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 2 Tm /F1 10 Tf 12 TL (decorators help separation of concerns;) Tj T* ET

+Q

+Q

+q

+Q

+Q

+q

+1 0 0 1 62.69291 164.0236 cm

+Q

+q

+1 0 0 1 62.69291 152.0236 cm

+0 0 0 rg

+BT /F1 10 Tf 12 TL ET

+q

+1 0 0 1 6 -3 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 2 Tm /F1 10 Tf 12 TL 10.5 0 Td (\177) Tj T* -10.5 0 Td ET

+Q

+Q

+q

+1 0 0 1 23 -3 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 2 Tm /F1 10 Tf 12 TL (decorators enhance readability and maintenability;) Tj T* ET

+Q

+Q

+q

+Q

+Q

+q

+1 0 0 1 62.69291 146.0236 cm

+Q

+q

+1 0 0 1 62.69291 134.0236 cm

+0 0 0 rg

+BT /F1 10 Tf 12 TL ET

+q

+1 0 0 1 6 -3 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 2 Tm /F1 10 Tf 12 TL 10.5 0 Td (\177) Tj T* -10.5 0 Td ET

+Q

+Q

+q

+1 0 0 1 23 -3 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 2 Tm /F1 10 Tf 12 TL (decorators are explicit.) Tj T* ET

+Q

+Q

+q

+Q

+Q

+q

+1 0 0 1 62.69291 134.0236 cm

+Q

+q

+1 0 0 1 62.69291 92.02362 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 26 Tm /F1 10 Tf 12 TL .848876 Tw (Still, as of now, writing custom decorators correctly requires some experience and it is not as easy as it) Tj T* 0 Tw 1.049269 Tw (could be. For instance, typical implementations of decorators involve nested functions, and we all know) Tj T* 0 Tw (that flat is better than nested.) Tj T* ET

+Q

+Q

+ 

+endstream

+endobj

+% 'R86': class PDFStream 

+86 0 obj

+% page stream

+<< /Length 7546 >>

+stream

+1 0 0 1 0 0 cm  BT /F1 12 Tf 14.4 TL ET

+q

+1 0 0 1 62.69291 717.0236 cm

+q

+BT 1 0 0 1 0 38 Tm 1.093735 Tw 12 TL /F1 10 Tf 0 0 0 rg (The aim of the ) Tj /F4 10 Tf (decorator ) Tj /F1 10 Tf (module it to simplify the usage of decorators for the average programmer,) Tj T* 0 Tw 2.456136 Tw (and to popularize decorators by showing various non-trivial examples. Of course, as all techniques,) Tj T* 0 Tw 2.234987 Tw (decorators can be abused \(I have seen that\) and you should not try to solve every problem with a) Tj T* 0 Tw (decorator, just because you can.) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 687.0236 cm

+q

+BT 1 0 0 1 0 14 Tm .13561 Tw 12 TL /F1 10 Tf 0 0 0 rg (You may find the source code for all the examples discussed here in the ) Tj /F4 10 Tf (documentation.py ) Tj /F1 10 Tf (file, which) Tj T* 0 Tw (contains this documentation in the form of doctests.) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 654.0236 cm

+q

+BT 1 0 0 1 0 3.5 Tm 21 TL /F2 17.5 Tf 0 0 0 rg (Definitions) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 612.0236 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 26 Tm /F1 10 Tf 12 TL 2.37561 Tw (Technically speaking, any Python object which can be called with one argument can be used as a) Tj T* 0 Tw .472339 Tw (decorator. However, this definition is somewhat too large to be really useful. It is more convenient to split) Tj T* 0 Tw (the generic class of decorators in two subclasses:) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 606.0236 cm

+Q

+q

+1 0 0 1 62.69291 606.0236 cm

+Q

+q

+1 0 0 1 62.69291 582.0236 cm

+0 0 0 rg

+BT /F1 10 Tf 12 TL ET

+q

+1 0 0 1 6 9 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 2 Tm /F1 10 Tf 12 TL 10.5 0 Td (\177) Tj T* -10.5 0 Td ET

+Q

+Q

+q

+1 0 0 1 23 -3 cm

+q

+BT 1 0 0 1 0 14 Tm 2.68748 Tw 12 TL /F5 10 Tf 0 0 0 rg (signature-preserving ) Tj /F1 10 Tf (decorators, i.e. callable objects taking a function as input and returning a) Tj T* 0 Tw (function ) Tj /F5 10 Tf (with the same signature ) Tj /F1 10 Tf (as output;) Tj T* ET

+Q

+Q

+q

+Q

+Q

+q

+1 0 0 1 62.69291 576.0236 cm

+Q

+q

+1 0 0 1 62.69291 552.0236 cm

+0 0 0 rg

+BT /F1 10 Tf 12 TL ET

+q

+1 0 0 1 6 9 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 2 Tm /F1 10 Tf 12 TL 10.5 0 Td (\177) Tj T* -10.5 0 Td ET

+Q

+Q

+q

+1 0 0 1 23 -3 cm

+q

+BT 1 0 0 1 0 14 Tm 1.43498 Tw 12 TL /F5 10 Tf 0 0 0 rg (signature-changing ) Tj /F1 10 Tf (decorators, i.e. decorators that change the signature of their input function, or) Tj T* 0 Tw (decorators returning non-callable objects.) Tj T* ET

+Q

+Q

+q

+Q

+Q

+q

+1 0 0 1 62.69291 552.0236 cm

+Q

+q

+1 0 0 1 62.69291 510.0236 cm

+q

+BT 1 0 0 1 0 26 Tm 2.832706 Tw 12 TL /F1 10 Tf 0 0 0 rg (Signature-changing decorators have their use: for instance the builtin classes ) Tj /F4 10 Tf (staticmethod ) Tj /F1 10 Tf (and) Tj T* 0 Tw 1.506651 Tw /F4 10 Tf (classmethod ) Tj /F1 10 Tf (are in this group, since they take functions and return descriptor objects which are not) Tj T* 0 Tw (functions, nor callables.) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 480.0236 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 14 Tm /F1 10 Tf 12 TL 1.735814 Tw (However, signature-preserving decorators are more common and easier to reason about; in particular) Tj T* 0 Tw (signature-preserving decorators can be composed together whereas other decorators in general cannot.) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 450.0236 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 14 Tm /F1 10 Tf 12 TL .494983 Tw (Writing signature-preserving decorators from scratch is not that obvious, especially if one wants to define) Tj T* 0 Tw (proper decorators that can accept functions with any signature. A simple example will clarify the issue.) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 417.0236 cm

+q

+BT 1 0 0 1 0 3.5 Tm 21 TL /F2 17.5 Tf 0 0 0 rg (Statement of the problem) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 339.0236 cm

+q

+BT 1 0 0 1 0 62 Tm .351235 Tw 12 TL /F1 10 Tf 0 0 0 rg (A very common use case for decorators is the memoization of functions. A ) Tj /F4 10 Tf (memoize ) Tj /F1 10 Tf (decorator works by) Tj T* 0 Tw .871988 Tw (caching the result of the function call in a dictionary, so that the next time the function is called with the) Tj T* 0 Tw 2.350651 Tw (same input parameters the result is retrieved from the cache and not recomputed. There are many) Tj T* 0 Tw 2.92247 Tw (implementations of ) Tj /F4 10 Tf (memoize ) Tj /F1 10 Tf (in ) Tj 0 0 .501961 rg (http://www.python.org/moin/PythonDecoratorLibrary) Tj 0 0 0 rg (, but they do not) Tj T* 0 Tw 2.683984 Tw (preserve the signature. A simple implementation could be the following \(notice that in general it is) Tj T* 0 Tw (impossible to memoize correctly something that depends on non-hashable arguments\):) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 149.8236 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 180 re B*

+Q

+q

+BT 1 0 0 1 0 158 Tm 12 TL /F3 10 Tf 0 .501961 0 rg (def) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 0 1 rg (memoize_uw) Tj 0 0 0 rg (\() Tj (func) Tj (\):) Tj  T* (    ) Tj (func) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (cache) Tj ( ) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ( ) Tj ({}) Tj  T* (    ) Tj /F3 10 Tf 0 .501961 0 rg (def) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 0 1 rg (memoize) Tj 0 0 0 rg (\() Tj .4 .4 .4 rg (*) Tj 0 0 0 rg (args) Tj (,) Tj ( ) Tj .4 .4 .4 rg (**) Tj 0 0 0 rg (kw) Tj (\):) Tj  T* (        ) Tj /F3 10 Tf 0 .501961 0 rg (if) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (kw) Tj (:) Tj ( ) Tj /F6 10 Tf .25098 .501961 .501961 rg (# frozenset is used to ensure hashability) Tj /F4 10 Tf 0 0 0 rg  T* (            ) Tj (key) Tj ( ) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ( ) Tj (args) Tj (,) Tj ( ) Tj 0 .501961 0 rg (frozenset) Tj 0 0 0 rg (\() Tj (kw) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (iteritems) Tj (\(\)\)) Tj  T* (        ) Tj /F3 10 Tf 0 .501961 0 rg (else) Tj /F4 10 Tf 0 0 0 rg (:) Tj  T* (            ) Tj (key) Tj ( ) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ( ) Tj (args) Tj  T* (        ) Tj (cache) Tj ( ) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ( ) Tj (func) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (cache) Tj  T* (        ) Tj /F3 10 Tf 0 .501961 0 rg (if) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (key) Tj ( ) Tj /F3 10 Tf .666667 .133333 1 rg (in) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (cache) Tj (:) Tj  T* (            ) Tj /F3 10 Tf 0 .501961 0 rg (return) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (cache) Tj ([) Tj (key) Tj (]) Tj  T* (        ) Tj /F3 10 Tf 0 .501961 0 rg (else) Tj /F4 10 Tf 0 0 0 rg (:) Tj  T* (            ) Tj (cache) Tj ([) Tj (key) Tj (]) Tj ( ) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ( ) Tj (result) Tj ( ) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ( ) Tj (func) Tj (\() Tj .4 .4 .4 rg (*) Tj 0 0 0 rg (args) Tj (,) Tj ( ) Tj .4 .4 .4 rg (**) Tj 0 0 0 rg (kw) Tj (\)) Tj  T* (            ) Tj /F3 10 Tf 0 .501961 0 rg (return) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (result) Tj  T* (    ) Tj /F3 10 Tf 0 .501961 0 rg (return) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (functools) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (update_wrapper) Tj (\() Tj (memoize) Tj (,) Tj ( ) Tj (func) Tj (\)) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 93.82362 cm

+q

+BT 1 0 0 1 0 38 Tm 1.801412 Tw 12 TL /F1 10 Tf 0 0 0 rg (Here we used the ) Tj 0 0 .501961 rg (functools.update_wrapper ) Tj 0 0 0 rg (utility, which has been added in Python 2.5 expressly to) Tj T* 0 Tw .91686 Tw (simplify the definition of decorators \(in older versions of Python you need to copy the function attributes) Tj T* 0 Tw .580814 Tw /F4 10 Tf (__name__) Tj /F1 10 Tf (, ) Tj /F4 10 Tf (__doc__) Tj /F1 10 Tf (, ) Tj /F4 10 Tf (__module__ ) Tj /F1 10 Tf (and ) Tj /F4 10 Tf (__dict__ ) Tj /F1 10 Tf (from the original function to the decorated function) Tj T* 0 Tw (by hand\).) Tj T* ET

+Q

+Q

+ 

+endstream

+endobj

+% 'R87': class PDFStream 

+87 0 obj

+% page stream

+<< /Length 8057 >>

+stream

+1 0 0 1 0 0 cm  BT /F1 12 Tf 14.4 TL ET

+q

+1 0 0 1 62.69291 729.0236 cm

+q

+BT 1 0 0 1 0 26 Tm 2.517126 Tw 12 TL /F1 10 Tf 0 0 0 rg (The implementation above works in the sense that the decorator can accept functions with generic) Tj T* 0 Tw 1.233615 Tw (signatures; unfortunately this implementation does ) Tj /F5 10 Tf (not ) Tj /F1 10 Tf (define a signature-preserving decorator, since in) Tj T* 0 Tw (general ) Tj /F4 10 Tf (memoize_uw ) Tj /F1 10 Tf (returns a function with a ) Tj /F5 10 Tf (different signature ) Tj /F1 10 Tf (from the original function.) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 711.0236 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 2 Tm /F1 10 Tf 12 TL (Consider for instance the following case:) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 641.8236 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 60 re B*

+Q

+q

+BT 1 0 0 1 0 38 Tm 12 TL /F4 10 Tf .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj .666667 .133333 1 rg (@memoize_uw) Tj 0 0 0 rg  T* .4 .4 .4 rg (...) Tj 0 0 0 rg ( ) Tj /F3 10 Tf 0 .501961 0 rg (def) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 0 1 rg (f1) Tj 0 0 0 rg (\() Tj (x) Tj (\):) Tj  T* .4 .4 .4 rg (...) Tj 0 0 0 rg (     ) Tj (time) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (sleep) Tj (\() Tj .4 .4 .4 rg (1) Tj 0 0 0 rg (\)) Tj ( ) Tj /F6 10 Tf .25098 .501961 .501961 rg (# simulate some long computation) Tj /F4 10 Tf 0 0 0 rg  T* .4 .4 .4 rg (...) Tj 0 0 0 rg (     ) Tj /F3 10 Tf 0 .501961 0 rg (return) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (x) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 609.8236 cm

+q

+BT 1 0 0 1 0 14 Tm .26311 Tw 12 TL /F1 10 Tf 0 0 0 rg (Here the original function takes a single argument named ) Tj /F4 10 Tf (x) Tj /F1 10 Tf (, but the decorated function takes any number) Tj T* 0 Tw (of arguments and keyword arguments:) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 552.6236 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 48 re B*

+Q

+q

+BT 1 0 0 1 0 26 Tm 12 TL /F4 10 Tf .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj /F3 10 Tf 0 .501961 0 rg (from) Tj /F4 10 Tf 0 0 0 rg ( ) Tj /F3 10 Tf 0 0 1 rg (inspect) Tj /F4 10 Tf 0 0 0 rg ( ) Tj /F3 10 Tf 0 .501961 0 rg (import) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (getargspec) Tj  T* .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj /F3 10 Tf 0 .501961 0 rg (print) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (getargspec) Tj (\() Tj (f1) Tj (\)) Tj ( ) Tj /F6 10 Tf .25098 .501961 .501961 rg (# I am using Python 2.6+ here) Tj /F4 10 Tf 0 0 0 rg  T* (ArgSpec) Tj (\() Tj (args) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ([],) Tj ( ) Tj (varargs) Tj .4 .4 .4 rg (=) Tj .729412 .129412 .129412 rg ('args') Tj 0 0 0 rg (,) Tj ( ) Tj (keywords) Tj .4 .4 .4 rg (=) Tj .729412 .129412 .129412 rg ('kw') Tj 0 0 0 rg (,) Tj ( ) Tj (defaults) Tj .4 .4 .4 rg (=) Tj 0 .501961 0 rg (None) Tj 0 0 0 rg (\)) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 508.6236 cm

+q

+BT 1 0 0 1 0 26 Tm .411235 Tw 12 TL /F1 10 Tf 0 0 0 rg (This means that introspection tools such as pydoc will give wrong informations about the signature of ) Tj /F4 10 Tf (f1) Tj /F1 10 Tf (.) Tj T* 0 Tw .161654 Tw (This is pretty bad: pydoc will tell you that the function accepts a generic signature ) Tj /F4 10 Tf (*args) Tj /F1 10 Tf (, ) Tj /F4 10 Tf (**kw) Tj /F1 10 Tf (, but when) Tj T* 0 Tw (you try to call the function with more than an argument, you will get an error:) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 439.4236 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 60 re B*

+Q

+q

+BT 1 0 0 1 0 38 Tm 12 TL /F4 10 Tf .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj (f1) Tj (\() Tj .4 .4 .4 rg (0) Tj 0 0 0 rg (,) Tj ( ) Tj .4 .4 .4 rg (1) Tj 0 0 0 rg (\)) Tj  T* (Traceback) Tj ( ) Tj (\() Tj (most) Tj ( ) Tj (recent) Tj ( ) Tj (call) Tj ( ) Tj (last) Tj (\):) Tj  T* (   ) Tj .4 .4 .4 rg (...) Tj 0 0 0 rg  T* /F3 10 Tf .823529 .254902 .227451 rg (TypeError) Tj /F4 10 Tf 0 0 0 rg (:) Tj ( ) Tj (f1) Tj (\(\)) Tj ( ) Tj (takes) Tj ( ) Tj (exactly) Tj ( ) Tj .4 .4 .4 rg (1) Tj 0 0 0 rg ( ) Tj (argument) Tj ( ) Tj (\() Tj .4 .4 .4 rg (2) Tj 0 0 0 rg ( ) Tj (given) Tj (\)) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 406.4236 cm

+q

+BT 1 0 0 1 0 3.5 Tm 21 TL /F2 17.5 Tf 0 0 0 rg (The solution) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 364.4236 cm

+q

+BT 1 0 0 1 0 26 Tm 3.313984 Tw 12 TL /F1 10 Tf 0 0 0 rg (The solution is to provide a generic factory of generators, which hides the complexity of making) Tj T* 0 Tw 3.362976 Tw (signature-preserving decorators from the application programmer. The ) Tj /F4 10 Tf (decorator ) Tj /F1 10 Tf (function in the) Tj T* 0 Tw /F4 10 Tf (decorator ) Tj /F1 10 Tf (module is such a factory:) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 331.2236 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 24 re B*

+Q

+q

+BT 1 0 0 1 0 2 Tm 12 TL /F4 10 Tf .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj /F3 10 Tf 0 .501961 0 rg (from) Tj /F4 10 Tf 0 0 0 rg ( ) Tj /F3 10 Tf 0 0 1 rg (decorator) Tj /F4 10 Tf 0 0 0 rg ( ) Tj /F3 10 Tf 0 .501961 0 rg (import) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (decorator) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 275.2236 cm

+q

+BT 1 0 0 1 0 38 Tm 1.716412 Tw 12 TL /F4 10 Tf 0 0 0 rg (decorator ) Tj /F1 10 Tf (takes two arguments, a caller function describing the functionality of the decorator and a) Tj T* 0 Tw 2.594983 Tw (function to be decorated; it returns the decorated function. The caller function must have signature) Tj T* 0 Tw .19311 Tw /F4 10 Tf (\(f,) Tj ( ) Tj (*args,) Tj ( ) Tj (**kw\) ) Tj /F1 10 Tf (and it must call the original function ) Tj /F4 10 Tf (f ) Tj /F1 10 Tf (with arguments ) Tj /F4 10 Tf (args ) Tj /F1 10 Tf (and ) Tj /F4 10 Tf (kw) Tj /F1 10 Tf (, implementing) Tj T* 0 Tw (the wanted capability, i.e. memoization in this case:) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 122.0236 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 144 re B*

+Q

+q

+BT 1 0 0 1 0 122 Tm 12 TL /F3 10 Tf 0 .501961 0 rg (def) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 0 1 rg (_memoize) Tj 0 0 0 rg (\() Tj (func) Tj (,) Tj ( ) Tj .4 .4 .4 rg (*) Tj 0 0 0 rg (args) Tj (,) Tj ( ) Tj .4 .4 .4 rg (**) Tj 0 0 0 rg (kw) Tj (\):) Tj  T* (    ) Tj /F3 10 Tf 0 .501961 0 rg (if) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (kw) Tj (:) Tj ( ) Tj /F6 10 Tf .25098 .501961 .501961 rg (# frozenset is used to ensure hashability) Tj /F4 10 Tf 0 0 0 rg  T* (        ) Tj (key) Tj ( ) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ( ) Tj (args) Tj (,) Tj ( ) Tj 0 .501961 0 rg (frozenset) Tj 0 0 0 rg (\() Tj (kw) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (iteritems) Tj (\(\)\)) Tj  T* (    ) Tj /F3 10 Tf 0 .501961 0 rg (else) Tj /F4 10 Tf 0 0 0 rg (:) Tj  T* (        ) Tj (key) Tj ( ) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ( ) Tj (args) Tj  T* (    ) Tj (cache) Tj ( ) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ( ) Tj (func) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (cache) Tj ( ) Tj /F6 10 Tf .25098 .501961 .501961 rg (# attributed added by memoize) Tj /F4 10 Tf 0 0 0 rg  T* (    ) Tj /F3 10 Tf 0 .501961 0 rg (if) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (key) Tj ( ) Tj /F3 10 Tf .666667 .133333 1 rg (in) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (cache) Tj (:) Tj  T* (        ) Tj /F3 10 Tf 0 .501961 0 rg (return) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (cache) Tj ([) Tj (key) Tj (]) Tj  T* (    ) Tj /F3 10 Tf 0 .501961 0 rg (else) Tj /F4 10 Tf 0 0 0 rg (:) Tj  T* (        ) Tj (cache) Tj ([) Tj (key) Tj (]) Tj ( ) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ( ) Tj (result) Tj ( ) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ( ) Tj (func) Tj (\() Tj .4 .4 .4 rg (*) Tj 0 0 0 rg (args) Tj (,) Tj ( ) Tj .4 .4 .4 rg (**) Tj 0 0 0 rg (kw) Tj (\)) Tj  T* (        ) Tj /F3 10 Tf 0 .501961 0 rg (return) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (result) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 102.0236 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 2 Tm /F1 10 Tf 12 TL (At this point you can define your decorator as follows:) Tj T* ET

+Q

+Q

+ 

+endstream

+endobj

+% 'R88': class PDFStream 

+88 0 obj

+% page stream

+<< /Length 7115 >>

+stream

+1 0 0 1 0 0 cm  BT /F1 12 Tf 14.4 TL ET

+q

+1 0 0 1 62.69291 715.8236 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 48 re B*

+Q

+q

+BT 1 0 0 1 0 26 Tm 12 TL /F3 10 Tf 0 .501961 0 rg (def) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 0 1 rg (memoize) Tj 0 0 0 rg (\() Tj (f) Tj (\):) Tj  T* (    ) Tj (f) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (cache) Tj ( ) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ( ) Tj ({}) Tj  T* (    ) Tj /F3 10 Tf 0 .501961 0 rg (return) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (decorator) Tj (\() Tj (_memoize) Tj (,) Tj ( ) Tj (f) Tj (\)) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 671.8236 cm

+q

+BT 1 0 0 1 0 26 Tm .12561 Tw 12 TL /F1 10 Tf 0 0 0 rg (The difference with respect to the ) Tj /F4 10 Tf (memoize_uw ) Tj /F1 10 Tf (approach, which is based on nested functions, is that the) Tj T* 0 Tw 2.59528 Tw (decorator module forces you to lift the inner function at the outer level \() Tj /F5 10 Tf (flat is better than nested) Tj /F1 10 Tf (\).) Tj T* 0 Tw (Moreover, you are forced to pass explicitly the function you want to decorate to the caller function.) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 653.8236 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 2 Tm /F1 10 Tf 12 TL (Here is a test of usage:) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 512.6236 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 132 re B*

+Q

+q

+BT 1 0 0 1 0 110 Tm 12 TL /F4 10 Tf .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj .666667 .133333 1 rg (@memoize) Tj 0 0 0 rg  T* .4 .4 .4 rg (...) Tj 0 0 0 rg ( ) Tj /F3 10 Tf 0 .501961 0 rg (def) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 0 1 rg (heavy_computation) Tj 0 0 0 rg (\(\):) Tj  T* .4 .4 .4 rg (...) Tj 0 0 0 rg (     ) Tj (time) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (sleep) Tj (\() Tj .4 .4 .4 rg (2) Tj 0 0 0 rg (\)) Tj  T* .4 .4 .4 rg (...) Tj 0 0 0 rg (     ) Tj /F3 10 Tf 0 .501961 0 rg (return) Tj /F4 10 Tf 0 0 0 rg ( ) Tj .729412 .129412 .129412 rg ("done") Tj 0 0 0 rg  T*  T* .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj /F3 10 Tf 0 .501961 0 rg (print) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (heavy_computation) Tj (\(\)) Tj ( ) Tj /F6 10 Tf .25098 .501961 .501961 rg (# the first time it will take 2 seconds) Tj /F4 10 Tf 0 0 0 rg  T* (done) Tj  T*  T* .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj /F3 10 Tf 0 .501961 0 rg (print) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (heavy_computation) Tj (\(\)) Tj ( ) Tj /F6 10 Tf .25098 .501961 .501961 rg (# the second time it will be instantaneous) Tj /F4 10 Tf 0 0 0 rg  T* (done) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 492.6236 cm

+q

+BT 1 0 0 1 0 2 Tm 12 TL /F1 10 Tf 0 0 0 rg (The signature of ) Tj /F4 10 Tf (heavy_computation ) Tj /F1 10 Tf (is the one you would expect:) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 447.4236 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 36 re B*

+Q

+q

+BT 1 0 0 1 0 14 Tm 12 TL /F4 10 Tf .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj /F3 10 Tf 0 .501961 0 rg (print) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (getargspec) Tj (\() Tj (heavy_computation) Tj (\)) Tj  T* (ArgSpec) Tj (\() Tj (args) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ([],) Tj ( ) Tj (varargs) Tj .4 .4 .4 rg (=) Tj 0 .501961 0 rg (None) Tj 0 0 0 rg (,) Tj ( ) Tj (keywords) Tj .4 .4 .4 rg (=) Tj 0 .501961 0 rg (None) Tj 0 0 0 rg (,) Tj ( ) Tj (defaults) Tj .4 .4 .4 rg (=) Tj 0 .501961 0 rg (None) Tj 0 0 0 rg (\)) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 414.4236 cm

+q

+BT 1 0 0 1 0 3.5 Tm 21 TL /F2 17.5 Tf 0 0 0 rg (A ) Tj /F3 17.5 Tf (trace ) Tj /F2 17.5 Tf (decorator) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 384.4236 cm

+q

+BT 1 0 0 1 0 14 Tm .479398 Tw 12 TL /F1 10 Tf 0 0 0 rg (As an additional example, here is how you can define a trivial ) Tj /F4 10 Tf (trace ) Tj /F1 10 Tf (decorator, which prints a message) Tj T* 0 Tw (everytime the traced function is called:) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 327.2236 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 48 re B*

+Q

+q

+BT 1 0 0 1 0 26 Tm 12 TL /F3 10 Tf 0 .501961 0 rg (def) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 0 1 rg (_trace) Tj 0 0 0 rg (\() Tj (f) Tj (,) Tj ( ) Tj .4 .4 .4 rg (*) Tj 0 0 0 rg (args) Tj (,) Tj ( ) Tj .4 .4 .4 rg (**) Tj 0 0 0 rg (kw) Tj (\):) Tj  T* (    ) Tj /F3 10 Tf 0 .501961 0 rg (print) Tj /F4 10 Tf 0 0 0 rg ( ) Tj .729412 .129412 .129412 rg ("calling ) Tj /F3 10 Tf .733333 .4 .533333 rg (%s) Tj /F4 10 Tf .729412 .129412 .129412 rg ( with args ) Tj /F3 10 Tf .733333 .4 .533333 rg (%s) Tj /F4 10 Tf .729412 .129412 .129412 rg (, ) Tj /F3 10 Tf .733333 .4 .533333 rg (%s) Tj /F4 10 Tf .729412 .129412 .129412 rg (") Tj 0 0 0 rg ( ) Tj .4 .4 .4 rg (%) Tj 0 0 0 rg ( ) Tj (\() Tj (f) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (__name__) Tj (,) Tj ( ) Tj (args) Tj (,) Tj ( ) Tj (kw) Tj (\)) Tj  T* (    ) Tj /F3 10 Tf 0 .501961 0 rg (return) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (f) Tj (\() Tj .4 .4 .4 rg (*) Tj 0 0 0 rg (args) Tj (,) Tj ( ) Tj .4 .4 .4 rg (**) Tj 0 0 0 rg (kw) Tj (\)) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 282.0236 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 36 re B*

+Q

+q

+BT 1 0 0 1 0 14 Tm 12 TL /F3 10 Tf 0 .501961 0 rg (def) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 0 1 rg (trace) Tj 0 0 0 rg (\() Tj (f) Tj (\):) Tj  T* (    ) Tj /F3 10 Tf 0 .501961 0 rg (return) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (decorator) Tj (\() Tj (_trace) Tj (,) Tj ( ) Tj (f) Tj (\)) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 262.0236 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 2 Tm /F1 10 Tf 12 TL (Here is an example of usage:) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 204.8236 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 48 re B*

+Q

+q

+BT 1 0 0 1 0 26 Tm 12 TL /F4 10 Tf .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj .666667 .133333 1 rg (@trace) Tj 0 0 0 rg  T* .4 .4 .4 rg (...) Tj 0 0 0 rg ( ) Tj /F3 10 Tf 0 .501961 0 rg (def) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 0 1 rg (f1) Tj 0 0 0 rg (\() Tj (x) Tj (\):) Tj  T* .4 .4 .4 rg (...) Tj 0 0 0 rg (     ) Tj /F3 10 Tf 0 .501961 0 rg (pass) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 184.8236 cm

+q

+BT 1 0 0 1 0 2 Tm 12 TL /F1 10 Tf 0 0 0 rg (It is immediate to verify that ) Tj /F4 10 Tf (f1 ) Tj /F1 10 Tf (works) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 139.6236 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 36 re B*

+Q

+q

+BT 1 0 0 1 0 14 Tm 12 TL /F4 10 Tf .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj (f1) Tj (\() Tj .4 .4 .4 rg (0) Tj 0 0 0 rg (\)) Tj  T* (calling) Tj ( ) Tj (f1) Tj ( ) Tj /F3 10 Tf 0 .501961 0 rg (with) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (args) Tj ( ) Tj (\() Tj .4 .4 .4 rg (0) Tj 0 0 0 rg (,\),) Tj ( ) Tj ({}) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 119.6236 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 2 Tm /F1 10 Tf 12 TL (and it that it has the correct signature:) Tj T* ET

+Q

+Q

+ 

+endstream

+endobj

+% 'R89': class PDFStream 

+89 0 obj

+% page stream

+<< /Length 8852 >>

+stream

+1 0 0 1 0 0 cm  BT /F1 12 Tf 14.4 TL ET

+q

+1 0 0 1 62.69291 727.8236 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 36 re B*

+Q

+q

+BT 1 0 0 1 0 14 Tm 12 TL /F4 10 Tf .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj /F3 10 Tf 0 .501961 0 rg (print) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (getargspec) Tj (\() Tj (f1) Tj (\)) Tj  T* (ArgSpec) Tj (\() Tj (args) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ([) Tj .729412 .129412 .129412 rg ('x') Tj 0 0 0 rg (],) Tj ( ) Tj (varargs) Tj .4 .4 .4 rg (=) Tj 0 .501961 0 rg (None) Tj 0 0 0 rg (,) Tj ( ) Tj (keywords) Tj .4 .4 .4 rg (=) Tj 0 .501961 0 rg (None) Tj 0 0 0 rg (,) Tj ( ) Tj (defaults) Tj .4 .4 .4 rg (=) Tj 0 .501961 0 rg (None) Tj 0 0 0 rg (\)) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 707.8236 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 2 Tm /F1 10 Tf 12 TL (The same decorator works with functions of any signature:) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 579.978 cm

+q

+q

+.988825 0 0 .988825 0 0 cm

+q

+1 0 0 1 6.6 6.674587 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 474 120 re B*

+Q

+q

+BT 1 0 0 1 0 98 Tm 12 TL /F4 10 Tf .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj .666667 .133333 1 rg (@trace) Tj 0 0 0 rg  T* .4 .4 .4 rg (...) Tj 0 0 0 rg ( ) Tj /F3 10 Tf 0 .501961 0 rg (def) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 0 1 rg (f) Tj 0 0 0 rg (\() Tj (x) Tj (,) Tj ( ) Tj (y) Tj .4 .4 .4 rg (=) Tj (1) Tj 0 0 0 rg (,) Tj ( ) Tj (z) Tj .4 .4 .4 rg (=) Tj (2) Tj 0 0 0 rg (,) Tj ( ) Tj .4 .4 .4 rg (*) Tj 0 0 0 rg (args) Tj (,) Tj ( ) Tj .4 .4 .4 rg (**) Tj 0 0 0 rg (kw) Tj (\):) Tj  T* .4 .4 .4 rg (...) Tj 0 0 0 rg (     ) Tj /F3 10 Tf 0 .501961 0 rg (pass) Tj /F4 10 Tf 0 0 0 rg  T*  T* .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj (f) Tj (\() Tj .4 .4 .4 rg (0) Tj 0 0 0 rg (,) Tj ( ) Tj .4 .4 .4 rg (3) Tj 0 0 0 rg (\)) Tj  T* (calling) Tj ( ) Tj (f) Tj ( ) Tj /F3 10 Tf 0 .501961 0 rg (with) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (args) Tj ( ) Tj (\() Tj .4 .4 .4 rg (0) Tj 0 0 0 rg (,) Tj ( ) Tj .4 .4 .4 rg (3) Tj 0 0 0 rg (,) Tj ( ) Tj .4 .4 .4 rg (2) Tj 0 0 0 rg (\),) Tj ( ) Tj ({}) Tj  T*  T* .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj /F3 10 Tf 0 .501961 0 rg (print) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (getargspec) Tj (\() Tj (f) Tj (\)) Tj  T* (ArgSpec) Tj (\() Tj (args) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ([) Tj .729412 .129412 .129412 rg ('x') Tj 0 0 0 rg (,) Tj ( ) Tj .729412 .129412 .129412 rg ('y') Tj 0 0 0 rg (,) Tj ( ) Tj .729412 .129412 .129412 rg ('z') Tj 0 0 0 rg (],) Tj ( ) Tj (varargs) Tj .4 .4 .4 rg (=) Tj .729412 .129412 .129412 rg ('args') Tj 0 0 0 rg (,) Tj ( ) Tj (keywords) Tj .4 .4 .4 rg (=) Tj .729412 .129412 .129412 rg ('kw') Tj 0 0 0 rg (,) Tj ( ) Tj (defaults) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg (\() Tj .4 .4 .4 rg (1) Tj 0 0 0 rg (,) Tj ( ) Tj .4 .4 .4 rg (2) Tj 0 0 0 rg (\)\)) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 559.978 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 2 Tm /F1 10 Tf 12 TL (That includes even functions with exotic signatures like the following:) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 442.778 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 108 re B*

+Q

+q

+BT 1 0 0 1 0 86 Tm 12 TL /F4 10 Tf .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj .666667 .133333 1 rg (@trace) Tj 0 0 0 rg  T* .4 .4 .4 rg (...) Tj 0 0 0 rg ( ) Tj /F3 10 Tf 0 .501961 0 rg (def) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 0 1 rg (exotic_signature) Tj 0 0 0 rg (\(\() Tj (x) Tj (,) Tj ( ) Tj (y) Tj (\)) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg (\() Tj .4 .4 .4 rg (1) Tj 0 0 0 rg (,) Tj .4 .4 .4 rg (2) Tj 0 0 0 rg (\)\):) Tj ( ) Tj /F3 10 Tf 0 .501961 0 rg (return) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (x) Tj .4 .4 .4 rg (+) Tj 0 0 0 rg (y) Tj  T*  T* .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj /F3 10 Tf 0 .501961 0 rg (print) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (getargspec) Tj (\() Tj (exotic_signature) Tj (\)) Tj  T* (ArgSpec) Tj (\() Tj (args) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ([[) Tj .729412 .129412 .129412 rg ('x') Tj 0 0 0 rg (,) Tj ( ) Tj .729412 .129412 .129412 rg ('y') Tj 0 0 0 rg (]],) Tj ( ) Tj (varargs) Tj .4 .4 .4 rg (=) Tj 0 .501961 0 rg (None) Tj 0 0 0 rg (,) Tj ( ) Tj (keywords) Tj .4 .4 .4 rg (=) Tj 0 .501961 0 rg (None) Tj 0 0 0 rg (,) Tj ( ) Tj (defaults) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg (\(\() Tj .4 .4 .4 rg (1) Tj 0 0 0 rg (,) Tj ( ) Tj .4 .4 .4 rg (2) Tj 0 0 0 rg (\),\)\)) Tj  T* .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj (exotic_signature) Tj (\(\)) Tj  T* (calling) Tj ( ) Tj (exotic_signature) Tj ( ) Tj /F3 10 Tf 0 .501961 0 rg (with) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (args) Tj ( ) Tj (\(\() Tj .4 .4 .4 rg (1) Tj 0 0 0 rg (,) Tj ( ) Tj .4 .4 .4 rg (2) Tj 0 0 0 rg (\),\),) Tj ( ) Tj ({}) Tj  T* .4 .4 .4 rg (3) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 410.778 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 14 Tm /F1 10 Tf 12 TL .84561 Tw (Notice that the support for exotic signatures has been deprecated in Python 2.6 and removed in Python) Tj T* 0 Tw (3.0.) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 377.778 cm

+q

+BT 1 0 0 1 0 3.5 Tm 21 TL /F3 17.5 Tf 0 0 0 rg (decorator ) Tj /F2 17.5 Tf (is a decorator) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 275.778 cm

+q

+BT 1 0 0 1 0 86 Tm .643876 Tw 12 TL /F1 10 Tf 0 0 0 rg (It may be annoying to write a caller function \(like the ) Tj /F4 10 Tf (_trace ) Tj /F1 10 Tf (function above\) and then a trivial wrapper) Tj T* 0 Tw 1.510888 Tw (\() Tj /F4 10 Tf (def) Tj ( ) Tj (trace\(f\):) Tj ( ) Tj (return) Tj ( ) Tj (decorator\(_trace,) Tj ( ) Tj (f\)) Tj /F1 10 Tf (\) every time. For this reason, the ) Tj /F4 10 Tf (decorator) Tj T* 0 Tw .334269 Tw /F1 10 Tf (module provides an easy shortcut to convert the caller function into a signature-preserving decorator: you) Tj T* 0 Tw 7.364269 Tw (can just call ) Tj /F4 10 Tf (decorator ) Tj /F1 10 Tf (with a single argument. In our example you can just write) Tj T* 0 Tw .951647 Tw /F4 10 Tf (trace) Tj ( ) Tj (=) Tj ( ) Tj (decorator\(_trace\)) Tj /F1 10 Tf (. The ) Tj /F4 10 Tf (decorator ) Tj /F1 10 Tf (function can also be used as a signature-changing) Tj T* 0 Tw 1.077752 Tw (decorator, just as ) Tj /F4 10 Tf (classmethod ) Tj /F1 10 Tf (and ) Tj /F4 10 Tf (staticmethod) Tj /F1 10 Tf (. However, ) Tj /F4 10 Tf (classmethod ) Tj /F1 10 Tf (and ) Tj /F4 10 Tf (staticmethod) Tj T* 0 Tw .531797 Tw /F1 10 Tf (return generic objects which are not callable, while ) Tj /F4 10 Tf (decorator ) Tj /F1 10 Tf (returns signature-preserving decorators,) Tj T* 0 Tw (i.e. functions of a single argument. For instance, you can write directly) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 206.578 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 60 re B*

+Q

+q

+BT 1 0 0 1 0 38 Tm 12 TL /F4 10 Tf .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj .666667 .133333 1 rg (@decorator) Tj 0 0 0 rg  T* .4 .4 .4 rg (...) Tj 0 0 0 rg ( ) Tj /F3 10 Tf 0 .501961 0 rg (def) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 0 1 rg (trace) Tj 0 0 0 rg (\() Tj (f) Tj (,) Tj ( ) Tj .4 .4 .4 rg (*) Tj 0 0 0 rg (args) Tj (,) Tj ( ) Tj .4 .4 .4 rg (**) Tj 0 0 0 rg (kw) Tj (\):) Tj  T* .4 .4 .4 rg (...) Tj 0 0 0 rg (     ) Tj /F3 10 Tf 0 .501961 0 rg (print) Tj /F4 10 Tf 0 0 0 rg ( ) Tj .729412 .129412 .129412 rg ("calling ) Tj /F3 10 Tf .733333 .4 .533333 rg (%s) Tj /F4 10 Tf .729412 .129412 .129412 rg ( with args ) Tj /F3 10 Tf .733333 .4 .533333 rg (%s) Tj /F4 10 Tf .729412 .129412 .129412 rg (, ) Tj /F3 10 Tf .733333 .4 .533333 rg (%s) Tj /F4 10 Tf .729412 .129412 .129412 rg (") Tj 0 0 0 rg ( ) Tj .4 .4 .4 rg (%) Tj 0 0 0 rg ( ) Tj (\() Tj (f) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (func_name) Tj (,) Tj ( ) Tj (args) Tj (,) Tj ( ) Tj (kw) Tj (\)) Tj  T* .4 .4 .4 rg (...) Tj 0 0 0 rg (     ) Tj /F3 10 Tf 0 .501961 0 rg (return) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (f) Tj (\() Tj .4 .4 .4 rg (*) Tj 0 0 0 rg (args) Tj (,) Tj ( ) Tj .4 .4 .4 rg (**) Tj 0 0 0 rg (kw) Tj (\)) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 174.578 cm

+q

+BT 1 0 0 1 0 14 Tm 1.806654 Tw 12 TL /F1 10 Tf 0 0 0 rg (and now ) Tj /F4 10 Tf (trace ) Tj /F1 10 Tf (will be a decorator. Actually ) Tj /F4 10 Tf (trace ) Tj /F1 10 Tf (is a ) Tj /F4 10 Tf (partial ) Tj /F1 10 Tf (object which can be used as a) Tj T* 0 Tw (decorator:) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 129.378 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 36 re B*

+Q

+q

+BT 1 0 0 1 0 14 Tm 12 TL /F4 10 Tf .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj (trace) Tj  T* .4 .4 .4 rg (<) Tj 0 0 0 rg (function) Tj ( ) Tj (trace) Tj ( ) Tj (at) Tj ( ) Tj .4 .4 .4 rg (0) Tj 0 0 0 rg (x) Tj .4 .4 .4 rg (...) Tj (>) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 109.378 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 2 Tm /F1 10 Tf 12 TL (Here is an example of usage:) Tj T* ET

+Q

+Q

+ 

+endstream

+endobj

+% 'R90': class PDFStream 

+90 0 obj

+% page stream

+<< /Length 7156 >>

+stream

+1 0 0 1 0 0 cm  BT /F1 12 Tf 14.4 TL ET

+q

+1 0 0 1 62.69291 691.8236 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 72 re B*

+Q

+q

+BT 1 0 0 1 0 50 Tm 12 TL /F4 10 Tf .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj .666667 .133333 1 rg (@trace) Tj 0 0 0 rg  T* .4 .4 .4 rg (...) Tj 0 0 0 rg ( ) Tj /F3 10 Tf 0 .501961 0 rg (def) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 0 1 rg (func) Tj 0 0 0 rg (\(\):) Tj ( ) Tj /F3 10 Tf 0 .501961 0 rg (pass) Tj /F4 10 Tf 0 0 0 rg  T*  T* .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj (func) Tj (\(\)) Tj  T* (calling) Tj ( ) Tj (func) Tj ( ) Tj /F3 10 Tf 0 .501961 0 rg (with) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (args) Tj ( ) Tj (\(\),) Tj ( ) Tj ({}) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 659.8236 cm

+q

+BT 1 0 0 1 0 14 Tm 2.44686 Tw 12 TL /F1 10 Tf 0 0 0 rg (If you are using an old Python version \(Python 2.4\) the ) Tj /F4 10 Tf (decorator ) Tj /F1 10 Tf (module provides a poor man) Tj T* 0 Tw (replacement for ) Tj /F4 10 Tf (functools.partial) Tj /F1 10 Tf (.) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 626.8236 cm

+q

+BT 1 0 0 1 0 3.5 Tm 21 TL /F3 17.5 Tf 0 0 0 rg (blocking) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 584.8236 cm

+q

+BT 1 0 0 1 0 26 Tm 1.224692 Tw 12 TL /F1 10 Tf 0 0 0 rg (Sometimes one has to deal with blocking resources, such as ) Tj /F4 10 Tf (stdin) Tj /F1 10 Tf (, and sometimes it is best to have) Tj T* 0 Tw .266235 Tw (back a "busy" message than to block everything. This behavior can be implemented with a suitable family) Tj T* 0 Tw (of decorators, where the parameter is the busy message:) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 407.6236 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 168 re B*

+Q

+q

+BT 1 0 0 1 0 146 Tm 12 TL /F3 10 Tf 0 .501961 0 rg (def) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 0 1 rg (blocking) Tj 0 0 0 rg (\() Tj (not_avail) Tj (\):) Tj  T* (    ) Tj /F3 10 Tf 0 .501961 0 rg (def) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 0 1 rg (blocking) Tj 0 0 0 rg (\() Tj (f) Tj (,) Tj ( ) Tj .4 .4 .4 rg (*) Tj 0 0 0 rg (args) Tj (,) Tj ( ) Tj .4 .4 .4 rg (**) Tj 0 0 0 rg (kw) Tj (\):) Tj  T* (        ) Tj /F3 10 Tf 0 .501961 0 rg (if) Tj /F4 10 Tf 0 0 0 rg ( ) Tj /F3 10 Tf .666667 .133333 1 rg (not) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 .501961 0 rg (hasattr) Tj 0 0 0 rg (\() Tj (f) Tj (,) Tj ( ) Tj .729412 .129412 .129412 rg ("thread") Tj 0 0 0 rg (\):) Tj ( ) Tj /F6 10 Tf .25098 .501961 .501961 rg (# no thread running) Tj /F4 10 Tf 0 0 0 rg  T* (            ) Tj /F3 10 Tf 0 .501961 0 rg (def) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 0 1 rg (set_result) Tj 0 0 0 rg (\(\):) Tj ( ) Tj (f) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (result) Tj ( ) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ( ) Tj (f) Tj (\() Tj .4 .4 .4 rg (*) Tj 0 0 0 rg (args) Tj (,) Tj ( ) Tj .4 .4 .4 rg (**) Tj 0 0 0 rg (kw) Tj (\)) Tj  T* (            ) Tj (f) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (thread) Tj ( ) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ( ) Tj (threading) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (Thread) Tj (\() Tj 0 .501961 0 rg (None) Tj 0 0 0 rg (,) Tj ( ) Tj (set_result) Tj (\)) Tj  T* (            ) Tj (f) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (thread) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (start) Tj (\(\)) Tj  T* (            ) Tj /F3 10 Tf 0 .501961 0 rg (return) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (not_avail) Tj  T* (        ) Tj /F3 10 Tf 0 .501961 0 rg (elif) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (f) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (thread) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (isAlive) Tj (\(\):) Tj  T* (            ) Tj /F3 10 Tf 0 .501961 0 rg (return) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (not_avail) Tj  T* (        ) Tj /F3 10 Tf 0 .501961 0 rg (else) Tj /F4 10 Tf 0 0 0 rg (:) Tj ( ) Tj /F6 10 Tf .25098 .501961 .501961 rg (# the thread is ended, return the stored result) Tj /F4 10 Tf 0 0 0 rg  T* (            ) Tj /F3 10 Tf 0 .501961 0 rg (del) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (f) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (thread) Tj  T* (            ) Tj /F3 10 Tf 0 .501961 0 rg (return) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (f) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (result) Tj  T* (    ) Tj /F3 10 Tf 0 .501961 0 rg (return) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (decorator) Tj (\() Tj (blocking) Tj (\)) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 375.6236 cm

+q

+BT 1 0 0 1 0 14 Tm 1.010651 Tw 12 TL /F1 10 Tf 0 0 0 rg (Functions decorated with ) Tj /F4 10 Tf (blocking ) Tj /F1 10 Tf (will return a busy message if the resource is unavailable, and the) Tj T* 0 Tw (intended result if the resource is available. For instance:) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 126.4236 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 240 re B*

+Q

+q

+BT 1 0 0 1 0 218 Tm 12 TL /F4 10 Tf .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj .666667 .133333 1 rg (@blocking) Tj 0 0 0 rg (\() Tj .729412 .129412 .129412 rg ("Please wait ...") Tj 0 0 0 rg (\)) Tj  T* .4 .4 .4 rg (...) Tj 0 0 0 rg ( ) Tj /F3 10 Tf 0 .501961 0 rg (def) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 0 1 rg (read_data) Tj 0 0 0 rg (\(\):) Tj  T* .4 .4 .4 rg (...) Tj 0 0 0 rg (     ) Tj (time) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (sleep) Tj (\() Tj .4 .4 .4 rg (3) Tj 0 0 0 rg (\)) Tj ( ) Tj /F6 10 Tf .25098 .501961 .501961 rg (# simulate a blocking resource) Tj /F4 10 Tf 0 0 0 rg  T* .4 .4 .4 rg (...) Tj 0 0 0 rg (     ) Tj /F3 10 Tf 0 .501961 0 rg (return) Tj /F4 10 Tf 0 0 0 rg ( ) Tj .729412 .129412 .129412 rg ("some data") Tj 0 0 0 rg  T*  T* .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj /F3 10 Tf 0 .501961 0 rg (print) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (read_data) Tj (\(\)) Tj ( ) Tj /F6 10 Tf .25098 .501961 .501961 rg (# data is not available yet) Tj /F4 10 Tf 0 0 0 rg  T* (Please) Tj ( ) Tj (wait) Tj ( ) Tj .4 .4 .4 rg (...) Tj 0 0 0 rg  T*  T* .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj (time) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (sleep) Tj (\() Tj .4 .4 .4 rg (1) Tj 0 0 0 rg (\)) Tj  T* .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj /F3 10 Tf 0 .501961 0 rg (print) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (read_data) Tj (\(\)) Tj ( ) Tj /F6 10 Tf .25098 .501961 .501961 rg (# data is not available yet) Tj /F4 10 Tf 0 0 0 rg  T* (Please) Tj ( ) Tj (wait) Tj ( ) Tj .4 .4 .4 rg (...) Tj 0 0 0 rg  T*  T* .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj (time) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (sleep) Tj (\() Tj .4 .4 .4 rg (1) Tj 0 0 0 rg (\)) Tj  T* .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj /F3 10 Tf 0 .501961 0 rg (print) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (read_data) Tj (\(\)) Tj ( ) Tj /F6 10 Tf .25098 .501961 .501961 rg (# data is not available yet) Tj /F4 10 Tf 0 0 0 rg  T* (Please) Tj ( ) Tj (wait) Tj ( ) Tj .4 .4 .4 rg (...) Tj 0 0 0 rg  T*  T* .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj (time) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (sleep) Tj (\() Tj .4 .4 .4 rg (1.1) Tj 0 0 0 rg (\)) Tj ( ) Tj /F6 10 Tf .25098 .501961 .501961 rg (# after 3.1 seconds, data is available) Tj /F4 10 Tf 0 0 0 rg  T* .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj /F3 10 Tf 0 .501961 0 rg (print) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (read_data) Tj (\(\)) Tj  T* (some) Tj ( ) Tj (data) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+ 

+endstream

+endobj

+% 'R91': class PDFStream 

+91 0 obj

+% page stream

+<< /Length 7381 >>

+stream

+1 0 0 1 0 0 cm  BT /F1 12 Tf 14.4 TL ET

+q

+1 0 0 1 62.69291 744.0236 cm

+q

+BT 1 0 0 1 0 3.5 Tm 21 TL /F3 17.5 Tf 0 0 0 rg (async) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 702.0236 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 26 Tm /F1 10 Tf 12 TL 1.647485 Tw (We have just seen an examples of a simple decorator factory, implemented as a function returning a) Tj T* 0 Tw .29784 Tw (decorator. For more complex situations, it is more convenient to implement decorator factories as classes) Tj T* 0 Tw (returning callable objects that can be converted into decorators.) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 636.0236 cm

+q

+BT 1 0 0 1 0 50 Tm 2.853876 Tw 12 TL /F1 10 Tf 0 0 0 rg (As an example, here will I show a decorator which is able to convert a blocking function into an) Tj T* 0 Tw 2.477126 Tw (asynchronous function. The function, when called, is executed in a separate thread. Moreover, it is) Tj T* 0 Tw .288443 Tw (possible to set three callbacks ) Tj /F4 10 Tf (on_success) Tj /F1 10 Tf (, ) Tj /F4 10 Tf (on_failure ) Tj /F1 10 Tf (and ) Tj /F4 10 Tf (on_closing) Tj /F1 10 Tf (, to specify how to manage) Tj T* 0 Tw 1.854724 Tw (the function call \(of course the code here is just an example, it is not a recommended way of doing) Tj T* 0 Tw (multi-threaded programming\). The implementation is the following:) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 578.8236 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 48 re B*

+Q

+q

+BT 1 0 0 1 0 26 Tm 12 TL /F3 10 Tf 0 .501961 0 rg (def) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 0 1 rg (on_success) Tj 0 0 0 rg (\() Tj (result) Tj (\):) Tj ( ) Tj /F6 10 Tf .25098 .501961 .501961 rg (# default implementation) Tj /F4 10 Tf 0 0 0 rg  T* (    ) Tj .729412 .129412 .129412 rg ("Called on the result of the function") Tj 0 0 0 rg  T* (    ) Tj /F3 10 Tf 0 .501961 0 rg (return) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (result) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 521.6236 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 48 re B*

+Q

+q

+BT 1 0 0 1 0 26 Tm 12 TL /F3 10 Tf 0 .501961 0 rg (def) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 0 1 rg (on_failure) Tj 0 0 0 rg (\() Tj (exc_info) Tj (\):) Tj ( ) Tj /F6 10 Tf .25098 .501961 .501961 rg (# default implementation) Tj /F4 10 Tf 0 0 0 rg  T* (    ) Tj .729412 .129412 .129412 rg ("Called if the function fails") Tj 0 0 0 rg  T* (    ) Tj /F3 10 Tf 0 .501961 0 rg (pass) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 464.4236 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 48 re B*

+Q

+q

+BT 1 0 0 1 0 26 Tm 12 TL /F3 10 Tf 0 .501961 0 rg (def) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 0 1 rg (on_closing) Tj 0 0 0 rg (\(\):) Tj ( ) Tj /F6 10 Tf .25098 .501961 .501961 rg (# default implementation) Tj /F4 10 Tf 0 0 0 rg  T* (    ) Tj .729412 .129412 .129412 rg ("Called at the end, both in case of success and failure") Tj 0 0 0 rg  T* (    ) Tj /F3 10 Tf 0 .501961 0 rg (pass) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 83.22362 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 372 re B*

+Q

+q

+BT 1 0 0 1 0 350 Tm 12 TL /F3 10 Tf 0 .501961 0 rg (class) Tj /F4 10 Tf 0 0 0 rg ( ) Tj /F3 10 Tf 0 0 1 rg (Async) Tj /F4 10 Tf 0 0 0 rg (\() Tj 0 .501961 0 rg (object) Tj 0 0 0 rg (\):) Tj  T* (    ) Tj /F6 10 Tf .729412 .129412 .129412 rg (""") Tj T* (    A decorator converting blocking functions into asynchronous) Tj T* (    functions, by using threads or processes. Examples:) Tj T*  T* (    async_with_threads =  Async\(threading.Thread\)) Tj T* (    async_with_processes =  Async\(multiprocessing.Process\)) Tj T* (    """) Tj /F4 10 Tf 0 0 0 rg  T*  T* (    ) Tj /F3 10 Tf 0 .501961 0 rg (def) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 0 1 rg (__init__) Tj 0 0 0 rg (\() Tj 0 .501961 0 rg (self) Tj 0 0 0 rg (,) Tj ( ) Tj (threadfactory) Tj (,) Tj ( ) Tj (on_success) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg (on_success) Tj (,) Tj  T* (                 ) Tj (on_failure) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg (on_failure) Tj (,) Tj ( ) Tj (on_closing) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg (on_closing) Tj (\):) Tj  T* (        ) Tj 0 .501961 0 rg (self) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (threadfactory) Tj ( ) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ( ) Tj (threadfactory) Tj  T* (        ) Tj 0 .501961 0 rg (self) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (on_success) Tj ( ) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ( ) Tj (on_success) Tj  T* (        ) Tj 0 .501961 0 rg (self) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (on_failure) Tj ( ) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ( ) Tj (on_failure) Tj  T* (        ) Tj 0 .501961 0 rg (self) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (on_closing) Tj ( ) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ( ) Tj (on_closing) Tj  T*  T* (    ) Tj /F3 10 Tf 0 .501961 0 rg (def) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 0 1 rg (__call__) Tj 0 0 0 rg (\() Tj 0 .501961 0 rg (self) Tj 0 0 0 rg (,) Tj ( ) Tj (func) Tj (,) Tj ( ) Tj .4 .4 .4 rg (*) Tj 0 0 0 rg (args) Tj (,) Tj ( ) Tj .4 .4 .4 rg (**) Tj 0 0 0 rg (kw) Tj (\):) Tj  T* (        ) Tj /F3 10 Tf 0 .501961 0 rg (try) Tj /F4 10 Tf 0 0 0 rg (:) Tj  T* (            ) Tj (counter) Tj ( ) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ( ) Tj (func) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (counter) Tj  T* (        ) Tj /F3 10 Tf 0 .501961 0 rg (except) Tj /F4 10 Tf 0 0 0 rg ( ) Tj /F3 10 Tf .823529 .254902 .227451 rg (AttributeError) Tj /F4 10 Tf 0 0 0 rg (:) Tj ( ) Tj /F6 10 Tf .25098 .501961 .501961 rg (# instantiate the counter at the first call) Tj /F4 10 Tf 0 0 0 rg  T* (            ) Tj (counter) Tj ( ) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ( ) Tj (func) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (counter) Tj ( ) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ( ) Tj (itertools) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (count) Tj (\() Tj .4 .4 .4 rg (1) Tj 0 0 0 rg (\)) Tj  T* (        ) Tj (name) Tj ( ) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ( ) Tj .729412 .129412 .129412 rg (') Tj /F3 10 Tf .733333 .4 .533333 rg (%s) Tj /F4 10 Tf .729412 .129412 .129412 rg (-) Tj /F3 10 Tf .733333 .4 .533333 rg (%s) Tj /F4 10 Tf .729412 .129412 .129412 rg (') Tj 0 0 0 rg ( ) Tj .4 .4 .4 rg (%) Tj 0 0 0 rg ( ) Tj (\() Tj (func) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (__name__) Tj (,) Tj ( ) Tj (counter) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (next) Tj (\(\)\)) Tj  T* (        ) Tj /F3 10 Tf 0 .501961 0 rg (def) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 0 1 rg (func_wrapper) Tj 0 0 0 rg (\(\):) Tj  T* (            ) Tj /F3 10 Tf 0 .501961 0 rg (try) Tj /F4 10 Tf 0 0 0 rg (:) Tj  T* (                ) Tj (result) Tj ( ) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ( ) Tj (func) Tj (\() Tj .4 .4 .4 rg (*) Tj 0 0 0 rg (args) Tj (,) Tj ( ) Tj .4 .4 .4 rg (**) Tj 0 0 0 rg (kw) Tj (\)) Tj  T* (            ) Tj /F3 10 Tf 0 .501961 0 rg (except) Tj /F4 10 Tf 0 0 0 rg (:) Tj  T* (                ) Tj 0 .501961 0 rg (self) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (on_failure) Tj (\() Tj (sys) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (exc_info) Tj (\(\)\)) Tj  T* (            ) Tj /F3 10 Tf 0 .501961 0 rg (else) Tj /F4 10 Tf 0 0 0 rg (:) Tj  T* (                ) Tj /F3 10 Tf 0 .501961 0 rg (return) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 .501961 0 rg (self) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (on_success) Tj (\() Tj (result) Tj (\)) Tj  T* (            ) Tj /F3 10 Tf 0 .501961 0 rg (finally) Tj /F4 10 Tf 0 0 0 rg (:) Tj  T* ET

+Q

+Q

+Q

+Q

+Q

+ 

+endstream

+endobj

+% 'R92': class PDFStream 

+92 0 obj

+% page stream

+<< /Length 7221 >>

+stream

+1 0 0 1 0 0 cm  BT /F1 12 Tf 14.4 TL ET

+q

+1 0 0 1 62.69291 703.8236 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 60 re B*

+Q

+q

+BT 1 0 0 1 0 38 Tm 12 TL /F4 10 Tf 0 0 0 rg (                ) Tj 0 .501961 0 rg (self) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (on_closing) Tj (\(\)) Tj  T* (        ) Tj (thread) Tj ( ) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ( ) Tj 0 .501961 0 rg (self) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (threadfactory) Tj (\() Tj 0 .501961 0 rg (None) Tj 0 0 0 rg (,) Tj ( ) Tj (func_wrapper) Tj (,) Tj ( ) Tj (name) Tj (\)) Tj  T* (        ) Tj (thread) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (start) Tj (\(\)) Tj  T* (        ) Tj /F3 10 Tf 0 .501961 0 rg (return) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (thread) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 671.8236 cm

+q

+BT 1 0 0 1 0 14 Tm .865984 Tw 12 TL /F1 10 Tf 0 0 0 rg (The decorated function returns the current execution thread, which can be stored and checked later, for) Tj T* 0 Tw (instance to verify that the thread ) Tj /F4 10 Tf (.isAlive\(\)) Tj /F1 10 Tf (.) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 629.8236 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 26 Tm /F1 10 Tf 12 TL .691654 Tw (Here is an example of usage. Suppose one wants to write some data to an external resource which can) Tj T* 0 Tw .21683 Tw (be accessed by a single user at once \(for instance a printer\). Then the access to the writing function must) Tj T* 0 Tw (be locked. Here is a minimalistic example:) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 476.6236 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 144 re B*

+Q

+q

+BT 1 0 0 1 0 122 Tm 12 TL /F4 10 Tf .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj (async) Tj ( ) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ( ) Tj (decorator) Tj (\() Tj (Async) Tj (\() Tj (threading) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (Thread) Tj (\)\)) Tj  T*  T* .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj (datalist) Tj ( ) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ( ) Tj ([]) Tj ( ) Tj /F6 10 Tf .25098 .501961 .501961 rg (# for simplicity the written data are stored into a list.) Tj /F4 10 Tf 0 0 0 rg  T*  T* .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj .666667 .133333 1 rg (@async) Tj 0 0 0 rg  T* .4 .4 .4 rg (...) Tj 0 0 0 rg ( ) Tj /F3 10 Tf 0 .501961 0 rg (def) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 0 1 rg (write) Tj 0 0 0 rg (\() Tj (data) Tj (\):) Tj  T* .4 .4 .4 rg (...) Tj 0 0 0 rg (     ) Tj /F6 10 Tf .25098 .501961 .501961 rg (# append data to the datalist by locking) Tj /F4 10 Tf 0 0 0 rg  T* .4 .4 .4 rg (...) Tj 0 0 0 rg (     ) Tj /F3 10 Tf 0 .501961 0 rg (with) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (threading) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (Lock) Tj (\(\):) Tj  T* .4 .4 .4 rg (...) Tj 0 0 0 rg (         ) Tj (time) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (sleep) Tj (\() Tj .4 .4 .4 rg (1) Tj 0 0 0 rg (\)) Tj ( ) Tj /F6 10 Tf .25098 .501961 .501961 rg (# emulate some long running operation) Tj /F4 10 Tf 0 0 0 rg  T* .4 .4 .4 rg (...) Tj 0 0 0 rg (         ) Tj (datalist) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (append) Tj (\() Tj (data) Tj (\)) Tj  T* .4 .4 .4 rg (...) Tj 0 0 0 rg (     ) Tj /F6 10 Tf .25098 .501961 .501961 rg (# other operations not requiring a lock here) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 444.6236 cm

+q

+BT 1 0 0 1 0 14 Tm .905868 Tw 12 TL /F1 10 Tf 0 0 0 rg (Each call to ) Tj /F4 10 Tf (write ) Tj /F1 10 Tf (will create a new writer thread, but there will be no synchronization problems since) Tj T* 0 Tw /F4 10 Tf (write ) Tj /F1 10 Tf (is locked.) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 279.4236 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 156 re B*

+Q

+q

+BT 1 0 0 1 0 134 Tm 12 TL /F4 10 Tf .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj (write) Tj (\() Tj .729412 .129412 .129412 rg ("data1") Tj 0 0 0 rg (\)) Tj  T* .4 .4 .4 rg (<) Tj 0 0 0 rg (Thread) Tj (\() Tj (write) Tj .4 .4 .4 rg (-) Tj (1) Tj 0 0 0 rg (,) Tj ( ) Tj (started) Tj .4 .4 .4 rg (...) Tj 0 0 0 rg (\)) Tj .4 .4 .4 rg (>) Tj 0 0 0 rg  T*  T* .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj (time) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (sleep) Tj (\() Tj .4 .4 .4 rg (.) Tj (1) Tj 0 0 0 rg (\)) Tj ( ) Tj /F6 10 Tf .25098 .501961 .501961 rg (# wait a bit, so we are sure data2 is written after data1) Tj /F4 10 Tf 0 0 0 rg  T*  T* .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj (write) Tj (\() Tj .729412 .129412 .129412 rg ("data2") Tj 0 0 0 rg (\)) Tj  T* .4 .4 .4 rg (<) Tj 0 0 0 rg (Thread) Tj (\() Tj (write) Tj .4 .4 .4 rg (-) Tj (2) Tj 0 0 0 rg (,) Tj ( ) Tj (started) Tj .4 .4 .4 rg (...) Tj 0 0 0 rg (\)) Tj .4 .4 .4 rg (>) Tj 0 0 0 rg  T*  T* .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj (time) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (sleep) Tj (\() Tj .4 .4 .4 rg (2) Tj 0 0 0 rg (\)) Tj ( ) Tj /F6 10 Tf .25098 .501961 .501961 rg (# wait for the writers to complete) Tj /F4 10 Tf 0 0 0 rg  T*  T* .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj /F3 10 Tf 0 .501961 0 rg (print) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (datalist) Tj  T* ([) Tj .729412 .129412 .129412 rg ('data1') Tj 0 0 0 rg (,) Tj ( ) Tj .729412 .129412 .129412 rg ('data2') Tj 0 0 0 rg (]) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 246.4236 cm

+q

+BT 1 0 0 1 0 3.5 Tm 21 TL /F2 17.5 Tf 0 0 0 rg (contextmanager) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 216.4236 cm

+q

+BT 1 0 0 1 0 14 Tm 2.685984 Tw 12 TL /F1 10 Tf 0 0 0 rg (For a long time Python had in its standard library a ) Tj /F4 10 Tf (contextmanager ) Tj /F1 10 Tf (decorator, able to convert) Tj T* 0 Tw (generator functions into ) Tj /F4 10 Tf (GeneratorContextManager ) Tj /F1 10 Tf (factories. For instance if you write) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 123.2236 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 84 re B*

+Q

+q

+BT 1 0 0 1 0 62 Tm 12 TL /F4 10 Tf .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj /F3 10 Tf 0 .501961 0 rg (from) Tj /F4 10 Tf 0 0 0 rg ( ) Tj /F3 10 Tf 0 0 1 rg (contextlib) Tj /F4 10 Tf 0 0 0 rg ( ) Tj /F3 10 Tf 0 .501961 0 rg (import) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (contextmanager) Tj  T* .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj .666667 .133333 1 rg (@contextmanager) Tj 0 0 0 rg  T* .4 .4 .4 rg (...) Tj 0 0 0 rg ( ) Tj /F3 10 Tf 0 .501961 0 rg (def) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 0 1 rg (before_after) Tj 0 0 0 rg (\() Tj (before) Tj (,) Tj ( ) Tj (after) Tj (\):) Tj  T* .4 .4 .4 rg (...) Tj 0 0 0 rg (     ) Tj /F3 10 Tf 0 .501961 0 rg (print) Tj /F4 10 Tf 0 0 0 rg (\() Tj (before) Tj (\)) Tj  T* .4 .4 .4 rg (...) Tj 0 0 0 rg (     ) Tj /F3 10 Tf 0 .501961 0 rg (yield) Tj /F4 10 Tf 0 0 0 rg  T* .4 .4 .4 rg (...) Tj 0 0 0 rg (     ) Tj /F3 10 Tf 0 .501961 0 rg (print) Tj /F4 10 Tf 0 0 0 rg (\() Tj (after) Tj (\)) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 91.22362 cm

+q

+BT 1 0 0 1 0 14 Tm .150888 Tw 12 TL /F1 10 Tf 0 0 0 rg (then ) Tj /F4 10 Tf (before_after ) Tj /F1 10 Tf (is a factory function returning ) Tj /F4 10 Tf (GeneratorContextManager ) Tj /F1 10 Tf (objects which can be) Tj T* 0 Tw (used with the ) Tj /F4 10 Tf (with ) Tj /F1 10 Tf (statement:) Tj T* ET

+Q

+Q

+ 

+endstream

+endobj

+% 'R93': class PDFStream 

+93 0 obj

+% page stream

+<< /Length 7180 >>

+stream

+1 0 0 1 0 0 cm  BT /F1 12 Tf 14.4 TL ET

+q

+1 0 0 1 62.69291 655.8236 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 108 re B*

+Q

+q

+BT 1 0 0 1 0 86 Tm 12 TL /F4 10 Tf .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj (ba) Tj ( ) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ( ) Tj (before_after) Tj (\() Tj .729412 .129412 .129412 rg ('BEFORE') Tj 0 0 0 rg (,) Tj ( ) Tj .729412 .129412 .129412 rg ('AFTER') Tj 0 0 0 rg (\)) Tj  T* .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj 0 .501961 0 rg (type) Tj 0 0 0 rg (\() Tj (ba) Tj (\)) Tj  T* .4 .4 .4 rg (<) Tj /F3 10 Tf 0 .501961 0 rg (class) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (') Tj /F3 10 Tf 0 0 1 rg (contextlib) Tj /F4 10 Tf .4 .4 .4 rg (.) Tj 0 0 0 rg (GeneratorContextManager) Tj .729412 .129412 .129412 rg (') Tj (>) Tj 0 0 0 rg  T* .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj /F3 10 Tf 0 .501961 0 rg (with) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (ba) Tj (:) Tj  T* .4 .4 .4 rg (...) Tj 0 0 0 rg (     ) Tj /F3 10 Tf 0 .501961 0 rg (print) Tj /F4 10 Tf 0 0 0 rg ( ) Tj .729412 .129412 .129412 rg ('hello') Tj 0 0 0 rg  T* (BEFORE) Tj  T* (hello) Tj  T* (AFTER) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 611.8236 cm

+q

+BT 1 0 0 1 0 26 Tm .462488 Tw 12 TL /F1 10 Tf 0 0 0 rg (Basically, it is as if the content of the ) Tj /F4 10 Tf (with ) Tj /F1 10 Tf (block was executed in the place of the ) Tj /F4 10 Tf (yield ) Tj /F1 10 Tf (expression in) Tj T* 0 Tw 2.691797 Tw (the generator function. In Python 3.2 ) Tj /F4 10 Tf (GeneratorContextManager ) Tj /F1 10 Tf (objects were enhanced with a) Tj T* 0 Tw /F4 10 Tf (__call__ ) Tj /F1 10 Tf (method, so that they can be used as decorators as in this example:) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 494.6236 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 108 re B*

+Q

+q

+BT 1 0 0 1 0 86 Tm 12 TL /F4 10 Tf .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj .666667 .133333 1 rg (@ba) Tj 0 0 0 rg  T* .4 .4 .4 rg (...) Tj 0 0 0 rg ( ) Tj /F3 10 Tf 0 .501961 0 rg (def) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 0 1 rg (hello) Tj 0 0 0 rg (\(\):) Tj  T* .4 .4 .4 rg (...) Tj 0 0 0 rg (     ) Tj /F3 10 Tf 0 .501961 0 rg (print) Tj /F4 10 Tf 0 0 0 rg ( ) Tj .729412 .129412 .129412 rg ('hello') Tj 0 0 0 rg  T* .4 .4 .4 rg (...) Tj 0 0 0 rg  T* .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj (hello) Tj (\(\)) Tj  T* (BEFORE) Tj  T* (hello) Tj  T* (AFTER) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 366.6236 cm

+q

+BT 1 0 0 1 0 110 Tm .20561 Tw 12 TL /F1 10 Tf 0 0 0 rg (The ) Tj /F4 10 Tf (ba ) Tj /F1 10 Tf (decorator is basically inserting a ) Tj /F4 10 Tf (with) Tj ( ) Tj (ba: ) Tj /F1 10 Tf (block inside the function. However there two issues:) Tj T* 0 Tw 1.402126 Tw (the first is that ) Tj /F4 10 Tf (GeneratorContextManager ) Tj /F1 10 Tf (objects are callable only in Python 3.2, so the previous) Tj T* 0 Tw .356905 Tw (example will break in older versions of Python; the second is that ) Tj /F4 10 Tf (GeneratorContextManager ) Tj /F1 10 Tf (objects) Tj T* 0 Tw .57561 Tw (do not preserve the signature of the decorated functions: the decorated ) Tj /F4 10 Tf (hello ) Tj /F1 10 Tf (function here will have a) Tj T* 0 Tw 3.990814 Tw (generic signature ) Tj /F4 10 Tf (hello\(*args,) Tj ( ) Tj (**kwargs\) ) Tj /F1 10 Tf (but will break when called with more than zero) Tj T* 0 Tw 7.708314 Tw (arguments. For such reasons the decorator module, starting with release 3.4, offers a) Tj T* 0 Tw .616647 Tw /F4 10 Tf (decorator.contextmanager ) Tj /F1 10 Tf (decorator that solves both problems and works even in Python 2.5. The) Tj T* 0 Tw .34998 Tw (usage is the same and factories decorated with ) Tj /F4 10 Tf (decorator.contextmanager ) Tj /F1 10 Tf (will returns instances of) Tj T* 0 Tw 4.152823 Tw /F4 10 Tf (ContextManager) Tj /F1 10 Tf (, a subclass of ) Tj /F4 10 Tf (contextlib.GeneratorContextManager ) Tj /F1 10 Tf (with a ) Tj /F4 10 Tf (__call__) Tj T* 0 Tw /F1 10 Tf (method acting as a signature-preserving decorator.) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 333.6236 cm

+q

+BT 1 0 0 1 0 3.5 Tm 21 TL /F2 17.5 Tf 0 0 0 rg (The ) Tj /F3 17.5 Tf (FunctionMaker ) Tj /F2 17.5 Tf (class) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 267.6236 cm

+q

+BT 1 0 0 1 0 50 Tm 2.241412 Tw 12 TL /F1 10 Tf 0 0 0 rg (You may wonder about how the functionality of the ) Tj /F4 10 Tf (decorator ) Tj /F1 10 Tf (module is implemented. The basic) Tj T* 0 Tw 1.545868 Tw (building block is a ) Tj /F4 10 Tf (FunctionMaker ) Tj /F1 10 Tf (class which is able to generate on the fly functions with a given) Tj T* 0 Tw .047485 Tw (name and signature from a function template passed as a string. Generally speaking, you should not need) Tj T* 0 Tw 1.164983 Tw (to resort to ) Tj /F4 10 Tf (FunctionMaker ) Tj /F1 10 Tf (when writing ordinary decorators, but it is handy in some circumstances.) Tj T* 0 Tw (You will see an example shortly, in the implementation of a cool decorator utility \() Tj /F4 10 Tf (decorator_apply) Tj /F1 10 Tf (\).) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 225.6236 cm

+q

+BT 1 0 0 1 0 26 Tm .414597 Tw 12 TL /F4 10 Tf 0 0 0 rg (FunctionMaker ) Tj /F1 10 Tf (provides a ) Tj /F4 10 Tf (.create ) Tj /F1 10 Tf (classmethod which takes as input the name, signature, and body) Tj T* 0 Tw .632927 Tw (of the function we want to generate as well as the execution environment were the function is generated) Tj T* 0 Tw (by ) Tj /F4 10 Tf (exec) Tj /F1 10 Tf (. Here is an example:) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 132.4236 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 84 re B*

+Q

+q

+BT 1 0 0 1 0 62 Tm 12 TL /F4 10 Tf .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj /F3 10 Tf 0 .501961 0 rg (def) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 0 1 rg (f) Tj 0 0 0 rg (\() Tj .4 .4 .4 rg (*) Tj 0 0 0 rg (args) Tj (,) Tj ( ) Tj .4 .4 .4 rg (**) Tj 0 0 0 rg (kw) Tj (\):) Tj ( ) Tj /F6 10 Tf .25098 .501961 .501961 rg (# a function with a generic signature) Tj /F4 10 Tf 0 0 0 rg  T* .4 .4 .4 rg (...) Tj 0 0 0 rg (     ) Tj /F3 10 Tf 0 .501961 0 rg (print) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (args) Tj (,) Tj ( ) Tj (kw) Tj  T*  T* .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj (f1) Tj ( ) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ( ) Tj (FunctionMaker) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (create) Tj (\() Tj .729412 .129412 .129412 rg ('f1\(a, b\)') Tj 0 0 0 rg (,) Tj ( ) Tj .729412 .129412 .129412 rg ('f\(a, b\)') Tj 0 0 0 rg (,) Tj ( ) Tj 0 .501961 0 rg (dict) Tj 0 0 0 rg (\() Tj (f) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg (f) Tj (\)\)) Tj  T* .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj (f1) Tj (\() Tj .4 .4 .4 rg (1) Tj 0 0 0 rg (,) Tj .4 .4 .4 rg (2) Tj 0 0 0 rg (\)) Tj  T* (\() Tj .4 .4 .4 rg (1) Tj 0 0 0 rg (,) Tj ( ) Tj .4 .4 .4 rg (2) Tj 0 0 0 rg (\)) Tj ( ) Tj ({}) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 100.4236 cm

+q

+BT 1 0 0 1 0 14 Tm .226654 Tw 12 TL /F1 10 Tf 0 0 0 rg (It is important to notice that the function body is interpolated before being executed, so be careful with the) Tj T* 0 Tw /F4 10 Tf (% ) Tj /F1 10 Tf (sign!) Tj T* ET

+Q

+Q

+ 

+endstream

+endobj

+% 'R94': class PDFStream 

+94 0 obj

+% page stream

+<< /Length 7802 >>

+stream

+1 0 0 1 0 0 cm  BT /F1 12 Tf 14.4 TL ET

+q

+1 0 0 1 62.69291 729.0236 cm

+q

+BT 1 0 0 1 0 26 Tm 1.995433 Tw 12 TL /F4 10 Tf 0 0 0 rg (FunctionMaker.create ) Tj /F1 10 Tf (also accepts keyword arguments and such arguments are attached to the) Tj T* 0 Tw 1.64686 Tw (resulting function. This is useful if you want to set some function attributes, for instance the docstring) Tj T* 0 Tw /F4 10 Tf (__doc__) Tj /F1 10 Tf (.) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 687.0236 cm

+q

+BT 1 0 0 1 0 26 Tm .605318 Tw 12 TL /F1 10 Tf 0 0 0 rg (For debugging/introspection purposes it may be useful to see the source code of the generated function;) Tj T* 0 Tw 2.246235 Tw (to do that, just pass the flag ) Tj /F4 10 Tf (addsource=True ) Tj /F1 10 Tf (and a ) Tj /F4 10 Tf (__source__ ) Tj /F1 10 Tf (attribute will be added to the) Tj T* 0 Tw (generated function:) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 593.8236 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 84 re B*

+Q

+q

+BT 1 0 0 1 0 62 Tm 12 TL /F4 10 Tf .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj (f1) Tj ( ) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ( ) Tj (FunctionMaker) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (create) Tj (\() Tj  T* .4 .4 .4 rg (...) Tj 0 0 0 rg (     ) Tj .729412 .129412 .129412 rg ('f1\(a, b\)') Tj 0 0 0 rg (,) Tj ( ) Tj .729412 .129412 .129412 rg ('f\(a, b\)') Tj 0 0 0 rg (,) Tj ( ) Tj 0 .501961 0 rg (dict) Tj 0 0 0 rg (\() Tj (f) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg (f) Tj (\),) Tj ( ) Tj (addsource) Tj .4 .4 .4 rg (=) Tj 0 .501961 0 rg (True) Tj 0 0 0 rg (\)) Tj  T* .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj /F3 10 Tf 0 .501961 0 rg (print) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (f1) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (__source__) Tj  T* /F3 10 Tf 0 .501961 0 rg (def) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 0 1 rg (f1) Tj 0 0 0 rg (\() Tj (a) Tj (,) Tj ( ) Tj (b) Tj (\):) Tj  T* (    ) Tj (f) Tj (\() Tj (a) Tj (,) Tj ( ) Tj (b) Tj (\)) Tj  T* .4 .4 .4 rg (<) Tj 0 0 0 rg (BLANKLINE) Tj .4 .4 .4 rg (>) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 453.8236 cm

+q

+BT 1 0 0 1 0 122 Tm .870651 Tw 12 TL /F4 10 Tf 0 0 0 rg (FunctionMaker.create ) Tj /F1 10 Tf (can take as first argument a string, as in the examples before, or a function.) Tj T* 0 Tw .224985 Tw (This is the most common usage, since typically you want to decorate a pre-existing function. A framework) Tj T* 0 Tw 1.606136 Tw (author may want to use directly ) Tj /F4 10 Tf (FunctionMaker.create ) Tj /F1 10 Tf (instead of ) Tj /F4 10 Tf (decorator) Tj /F1 10 Tf (, since it gives you) Tj T* 0 Tw 1.36686 Tw (direct access to the body of the generated function. For instance, suppose you want to instrument the) Tj T* 0 Tw .372209 Tw /F4 10 Tf (__init__ ) Tj /F1 10 Tf (methods of a set of classes, by preserving their signature \(such use case is not made up; this) Tj T* 0 Tw .673828 Tw (is done in SQAlchemy and in other frameworks\). When the first argument of ) Tj /F4 10 Tf (FunctionMaker.create) Tj T* 0 Tw 3.405814 Tw /F1 10 Tf (is a function, a ) Tj /F4 10 Tf (FunctionMaker ) Tj /F1 10 Tf (object is instantiated internally, with attributes ) Tj /F4 10 Tf (args) Tj /F1 10 Tf (, ) Tj /F4 10 Tf (varargs) Tj /F1 10 Tf (,) Tj T* 0 Tw 5.509982 Tw /F4 10 Tf (keywords ) Tj /F1 10 Tf (and ) Tj /F4 10 Tf (defaults ) Tj /F1 10 Tf (which are the the return values of the standard library function) Tj T* 0 Tw .561318 Tw /F4 10 Tf (inspect.getargspec) Tj /F1 10 Tf (. For each argument in the ) Tj /F4 10 Tf (args ) Tj /F1 10 Tf (\(which is a list of strings containing the names) Tj T* 0 Tw 1.599985 Tw (of the mandatory arguments\) an attribute ) Tj /F4 10 Tf (arg0) Tj /F1 10 Tf (, ) Tj /F4 10 Tf (arg1) Tj /F1 10 Tf (, ..., ) Tj /F4 10 Tf (argN ) Tj /F1 10 Tf (is also generated. Finally, there is a) Tj T* 0 Tw /F4 10 Tf (signature ) Tj /F1 10 Tf (attribute, a string with the signature of the original function.) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 375.8236 cm

+q

+BT 1 0 0 1 0 62 Tm 4.63311 Tw 12 TL /F1 10 Tf 0 0 0 rg (Notice that while I do not have plans to change or remove the functionality provided in the) Tj T* 0 Tw 1.00936 Tw /F4 10 Tf (FunctionMaker ) Tj /F1 10 Tf (class, I do not guarantee that it will stay unchanged forever. For instance, right now I) Tj T* 0 Tw .791318 Tw (am using the traditional string interpolation syntax for function templates, but Python 2.6 and Python 3.0) Tj T* 0 Tw .712093 Tw (provide a newer interpolation syntax and I may use the new syntax in the future. On the other hand, the) Tj T* 0 Tw .639985 Tw (functionality provided by ) Tj /F4 10 Tf (decorator ) Tj /F1 10 Tf (has been there from version 0.1 and it is guaranteed to stay there) Tj T* 0 Tw (forever.) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 342.8236 cm

+q

+BT 1 0 0 1 0 3.5 Tm 21 TL /F2 17.5 Tf 0 0 0 rg (Getting the source code) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 264.8236 cm

+q

+BT 1 0 0 1 0 62 Tm 5.045529 Tw 12 TL /F1 10 Tf 0 0 0 rg (Internally ) Tj /F4 10 Tf (FunctionMaker.create ) Tj /F1 10 Tf (uses ) Tj /F4 10 Tf (exec ) Tj /F1 10 Tf (to generate the decorated function. Therefore) Tj T* 0 Tw 2.542126 Tw /F4 10 Tf (inspect.getsource ) Tj /F1 10 Tf (will not work for decorated functions. That means that the usual '??' trick in) Tj T* 0 Tw 26.45775 Tw (IPython will give you the \(right on the spot\) message) Tj T* 0 Tw .261647 Tw /F4 10 Tf (Dynamically) Tj ( ) Tj (generated) Tj ( ) Tj (function.) Tj ( ) Tj (No) Tj ( ) Tj (source) Tj ( ) Tj (code available) Tj /F1 10 Tf (. In the past I have considered) Tj T* 0 Tw .945366 Tw (this acceptable, since ) Tj /F4 10 Tf (inspect.getsource ) Tj /F1 10 Tf (does not really work even with regular decorators. In that) Tj T* 0 Tw (case ) Tj /F4 10 Tf (inspect.getsource ) Tj /F1 10 Tf (gives you the wrapper source code which is probably not what you want:) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 195.6236 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 60 re B*

+Q

+q

+BT 1 0 0 1 0 38 Tm 12 TL /F3 10 Tf 0 .501961 0 rg (def) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 0 1 rg (identity_dec) Tj 0 0 0 rg (\() Tj (func) Tj (\):) Tj  T* (    ) Tj /F3 10 Tf 0 .501961 0 rg (def) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 0 1 rg (wrapper) Tj 0 0 0 rg (\() Tj .4 .4 .4 rg (*) Tj 0 0 0 rg (args) Tj (,) Tj ( ) Tj .4 .4 .4 rg (**) Tj 0 0 0 rg (kw) Tj (\):) Tj  T* (        ) Tj /F3 10 Tf 0 .501961 0 rg (return) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (func) Tj (\() Tj .4 .4 .4 rg (*) Tj 0 0 0 rg (args) Tj (,) Tj ( ) Tj .4 .4 .4 rg (**) Tj 0 0 0 rg (kw) Tj (\)) Tj  T* (    ) Tj /F3 10 Tf 0 .501961 0 rg (return) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (wrapper) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 90.42362 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 96 re B*

+Q

+q

+BT 1 0 0 1 0 74 Tm 12 TL /F4 10 Tf .666667 .133333 1 rg (@identity_dec) Tj 0 0 0 rg  T* /F3 10 Tf 0 .501961 0 rg (def) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 0 1 rg (example) Tj 0 0 0 rg (\(\):) Tj ( ) Tj /F3 10 Tf 0 .501961 0 rg (pass) Tj /F4 10 Tf 0 0 0 rg  T*  T* .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj /F3 10 Tf 0 .501961 0 rg (print) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (inspect) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (getsource) Tj (\() Tj (example) Tj (\)) Tj  T* (    ) Tj /F3 10 Tf 0 .501961 0 rg (def) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 0 1 rg (wrapper) Tj 0 0 0 rg (\() Tj .4 .4 .4 rg (*) Tj 0 0 0 rg (args) Tj (,) Tj ( ) Tj .4 .4 .4 rg (**) Tj 0 0 0 rg (kw) Tj (\):) Tj  T* (        ) Tj /F3 10 Tf 0 .501961 0 rg (return) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (func) Tj (\() Tj .4 .4 .4 rg (*) Tj 0 0 0 rg (args) Tj (,) Tj ( ) Tj .4 .4 .4 rg (**) Tj 0 0 0 rg (kw) Tj (\)) Tj  T* .4 .4 .4 rg (<) Tj 0 0 0 rg (BLANKLINE) Tj .4 .4 .4 rg (>) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+ 

+endstream

+endobj

+% 'R95': class PDFStream 

+95 0 obj

+% page stream

+<< /Length 7279 >>

+stream

+1 0 0 1 0 0 cm  BT /F1 12 Tf 14.4 TL ET

+q

+1 0 0 1 62.69291 717.0236 cm

+q

+BT 1 0 0 1 0 38 Tm 1.471235 Tw 12 TL /F1 10 Tf 0 0 0 rg (\(see bug report ) Tj 0 0 .501961 rg (1764286 ) Tj 0 0 0 rg (for an explanation of what is happening\). Unfortunately the bug is still there,) Tj T* 0 Tw 1.541235 Tw (even in Python 2.7 and 3.1. There is however a workaround. The decorator module adds an attribute) Tj T* 0 Tw .103984 Tw /F4 10 Tf (.__wrapped__ ) Tj /F1 10 Tf (to the decorated function, containing a reference to the original function. The easy way to) Tj T* 0 Tw (get the source code is to call ) Tj /F4 10 Tf (inspect.getsource ) Tj /F1 10 Tf (on the undecorated function:) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 611.8236 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 96 re B*

+Q

+q

+BT 1 0 0 1 0 74 Tm 12 TL /F4 10 Tf .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj /F3 10 Tf 0 .501961 0 rg (print) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (inspect) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (getsource) Tj (\() Tj (factorial) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (__wrapped__) Tj (\)) Tj  T* .666667 .133333 1 rg (@tail_recursive) Tj 0 0 0 rg  T* /F3 10 Tf 0 .501961 0 rg (def) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 0 1 rg (factorial) Tj 0 0 0 rg (\() Tj (n) Tj (,) Tj ( ) Tj (acc) Tj .4 .4 .4 rg (=) Tj (1) Tj 0 0 0 rg (\):) Tj  T* (    ) Tj .729412 .129412 .129412 rg ("The good old factorial") Tj 0 0 0 rg  T* (    ) Tj /F3 10 Tf 0 .501961 0 rg (if) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (n) Tj ( ) Tj .4 .4 .4 rg (==) Tj 0 0 0 rg ( ) Tj .4 .4 .4 rg (0) Tj 0 0 0 rg (:) Tj ( ) Tj /F3 10 Tf 0 .501961 0 rg (return) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (acc) Tj  T* (    ) Tj /F3 10 Tf 0 .501961 0 rg (return) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (factorial) Tj (\() Tj (n) Tj .4 .4 .4 rg (-) Tj (1) Tj 0 0 0 rg (,) Tj ( ) Tj (n) Tj .4 .4 .4 rg (*) Tj 0 0 0 rg (acc) Tj (\)) Tj  T* .4 .4 .4 rg (<) Tj 0 0 0 rg (BLANKLINE) Tj .4 .4 .4 rg (>) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 578.8236 cm

+q

+BT 1 0 0 1 0 3.5 Tm 21 TL /F2 17.5 Tf 0 0 0 rg (Dealing with third party decorators) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 524.8236 cm

+q

+BT 1 0 0 1 0 38 Tm .321654 Tw 12 TL /F1 10 Tf 0 0 0 rg (Sometimes you find on the net some cool decorator that you would like to include in your code. However,) Tj T* 0 Tw .50061 Tw (more often than not the cool decorator is not signature-preserving. Therefore you may want an easy way) Tj T* 0 Tw 1.814597 Tw (to upgrade third party decorators to signature-preserving decorators without having to rewrite them in) Tj T* 0 Tw (terms of ) Tj /F4 10 Tf (decorator) Tj /F1 10 Tf (. You can use a ) Tj /F4 10 Tf (FunctionMaker ) Tj /F1 10 Tf (to implement that functionality as follows:) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 407.6236 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 108 re B*

+Q

+q

+BT 1 0 0 1 0 86 Tm 12 TL /F3 10 Tf 0 .501961 0 rg (def) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 0 1 rg (decorator_apply) Tj 0 0 0 rg (\() Tj (dec) Tj (,) Tj ( ) Tj (func) Tj (\):) Tj  T* (    ) Tj /F6 10 Tf .729412 .129412 .129412 rg (""") Tj T* (    Decorate a function by preserving the signature even if dec) Tj T* (    is not a signature-preserving decorator.) Tj T* (    """) Tj /F4 10 Tf 0 0 0 rg  T* (    ) Tj /F3 10 Tf 0 .501961 0 rg (return) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (FunctionMaker) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (create) Tj (\() Tj  T* (        ) Tj (func) Tj (,) Tj ( ) Tj .729412 .129412 .129412 rg ('return decorated\() Tj /F3 10 Tf .733333 .4 .533333 rg (%\(signature\)s) Tj /F4 10 Tf .729412 .129412 .129412 rg (\)') Tj 0 0 0 rg (,) Tj  T* (        ) Tj 0 .501961 0 rg (dict) Tj 0 0 0 rg (\() Tj (decorated) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg (dec) Tj (\() Tj (func) Tj (\)\),) Tj ( ) Tj (__wrapped__) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg (func) Tj (\)) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 375.6236 cm

+q

+BT 1 0 0 1 0 14 Tm .698314 Tw 12 TL /F4 10 Tf 0 0 0 rg (decorator_apply ) Tj /F1 10 Tf (sets the attribute ) Tj /F4 10 Tf (.__wrapped__ ) Tj /F1 10 Tf (of the generated function to the original function,) Tj T* 0 Tw (so that you can get the right source code.) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 333.6236 cm

+q

+BT 1 0 0 1 0 26 Tm .13104 Tw 12 TL /F1 10 Tf 0 0 0 rg (Notice that I am not providing this functionality in the ) Tj /F4 10 Tf (decorator ) Tj /F1 10 Tf (module directly since I think it is best to) Tj T* 0 Tw 2.070751 Tw (rewrite the decorator rather than adding an additional level of indirection. However, practicality beats) Tj T* 0 Tw (purity, so you can add ) Tj /F4 10 Tf (decorator_apply ) Tj /F1 10 Tf (to your toolbox and use it if you need to.) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 279.6236 cm

+q

+BT 1 0 0 1 0 38 Tm 1.74881 Tw 12 TL /F1 10 Tf 0 0 0 rg (In order to give an example of usage of ) Tj /F4 10 Tf (decorator_apply) Tj /F1 10 Tf (, I will show a pretty slick decorator that) Tj T* 0 Tw 1.276651 Tw (converts a tail-recursive function in an iterative function. I have shamelessly stolen the basic idea from) Tj T* 0 Tw 43.62829 Tw (Kay Schluehr's recipe in the Python Cookbook,) Tj T* 0 Tw 0 0 .501961 rg (http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/496691) Tj 0 0 0 rg (.) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 78.42362 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 192 re B*

+Q

+q

+BT 1 0 0 1 0 170 Tm 12 TL /F3 10 Tf 0 .501961 0 rg (class) Tj /F4 10 Tf 0 0 0 rg ( ) Tj /F3 10 Tf 0 0 1 rg (TailRecursive) Tj /F4 10 Tf 0 0 0 rg (\() Tj 0 .501961 0 rg (object) Tj 0 0 0 rg (\):) Tj  T* (    ) Tj /F6 10 Tf .729412 .129412 .129412 rg (""") Tj T* (    tail_recursive decorator based on Kay Schluehr's recipe) Tj T* (    http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/496691) Tj T* (    with improvements by me and George Sakkis.) Tj T* (    """) Tj /F4 10 Tf 0 0 0 rg  T*  T* (    ) Tj /F3 10 Tf 0 .501961 0 rg (def) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 0 1 rg (__init__) Tj 0 0 0 rg (\() Tj 0 .501961 0 rg (self) Tj 0 0 0 rg (,) Tj ( ) Tj (func) Tj (\):) Tj  T* (        ) Tj 0 .501961 0 rg (self) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (func) Tj ( ) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ( ) Tj (func) Tj  T* (        ) Tj 0 .501961 0 rg (self) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (firstcall) Tj ( ) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ( ) Tj 0 .501961 0 rg (True) Tj 0 0 0 rg  T* (        ) Tj 0 .501961 0 rg (self) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (CONTINUE) Tj ( ) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ( ) Tj 0 .501961 0 rg (object) Tj 0 0 0 rg (\(\)) Tj ( ) Tj /F6 10 Tf .25098 .501961 .501961 rg (# sentinel) Tj /F4 10 Tf 0 0 0 rg  T*  T* (    ) Tj /F3 10 Tf 0 .501961 0 rg (def) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 0 1 rg (__call__) Tj 0 0 0 rg (\() Tj 0 .501961 0 rg (self) Tj 0 0 0 rg (,) Tj ( ) Tj .4 .4 .4 rg (*) Tj 0 0 0 rg (args) Tj (,) Tj ( ) Tj .4 .4 .4 rg (**) Tj 0 0 0 rg (kwd) Tj (\):) Tj  T* (        ) Tj (CONTINUE) Tj ( ) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ( ) Tj 0 .501961 0 rg (self) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (CONTINUE) Tj  T* (        ) Tj /F3 10 Tf 0 .501961 0 rg (if) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 .501961 0 rg (self) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (firstcall) Tj (:) Tj  T* ET

+Q

+Q

+Q

+Q

+Q

+ 

+endstream

+endobj

+% 'R96': class PDFStream 

+96 0 obj

+% page stream

+<< /Length 7146 >>

+stream

+1 0 0 1 0 0 cm  BT /F1 12 Tf 14.4 TL ET

+q

+1 0 0 1 62.69291 583.8236 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 180 re B*

+Q

+q

+BT 1 0 0 1 0 158 Tm 12 TL /F4 10 Tf 0 0 0 rg (            ) Tj (func) Tj ( ) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ( ) Tj 0 .501961 0 rg (self) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (func) Tj  T* (            ) Tj 0 .501961 0 rg (self) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (firstcall) Tj ( ) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ( ) Tj 0 .501961 0 rg (False) Tj 0 0 0 rg  T* (            ) Tj /F3 10 Tf 0 .501961 0 rg (try) Tj /F4 10 Tf 0 0 0 rg (:) Tj  T* (                ) Tj /F3 10 Tf 0 .501961 0 rg (while) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 .501961 0 rg (True) Tj 0 0 0 rg (:) Tj  T* (                    ) Tj (result) Tj ( ) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ( ) Tj (func) Tj (\() Tj .4 .4 .4 rg (*) Tj 0 0 0 rg (args) Tj (,) Tj ( ) Tj .4 .4 .4 rg (**) Tj 0 0 0 rg (kwd) Tj (\)) Tj  T* (                    ) Tj /F3 10 Tf 0 .501961 0 rg (if) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (result) Tj ( ) Tj /F3 10 Tf .666667 .133333 1 rg (is) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (CONTINUE) Tj (:) Tj ( ) Tj /F6 10 Tf .25098 .501961 .501961 rg (# update arguments) Tj /F4 10 Tf 0 0 0 rg  T* (                        ) Tj (args) Tj (,) Tj ( ) Tj (kwd) Tj ( ) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ( ) Tj 0 .501961 0 rg (self) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (argskwd) Tj  T* (                    ) Tj /F3 10 Tf 0 .501961 0 rg (else) Tj /F4 10 Tf 0 0 0 rg (:) Tj ( ) Tj /F6 10 Tf .25098 .501961 .501961 rg (# last call) Tj /F4 10 Tf 0 0 0 rg  T* (                        ) Tj /F3 10 Tf 0 .501961 0 rg (return) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (result) Tj  T* (            ) Tj /F3 10 Tf 0 .501961 0 rg (finally) Tj /F4 10 Tf 0 0 0 rg (:) Tj  T* (                ) Tj 0 .501961 0 rg (self) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (firstcall) Tj ( ) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ( ) Tj 0 .501961 0 rg (True) Tj 0 0 0 rg  T* (        ) Tj /F3 10 Tf 0 .501961 0 rg (else) Tj /F4 10 Tf 0 0 0 rg (:) Tj ( ) Tj /F6 10 Tf .25098 .501961 .501961 rg (# return the arguments of the tail call) Tj /F4 10 Tf 0 0 0 rg  T* (            ) Tj 0 .501961 0 rg (self) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (argskwd) Tj ( ) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ( ) Tj (args) Tj (,) Tj ( ) Tj (kwd) Tj  T* (            ) Tj /F3 10 Tf 0 .501961 0 rg (return) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (CONTINUE) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 563.8236 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 2 Tm /F1 10 Tf 12 TL (Here the decorator is implemented as a class returning callable objects.) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 518.6236 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 36 re B*

+Q

+q

+BT 1 0 0 1 0 14 Tm 12 TL /F3 10 Tf 0 .501961 0 rg (def) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 0 1 rg (tail_recursive) Tj 0 0 0 rg (\() Tj (func) Tj (\):) Tj  T* (    ) Tj /F3 10 Tf 0 .501961 0 rg (return) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (decorator_apply) Tj (\() Tj (TailRecursive) Tj (,) Tj ( ) Tj (func) Tj (\)) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 498.6236 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 2 Tm /F1 10 Tf 12 TL (Here is how you apply the upgraded decorator to the good old factorial:) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 417.4236 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 72 re B*

+Q

+q

+BT 1 0 0 1 0 50 Tm 12 TL /F4 10 Tf .666667 .133333 1 rg (@tail_recursive) Tj 0 0 0 rg  T* /F3 10 Tf 0 .501961 0 rg (def) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 0 1 rg (factorial) Tj 0 0 0 rg (\() Tj (n) Tj (,) Tj ( ) Tj (acc) Tj .4 .4 .4 rg (=) Tj (1) Tj 0 0 0 rg (\):) Tj  T* (    ) Tj .729412 .129412 .129412 rg ("The good old factorial") Tj 0 0 0 rg  T* (    ) Tj /F3 10 Tf 0 .501961 0 rg (if) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (n) Tj ( ) Tj .4 .4 .4 rg (==) Tj 0 0 0 rg ( ) Tj .4 .4 .4 rg (0) Tj 0 0 0 rg (:) Tj ( ) Tj /F3 10 Tf 0 .501961 0 rg (return) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (acc) Tj  T* (    ) Tj /F3 10 Tf 0 .501961 0 rg (return) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (factorial) Tj (\() Tj (n) Tj .4 .4 .4 rg (-) Tj (1) Tj 0 0 0 rg (,) Tj ( ) Tj (n) Tj .4 .4 .4 rg (*) Tj 0 0 0 rg (acc) Tj (\)) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 372.2236 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 36 re B*

+Q

+q

+BT 1 0 0 1 0 14 Tm 12 TL /F4 10 Tf .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj /F3 10 Tf 0 .501961 0 rg (print) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (factorial) Tj (\() Tj .4 .4 .4 rg (4) Tj 0 0 0 rg (\)) Tj  T* .4 .4 .4 rg (24) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 316.2236 cm

+q

+BT 1 0 0 1 0 38 Tm .188935 Tw 12 TL /F1 10 Tf 0 0 0 rg (This decorator is pretty impressive, and should give you some food for your mind ;\) Notice that there is no) Tj T* 0 Tw 1.339983 Tw (recursion limit now, and you can easily compute ) Tj /F4 10 Tf (factorial\(1001\) ) Tj /F1 10 Tf (or larger without filling the stack) Tj T* 0 Tw .909431 Tw (frame. Notice also that the decorator will not work on functions which are not tail recursive, such as the) Tj T* 0 Tw (following) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 259.0236 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 48 re B*

+Q

+q

+BT 1 0 0 1 0 26 Tm 12 TL /F3 10 Tf 0 .501961 0 rg (def) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 0 1 rg (fact) Tj 0 0 0 rg (\() Tj (n) Tj (\):) Tj ( ) Tj /F6 10 Tf .25098 .501961 .501961 rg (# this is not tail-recursive) Tj /F4 10 Tf 0 0 0 rg  T* (    ) Tj /F3 10 Tf 0 .501961 0 rg (if) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (n) Tj ( ) Tj .4 .4 .4 rg (==) Tj 0 0 0 rg ( ) Tj .4 .4 .4 rg (0) Tj 0 0 0 rg (:) Tj ( ) Tj /F3 10 Tf 0 .501961 0 rg (return) Tj /F4 10 Tf 0 0 0 rg ( ) Tj .4 .4 .4 rg (1) Tj 0 0 0 rg  T* (    ) Tj /F3 10 Tf 0 .501961 0 rg (return) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (n) Tj ( ) Tj .4 .4 .4 rg (*) Tj 0 0 0 rg ( ) Tj (fact) Tj (\() Tj (n) Tj .4 .4 .4 rg (-) Tj (1) Tj 0 0 0 rg (\)) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 227.0236 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 14 Tm /F1 10 Tf 12 TL .541098 Tw (\(reminder: a function is tail recursive if it either returns a value without making a recursive call, or returns) Tj T* 0 Tw (directly the result of a recursive call\).) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 194.0236 cm

+q

+BT 1 0 0 1 0 3.5 Tm 21 TL /F2 17.5 Tf 0 0 0 rg (Caveats and limitations) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 164.0236 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 14 Tm /F1 10 Tf 12 TL .474987 Tw (The first thing you should be aware of, it the fact that decorators have a performance penalty. The worse) Tj T* 0 Tw (case is shown by the following example:) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 82.82362 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 72 re B*

+Q

+q

+0 0 0 rg

+BT 1 0 0 1 0 50 Tm /F4 10 Tf 12 TL ($ cat performance.sh) Tj T* (python -m timeit -s ") Tj T* (from decorator import decorator) Tj T*  T* (@decorator) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+ 

+endstream

+endobj

+% 'R97': class PDFStream 

+97 0 obj

+% page stream

+<< /Length 6291 >>

+stream

+1 0 0 1 0 0 cm  BT /F1 12 Tf 14.4 TL ET

+q

+1 0 0 1 62.69291 607.8236 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 156 re B*

+Q

+q

+0 0 0 rg

+BT 1 0 0 1 0 134 Tm /F4 10 Tf 12 TL (def do_nothing\(func, *args, **kw\):) Tj T* (    return func\(*args, **kw\)) Tj T*  T* (@do_nothing) Tj T* (def f\(\):) Tj T* (    pass) Tj T* (" "f\(\)") Tj T*  T* (python -m timeit -s ") Tj T* (def f\(\):) Tj T* (    pass) Tj T* (" "f\(\)") Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 575.8236 cm

+q

+BT 1 0 0 1 0 14 Tm .266235 Tw 12 TL /F1 10 Tf 0 0 0 rg (On my MacBook, using the ) Tj /F4 10 Tf (do_nothing ) Tj /F1 10 Tf (decorator instead of the plain function is more than three times) Tj T* 0 Tw (slower:) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 518.6236 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 48 re B*

+Q

+q

+0 0 0 rg

+BT 1 0 0 1 0 26 Tm /F4 10 Tf 12 TL ($ bash performance.sh) Tj T* (1000000 loops, best of 3: 0.995 usec per loop) Tj T* (1000000 loops, best of 3: 0.273 usec per loop) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 474.6236 cm

+q

+BT 1 0 0 1 0 26 Tm 1.25832 Tw 12 TL /F1 10 Tf 0 0 0 rg (It should be noted that a real life function would probably do something more useful than ) Tj /F4 10 Tf (f ) Tj /F1 10 Tf (here, and) Tj T* 0 Tw .91811 Tw (therefore in real life the performance penalty could be completely negligible. As always, the only way to) Tj T* 0 Tw (know if there is a penalty in your specific use case is to measure it.) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 444.6236 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 14 Tm /F1 10 Tf 12 TL .867984 Tw (You should be aware that decorators will make your tracebacks longer and more difficult to understand.) Tj T* 0 Tw (Consider this example:) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 387.4236 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 48 re B*

+Q

+q

+BT 1 0 0 1 0 26 Tm 12 TL /F4 10 Tf .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj .666667 .133333 1 rg (@trace) Tj 0 0 0 rg  T* .4 .4 .4 rg (...) Tj 0 0 0 rg ( ) Tj /F3 10 Tf 0 .501961 0 rg (def) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 0 1 rg (f) Tj 0 0 0 rg (\(\):) Tj  T* .4 .4 .4 rg (...) Tj 0 0 0 rg (     ) Tj .4 .4 .4 rg (1) Tj (/) Tj (0) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 355.4236 cm

+q

+BT 1 0 0 1 0 14 Tm .583318 Tw 12 TL /F1 10 Tf 0 0 0 rg (Calling ) Tj /F4 10 Tf (f\(\) ) Tj /F1 10 Tf (will give you a ) Tj /F4 10 Tf (ZeroDivisionError) Tj /F1 10 Tf (, but since the function is decorated the traceback will) Tj T* 0 Tw (be longer:) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 226.2236 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 120 re B*

+Q

+q

+BT 1 0 0 1 0 98 Tm 12 TL /F4 10 Tf .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj (f) Tj (\(\)) Tj  T* (Traceback) Tj ( ) Tj (\() Tj (most) Tj ( ) Tj (recent) Tj ( ) Tj (call) Tj ( ) Tj (last) Tj (\):) Tj  T* (  ) Tj .4 .4 .4 rg (...) Tj 0 0 0 rg  T* (     ) Tj (File) Tj ( ) Tj .729412 .129412 .129412 rg (") Tj (<) Tj (string) Tj (>) Tj (") Tj 0 0 0 rg (,) Tj ( ) Tj (line) Tj ( ) Tj .4 .4 .4 rg (2) Tj 0 0 0 rg (,) Tj ( ) Tj /F3 10 Tf .666667 .133333 1 rg (in) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (f) Tj  T* (     ) Tj (File) Tj ( ) Tj .729412 .129412 .129412 rg (") Tj (<) Tj (doctest __main__[18]) Tj (>) Tj (") Tj 0 0 0 rg (,) Tj ( ) Tj (line) Tj ( ) Tj .4 .4 .4 rg (4) Tj 0 0 0 rg (,) Tj ( ) Tj /F3 10 Tf .666667 .133333 1 rg (in) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (trace) Tj  T* (       ) Tj /F3 10 Tf 0 .501961 0 rg (return) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (f) Tj (\() Tj .4 .4 .4 rg (*) Tj 0 0 0 rg (args) Tj (,) Tj ( ) Tj .4 .4 .4 rg (**) Tj 0 0 0 rg (kw) Tj (\)) Tj  T* (     ) Tj (File) Tj ( ) Tj .729412 .129412 .129412 rg (") Tj (<) Tj (doctest __main__[47]) Tj (>) Tj (") Tj 0 0 0 rg (,) Tj ( ) Tj (line) Tj ( ) Tj .4 .4 .4 rg (3) Tj 0 0 0 rg (,) Tj ( ) Tj /F3 10 Tf .666667 .133333 1 rg (in) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (f) Tj  T* (       ) Tj .4 .4 .4 rg (1) Tj (/) Tj (0) Tj 0 0 0 rg  T* /F3 10 Tf .823529 .254902 .227451 rg (ZeroDivisionError) Tj /F4 10 Tf 0 0 0 rg (:) Tj ( ) Tj (integer) Tj ( ) Tj (division) Tj ( ) Tj /F3 10 Tf .666667 .133333 1 rg (or) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (modulo) Tj ( ) Tj (by) Tj ( ) Tj (zero) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 158.2236 cm

+q

+BT 1 0 0 1 0 50 Tm 1.05528 Tw 12 TL /F1 10 Tf 0 0 0 rg (You see here the inner call to the decorator ) Tj /F4 10 Tf (trace) Tj /F1 10 Tf (, which calls ) Tj /F4 10 Tf (f\(*args,) Tj ( ) Tj (**kw\)) Tj /F1 10 Tf (, and a reference to) Tj T* 0 Tw .076457 Tw /F4 10 Tf (File) Tj ( ) Tj (") Tj (<) Tj (string) Tj (>) Tj (",) Tj ( ) Tj (line) Tj ( ) Tj (2,) Tj ( ) Tj (in) Tj ( ) Tj (f) Tj /F1 10 Tf (. This latter reference is due to the fact that internally the decorator) Tj T* 0 Tw 2.053318 Tw (module uses ) Tj /F4 10 Tf (exec ) Tj /F1 10 Tf (to generate the decorated function. Notice that ) Tj /F4 10 Tf (exec ) Tj /F1 10 Tf (is ) Tj /F5 10 Tf (not ) Tj /F1 10 Tf (responsibile for the) Tj T* 0 Tw 1.507485 Tw (performance penalty, since is the called ) Tj /F5 10 Tf (only once ) Tj /F1 10 Tf (at function decoration time, and not every time the) Tj T* 0 Tw (decorated function is called.) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 80.22362 cm

+q

+BT 1 0 0 1 0 62 Tm .932209 Tw 12 TL /F1 10 Tf 0 0 0 rg (At present, there is no clean way to avoid ) Tj /F4 10 Tf (exec) Tj /F1 10 Tf (. A clean solution would require to change the CPython) Tj T* 0 Tw .777485 Tw (implementation of functions and add an hook to make it possible to change their signature directly. That) Tj T* 0 Tw .74186 Tw (could happen in future versions of Python \(see PEP ) Tj 0 0 .501961 rg (362) Tj 0 0 0 rg (\) and then the decorator module would become) Tj T* 0 Tw 2.385318 Tw (obsolete. However, at present, even in Python 3.1 it is impossible to change the function signature) Tj T* 0 Tw .931751 Tw (directly, therefore the ) Tj /F4 10 Tf (decorator ) Tj /F1 10 Tf (module is still useful. Actually, this is one of the main reasons why I) Tj T* 0 Tw (keep maintaining the module and releasing new versions.) Tj T* ET

+Q

+Q

+ 

+endstream

+endobj

+% 'R98': class PDFStream 

+98 0 obj

+% page stream

+<< /Length 8028 >>

+stream

+1 0 0 1 0 0 cm  BT /F1 12 Tf 14.4 TL ET

+q

+1 0 0 1 62.69291 705.0236 cm

+q

+BT 1 0 0 1 0 50 Tm 1.043828 Tw 12 TL /F1 10 Tf 0 0 0 rg (In the present implementation, decorators generated by ) Tj /F4 10 Tf (decorator ) Tj /F1 10 Tf (can only be used on user-defined) Tj T* 0 Tw .152485 Tw (Python functions or methods, not on generic callable objects, nor on built-in functions, due to limitations of) Tj T* 0 Tw .591235 Tw (the ) Tj /F4 10 Tf (inspect ) Tj /F1 10 Tf (module in the standard library. Moreover, notice that you can decorate a method, but only) Tj T* 0 Tw 2.693516 Tw (before if becomes a bound or unbound method, i.e. inside the class. Here is an example of valid) Tj T* 0 Tw (decoration:) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 635.8236 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 60 re B*

+Q

+q

+BT 1 0 0 1 0 38 Tm 12 TL /F4 10 Tf .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj /F3 10 Tf 0 .501961 0 rg (class) Tj /F4 10 Tf 0 0 0 rg ( ) Tj /F3 10 Tf 0 0 1 rg (C) Tj /F4 10 Tf 0 0 0 rg (\() Tj 0 .501961 0 rg (object) Tj 0 0 0 rg (\):) Tj  T* .4 .4 .4 rg (...) Tj 0 0 0 rg (      ) Tj .666667 .133333 1 rg (@trace) Tj 0 0 0 rg  T* .4 .4 .4 rg (...) Tj 0 0 0 rg (      ) Tj /F3 10 Tf 0 .501961 0 rg (def) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 0 1 rg (meth) Tj 0 0 0 rg (\() Tj 0 .501961 0 rg (self) Tj 0 0 0 rg (\):) Tj  T* .4 .4 .4 rg (...) Tj 0 0 0 rg (          ) Tj /F3 10 Tf 0 .501961 0 rg (pass) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 615.8236 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 2 Tm /F1 10 Tf 12 TL (Here is an example of invalid decoration, when the decorator in called too late:) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 498.6236 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 108 re B*

+Q

+q

+BT 1 0 0 1 0 86 Tm 12 TL /F4 10 Tf .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj /F3 10 Tf 0 .501961 0 rg (class) Tj /F4 10 Tf 0 0 0 rg ( ) Tj /F3 10 Tf 0 0 1 rg (C) Tj /F4 10 Tf 0 0 0 rg (\() Tj 0 .501961 0 rg (object) Tj 0 0 0 rg (\):) Tj  T* .4 .4 .4 rg (...) Tj 0 0 0 rg (      ) Tj /F3 10 Tf 0 .501961 0 rg (def) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 0 1 rg (meth) Tj 0 0 0 rg (\() Tj 0 .501961 0 rg (self) Tj 0 0 0 rg (\):) Tj  T* .4 .4 .4 rg (...) Tj 0 0 0 rg (          ) Tj /F3 10 Tf 0 .501961 0 rg (pass) Tj /F4 10 Tf 0 0 0 rg  T* .4 .4 .4 rg (...) Tj 0 0 0 rg  T* .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj (trace) Tj (\() Tj (C) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (meth) Tj (\)) Tj  T* (Traceback) Tj ( ) Tj (\() Tj (most) Tj ( ) Tj (recent) Tj ( ) Tj (call) Tj ( ) Tj (last) Tj (\):) Tj  T* (  ) Tj .4 .4 .4 rg (...) Tj 0 0 0 rg  T* /F3 10 Tf .823529 .254902 .227451 rg (TypeError) Tj /F4 10 Tf 0 0 0 rg (:) Tj ( ) Tj (You) Tj ( ) Tj (are) Tj ( ) Tj (decorating) Tj ( ) Tj (a) Tj ( ) Tj (non) Tj ( ) Tj (function) Tj (:) Tj ( ) Tj .4 .4 .4 rg (<) Tj 0 0 0 rg (unbound) Tj ( ) Tj (method) Tj ( ) Tj (C) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (meth) Tj .4 .4 .4 rg (>) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 478.6236 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 2 Tm /F1 10 Tf 12 TL (The solution is to extract the inner function from the unbound method:) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 433.4236 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 36 re B*

+Q

+q

+BT 1 0 0 1 0 14 Tm 12 TL /F4 10 Tf .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj (trace) Tj (\() Tj (C) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (meth) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (im_func) Tj (\)) Tj  T* .4 .4 .4 rg (<) Tj 0 0 0 rg (function) Tj ( ) Tj (meth) Tj ( ) Tj (at) Tj ( ) Tj .4 .4 .4 rg (0) Tj 0 0 0 rg (x) Tj .4 .4 .4 rg (...) Tj (>) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 401.4236 cm

+q

+BT 1 0 0 1 0 14 Tm .785777 Tw 12 TL /F1 10 Tf 0 0 0 rg (There is a restriction on the names of the arguments: for instance, if try to call an argument ) Tj /F4 10 Tf (_call_ ) Tj /F1 10 Tf (or) Tj T* 0 Tw /F4 10 Tf (_func_ ) Tj /F1 10 Tf (you will get a ) Tj /F4 10 Tf (NameError) Tj /F1 10 Tf (:) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 284.2236 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 108 re B*

+Q

+q

+BT 1 0 0 1 0 86 Tm 12 TL /F4 10 Tf .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj .666667 .133333 1 rg (@trace) Tj 0 0 0 rg  T* .4 .4 .4 rg (...) Tj 0 0 0 rg ( ) Tj /F3 10 Tf 0 .501961 0 rg (def) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 0 1 rg (f) Tj 0 0 0 rg (\() Tj (_func_) Tj (\):) Tj ( ) Tj /F3 10 Tf 0 .501961 0 rg (print) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (f) Tj  T* .4 .4 .4 rg (...) Tj 0 0 0 rg  T* (Traceback) Tj ( ) Tj (\() Tj (most) Tj ( ) Tj (recent) Tj ( ) Tj (call) Tj ( ) Tj (last) Tj (\):) Tj  T* (  ) Tj .4 .4 .4 rg (...) Tj 0 0 0 rg  T* /F3 10 Tf .823529 .254902 .227451 rg (NameError) Tj /F4 10 Tf 0 0 0 rg (:) Tj ( ) Tj (_func_) Tj ( ) Tj /F3 10 Tf .666667 .133333 1 rg (is) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (overridden) Tj ( ) Tj /F3 10 Tf .666667 .133333 1 rg (in) Tj /F4 10 Tf 0 0 0 rg  T* /F3 10 Tf 0 .501961 0 rg (def) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 0 1 rg (f) Tj 0 0 0 rg (\() Tj (_func_) Tj (\):) Tj  T* (    ) Tj /F3 10 Tf 0 .501961 0 rg (return) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (_call_) Tj (\() Tj (_func_) Tj (,) Tj ( ) Tj (_func_) Tj (\)) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 240.2236 cm

+q

+BT 1 0 0 1 0 26 Tm .194651 Tw 12 TL /F1 10 Tf 0 0 0 rg (Finally, the implementation is such that the decorated function attribute ) Tj /F4 10 Tf (.func_globals ) Tj /F1 10 Tf (is a ) Tj /F5 10 Tf (copy ) Tj /F1 10 Tf (of the) Tj T* 0 Tw 2.966136 Tw (original function attribute. Moreover the decorated function contains a ) Tj /F5 10 Tf (copy ) Tj /F1 10 Tf (of the original function) Tj T* 0 Tw (dictionary \() Tj /F4 10 Tf (vars\(decorated_f\)) Tj ( ) Tj (is) Tj ( ) Tj (not) Tj ( ) Tj (vars\(f\)) Tj /F1 10 Tf (\):) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 87.02362 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 144 re B*

+Q

+q

+BT 1 0 0 1 0 122 Tm 12 TL /F4 10 Tf .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj /F3 10 Tf 0 .501961 0 rg (def) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 0 1 rg (f) Tj 0 0 0 rg (\(\):) Tj ( ) Tj /F3 10 Tf 0 .501961 0 rg (pass) Tj /F4 10 Tf 0 0 0 rg ( ) Tj /F6 10 Tf .25098 .501961 .501961 rg (# the original function) Tj /F4 10 Tf 0 0 0 rg  T* .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj (f) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (attr1) Tj ( ) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ( ) Tj .729412 .129412 .129412 rg ("something") Tj 0 0 0 rg ( ) Tj /F6 10 Tf .25098 .501961 .501961 rg (# setting an attribute) Tj /F4 10 Tf 0 0 0 rg  T* .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj (f) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (attr2) Tj ( ) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ( ) Tj .729412 .129412 .129412 rg ("something else") Tj 0 0 0 rg ( ) Tj /F6 10 Tf .25098 .501961 .501961 rg (# setting another attribute) Tj /F4 10 Tf 0 0 0 rg  T*  T* .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj (traced_f) Tj ( ) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ( ) Tj (trace) Tj (\() Tj (f) Tj (\)) Tj ( ) Tj /F6 10 Tf .25098 .501961 .501961 rg (# the decorated function) Tj /F4 10 Tf 0 0 0 rg  T*  T* .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj (traced_f) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (attr1) Tj  T* .729412 .129412 .129412 rg ('something') Tj 0 0 0 rg  T* .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj (traced_f) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (attr2) Tj ( ) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ( ) Tj .729412 .129412 .129412 rg ("something different") Tj 0 0 0 rg ( ) Tj /F6 10 Tf .25098 .501961 .501961 rg (# setting attr) Tj /F4 10 Tf 0 0 0 rg  T* .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj (f) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (attr2) Tj ( ) Tj /F6 10 Tf .25098 .501961 .501961 rg (# the original attribute did not change) Tj /F4 10 Tf 0 0 0 rg  T* .729412 .129412 .129412 rg ('something else') Tj T* ET

+Q

+Q

+Q

+Q

+Q

+ 

+endstream

+endobj

+% 'R99': class PDFStream 

+99 0 obj

+% page stream

+<< /Length 6552 >>

+stream

+1 0 0 1 0 0 cm  BT /F1 12 Tf 14.4 TL ET

+q

+1 0 0 1 62.69291 744.0236 cm

+q

+BT 1 0 0 1 0 3.5 Tm 21 TL /F2 17.5 Tf 0 0 0 rg (Compatibility notes) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 678.0236 cm

+q

+BT 1 0 0 1 0 50 Tm 1.404985 Tw 12 TL /F1 10 Tf 0 0 0 rg (Version 3.3 is the first version of the ) Tj /F4 10 Tf (decorator ) Tj /F1 10 Tf (module to fully support Python 3, including ) Tj 0 0 .501961 rg (function) Tj T* 0 Tw .07881 Tw (annotations) Tj 0 0 0 rg (. Version 3.2 was the first version to support Python 3 via the ) Tj /F4 10 Tf (2to3 ) Tj /F1 10 Tf (conversion tool invoked in) Tj T* 0 Tw .373555 Tw (the build process by the ) Tj 0 0 .501961 rg (distribute ) Tj 0 0 0 rg (project, the Python 3-compatible replacement of easy_install. The hard) Tj T* 0 Tw .326235 Tw (work \(for me\) has been converting the documentation and the doctests. This has been possible only after) Tj T* 0 Tw (that ) Tj 0 0 .501961 rg (docutils ) Tj 0 0 0 rg (and ) Tj 0 0 .501961 rg (pygments ) Tj 0 0 0 rg (have been ported to Python 3.) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 600.0236 cm

+q

+BT 1 0 0 1 0 62 Tm .793984 Tw 12 TL /F1 10 Tf 0 0 0 rg (Version 3 of the ) Tj /F4 10 Tf (decorator ) Tj /F1 10 Tf (module do not contain any backward incompatible change, apart from the) Tj T* 0 Tw 3.63498 Tw (removal of the functions ) Tj /F4 10 Tf (get_info ) Tj /F1 10 Tf (and ) Tj /F4 10 Tf (new_wrapper) Tj /F1 10 Tf (, which have been deprecated for years.) Tj T* 0 Tw .293672 Tw /F4 10 Tf (get_info ) Tj /F1 10 Tf (has been removed since it was little used and since it had to be changed anyway to work with) Tj T* 0 Tw 2.298555 Tw (Python 3.0; ) Tj /F4 10 Tf (new_wrapper ) Tj /F1 10 Tf (has been removed since it was useless: its major use case \(converting) Tj T* 0 Tw 7.136976 Tw (signature changing decorators to signature preserving decorators\) has been subsumed by) Tj T* 0 Tw /F4 10 Tf (decorator_apply) Tj /F1 10 Tf (, whereas the other use case can be managed with the ) Tj /F4 10 Tf (FunctionMaker) Tj /F1 10 Tf (.) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 558.0236 cm

+q

+BT 1 0 0 1 0 26 Tm 1.329213 Tw 12 TL /F1 10 Tf 0 0 0 rg (There are a few changes in the documentation: I removed the ) Tj /F4 10 Tf (decorator_factory ) Tj /F1 10 Tf (example, which) Tj T* 0 Tw 2.562927 Tw (was confusing some of my users, and I removed the part about exotic signatures in the Python 3) Tj T* 0 Tw (documentation, since Python 3 does not support them.) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 492.0236 cm

+q

+BT 1 0 0 1 0 50 Tm .942651 Tw 12 TL /F1 10 Tf 0 0 0 rg (Finally ) Tj /F4 10 Tf (decorator ) Tj /F1 10 Tf (cannot be used as a class decorator and the ) Tj 0 0 .501961 rg (functionality introduced in version 2.3) Tj T* 0 Tw .241163 Tw 0 0 0 rg (has been removed. That means that in order to define decorator factories with classes you need to define) Tj T* 0 Tw 1.122126 Tw (the ) Tj /F4 10 Tf (__call__ ) Tj /F1 10 Tf (method explicitly \(no magic anymore\). All these changes should not cause any trouble,) Tj T* 0 Tw .601163 Tw (since they were all rarely used features. Should you have any trouble, you can always downgrade to the) Tj T* 0 Tw (2.3 version.) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 426.0236 cm

+q

+BT 1 0 0 1 0 50 Tm .196098 Tw 12 TL /F1 10 Tf 0 0 0 rg (The examples shown here have been tested with Python 2.6. Python 2.4 is also supported - of course the) Tj T* 0 Tw 1.649398 Tw (examples requiring the ) Tj /F4 10 Tf (with ) Tj /F1 10 Tf (statement will not work there. Python 2.5 works fine, but if you run the) Tj T* 0 Tw 1.41784 Tw (examples in the interactive interpreter you will notice a few differences since ) Tj /F4 10 Tf (getargspec ) Tj /F1 10 Tf (returns an) Tj T* 0 Tw .909982 Tw /F4 10 Tf (ArgSpec ) Tj /F1 10 Tf (namedtuple instead of a regular tuple. That means that running the file ) Tj /F4 10 Tf (documentation.py) Tj T* 0 Tw /F1 10 Tf (under Python 2.5 will print a few errors, but they are not serious.) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 393.0236 cm

+q

+BT 1 0 0 1 0 3.5 Tm 21 TL /F2 17.5 Tf 0 0 0 rg (LICENCE) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 375.0236 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 2 Tm /F1 10 Tf 12 TL (Copyright \(c\) 2005-2012, Michele Simionato All rights reserved.) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 345.0236 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 14 Tm /F1 10 Tf 12 TL 1.328555 Tw (Redistribution and use in source and binary forms, with or without modification, are permitted provided) Tj T* 0 Tw (that the following conditions are met:) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 339.0236 cm

+Q

+q

+1 0 0 1 62.69291 291.0236 cm

+0 0 0 rg

+BT /F1 10 Tf 12 TL ET

+BT 1 0 0 1 0 2 Tm  T* ET

+q

+1 0 0 1 20 0 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 38 Tm /F1 10 Tf 12 TL .830651 Tw (Redistributions of source code must retain the above copyright notice, this list of conditions and the) Tj T* 0 Tw .161647 Tw (following disclaimer. Redistributions in bytecode form must reproduce the above copyright notice, this) Tj T* 0 Tw 1.259213 Tw (list of conditions and the following disclaimer in the documentation and/or other materials provided) Tj T* 0 Tw (with the distribution.) Tj T* ET

+Q

+Q

+q

+Q

+Q

+q

+1 0 0 1 62.69291 291.0236 cm

+Q

+q

+1 0 0 1 62.69291 165.0236 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 110 Tm /F1 10 Tf 12 TL .17998 Tw (THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND) Tj T* 0 Tw 2.911797 Tw (ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED) Tj T* 0 Tw 5.165529 Tw (WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE) Tj T* 0 Tw 1.395433 Tw (DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE) Tj T* 0 Tw 5.53122 Tw (FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL) Tj T* 0 Tw 2.705976 Tw (DAMAGES \(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR) Tj T* 0 Tw 3.868976 Tw (SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION\) HOWEVER) Tj T* 0 Tw 1.326647 Tw (CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR) Tj T* 0 Tw 1.525366 Tw (TORT \(INCLUDING NEGLIGENCE OR OTHERWISE\) ARISING IN ANY WAY OUT OF THE USE OF) Tj T* 0 Tw (THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 135.0236 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 14 Tm /F1 10 Tf 12 TL .407132 Tw (If you use this software and you are happy with it, consider sending me a note, just to gratify my ego. On) Tj T* 0 Tw (the other hand, if you use this software and you are unhappy with it, send me a patch!) Tj T* ET

+Q

+Q

+ 

+endstream

+endobj

+% 'R100': class PDFPageLabels 

+100 0 obj

+% Document Root

+<< /Nums [ 0

+ 101 0 R

+ 1

+ 102 0 R

+ 2

+ 103 0 R

+ 3

+ 104 0 R

+ 4

+ 105 0 R

+ 5

+ 106 0 R

+ 6

+ 107 0 R

+ 7

+ 108 0 R

+ 8

+ 109 0 R

+ 9

+ 110 0 R

+ 10

+ 111 0 R

+ 11

+ 112 0 R

+ 12

+ 113 0 R

+ 13

+ 114 0 R

+ 14

+ 115 0 R ] >>

+endobj

+% 'R101': class PDFPageLabel 

+101 0 obj

+% None

+<< /S /D

+ /St 1 >>

+endobj

+% 'R102': class PDFPageLabel 

+102 0 obj

+% None

+<< /S /D

+ /St 2 >>

+endobj

+% 'R103': class PDFPageLabel 

+103 0 obj

+% None

+<< /S /D

+ /St 3 >>

+endobj

+% 'R104': class PDFPageLabel 

+104 0 obj

+% None

+<< /S /D

+ /St 4 >>

+endobj

+% 'R105': class PDFPageLabel 

+105 0 obj

+% None

+<< /S /D

+ /St 5 >>

+endobj

+% 'R106': class PDFPageLabel 

+106 0 obj

+% None

+<< /S /D

+ /St 6 >>

+endobj

+% 'R107': class PDFPageLabel 

+107 0 obj

+% None

+<< /S /D

+ /St 7 >>

+endobj

+% 'R108': class PDFPageLabel 

+108 0 obj

+% None

+<< /S /D

+ /St 8 >>

+endobj

+% 'R109': class PDFPageLabel 

+109 0 obj

+% None

+<< /S /D

+ /St 9 >>

+endobj

+% 'R110': class PDFPageLabel 

+110 0 obj

+% None

+<< /S /D

+ /St 10 >>

+endobj

+% 'R111': class PDFPageLabel 

+111 0 obj

+% None

+<< /S /D

+ /St 11 >>

+endobj

+% 'R112': class PDFPageLabel 

+112 0 obj

+% None

+<< /S /D

+ /St 12 >>

+endobj

+% 'R113': class PDFPageLabel 

+113 0 obj

+% None

+<< /S /D

+ /St 13 >>

+endobj

+% 'R114': class PDFPageLabel 

+114 0 obj

+% None

+<< /S /D

+ /St 14 >>

+endobj

+% 'R115': class PDFPageLabel 

+115 0 obj

+% None

+<< /S /D

+ /St 15 >>

+endobj

+xref

+0 116

+0000000000 65535 f

+0000000113 00000 n

+0000000271 00000 n

+0000000436 00000 n

+0000000611 00000 n

+0000000794 00000 n

+0000001046 00000 n

+0000001295 00000 n

+0000001469 00000 n

+0000001710 00000 n

+0000001951 00000 n

+0000002193 00000 n

+0000002435 00000 n

+0000002677 00000 n

+0000002919 00000 n

+0000003162 00000 n

+0000003405 00000 n

+0000003648 00000 n

+0000003891 00000 n

+0000004133 00000 n

+0000004375 00000 n

+0000004618 00000 n

+0000004861 00000 n

+0000005104 00000 n

+0000005347 00000 n

+0000005590 00000 n

+0000005833 00000 n

+0000006076 00000 n

+0000006319 00000 n

+0000006562 00000 n

+0000006805 00000 n

+0000007048 00000 n

+0000007291 00000 n

+0000007534 00000 n

+0000007777 00000 n

+0000008020 00000 n

+0000008263 00000 n

+0000008506 00000 n

+0000008733 00000 n

+0000009311 00000 n

+0000009506 00000 n

+0000009762 00000 n

+0000009953 00000 n

+0000010213 00000 n

+0000010523 00000 n

+0000010803 00000 n

+0000011083 00000 n

+0000011363 00000 n

+0000011643 00000 n

+0000011923 00000 n

+0000012203 00000 n

+0000012484 00000 n

+0000012779 00000 n

+0000013034 00000 n

+0000013302 00000 n

+0000013613 00000 n

+0000013908 00000 n

+0000014153 00000 n

+0000014455 00000 n

+0000014750 00000 n

+0000015010 00000 n

+0000015270 00000 n

+0000015528 00000 n

+0000015780 00000 n

+0000016020 00000 n

+0000016327 00000 n

+0000016674 00000 n

+0000016834 00000 n

+0000017119 00000 n

+0000017245 00000 n

+0000017418 00000 n

+0000017605 00000 n

+0000017805 00000 n

+0000017993 00000 n

+0000018186 00000 n

+0000018385 00000 n

+0000018569 00000 n

+0000018750 00000 n

+0000018940 00000 n

+0000019140 00000 n

+0000019340 00000 n

+0000019552 00000 n

+0000019752 00000 n

+0000019948 00000 n

+0000020100 00000 n

+0000020335 00000 n

+0000029480 00000 n

+0000037125 00000 n

+0000045281 00000 n

+0000052495 00000 n

+0000061446 00000 n

+0000068701 00000 n

+0000076181 00000 n

+0000083501 00000 n

+0000090780 00000 n

+0000098681 00000 n

+0000106059 00000 n

+0000113304 00000 n

+0000119694 00000 n

+0000127821 00000 n

+0000134477 00000 n

+0000134774 00000 n

+0000134853 00000 n

+0000134932 00000 n

+0000135011 00000 n

+0000135090 00000 n

+0000135169 00000 n

+0000135248 00000 n

+0000135327 00000 n

+0000135406 00000 n

+0000135485 00000 n

+0000135565 00000 n

+0000135645 00000 n

+0000135725 00000 n

+0000135805 00000 n

+0000135885 00000 n

+trailer

+<< /ID 

+ % ReportLab generated PDF document -- digest (http://www.reportlab.com) 

+ [(%\2119\\+X\235\026\270\000 \364\017F\214k) (%\2119\\+X\235\026\270\000 \364\017F\214k)] 

+

+ /Info 67 0 R

+ /Root 66 0 R

+ /Size 116 >>

+startxref

+135934

+%%EOF

diff --git a/documentation.py b/documentation.py
new file mode 100644
index 0000000..17de544
--- /dev/null
+++ b/documentation.py
@@ -0,0 +1,1114 @@
+r"""
+The ``decorator`` module
+=============================================================
+
+:Author: Michele Simionato
+:E-mail: michele.simionato@gmail.com
+:Version: $VERSION ($DATE)
+:Requires: Python 2.4+
+:Download page: http://pypi.python.org/pypi/decorator/$VERSION
+: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):
+
+$$memoize_uw
+
+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: http://www.python.org/doc/2.5.2/lib/module-functools.html
+
+The implementation above works in the sense that the decorator 
+can accept functions with generic signatures; unfortunately this
+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:
+
+$$_memoize
+
+At this point you can define your decorator as follows:
+
+$$memoize
+
+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:
+
+$$_trace
+
+$$trace
+
+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 # doctest: +ELLIPSIS
+ <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:
+
+$$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:
+
+$$on_success
+$$on_failure
+$$on_closing
+$$Async
+
+The decorated function returns 
+the current execution thread, which can be stored and checked later, for 
+instance to verify that the thread ``.isAlive()``.
+
+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") # doctest: +ELLIPSIS
+ <Thread(write-1, started...)>
+ 
+ >>> time.sleep(.1) # wait a bit, so we are sure data2 is written after data1
+ 
+ >>> write("data2") # doctest: +ELLIPSIS
+ <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 # doctest: +SKIP
+ ... def hello():
+ ...     print 'hello'
+ ...
+ >>> hello() # doctest: +SKIP
+ 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:
+
+$$identity_dec
+
+.. 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:
+
+$$decorator_apply
+
+``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.
+
+$$TailRecursive
+
+Here the decorator is implemented as a class returning callable
+objects.
+
+$$tail_recursive
+
+Here is how you apply the upgraded decorator to the good old factorial:
+
+$$factorial
+
+.. 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
+
+$$fact
+
+(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) # doctest: +ELLIPSIS
+ <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.3. 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-2012, 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!
+"""
+from __future__ import with_statement
+import sys, threading, time, functools, inspect, itertools  
+from decorator import *
+from functools import partial
+from setup import VERSION
+
+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 
+    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
+    "Called on the result of the function"
+    return result
+
+def on_failure(exc_info): # default implementation
+    "Called if the function fails"
+    pass
+
+def on_closing(): # default implementation
+    "Called at the end, both in case of success and failure"
+    pass
+
+class Async(object):
+    """
+    A decorator converting blocking functions into asynchronous
+    functions, by using threads or processes. Examples:
+
+    async_with_threads =  Async(threading.Thread)
+    async_with_processes =  Async(multiprocessing.Process)
+    """
+
+    def __init__(self, threadfactory, 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
+
+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
+            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)
+
+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
+
+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)
+            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)
+
+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"
+        userclass = get_userclass()
+        if issubclass(userclass, user_class):
+            return func(*args, **kw)
+        else:
+            raise PermissionError(
+                '%s does not have the permission to run %s!'
+                % (userclass.__name__, func.__name__))
+    return decorator(restricted)
+
+class Action(object):
+    """
+    >>> a = Action()
+    >>> a.view() # ok
+    >>> a.insert() # err
+    Traceback (most recent call last):
+       ...
+    PermissionError: User does not have the permission to run insert!
+
+    """
+    @restricted(User)
+    def view(self):
+        pass
+
+    @restricted(PowerUser)
+    def insert(self):
+        pass
+
+    @restricted(Admin)
+    def delete(self):
+        pass
+
+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
+
+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
+    return factorial(n-1, n*acc)
+
+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
+    object, thus breaking Pylons. That must not happen again.
+
+    >>> decorator(_memoize).__name__
+    '_memoize'
+
+    Here is another bug of version 3.1.1 missing the docstring to avoid:
+
+    >>> factorial.__doc__
+    'The good old factorial'
+    """
+
+@contextmanager
+def before_after(before, after):
+    print(before)
+    yield
+    print(after)
+
+ba = before_after('BEFORE', 'AFTER') # ContextManager instance
+
+@ba
+def hello(user):
+    """
+    >>> ba.__class__.__name__
+    'ContextManager'
+    >>> hello('michele')
+    BEFORE
+    hello michele
+    AFTER
+    """
+    print('hello %s' % user)
+
+if __name__ == '__main__':
+    import doctest; doctest.testmod()
diff --git a/documentation3.html b/documentation3.html
new file mode 100644
index 0000000..c5e2fac
--- /dev/null
+++ b/documentation3.html
@@ -0,0 +1,1102 @@
+<?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&#64;gmail.com">michele.simionato&#64;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">&gt;&gt;&gt;</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">&gt;&gt;&gt;</span> <span class="kn">from</span> <span class="nn">inspect</span> <span class="kn">import</span> <span class="n">getargspec</span>
+<span class="o">&gt;&gt;&gt;</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">&#39;args&#39;</span><span class="p">,</span> <span class="n">keywords</span><span class="o">=</span><span class="s">&#39;kw&#39;</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">&gt;&gt;&gt;</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">&gt;&gt;&gt;</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">&gt;&gt;&gt;</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">&quot;done&quot;</span>
+
+<span class="o">&gt;&gt;&gt;</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">&gt;&gt;&gt;</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">&gt;&gt;&gt;</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">&#39;, &#39;</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="s">&#39;</span><span class="si">%r</span><span class="s">: </span><span class="si">%r</span><span class="s">&#39;</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">&quot;calling </span><span class="si">%s</span><span class="s"> with args </span><span class="si">%s</span><span class="s">, {</span><span class="si">%s</span><span class="s">}&quot;</span> <span class="o">%</span> <span class="p">(</span><span class="n">f</span><span class="o">.</span><span class="n">__name__</span><span class="p">,</span> <span class="n">args</span><span class="p">,</span> <span class="n">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">&gt;&gt;&gt;</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">&gt;&gt;&gt;</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">&gt;&gt;&gt;</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">&#39;x&#39;</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">&gt;&gt;&gt;</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">&gt;&gt;&gt;</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">&gt;&gt;&gt;</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">&#39;x&#39;</span><span class="p">,</span> <span class="s">&#39;y&#39;</span><span class="p">,</span> <span class="s">&#39;z&#39;</span><span class="p">],</span> <span class="n">varargs</span><span class="o">=</span><span class="s">&#39;args&#39;</span><span class="p">,</span> <span class="n">keywords</span><span class="o">=</span><span class="s">&#39;kw&#39;</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">&gt;&gt;&gt;</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">&#39;the first argument&#39;</span><span class="p">,</span> <span class="n">y</span><span class="p">:</span> <span class="s">&#39;default argument&#39;</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">&#39;varargs&#39;</span><span class="p">,</span> <span class="o">**</span><span class="n">kw</span><span class="p">:</span> <span class="s">&#39;kwargs&#39;</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">&gt;&gt;&gt;</span> <span class="kn">from</span> <span class="nn">inspect</span> <span class="kn">import</span> <span class="n">getfullargspec</span>
+<span class="o">&gt;&gt;&gt;</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">&gt;&gt;&gt;</span> <span class="n">argspec</span><span class="o">.</span><span class="n">args</span>
+<span class="p">[</span><span class="s">&#39;x&#39;</span><span class="p">,</span> <span class="s">&#39;y&#39;</span><span class="p">,</span> <span class="s">&#39;z&#39;</span><span class="p">]</span>
+<span class="o">&gt;&gt;&gt;</span> <span class="n">argspec</span><span class="o">.</span><span class="n">varargs</span>
+<span class="s">&#39;args&#39;</span>
+<span class="o">&gt;&gt;&gt;</span> <span class="n">argspec</span><span class="o">.</span><span class="n">varkw</span>
+<span class="s">&#39;kw&#39;</span>
+<span class="o">&gt;&gt;&gt;</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">&gt;&gt;&gt;</span> <span class="n">argspec</span><span class="o">.</span><span class="n">kwonlyargs</span>
+<span class="p">[]</span>
+<span class="o">&gt;&gt;&gt;</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">&gt;&gt;&gt;</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">&gt;&gt;&gt;</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">&#39;, &#39;</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="s">&#39;</span><span class="si">%r</span><span class="s">: </span><span class="si">%r</span><span class="s">&#39;</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">&quot;calling </span><span class="si">%s</span><span class="s"> with args </span><span class="si">%s</span><span class="s">, {</span><span class="si">%s</span><span class="s">}&quot;</span> <span class="o">%</span> <span class="p">(</span><span class="n">f</span><span class="o">.</span><span class="n">__name__</span><span class="p">,</span> <span class="n">args</span><span class="p">,</span> <span class="n">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">&gt;&gt;&gt;</span> <span class="n">trace</span>
+<span class="o">&lt;</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">...&gt;</span>
+</pre></div>
+
+</div>
+<p>Here is an example of usage:</p>
+<div class="codeblock python">
+<div class="highlight"><pre><span class="o">&gt;&gt;&gt;</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">&gt;&gt;&gt;</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 &quot;busy&quot; 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">&quot;thread&quot;</span><span class="p">):</span> <span class="c"># no thread running</span>
+            <span class="k">def</span> <span class="nf">set_result</span><span class="p">():</span> <span class="n">f</span><span class="o">.</span><span class="n">result</span> <span class="o">=</span> <span class="n">f</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kw</span><span class="p">)</span>
+            <span class="n">f</span><span class="o">.</span><span class="n">thread</span> <span class="o">=</span> <span class="n">threading</span><span class="o">.</span><span class="n">Thread</span><span class="p">(</span><span class="bp">None</span><span class="p">,</span> <span class="n">set_result</span><span class="p">)</span>
+            <span class="n">f</span><span class="o">.</span><span class="n">thread</span><span class="o">.</span><span class="n">start</span><span class="p">()</span>
+            <span class="k">return</span> <span class="n">not_avail</span>
+        <span class="k">elif</span> <span class="n">f</span><span class="o">.</span><span class="n">thread</span><span class="o">.</span><span class="n">isAlive</span><span class="p">():</span>
+            <span class="k">return</span> <span class="n">not_avail</span>
+        <span class="k">else</span><span class="p">:</span> <span class="c"># the thread is ended, return the stored result</span>
+            <span class="k">del</span> <span class="n">f</span><span class="o">.</span><span class="n">thread</span>
+            <span class="k">return</span> <span class="n">f</span><span class="o">.</span><span class="n">result</span>
+    <span class="k">return</span> <span class="n">decorator</span><span class="p">(</span><span class="n">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">&gt;&gt;&gt;</span> <span class="nd">@blocking</span><span class="p">(</span><span class="s">&quot;Please wait ...&quot;</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">&quot;some data&quot;</span>
+
+<span class="o">&gt;&gt;&gt;</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">&gt;&gt;&gt;</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">&gt;&gt;&gt;</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">&gt;&gt;&gt;</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">&gt;&gt;&gt;</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">&gt;&gt;&gt;</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">&gt;&gt;&gt;</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">&quot;Called on the result of the function&quot;</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">&quot;Called if the function fails&quot;</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">&quot;Called at the end, both in case of success and failure&quot;</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">&quot;&quot;&quot;</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">    &quot;&quot;&quot;</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">&#39;</span><span class="si">%s</span><span class="s">-</span><span class="si">%s</span><span class="s">&#39;</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">&gt;&gt;&gt;</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">&gt;&gt;&gt;</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">&gt;&gt;&gt;</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">&gt;&gt;&gt;</span> <span class="n">write</span><span class="p">(</span><span class="s">&quot;data1&quot;</span><span class="p">)</span>
+<span class="o">&lt;</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">&gt;</span>
+
+<span class="o">&gt;&gt;&gt;</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">&gt;&gt;&gt;</span> <span class="n">write</span><span class="p">(</span><span class="s">&quot;data2&quot;</span><span class="p">)</span>
+<span class="o">&lt;</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">&gt;</span>
+
+<span class="o">&gt;&gt;&gt;</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">&gt;&gt;&gt;</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">&#39;data1&#39;</span><span class="p">,</span> <span class="s">&#39;data2&#39;</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">&gt;&gt;&gt;</span> <span class="kn">from</span> <span class="nn">contextlib</span> <span class="kn">import</span> <span class="n">contextmanager</span>
+<span class="o">&gt;&gt;&gt;</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">&gt;&gt;&gt;</span> <span class="n">ba</span> <span class="o">=</span> <span class="n">before_after</span><span class="p">(</span><span class="s">&#39;BEFORE&#39;</span><span class="p">,</span> <span class="s">&#39;AFTER&#39;</span><span class="p">)</span>
+<span class="o">&gt;&gt;&gt;</span> <span class="nb">type</span><span class="p">(</span><span class="n">ba</span><span class="p">)</span>
+<span class="o">&lt;</span><span class="k">class</span> <span class="err">&#39;</span><span class="nc">contextlib</span><span class="o">.</span><span class="n">_GeneratorContextManager</span><span class="s">&#39;&gt;</span>
+<span class="o">&gt;&gt;&gt;</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">&#39;hello&#39;</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">&gt;&gt;&gt;</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">&#39;hello&#39;</span><span class="p">)</span>
+<span class="o">...</span>
+<span class="o">&gt;&gt;&gt;</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">&gt;&gt;&gt;</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">&gt;&gt;&gt;</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">&#39;f1(a, b)&#39;</span><span class="p">,</span> <span class="s">&#39;f(a, b)&#39;</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">&gt;&gt;&gt;</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">&gt;&gt;&gt;</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">&#39;f1(a, b)&#39;</span><span class="p">,</span> <span class="s">&#39;f(a, b)&#39;</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">&gt;&gt;&gt;</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">&lt;</span><span class="n">BLANKLINE</span><span class="o">&gt;</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">&gt;&gt;&gt;</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">&lt;</span><span class="n">BLANKLINE</span><span class="o">&gt;</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">&gt;&gt;&gt;</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">&quot;The good old factorial&quot;</span>
+    <span class="k">if</span> <span class="n">n</span> <span class="o">==</span> <span class="mi">0</span><span class="p">:</span> <span class="k">return</span> <span class="n">acc</span>
+    <span class="k">return</span> <span class="n">factorial</span><span class="p">(</span><span class="n">n</span><span class="o">-</span><span class="mi">1</span><span class="p">,</span> <span class="n">n</span><span class="o">*</span><span class="n">acc</span><span class="p">)</span>
+<span class="o">&lt;</span><span class="n">BLANKLINE</span><span class="o">&gt;</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">&quot;&quot;&quot;</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">    &quot;&quot;&quot;</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">&#39;return decorated(</span><span class="si">%(signature)s</span><span class="s">)&#39;</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">&quot;&quot;&quot;</span>
+<span class="sd">    tail_recursive decorator based on Kay Schluehr&#39;s recipe</span>
+<span class="sd">    http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/496691</span>
+<span class="sd">    with improvements by me and George Sakkis.</span>
+<span class="sd">    &quot;&quot;&quot;</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">&quot;The good old factorial&quot;</span>
+    <span class="k">if</span> <span class="n">n</span> <span class="o">==</span> <span class="mi">0</span><span class="p">:</span> <span class="k">return</span> <span class="n">acc</span>
+    <span class="k">return</span> <span class="n">factorial</span><span class="p">(</span><span class="n">n</span><span class="o">-</span><span class="mi">1</span><span class="p">,</span> <span class="n">n</span><span class="o">*</span><span class="n">acc</span><span class="p">)</span>
+</pre></div>
+
+</div>
+<div class="codeblock python">
+<div class="highlight"><pre><span class="o">&gt;&gt;&gt;</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 &quot;
+from decorator import decorator
+
+&#64;decorator
+def do_nothing(func, *args, **kw):
+    return func(*args, **kw)
+
+&#64;do_nothing
+def f():
+    pass
+&quot; &quot;f()&quot;
+
+python3 -m timeit -s &quot;
+def f():
+    pass
+&quot; &quot;f()&quot;
+</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">&gt;&gt;&gt;</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">&gt;&gt;&gt;</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">&quot;&lt;string&gt;&quot;</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">&quot;&lt;doctest __main__[22]&gt;&quot;</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">&quot;&lt;doctest __main__[51]&gt;&quot;</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">&quot;&lt;string&gt;&quot;,</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">&gt;&gt;&gt;</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">&gt;&gt;&gt;</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">&gt;&gt;&gt;</span> <span class="n">f</span><span class="o">.</span><span class="n">attr1</span> <span class="o">=</span> <span class="s">&quot;something&quot;</span> <span class="c"># setting an attribute</span>
+<span class="o">&gt;&gt;&gt;</span> <span class="n">f</span><span class="o">.</span><span class="n">attr2</span> <span class="o">=</span> <span class="s">&quot;something else&quot;</span> <span class="c"># setting another attribute</span>
+
+<span class="o">&gt;&gt;&gt;</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">&gt;&gt;&gt;</span> <span class="n">traced_f</span><span class="o">.</span><span class="n">attr1</span>
+<span class="s">&#39;something&#39;</span>
+<span class="o">&gt;&gt;&gt;</span> <span class="n">traced_f</span><span class="o">.</span><span class="n">attr2</span> <span class="o">=</span> <span class="s">&quot;something different&quot;</span> <span class="c"># setting attr</span>
+<span class="o">&gt;&gt;&gt;</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">&#39;something else&#39;</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
+&quot;AS IS&quot; AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
+INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
+BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
+OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
+TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
+USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
+DAMAGE.</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.pdf b/documentation3.pdf
new file mode 100644
index 0000000..ffdcc6c
--- /dev/null
+++ b/documentation3.pdf
@@ -0,0 +1,4018 @@
+%PDF-1.4

+%���� ReportLab Generated PDF document http://www.reportlab.com

+% 'BasicFonts': class PDFDictionary 

+1 0 obj

+% The standard fonts dictionary

+<< /F1 2 0 R

+ /F2 3 0 R

+ /F3 4 0 R

+ /F4 7 0 R

+ /F5 41 0 R

+ /F6 43 0 R >>

+endobj

+% 'F1': class PDFType1Font 

+2 0 obj

+% Font Helvetica

+<< /BaseFont /Helvetica

+ /Encoding /WinAnsiEncoding

+ /Name /F1

+ /Subtype /Type1

+ /Type /Font >>

+endobj

+% 'F2': class PDFType1Font 

+3 0 obj

+% Font Helvetica-Bold

+<< /BaseFont /Helvetica-Bold

+ /Encoding /WinAnsiEncoding

+ /Name /F2

+ /Subtype /Type1

+ /Type /Font >>

+endobj

+% 'F3': class PDFType1Font 

+4 0 obj

+% Font Courier-Bold

+<< /BaseFont /Courier-Bold

+ /Encoding /WinAnsiEncoding

+ /Name /F3

+ /Subtype /Type1

+ /Type /Font >>

+endobj

+% 'Annot.NUMBER1': class PDFDictionary 

+5 0 obj

+<< /A << /S /URI

+ /Type /Action

+ /URI (mailto:michele.simionato@gmail.com) >>

+ /Border [ 0

+ 0

+ 0 ]

+ /Rect [ 153.7323

+ 704.7736

+ 289.4623

+ 716.7736 ]

+ /Subtype /Link

+ /Type /Annot >>

+endobj

+% 'Annot.NUMBER2': class PDFDictionary 

+6 0 obj

+<< /A << /S /URI

+ /Type /Action

+ /URI (http://pypi.python.org/pypi/decorator/3.4.0) >>

+ /Border [ 0

+ 0

+ 0 ]

+ /Rect [ 153.7323

+ 659.7736

+ 526.5827

+ 671.7736 ]

+ /Subtype /Link

+ /Type /Annot >>

+endobj

+% 'F4': class PDFType1Font 

+7 0 obj

+% Font Courier

+<< /BaseFont /Courier

+ /Encoding /WinAnsiEncoding

+ /Name /F4

+ /Subtype /Type1

+ /Type /Font >>

+endobj

+% 'Annot.NUMBER3': class LinkAnnotation 

+8 0 obj

+<< /Border [ 0

+ 0

+ 0 ]

+ /Contents ()

+ /Dest [ 40 0 R

+ /XYZ

+ 62.69291

+ 275.0236

+ 0 ]

+ /Rect [ 62.69291

+ 560.7736

+ 121.0229

+ 572.7736 ]

+ /Subtype /Link

+ /Type /Annot >>

+endobj

+% 'Annot.NUMBER4': class LinkAnnotation 

+9 0 obj

+<< /Border [ 0

+ 0

+ 0 ]

+ /Contents ()

+ /Dest [ 40 0 R

+ /XYZ

+ 62.69291

+ 275.0236

+ 0 ]

+ /Rect [ 527.0227

+ 560.7736

+ 532.5827

+ 572.7736 ]

+ /Subtype /Link

+ /Type /Annot >>

+endobj

+% 'Annot.NUMBER5': class LinkAnnotation 

+10 0 obj

+<< /Border [ 0

+ 0

+ 0 ]

+ /Contents ()

+ /Dest [ 45 0 R

+ /XYZ

+ 62.69291

+ 657.0236

+ 0 ]

+ /Rect [ 62.69291

+ 542.7736

+ 114.3629

+ 554.7736 ]

+ /Subtype /Link

+ /Type /Annot >>

+endobj

+% 'Annot.NUMBER6': class LinkAnnotation 

+11 0 obj

+<< /Border [ 0

+ 0

+ 0 ]

+ /Contents ()

+ /Dest [ 45 0 R

+ /XYZ

+ 62.69291

+ 657.0236

+ 0 ]

+ /Rect [ 527.0227

+ 542.7736

+ 532.5827

+ 554.7736 ]

+ /Subtype /Link

+ /Type /Annot >>

+endobj

+% 'Annot.NUMBER7': class LinkAnnotation 

+12 0 obj

+<< /Border [ 0

+ 0

+ 0 ]

+ /Contents ()

+ /Dest [ 45 0 R

+ /XYZ

+ 62.69291

+ 420.0236

+ 0 ]

+ /Rect [ 62.69291

+ 524.7736

+ 183.2629

+ 536.7736 ]

+ /Subtype /Link

+ /Type /Annot >>

+endobj

+% 'Annot.NUMBER8': class LinkAnnotation 

+13 0 obj

+<< /Border [ 0

+ 0

+ 0 ]

+ /Contents ()

+ /Dest [ 45 0 R

+ /XYZ

+ 62.69291

+ 420.0236

+ 0 ]

+ /Rect [ 527.0227

+ 524.7736

+ 532.5827

+ 536.7736 ]

+ /Subtype /Link

+ /Type /Annot >>

+endobj

+% 'Annot.NUMBER9': class LinkAnnotation 

+14 0 obj

+<< /Border [ 0

+ 0

+ 0 ]

+ /Contents ()

+ /Dest [ 46 0 R

+ /XYZ

+ 62.69291

+ 409.4236

+ 0 ]

+ /Rect [ 62.69291

+ 506.7736

+ 122.1429

+ 518.7736 ]

+ /Subtype /Link

+ /Type /Annot >>

+endobj

+% 'Annot.NUMBER10': class LinkAnnotation 

+15 0 obj

+<< /Border [ 0

+ 0

+ 0 ]

+ /Contents ()

+ /Dest [ 46 0 R

+ /XYZ

+ 62.69291

+ 409.4236

+ 0 ]

+ /Rect [ 527.0227

+ 506.7736

+ 532.5827

+ 518.7736 ]

+ /Subtype /Link

+ /Type /Annot >>

+endobj

+% 'Annot.NUMBER11': class LinkAnnotation 

+16 0 obj

+<< /Border [ 0

+ 0

+ 0 ]

+ /Contents ()

+ /Dest [ 47 0 R

+ /XYZ

+ 62.69291

+ 435.4236

+ 0 ]

+ /Rect [ 62.69291

+ 488.7736

+ 154.8129

+ 500.7736 ]

+ /Subtype /Link

+ /Type /Annot >>

+endobj

+% 'Annot.NUMBER12': class LinkAnnotation 

+17 0 obj

+<< /Border [ 0

+ 0

+ 0 ]

+ /Contents ()

+ /Dest [ 47 0 R

+ /XYZ

+ 62.69291

+ 435.4236

+ 0 ]

+ /Rect [ 527.0227

+ 488.7736

+ 532.5827

+ 500.7736 ]

+ /Subtype /Link

+ /Type /Annot >>

+endobj

+% 'Annot.NUMBER13': class LinkAnnotation 

+18 0 obj

+<< /Border [ 0

+ 0

+ 0 ]

+ /Contents ()

+ /Dest [ 49 0 R

+ /XYZ

+ 62.69291

+ 567.978

+ 0 ]

+ /Rect [ 62.69291

+ 470.7736

+ 164.3629

+ 482.7736 ]

+ /Subtype /Link

+ /Type /Annot >>

+endobj

+% 'Annot.NUMBER14': class LinkAnnotation 

+19 0 obj

+<< /Border [ 0

+ 0

+ 0 ]

+ /Contents ()

+ /Dest [ 49 0 R

+ /XYZ

+ 62.69291

+ 567.978

+ 0 ]

+ /Rect [ 527.0227

+ 470.7736

+ 532.5827

+ 482.7736 ]

+ /Subtype /Link

+ /Type /Annot >>

+endobj

+% 'Annot.NUMBER15': class LinkAnnotation 

+20 0 obj

+<< /Border [ 0

+ 0

+ 0 ]

+ /Contents ()

+ /Dest [ 50 0 R

+ /XYZ

+ 62.69291

+ 765.0236

+ 0 ]

+ /Rect [ 62.69291

+ 452.7736

+ 188.2729

+ 464.7736 ]

+ /Subtype /Link

+ /Type /Annot >>

+endobj

+% 'Annot.NUMBER16': class LinkAnnotation 

+21 0 obj

+<< /Border [ 0

+ 0

+ 0 ]

+ /Contents ()

+ /Dest [ 50 0 R

+ /XYZ

+ 62.69291

+ 765.0236

+ 0 ]

+ /Rect [ 527.0227

+ 452.7736

+ 532.5827

+ 464.7736 ]

+ /Subtype /Link

+ /Type /Annot >>

+endobj

+% 'Annot.NUMBER17': class LinkAnnotation 

+22 0 obj

+<< /Border [ 0

+ 0

+ 0 ]

+ /Contents ()

+ /Dest [ 50 0 R

+ /XYZ

+ 62.69291

+ 338.4236

+ 0 ]

+ /Rect [ 62.69291

+ 434.7736

+ 110.6929

+ 446.7736 ]

+ /Subtype /Link

+ /Type /Annot >>

+endobj

+% 'Annot.NUMBER18': class LinkAnnotation 

+23 0 obj

+<< /Border [ 0

+ 0

+ 0 ]

+ /Contents ()

+ /Dest [ 50 0 R

+ /XYZ

+ 62.69291

+ 338.4236

+ 0 ]

+ /Rect [ 527.0227

+ 434.7736

+ 532.5827

+ 446.7736 ]

+ /Subtype /Link

+ /Type /Annot >>

+endobj

+% 'Annot.NUMBER19': class LinkAnnotation 

+24 0 obj

+<< /Border [ 0

+ 0

+ 0 ]

+ /Contents ()

+ /Dest [ 51 0 R

+ /XYZ

+ 62.69291

+ 479.8236

+ 0 ]

+ /Rect [ 62.69291

+ 416.7736

+ 92.69291

+ 428.7736 ]

+ /Subtype /Link

+ /Type /Annot >>

+endobj

+% 'Annot.NUMBER20': class LinkAnnotation 

+25 0 obj

+<< /Border [ 0

+ 0

+ 0 ]

+ /Contents ()

+ /Dest [ 51 0 R

+ /XYZ

+ 62.69291

+ 479.8236

+ 0 ]

+ /Rect [ 527.0227

+ 416.7736

+ 532.5827

+ 428.7736 ]

+ /Subtype /Link

+ /Type /Annot >>

+endobj

+% 'Annot.NUMBER21': class LinkAnnotation 

+26 0 obj

+<< /Border [ 0

+ 0

+ 0 ]

+ /Contents ()

+ /Dest [ 53 0 R

+ /XYZ

+ 62.69291

+ 643.8236

+ 0 ]

+ /Rect [ 62.69291

+ 398.7736

+ 139.9329

+ 410.7736 ]

+ /Subtype /Link

+ /Type /Annot >>

+endobj

+% 'Annot.NUMBER22': class LinkAnnotation 

+27 0 obj

+<< /Border [ 0

+ 0

+ 0 ]

+ /Contents ()

+ /Dest [ 53 0 R

+ /XYZ

+ 62.69291

+ 643.8236

+ 0 ]

+ /Rect [ 527.0227

+ 398.7736

+ 532.5827

+ 410.7736 ]

+ /Subtype /Link

+ /Type /Annot >>

+endobj

+% 'Annot.NUMBER23': class LinkAnnotation 

+28 0 obj

+<< /Border [ 0

+ 0

+ 0 ]

+ /Contents ()

+ /Dest [ 54 0 R

+ /XYZ

+ 62.69291

+ 729.0236

+ 0 ]

+ /Rect [ 62.69291

+ 380.7736

+ 192.2729

+ 392.7736 ]

+ /Subtype /Link

+ /Type /Annot >>

+endobj

+% 'Annot.NUMBER24': class LinkAnnotation 

+29 0 obj

+<< /Border [ 0

+ 0

+ 0 ]

+ /Contents ()

+ /Dest [ 54 0 R

+ /XYZ

+ 62.69291

+ 729.0236

+ 0 ]

+ /Rect [ 521.4627

+ 380.7736

+ 532.5827

+ 392.7736 ]

+ /Subtype /Link

+ /Type /Annot >>

+endobj

+% 'Annot.NUMBER25': class LinkAnnotation 

+30 0 obj

+<< /Border [ 0

+ 0

+ 0 ]

+ /Contents ()

+ /Dest [ 56 0 R

+ /XYZ

+ 62.69291

+ 765.0236

+ 0 ]

+ /Rect [ 62.69291

+ 362.7736

+ 177.1629

+ 374.7736 ]

+ /Subtype /Link

+ /Type /Annot >>

+endobj

+% 'Annot.NUMBER26': class LinkAnnotation 

+31 0 obj

+<< /Border [ 0

+ 0

+ 0 ]

+ /Contents ()

+ /Dest [ 56 0 R

+ /XYZ

+ 62.69291

+ 765.0236

+ 0 ]

+ /Rect [ 521.4627

+ 362.7736

+ 532.5827

+ 374.7736 ]

+ /Subtype /Link

+ /Type /Annot >>

+endobj

+% 'Annot.NUMBER27': class LinkAnnotation 

+32 0 obj

+<< /Border [ 0

+ 0

+ 0 ]

+ /Contents ()

+ /Dest [ 56 0 R

+ /XYZ

+ 62.69291

+ 318.4236

+ 0 ]

+ /Rect [ 62.69291

+ 344.7736

+ 228.2829

+ 356.7736 ]

+ /Subtype /Link

+ /Type /Annot >>

+endobj

+% 'Annot.NUMBER28': class LinkAnnotation 

+33 0 obj

+<< /Border [ 0

+ 0

+ 0 ]

+ /Contents ()

+ /Dest [ 56 0 R

+ /XYZ

+ 62.69291

+ 318.4236

+ 0 ]

+ /Rect [ 521.4627

+ 344.7736

+ 532.5827

+ 356.7736 ]

+ /Subtype /Link

+ /Type /Annot >>

+endobj

+% 'Annot.NUMBER29': class LinkAnnotation 

+34 0 obj

+<< /Border [ 0

+ 0

+ 0 ]

+ /Contents ()

+ /Dest [ 59 0 R

+ /XYZ

+ 62.69291

+ 615.8236

+ 0 ]

+ /Rect [ 62.69291

+ 326.7736

+ 174.3929

+ 338.7736 ]

+ /Subtype /Link

+ /Type /Annot >>

+endobj

+% 'Annot.NUMBER30': class LinkAnnotation 

+35 0 obj

+<< /Border [ 0

+ 0

+ 0 ]

+ /Contents ()

+ /Dest [ 59 0 R

+ /XYZ

+ 62.69291

+ 615.8236

+ 0 ]

+ /Rect [ 521.4627

+ 326.7736

+ 532.5827

+ 338.7736 ]

+ /Subtype /Link

+ /Type /Annot >>

+endobj

+% 'Annot.NUMBER31': class LinkAnnotation 

+36 0 obj

+<< /Border [ 0

+ 0

+ 0 ]

+ /Contents ()

+ /Dest [ 68 0 R

+ /XYZ

+ 62.69291

+ 765.0236

+ 0 ]

+ /Rect [ 62.69291

+ 308.7736

+ 155.4829

+ 320.7736 ]

+ /Subtype /Link

+ /Type /Annot >>

+endobj

+% 'Annot.NUMBER32': class LinkAnnotation 

+37 0 obj

+<< /Border [ 0

+ 0

+ 0 ]

+ /Contents ()

+ /Dest [ 68 0 R

+ /XYZ

+ 62.69291

+ 765.0236

+ 0 ]

+ /Rect [ 521.4627

+ 308.7736

+ 532.5827

+ 320.7736 ]

+ /Subtype /Link

+ /Type /Annot >>

+endobj

+% 'Annot.NUMBER33': class LinkAnnotation 

+38 0 obj

+<< /Border [ 0

+ 0

+ 0 ]

+ /Contents ()

+ /Dest [ 68 0 R

+ /XYZ

+ 62.69291

+ 414.0236

+ 0 ]

+ /Rect [ 62.69291

+ 290.7736

+ 106.5829

+ 302.7736 ]

+ /Subtype /Link

+ /Type /Annot >>

+endobj

+% 'Annot.NUMBER34': class LinkAnnotation 

+39 0 obj

+<< /Border [ 0

+ 0

+ 0 ]

+ /Contents ()

+ /Dest [ 68 0 R

+ /XYZ

+ 62.69291

+ 414.0236

+ 0 ]

+ /Rect [ 521.4627

+ 290.7736

+ 532.5827

+ 302.7736 ]

+ /Subtype /Link

+ /Type /Annot >>

+endobj

+% 'Page1': class PDFPage 

+40 0 obj

+% Page dictionary

+<< /Annots [ 5 0 R

+ 6 0 R

+ 8 0 R

+ 9 0 R

+ 10 0 R

+ 11 0 R

+ 12 0 R

+ 13 0 R

+ 14 0 R

+ 15 0 R

+ 16 0 R

+ 17 0 R

+ 18 0 R

+ 19 0 R

+ 20 0 R

+ 21 0 R

+ 22 0 R

+ 23 0 R

+ 24 0 R

+ 25 0 R

+ 26 0 R

+ 27 0 R

+ 28 0 R

+ 29 0 R

+ 30 0 R

+ 31 0 R

+ 32 0 R

+ 33 0 R

+ 34 0 R

+ 35 0 R

+ 36 0 R

+ 37 0 R

+ 38 0 R

+ 39 0 R ]

+ /Contents 89 0 R

+ /MediaBox [ 0

+ 0

+ 595.2756

+ 841.8898 ]

+ /Parent 88 0 R

+ /Resources << /Font 1 0 R

+ /ProcSet [ /PDF

+ /Text

+ /ImageB

+ /ImageC

+ /ImageI ] >>

+ /Rotate 0

+ /Trans <<  >>

+ /Type /Page >>

+endobj

+% 'F5': class PDFType1Font 

+41 0 obj

+% Font Helvetica-Oblique

+<< /BaseFont /Helvetica-Oblique

+ /Encoding /WinAnsiEncoding

+ /Name /F5

+ /Subtype /Type1

+ /Type /Font >>

+endobj

+% 'Annot.NUMBER35': class PDFDictionary 

+42 0 obj

+<< /A << /S /URI

+ /Type /Action

+ /URI (http://www.python.org/moin/PythonDecoratorLibrary) >>

+ /Border [ 0

+ 0

+ 0 ]

+ /Rect [ 219.6428

+ 345.7736

+ 449.1728

+ 357.7736 ]

+ /Subtype /Link

+ /Type /Annot >>

+endobj

+% 'F6': class PDFType1Font 

+43 0 obj

+% Font Courier-Oblique

+<< /BaseFont /Courier-Oblique

+ /Encoding /WinAnsiEncoding

+ /Name /F6

+ /Subtype /Type1

+ /Type /Font >>

+endobj

+% 'Annot.NUMBER36': class PDFDictionary 

+44 0 obj

+<< /A << /S /URI

+ /Type /Action

+ /URI (http://www.python.org/doc/2.5.2/lib/module-functools.html) >>

+ /Border [ 0

+ 0

+ 0 ]

+ /Rect [ 151.0486

+ 112.5736

+ 270.69

+ 124.5736 ]

+ /Subtype /Link

+ /Type /Annot >>

+endobj

+% 'Page2': class PDFPage 

+45 0 obj

+% Page dictionary

+<< /Annots [ 42 0 R

+ 44 0 R ]

+ /Contents 90 0 R

+ /MediaBox [ 0

+ 0

+ 595.2756

+ 841.8898 ]

+ /Parent 88 0 R

+ /Resources << /Font 1 0 R

+ /ProcSet [ /PDF

+ /Text

+ /ImageB

+ /ImageC

+ /ImageI ] >>

+ /Rotate 0

+ /Trans <<  >>

+ /Type /Page >>

+endobj

+% 'Page3': class PDFPage 

+46 0 obj

+% Page dictionary

+<< /Contents 91 0 R

+ /MediaBox [ 0

+ 0

+ 595.2756

+ 841.8898 ]

+ /Parent 88 0 R

+ /Resources << /Font 1 0 R

+ /ProcSet [ /PDF

+ /Text

+ /ImageB

+ /ImageC

+ /ImageI ] >>

+ /Rotate 0

+ /Trans <<  >>

+ /Type /Page >>

+endobj

+% 'Page4': class PDFPage 

+47 0 obj

+% Page dictionary

+<< /Contents 92 0 R

+ /MediaBox [ 0

+ 0

+ 595.2756

+ 841.8898 ]

+ /Parent 88 0 R

+ /Resources << /Font 1 0 R

+ /ProcSet [ /PDF

+ /Text

+ /ImageB

+ /ImageC

+ /ImageI ] >>

+ /Rotate 0

+ /Trans <<  >>

+ /Type /Page >>

+endobj

+% 'Annot.NUMBER37': class PDFDictionary 

+48 0 obj

+<< /A << /S /URI

+ /Type /Action

+ /URI (http://www.python.org/dev/peps/pep-3107/) >>

+ /Border [ 0

+ 0

+ 0 ]

+ /Rect [ 231.6368

+ 529.728

+ 323.0741

+ 541.728 ]

+ /Subtype /Link

+ /Type /Annot >>

+endobj

+% 'Page5': class PDFPage 

+49 0 obj

+% Page dictionary

+<< /Annots [ 48 0 R ]

+ /Contents 93 0 R

+ /MediaBox [ 0

+ 0

+ 595.2756

+ 841.8898 ]

+ /Parent 88 0 R

+ /Resources << /Font 1 0 R

+ /ProcSet [ /PDF

+ /Text

+ /ImageB

+ /ImageC

+ /ImageI ] >>

+ /Rotate 0

+ /Trans <<  >>

+ /Type /Page >>

+endobj

+% 'Page6': class PDFPage 

+50 0 obj

+% Page dictionary

+<< /Contents 94 0 R

+ /MediaBox [ 0

+ 0

+ 595.2756

+ 841.8898 ]

+ /Parent 88 0 R

+ /Resources << /Font 1 0 R

+ /ProcSet [ /PDF

+ /Text

+ /ImageB

+ /ImageC

+ /ImageI ] >>

+ /Rotate 0

+ /Trans <<  >>

+ /Type /Page >>

+endobj

+% 'Page7': class PDFPage 

+51 0 obj

+% Page dictionary

+<< /Contents 95 0 R

+ /MediaBox [ 0

+ 0

+ 595.2756

+ 841.8898 ]

+ /Parent 88 0 R

+ /Resources << /Font 1 0 R

+ /ProcSet [ /PDF

+ /Text

+ /ImageB

+ /ImageC

+ /ImageI ] >>

+ /Rotate 0

+ /Trans <<  >>

+ /Type /Page >>

+endobj

+% 'Page8': class PDFPage 

+52 0 obj

+% Page dictionary

+<< /Contents 96 0 R

+ /MediaBox [ 0

+ 0

+ 595.2756

+ 841.8898 ]

+ /Parent 88 0 R

+ /Resources << /Font 1 0 R

+ /ProcSet [ /PDF

+ /Text

+ /ImageB

+ /ImageC

+ /ImageI ] >>

+ /Rotate 0

+ /Trans <<  >>

+ /Type /Page >>

+endobj

+% 'Page9': class PDFPage 

+53 0 obj

+% Page dictionary

+<< /Contents 97 0 R

+ /MediaBox [ 0

+ 0

+ 595.2756

+ 841.8898 ]

+ /Parent 88 0 R

+ /Resources << /Font 1 0 R

+ /ProcSet [ /PDF

+ /Text

+ /ImageB

+ /ImageC

+ /ImageI ] >>

+ /Rotate 0

+ /Trans <<  >>

+ /Type /Page >>

+endobj

+% 'Page10': class PDFPage 

+54 0 obj

+% Page dictionary

+<< /Contents 98 0 R

+ /MediaBox [ 0

+ 0

+ 595.2756

+ 841.8898 ]

+ /Parent 88 0 R

+ /Resources << /Font 1 0 R

+ /ProcSet [ /PDF

+ /Text

+ /ImageB

+ /ImageC

+ /ImageI ] >>

+ /Rotate 0

+ /Trans <<  >>

+ /Type /Page >>

+endobj

+% 'Annot.NUMBER38': class PDFDictionary 

+55 0 obj

+<< /A << /S /URI

+ /Type /Action

+ /URI (http://bugs.python.org/issue1764286) >>

+ /Border [ 0

+ 0

+ 0 ]

+ /Rect [ 137.6966

+ 472.3736

+ 180.8679

+ 484.3736 ]

+ /Subtype /Link

+ /Type /Annot >>

+endobj

+% 'Page11': class PDFPage 

+56 0 obj

+% Page dictionary

+<< /Annots [ 55 0 R ]

+ /Contents 99 0 R

+ /MediaBox [ 0

+ 0

+ 595.2756

+ 841.8898 ]

+ /Parent 88 0 R

+ /Resources << /Font 1 0 R

+ /ProcSet [ /PDF

+ /Text

+ /ImageB

+ /ImageC

+ /ImageI ] >>

+ /Rotate 0

+ /Trans <<  >>

+ /Type /Page >>

+endobj

+% 'Annot.NUMBER39': class PDFDictionary 

+57 0 obj

+<< /A << /S /URI

+ /Type /Action

+ /URI (http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/496691) >>

+ /Border [ 0

+ 0

+ 0 ]

+ /Rect [ 62.69291

+ 675.7736

+ 363.4029

+ 687.7736 ]

+ /Subtype /Link

+ /Type /Annot >>

+endobj

+% 'Page12': class PDFPage 

+58 0 obj

+% Page dictionary

+<< /Annots [ 57 0 R ]

+ /Contents 100 0 R

+ /MediaBox [ 0

+ 0

+ 595.2756

+ 841.8898 ]

+ /Parent 88 0 R

+ /Resources << /Font 1 0 R

+ /ProcSet [ /PDF

+ /Text

+ /ImageB

+ /ImageC

+ /ImageI ] >>

+ /Rotate 0

+ /Trans <<  >>

+ /Type /Page >>

+endobj

+% 'Page13': class PDFPage 

+59 0 obj

+% Page dictionary

+<< /Contents 101 0 R

+ /MediaBox [ 0

+ 0

+ 595.2756

+ 841.8898 ]

+ /Parent 88 0 R

+ /Resources << /Font 1 0 R

+ /ProcSet [ /PDF

+ /Text

+ /ImageB

+ /ImageC

+ /ImageI ] >>

+ /Rotate 0

+ /Trans <<  >>

+ /Type /Page >>

+endobj

+% 'Annot.NUMBER40': class PDFDictionary 

+60 0 obj

+<< /A << /S /URI

+ /Type /Action

+ /URI (http://www.python.org/dev/peps/pep-0362) >>

+ /Border [ 0

+ 0

+ 0 ]

+ /Rect [ 301.1597

+ 534.5736

+ 317.8397

+ 546.5736 ]

+ /Subtype /Link

+ /Type /Annot >>

+endobj

+% 'Page14': class PDFPage 

+61 0 obj

+% Page dictionary

+<< /Annots [ 60 0 R ]

+ /Contents 102 0 R

+ /MediaBox [ 0

+ 0

+ 595.2756

+ 841.8898 ]

+ /Parent 88 0 R

+ /Resources << /Font 1 0 R

+ /ProcSet [ /PDF

+ /Text

+ /ImageB

+ /ImageC

+ /ImageI ] >>

+ /Rotate 0

+ /Trans <<  >>

+ /Type /Page >>

+endobj

+% 'Annot.NUMBER41': class PDFDictionary 

+62 0 obj

+<< /A << /S /URI

+ /Type /Action

+ /URI (http://www.python.org/dev/peps/pep-3107/) >>

+ /Border [ 0

+ 0

+ 0 ]

+ /Rect [ 497.5627

+ 726.7736

+ 531.1777

+ 738.7736 ]

+ /Subtype /Link

+ /Type /Annot >>

+endobj

+% 'Annot.NUMBER42': class PDFDictionary 

+63 0 obj

+<< /A << /S /URI

+ /Type /Action

+ /URI (http://www.python.org/dev/peps/pep-3107/) >>

+ /Border [ 0

+ 0

+ 0 ]

+ /Rect [ 62.69291

+ 714.7736

+ 114.3929

+ 726.7736 ]

+ /Subtype /Link

+ /Type /Annot >>

+endobj

+% 'Annot.NUMBER43': class PDFDictionary 

+64 0 obj

+<< /A << /S /URI

+ /Type /Action

+ /URI (http://packages.python.org/distribute/) >>

+ /Border [ 0

+ 0

+ 0 ]

+ /Rect [ 172.9507

+ 702.7736

+ 216.6742

+ 714.7736 ]

+ /Subtype /Link

+ /Type /Annot >>

+endobj

+% 'Annot.NUMBER44': class PDFDictionary 

+65 0 obj

+<< /A << /S /URI

+ /Type /Action

+ /URI (http://docutils.sourceforge.net/) >>

+ /Border [ 0

+ 0

+ 0 ]

+ /Rect [ 82.15291

+ 678.7736

+ 118.8329

+ 690.7736 ]

+ /Subtype /Link

+ /Type /Annot >>

+endobj

+% 'Annot.NUMBER45': class PDFDictionary 

+66 0 obj

+<< /A << /S /URI

+ /Type /Action

+ /URI (http://pygments.org/) >>

+ /Border [ 0

+ 0

+ 0 ]

+ /Rect [ 138.2929

+ 678.7736

+ 184.4229

+ 690.7736 ]

+ /Subtype /Link

+ /Type /Annot >>

+endobj

+% 'Annot.NUMBER46': class PDFDictionary 

+67 0 obj

+<< /A << /S /URI

+ /Type /Action

+ /URI (http://www.phyast.pitt.edu/~micheles/python/documentation.html#class-decorators-and-decorator-factories) >>

+ /Border [ 0

+ 0

+ 0 ]

+ /Rect [ 364.2921

+ 540.7736

+ 531.64

+ 552.7736 ]

+ /Subtype /Link

+ /Type /Annot >>

+endobj

+% 'Page15': class PDFPage 

+68 0 obj

+% Page dictionary

+<< /Annots [ 62 0 R

+ 63 0 R

+ 64 0 R

+ 65 0 R

+ 66 0 R

+ 67 0 R ]

+ /Contents 103 0 R

+ /MediaBox [ 0

+ 0

+ 595.2756

+ 841.8898 ]

+ /Parent 88 0 R

+ /Resources << /Font 1 0 R

+ /ProcSet [ /PDF

+ /Text

+ /ImageB

+ /ImageC

+ /ImageI ] >>

+ /Rotate 0

+ /Trans <<  >>

+ /Type /Page >>

+endobj

+% 'R69': class PDFCatalog 

+69 0 obj

+% Document Root

+<< /Outlines 71 0 R

+ /PageLabels 104 0 R

+ /PageMode /UseNone

+ /Pages 88 0 R

+ /Type /Catalog >>

+endobj

+% 'R70': class PDFInfo 

+70 0 obj

+<< /Author (Michele Simionato)

+ /CreationDate (D:20121018102601-01'00')

+ /Creator (\(unspecified\))

+ /Keywords ()

+ /Producer (ReportLab PDF Library - www.reportlab.com)

+ /Subject (\(unspecified\))

+ /Title (The decorator module) >>

+endobj

+% 'R71': class PDFOutlines 

+71 0 obj

+<< /Count 16

+ /First 72 0 R

+ /Last 87 0 R

+ /Type /Outlines >>

+endobj

+% 'Outline.0': class OutlineEntryObject 

+72 0 obj

+<< /Dest [ 40 0 R

+ /XYZ

+ 62.69291

+ 275.0236

+ 0 ]

+ /Next 73 0 R

+ /Parent 71 0 R

+ /Title (Introduction) >>

+endobj

+% 'Outline.1': class OutlineEntryObject 

+73 0 obj

+<< /Dest [ 45 0 R

+ /XYZ

+ 62.69291

+ 657.0236

+ 0 ]

+ /Next 74 0 R

+ /Parent 71 0 R

+ /Prev 72 0 R

+ /Title (Definitions) >>

+endobj

+% 'Outline.2': class OutlineEntryObject 

+74 0 obj

+<< /Dest [ 45 0 R

+ /XYZ

+ 62.69291

+ 420.0236

+ 0 ]

+ /Next 75 0 R

+ /Parent 71 0 R

+ /Prev 73 0 R

+ /Title (Statement of the problem) >>

+endobj

+% 'Outline.3': class OutlineEntryObject 

+75 0 obj

+<< /Dest [ 46 0 R

+ /XYZ

+ 62.69291

+ 409.4236

+ 0 ]

+ /Next 76 0 R

+ /Parent 71 0 R

+ /Prev 74 0 R

+ /Title (The solution) >>

+endobj

+% 'Outline.4': class OutlineEntryObject 

+76 0 obj

+<< /Dest [ 47 0 R

+ /XYZ

+ 62.69291

+ 435.4236

+ 0 ]

+ /Next 77 0 R

+ /Parent 71 0 R

+ /Prev 75 0 R

+ /Title (A trace decorator) >>

+endobj

+% 'Outline.5': class OutlineEntryObject 

+77 0 obj

+<< /Dest [ 49 0 R

+ /XYZ

+ 62.69291

+ 567.978

+ 0 ]

+ /Next 78 0 R

+ /Parent 71 0 R

+ /Prev 76 0 R

+ /Title (Function annotations) >>

+endobj

+% 'Outline.6': class OutlineEntryObject 

+78 0 obj

+<< /Dest [ 50 0 R

+ /XYZ

+ 62.69291

+ 765.0236

+ 0 ]

+ /Next 79 0 R

+ /Parent 71 0 R

+ /Prev 77 0 R

+ /Title (decorator is a decorator) >>

+endobj

+% 'Outline.7': class OutlineEntryObject 

+79 0 obj

+<< /Dest [ 50 0 R

+ /XYZ

+ 62.69291

+ 338.4236

+ 0 ]

+ /Next 80 0 R

+ /Parent 71 0 R

+ /Prev 78 0 R

+ /Title (blocking) >>

+endobj

+% 'Outline.8': class OutlineEntryObject 

+80 0 obj

+<< /Dest [ 51 0 R

+ /XYZ

+ 62.69291

+ 479.8236

+ 0 ]

+ /Next 81 0 R

+ /Parent 71 0 R

+ /Prev 79 0 R

+ /Title (async) >>

+endobj

+% 'Outline.9': class OutlineEntryObject 

+81 0 obj

+<< /Dest [ 53 0 R

+ /XYZ

+ 62.69291

+ 643.8236

+ 0 ]

+ /Next 82 0 R

+ /Parent 71 0 R

+ /Prev 80 0 R

+ /Title (contextmanager) >>

+endobj

+% 'Outline.10': class OutlineEntryObject 

+82 0 obj

+<< /Dest [ 54 0 R

+ /XYZ

+ 62.69291

+ 729.0236

+ 0 ]

+ /Next 83 0 R

+ /Parent 71 0 R

+ /Prev 81 0 R

+ /Title (The FunctionMaker class) >>

+endobj

+% 'Outline.11': class OutlineEntryObject 

+83 0 obj

+<< /Dest [ 56 0 R

+ /XYZ

+ 62.69291

+ 765.0236

+ 0 ]

+ /Next 84 0 R

+ /Parent 71 0 R

+ /Prev 82 0 R

+ /Title (Getting the source code) >>

+endobj

+% 'Outline.12': class OutlineEntryObject 

+84 0 obj

+<< /Dest [ 56 0 R

+ /XYZ

+ 62.69291

+ 318.4236

+ 0 ]

+ /Next 85 0 R

+ /Parent 71 0 R

+ /Prev 83 0 R

+ /Title (Dealing with third party decorators) >>

+endobj

+% 'Outline.13': class OutlineEntryObject 

+85 0 obj

+<< /Dest [ 59 0 R

+ /XYZ

+ 62.69291

+ 615.8236

+ 0 ]

+ /Next 86 0 R

+ /Parent 71 0 R

+ /Prev 84 0 R

+ /Title (Caveats and limitations) >>

+endobj

+% 'Outline.14': class OutlineEntryObject 

+86 0 obj

+<< /Dest [ 68 0 R

+ /XYZ

+ 62.69291

+ 765.0236

+ 0 ]

+ /Next 87 0 R

+ /Parent 71 0 R

+ /Prev 85 0 R

+ /Title (Compatibility notes) >>

+endobj

+% 'Outline.15': class OutlineEntryObject 

+87 0 obj

+<< /Dest [ 68 0 R

+ /XYZ

+ 62.69291

+ 414.0236

+ 0 ]

+ /Parent 71 0 R

+ /Prev 86 0 R

+ /Title (LICENCE) >>

+endobj

+% 'R88': class PDFPages 

+88 0 obj

+% page tree

+<< /Count 15

+ /Kids [ 40 0 R

+ 45 0 R

+ 46 0 R

+ 47 0 R

+ 49 0 R

+ 50 0 R

+ 51 0 R

+ 52 0 R

+ 53 0 R

+ 54 0 R

+ 56 0 R

+ 58 0 R

+ 59 0 R

+ 61 0 R

+ 68 0 R ]

+ /Type /Pages >>

+endobj

+% 'R89': class PDFStream 

+89 0 obj

+% page stream

+<< /Length 9258 >>

+stream

+1 0 0 1 0 0 cm  BT /F1 12 Tf 14.4 TL ET

+q

+1 0 0 1 62.69291 741.0236 cm

+q

+BT 1 0 0 1 0 4 Tm 118.8249 0 Td 24 TL /F2 20 Tf 0 0 0 rg (The ) Tj /F3 20 Tf (decorator ) Tj /F2 20 Tf (module) Tj T* -118.8249 0 Td ET

+Q

+Q

+q

+1 0 0 1 62.69291 716.0236 cm

+0 0 0 rg

+BT /F1 10 Tf 12 TL ET

+q

+1 0 0 1 6 3 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 2 Tm /F2 10 Tf 12 TL 36.93937 0 Td (Author:) Tj T* -36.93937 0 Td ET

+Q

+Q

+q

+1 0 0 1 91.03937 3 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 2 Tm /F1 10 Tf 12 TL (Michele Simionato) Tj T* ET

+Q

+Q

+q

+Q

+Q

+q

+1 0 0 1 62.69291 701.0236 cm

+0 0 0 rg

+BT /F1 10 Tf 12 TL ET

+q

+1 0 0 1 6 3 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 2 Tm /F2 10 Tf 12 TL 39.69937 0 Td (E-mail:) Tj T* -39.69937 0 Td ET

+Q

+Q

+q

+1 0 0 1 91.03937 3 cm

+q

+BT 1 0 0 1 0 2 Tm 12 TL /F1 10 Tf 0 0 .501961 rg (michele.simionato@gmail.com) Tj T* ET

+Q

+Q

+q

+Q

+Q

+q

+1 0 0 1 62.69291 686.0236 cm

+0 0 0 rg

+BT /F1 10 Tf 12 TL ET

+q

+1 0 0 1 6 3 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 2 Tm /F2 10 Tf 12 TL 33.02937 0 Td (Version:) Tj T* -33.02937 0 Td ET

+Q

+Q

+q

+1 0 0 1 91.03937 3 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 2 Tm /F1 10 Tf 12 TL (3.4.0 \(2012-10-18\)) Tj T* ET

+Q

+Q

+q

+Q

+Q

+q

+1 0 0 1 62.69291 671.0236 cm

+0 0 0 rg

+BT /F1 10 Tf 12 TL ET

+q

+1 0 0 1 6 3 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 2 Tm /F2 10 Tf 12 TL 26.91937 0 Td (Requires:) Tj T* -26.91937 0 Td ET

+Q

+Q

+q

+1 0 0 1 91.03937 3 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 2 Tm /F1 10 Tf 12 TL (Python 2.4+) Tj T* ET

+Q

+Q

+q

+Q

+Q

+q

+1 0 0 1 62.69291 644.0236 cm

+0 0 0 rg

+BT /F1 10 Tf 12 TL ET

+q

+1 0 0 1 6 3 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 14 Tm /F2 10 Tf 12 TL 25.25937 0 Td (Download) Tj T* 21.11 0 Td (page:) Tj T* -46.36937 0 Td ET

+Q

+Q

+q

+1 0 0 1 91.03937 15 cm

+q

+0 0 .501961 rg

+0 0 .501961 RG

+BT 1 0 0 1 0 2 Tm /F1 10 Tf 12 TL (http://pypi.python.org/pypi/decorator/3.4.0) Tj T* ET

+Q

+Q

+q

+Q

+Q

+q

+1 0 0 1 62.69291 629.0236 cm

+0 0 0 rg

+BT /F1 10 Tf 12 TL ET

+q

+1 0 0 1 6 3 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 2 Tm /F2 10 Tf 12 TL 16.91937 0 Td (Installation:) Tj T* -16.91937 0 Td ET

+Q

+Q

+q

+1 0 0 1 91.03937 3 cm

+q

+BT 1 0 0 1 0 2 Tm 12 TL /F4 10 Tf 0 0 0 rg (easy_install) Tj ( ) Tj (decorator) Tj T* ET

+Q

+Q

+q

+Q

+Q

+q

+1 0 0 1 62.69291 614.0236 cm

+0 0 0 rg

+BT /F1 10 Tf 12 TL ET

+q

+1 0 0 1 6 3 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 2 Tm /F2 10 Tf 12 TL 32.46937 0 Td (License:) Tj T* -32.46937 0 Td ET

+Q

+Q

+q

+1 0 0 1 91.03937 3 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 2 Tm /F1 10 Tf 12 TL (BSD license) Tj T* ET

+Q

+Q

+q

+Q

+Q

+q

+1 0 0 1 62.69291 581.0236 cm

+q

+BT 1 0 0 1 0 3.5 Tm 21 TL /F2 17.5 Tf 0 0 0 rg (Contents) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 287.0236 cm

+0 0 0 rg

+BT /F1 10 Tf 12 TL ET

+q

+1 0 0 1 0 273 cm

+q

+BT 1 0 0 1 0 2 Tm 12 TL /F2 10 Tf 0 0 .501961 rg (Introduction) Tj T* ET

+Q

+Q

+q

+1 0 0 1 397.8898 273 cm

+q

+0 0 .501961 rg

+0 0 .501961 RG

+BT 1 0 0 1 0 2 Tm /F2 10 Tf 12 TL 66.44 0 Td (1) Tj T* -66.44 0 Td ET

+Q

+Q

+q

+1 0 0 1 0 255 cm

+q

+BT 1 0 0 1 0 2 Tm 12 TL /F2 10 Tf 0 0 .501961 rg (Definitions) Tj T* ET

+Q

+Q

+q

+1 0 0 1 397.8898 255 cm

+q

+0 0 .501961 rg

+0 0 .501961 RG

+BT 1 0 0 1 0 2 Tm /F2 10 Tf 12 TL 66.44 0 Td (2) Tj T* -66.44 0 Td ET

+Q

+Q

+q

+1 0 0 1 0 237 cm

+q

+BT 1 0 0 1 0 2 Tm 12 TL /F2 10 Tf 0 0 .501961 rg (Statement of the problem) Tj T* ET

+Q

+Q

+q

+1 0 0 1 397.8898 237 cm

+q

+0 0 .501961 rg

+0 0 .501961 RG

+BT 1 0 0 1 0 2 Tm /F2 10 Tf 12 TL 66.44 0 Td (2) Tj T* -66.44 0 Td ET

+Q

+Q

+q

+1 0 0 1 0 219 cm

+q

+BT 1 0 0 1 0 2 Tm 12 TL /F2 10 Tf 0 0 .501961 rg (The solution) Tj T* ET

+Q

+Q

+q

+1 0 0 1 397.8898 219 cm

+q

+0 0 .501961 rg

+0 0 .501961 RG

+BT 1 0 0 1 0 2 Tm /F2 10 Tf 12 TL 66.44 0 Td (3) Tj T* -66.44 0 Td ET

+Q

+Q

+q

+1 0 0 1 0 201 cm

+q

+BT 1 0 0 1 0 2 Tm 12 TL /F2 10 Tf 0 0 .501961 rg (A ) Tj /F3 10 Tf (trace ) Tj /F2 10 Tf (decorator) Tj T* ET

+Q

+Q

+q

+1 0 0 1 397.8898 201 cm

+q

+0 0 .501961 rg

+0 0 .501961 RG

+BT 1 0 0 1 0 2 Tm /F2 10 Tf 12 TL 66.44 0 Td (4) Tj T* -66.44 0 Td ET

+Q

+Q

+q

+1 0 0 1 0 183 cm

+q

+BT 1 0 0 1 0 2 Tm 12 TL /F2 10 Tf 0 0 .501961 rg (Function annotations) Tj T* ET

+Q

+Q

+q

+1 0 0 1 397.8898 183 cm

+q

+0 0 .501961 rg

+0 0 .501961 RG

+BT 1 0 0 1 0 2 Tm /F2 10 Tf 12 TL 66.44 0 Td (5) Tj T* -66.44 0 Td ET

+Q

+Q

+q

+1 0 0 1 0 165 cm

+q

+BT 1 0 0 1 0 2 Tm 12 TL /F3 10 Tf 0 0 .501961 rg (decorator ) Tj /F2 10 Tf (is a decorator) Tj T* ET

+Q

+Q

+q

+1 0 0 1 397.8898 165 cm

+q

+0 0 .501961 rg

+0 0 .501961 RG

+BT 1 0 0 1 0 2 Tm /F2 10 Tf 12 TL 66.44 0 Td (6) Tj T* -66.44 0 Td ET

+Q

+Q

+q

+1 0 0 1 0 147 cm

+q

+BT 1 0 0 1 0 2 Tm 12 TL /F3 10 Tf 0 0 .501961 rg (blocking) Tj T* ET

+Q

+Q

+q

+1 0 0 1 397.8898 147 cm

+q

+0 0 .501961 rg

+0 0 .501961 RG

+BT 1 0 0 1 0 2 Tm /F2 10 Tf 12 TL 66.44 0 Td (6) Tj T* -66.44 0 Td ET

+Q

+Q

+q

+1 0 0 1 0 129 cm

+q

+BT 1 0 0 1 0 2 Tm 12 TL /F3 10 Tf 0 0 .501961 rg (async) Tj T* ET

+Q

+Q

+q

+1 0 0 1 397.8898 129 cm

+q

+0 0 .501961 rg

+0 0 .501961 RG

+BT 1 0 0 1 0 2 Tm /F2 10 Tf 12 TL 66.44 0 Td (7) Tj T* -66.44 0 Td ET

+Q

+Q

+q

+1 0 0 1 0 111 cm

+q

+BT 1 0 0 1 0 2 Tm 12 TL /F2 10 Tf 0 0 .501961 rg (contextmanager) Tj T* ET

+Q

+Q

+q

+1 0 0 1 397.8898 111 cm

+q

+0 0 .501961 rg

+0 0 .501961 RG

+BT 1 0 0 1 0 2 Tm /F2 10 Tf 12 TL 66.44 0 Td (9) Tj T* -66.44 0 Td ET

+Q

+Q

+q

+1 0 0 1 0 93 cm

+q

+BT 1 0 0 1 0 2 Tm 12 TL /F2 10 Tf 0 0 .501961 rg (The ) Tj /F3 10 Tf (FunctionMaker ) Tj /F2 10 Tf (class) Tj T* ET

+Q

+Q

+q

+1 0 0 1 397.8898 93 cm

+q

+0 0 .501961 rg

+0 0 .501961 RG

+BT 1 0 0 1 0 2 Tm /F2 10 Tf 12 TL 60.88 0 Td (10) Tj T* -60.88 0 Td ET

+Q

+Q

+q

+1 0 0 1 0 75 cm

+q

+BT 1 0 0 1 0 2 Tm 12 TL /F2 10 Tf 0 0 .501961 rg (Getting the source code) Tj T* ET

+Q

+Q

+q

+1 0 0 1 397.8898 75 cm

+q

+0 0 .501961 rg

+0 0 .501961 RG

+BT 1 0 0 1 0 2 Tm /F2 10 Tf 12 TL 60.88 0 Td (11) Tj T* -60.88 0 Td ET

+Q

+Q

+q

+1 0 0 1 0 57 cm

+q

+BT 1 0 0 1 0 2 Tm 12 TL /F2 10 Tf 0 0 .501961 rg (Dealing with third party decorators) Tj T* ET

+Q

+Q

+q

+1 0 0 1 397.8898 57 cm

+q

+0 0 .501961 rg

+0 0 .501961 RG

+BT 1 0 0 1 0 2 Tm /F2 10 Tf 12 TL 60.88 0 Td (11) Tj T* -60.88 0 Td ET

+Q

+Q

+q

+1 0 0 1 0 39 cm

+q

+BT 1 0 0 1 0 2 Tm 12 TL /F2 10 Tf 0 0 .501961 rg (Caveats and limitations) Tj T* ET

+Q

+Q

+q

+1 0 0 1 397.8898 39 cm

+q

+0 0 .501961 rg

+0 0 .501961 RG

+BT 1 0 0 1 0 2 Tm /F2 10 Tf 12 TL 60.88 0 Td (13) Tj T* -60.88 0 Td ET

+Q

+Q

+q

+1 0 0 1 0 21 cm

+q

+BT 1 0 0 1 0 2 Tm 12 TL /F2 10 Tf 0 0 .501961 rg (Compatibility notes) Tj T* ET

+Q

+Q

+q

+1 0 0 1 397.8898 21 cm

+q

+0 0 .501961 rg

+0 0 .501961 RG

+BT 1 0 0 1 0 2 Tm /F2 10 Tf 12 TL 60.88 0 Td (15) Tj T* -60.88 0 Td ET

+Q

+Q

+q

+1 0 0 1 0 3 cm

+q

+BT 1 0 0 1 0 2 Tm 12 TL /F2 10 Tf 0 0 .501961 rg (LICENCE) Tj T* ET

+Q

+Q

+q

+1 0 0 1 397.8898 3 cm

+q

+0 0 .501961 rg

+0 0 .501961 RG

+BT 1 0 0 1 0 2 Tm /F2 10 Tf 12 TL 60.88 0 Td (15) Tj T* -60.88 0 Td ET

+Q

+Q

+q

+Q

+Q

+q

+1 0 0 1 62.69291 254.0236 cm

+q

+BT 1 0 0 1 0 3.5 Tm 21 TL /F2 17.5 Tf 0 0 0 rg (Introduction) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 188.0236 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 50 Tm /F1 10 Tf 12 TL 3.995366 Tw (Python decorators are an interesting example of why syntactic sugar matters. In principle, their) Tj T* 0 Tw .151235 Tw (introduction in Python 2.4 changed nothing, since they do not provide any new functionality which was not) Tj T* 0 Tw 2.238555 Tw (already present in the language. In practice, their introduction has significantly changed the way we) Tj T* 0 Tw .098409 Tw (structure our programs in Python. I believe the change is for the best, and that decorators are a great idea) Tj T* 0 Tw (since:) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 182.0236 cm

+Q

+q

+1 0 0 1 62.69291 182.0236 cm

+Q

+q

+1 0 0 1 62.69291 170.0236 cm

+0 0 0 rg

+BT /F1 10 Tf 12 TL ET

+q

+1 0 0 1 6 -3 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 2 Tm /F1 10 Tf 12 TL 10.5 0 Td (\177) Tj T* -10.5 0 Td ET

+Q

+Q

+q

+1 0 0 1 23 -3 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 2 Tm /F1 10 Tf 12 TL (decorators help reducing boilerplate code;) Tj T* ET

+Q

+Q

+q

+Q

+Q

+q

+1 0 0 1 62.69291 164.0236 cm

+Q

+q

+1 0 0 1 62.69291 152.0236 cm

+0 0 0 rg

+BT /F1 10 Tf 12 TL ET

+q

+1 0 0 1 6 -3 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 2 Tm /F1 10 Tf 12 TL 10.5 0 Td (\177) Tj T* -10.5 0 Td ET

+Q

+Q

+q

+1 0 0 1 23 -3 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 2 Tm /F1 10 Tf 12 TL (decorators help separation of concerns;) Tj T* ET

+Q

+Q

+q

+Q

+Q

+q

+1 0 0 1 62.69291 146.0236 cm

+Q

+q

+1 0 0 1 62.69291 134.0236 cm

+0 0 0 rg

+BT /F1 10 Tf 12 TL ET

+q

+1 0 0 1 6 -3 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 2 Tm /F1 10 Tf 12 TL 10.5 0 Td (\177) Tj T* -10.5 0 Td ET

+Q

+Q

+q

+1 0 0 1 23 -3 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 2 Tm /F1 10 Tf 12 TL (decorators enhance readability and maintenability;) Tj T* ET

+Q

+Q

+q

+Q

+Q

+q

+1 0 0 1 62.69291 128.0236 cm

+Q

+q

+1 0 0 1 62.69291 116.0236 cm

+0 0 0 rg

+BT /F1 10 Tf 12 TL ET

+q

+1 0 0 1 6 -3 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 2 Tm /F1 10 Tf 12 TL 10.5 0 Td (\177) Tj T* -10.5 0 Td ET

+Q

+Q

+q

+1 0 0 1 23 -3 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 2 Tm /F1 10 Tf 12 TL (decorators are explicit.) Tj T* ET

+Q

+Q

+q

+Q

+Q

+q

+1 0 0 1 62.69291 116.0236 cm

+Q

+q

+1 0 0 1 62.69291 86.02362 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 14 Tm /F1 10 Tf 12 TL .848876 Tw (Still, as of now, writing custom decorators correctly requires some experience and it is not as easy as it) Tj T* 0 Tw 1.049269 Tw (could be. For instance, typical implementations of decorators involve nested functions, and we all know) Tj T* 0 Tw ET

+Q

+Q

+ 

+endstream

+endobj

+% 'R90': class PDFStream 

+90 0 obj

+% page stream

+<< /Length 7660 >>

+stream

+1 0 0 1 0 0 cm  BT /F1 12 Tf 14.4 TL ET

+q

+1 0 0 1 62.69291 753.0236 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 2 Tm /F1 10 Tf 12 TL (that flat is better than nested.) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 699.0236 cm

+q

+BT 1 0 0 1 0 38 Tm 1.093735 Tw 12 TL /F1 10 Tf 0 0 0 rg (The aim of the ) Tj /F4 10 Tf (decorator ) Tj /F1 10 Tf (module it to simplify the usage of decorators for the average programmer,) Tj T* 0 Tw 2.456136 Tw (and to popularize decorators by showing various non-trivial examples. Of course, as all techniques,) Tj T* 0 Tw 2.234987 Tw (decorators can be abused \(I have seen that\) and you should not try to solve every problem with a) Tj T* 0 Tw (decorator, just because you can.) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 669.0236 cm

+q

+BT 1 0 0 1 0 14 Tm .13561 Tw 12 TL /F1 10 Tf 0 0 0 rg (You may find the source code for all the examples discussed here in the ) Tj /F4 10 Tf (documentation.py ) Tj /F1 10 Tf (file, which) Tj T* 0 Tw (contains this documentation in the form of doctests.) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 636.0236 cm

+q

+BT 1 0 0 1 0 3.5 Tm 21 TL /F2 17.5 Tf 0 0 0 rg (Definitions) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 594.0236 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 26 Tm /F1 10 Tf 12 TL 2.37561 Tw (Technically speaking, any Python object which can be called with one argument can be used as a) Tj T* 0 Tw .472339 Tw (decorator. However, this definition is somewhat too large to be really useful. It is more convenient to split) Tj T* 0 Tw (the generic class of decorators in two subclasses:) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 588.0236 cm

+Q

+q

+1 0 0 1 62.69291 588.0236 cm

+Q

+q

+1 0 0 1 62.69291 564.0236 cm

+0 0 0 rg

+BT /F1 10 Tf 12 TL ET

+q

+1 0 0 1 6 9 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 2 Tm /F1 10 Tf 12 TL 10.5 0 Td (\177) Tj T* -10.5 0 Td ET

+Q

+Q

+q

+1 0 0 1 23 -3 cm

+q

+BT 1 0 0 1 0 14 Tm 2.68748 Tw 12 TL /F5 10 Tf 0 0 0 rg (signature-preserving ) Tj /F1 10 Tf (decorators, i.e. callable objects taking a function as input and returning a) Tj T* 0 Tw (function ) Tj /F5 10 Tf (with the same signature ) Tj /F1 10 Tf (as output;) Tj T* ET

+Q

+Q

+q

+Q

+Q

+q

+1 0 0 1 62.69291 558.0236 cm

+Q

+q

+1 0 0 1 62.69291 534.0236 cm

+0 0 0 rg

+BT /F1 10 Tf 12 TL ET

+q

+1 0 0 1 6 9 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 2 Tm /F1 10 Tf 12 TL 10.5 0 Td (\177) Tj T* -10.5 0 Td ET

+Q

+Q

+q

+1 0 0 1 23 -3 cm

+q

+BT 1 0 0 1 0 14 Tm 1.43498 Tw 12 TL /F5 10 Tf 0 0 0 rg (signature-changing ) Tj /F1 10 Tf (decorators, i.e. decorators that change the signature of their input function, or) Tj T* 0 Tw (decorators returning non-callable objects.) Tj T* ET

+Q

+Q

+q

+Q

+Q

+q

+1 0 0 1 62.69291 534.0236 cm

+Q

+q

+1 0 0 1 62.69291 492.0236 cm

+q

+BT 1 0 0 1 0 26 Tm 2.832706 Tw 12 TL /F1 10 Tf 0 0 0 rg (Signature-changing decorators have their use: for instance the builtin classes ) Tj /F4 10 Tf (staticmethod ) Tj /F1 10 Tf (and) Tj T* 0 Tw 1.506651 Tw /F4 10 Tf (classmethod ) Tj /F1 10 Tf (are in this group, since they take functions and return descriptor objects which are not) Tj T* 0 Tw (functions, nor callables.) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 462.0236 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 14 Tm /F1 10 Tf 12 TL 1.735814 Tw (However, signature-preserving decorators are more common and easier to reason about; in particular) Tj T* 0 Tw (signature-preserving decorators can be composed together whereas other decorators in general cannot.) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 432.0236 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 14 Tm /F1 10 Tf 12 TL .494983 Tw (Writing signature-preserving decorators from scratch is not that obvious, especially if one wants to define) Tj T* 0 Tw (proper decorators that can accept functions with any signature. A simple example will clarify the issue.) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 399.0236 cm

+q

+BT 1 0 0 1 0 3.5 Tm 21 TL /F2 17.5 Tf 0 0 0 rg (Statement of the problem) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 321.0236 cm

+q

+BT 1 0 0 1 0 62 Tm .351235 Tw 12 TL /F1 10 Tf 0 0 0 rg (A very common use case for decorators is the memoization of functions. A ) Tj /F4 10 Tf (memoize ) Tj /F1 10 Tf (decorator works by) Tj T* 0 Tw .871988 Tw (caching the result of the function call in a dictionary, so that the next time the function is called with the) Tj T* 0 Tw 2.350651 Tw (same input parameters the result is retrieved from the cache and not recomputed. There are many) Tj T* 0 Tw 2.92247 Tw (implementations of ) Tj /F4 10 Tf (memoize ) Tj /F1 10 Tf (in ) Tj 0 0 .501961 rg (http://www.python.org/moin/PythonDecoratorLibrary) Tj 0 0 0 rg (, but they do not) Tj T* 0 Tw 2.683984 Tw (preserve the signature. A simple implementation could be the following \(notice that in general it is) Tj T* 0 Tw (impossible to memoize correctly something that depends on non-hashable arguments\):) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 131.8236 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 180 re B*

+Q

+q

+BT 1 0 0 1 0 158 Tm 12 TL /F3 10 Tf 0 .501961 0 rg (def) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 0 1 rg (memoize_uw) Tj 0 0 0 rg (\() Tj (func) Tj (\):) Tj  T* (    ) Tj (func) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (cache) Tj ( ) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ( ) Tj ({}) Tj  T* (    ) Tj /F3 10 Tf 0 .501961 0 rg (def) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 0 1 rg (memoize) Tj 0 0 0 rg (\() Tj .4 .4 .4 rg (*) Tj 0 0 0 rg (args) Tj (,) Tj ( ) Tj .4 .4 .4 rg (**) Tj 0 0 0 rg (kw) Tj (\):) Tj  T* (        ) Tj /F3 10 Tf 0 .501961 0 rg (if) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (kw) Tj (:) Tj ( ) Tj /F6 10 Tf .25098 .501961 .501961 rg (# frozenset is used to ensure hashability) Tj /F4 10 Tf 0 0 0 rg  T* (            ) Tj (key) Tj ( ) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ( ) Tj (args) Tj (,) Tj ( ) Tj 0 .501961 0 rg (frozenset) Tj 0 0 0 rg (\() Tj (kw) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (iteritems) Tj (\(\)\)) Tj  T* (        ) Tj /F3 10 Tf 0 .501961 0 rg (else) Tj /F4 10 Tf 0 0 0 rg (:) Tj  T* (            ) Tj (key) Tj ( ) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ( ) Tj (args) Tj  T* (        ) Tj (cache) Tj ( ) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ( ) Tj (func) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (cache) Tj  T* (        ) Tj /F3 10 Tf 0 .501961 0 rg (if) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (key) Tj ( ) Tj /F3 10 Tf .666667 .133333 1 rg (in) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (cache) Tj (:) Tj  T* (            ) Tj /F3 10 Tf 0 .501961 0 rg (return) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (cache) Tj ([) Tj (key) Tj (]) Tj  T* (        ) Tj /F3 10 Tf 0 .501961 0 rg (else) Tj /F4 10 Tf 0 0 0 rg (:) Tj  T* (            ) Tj (cache) Tj ([) Tj (key) Tj (]) Tj ( ) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ( ) Tj (result) Tj ( ) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ( ) Tj (func) Tj (\() Tj .4 .4 .4 rg (*) Tj 0 0 0 rg (args) Tj (,) Tj ( ) Tj .4 .4 .4 rg (**) Tj 0 0 0 rg (kw) Tj (\)) Tj  T* (            ) Tj /F3 10 Tf 0 .501961 0 rg (return) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (result) Tj  T* (    ) Tj /F3 10 Tf 0 .501961 0 rg (return) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (functools) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (update_wrapper) Tj (\() Tj (memoize) Tj (,) Tj ( ) Tj (func) Tj (\)) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 87.82362 cm

+q

+BT 1 0 0 1 0 26 Tm 1.801412 Tw 12 TL /F1 10 Tf 0 0 0 rg (Here we used the ) Tj 0 0 .501961 rg (functools.update_wrapper ) Tj 0 0 0 rg (utility, which has been added in Python 2.5 expressly to ) Tj T* 0 Tw .91686 Tw (simplify the definition of decorators \(in older versions of Python you need to copy the function attributes ) Tj T* 0 Tw .580814 Tw /F4 10 Tf (__name__) Tj /F1 10 Tf (, ) Tj /F4 10 Tf (__doc__) Tj /F1 10 Tf (, ) Tj /F4 10 Tf (__module__ ) Tj /F1 10 Tf (and ) Tj /F4 10 Tf (__dict__ ) Tj /F1 10 Tf (from the original function to the decorated function) Tj T* 0 Tw ET

+Q

+Q

+ 

+endstream

+endobj

+% 'R91': class PDFStream 

+91 0 obj

+% page stream

+<< /Length 8095 >>

+stream

+1 0 0 1 0 0 cm  BT /F1 12 Tf 14.4 TL ET

+q

+1 0 0 1 62.69291 753.0236 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 2 Tm /F1 10 Tf 12 TL (by hand\).) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 711.0236 cm

+q

+BT 1 0 0 1 0 26 Tm 2.517126 Tw 12 TL /F1 10 Tf 0 0 0 rg (The implementation above works in the sense that the decorator can accept functions with generic) Tj T* 0 Tw 1.233615 Tw (signatures; unfortunately this implementation does ) Tj /F5 10 Tf (not ) Tj /F1 10 Tf (define a signature-preserving decorator, since in) Tj T* 0 Tw (general ) Tj /F4 10 Tf (memoize_uw ) Tj /F1 10 Tf (returns a function with a ) Tj /F5 10 Tf (different signature ) Tj /F1 10 Tf (from the original function.) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 693.0236 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 2 Tm /F1 10 Tf 12 TL (Consider for instance the following case:) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 623.8236 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 60 re B*

+Q

+q

+BT 1 0 0 1 0 38 Tm 12 TL /F4 10 Tf .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj .666667 .133333 1 rg (@memoize_uw) Tj 0 0 0 rg  T* .4 .4 .4 rg (...) Tj 0 0 0 rg ( ) Tj /F3 10 Tf 0 .501961 0 rg (def) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 0 1 rg (f1) Tj 0 0 0 rg (\() Tj (x) Tj (\):) Tj  T* .4 .4 .4 rg (...) Tj 0 0 0 rg (     ) Tj (time) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (sleep) Tj (\() Tj .4 .4 .4 rg (1) Tj 0 0 0 rg (\)) Tj ( ) Tj /F6 10 Tf .25098 .501961 .501961 rg (# simulate some long computation) Tj /F4 10 Tf 0 0 0 rg  T* .4 .4 .4 rg (...) Tj 0 0 0 rg (     ) Tj /F3 10 Tf 0 .501961 0 rg (return) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (x) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 591.8236 cm

+q

+BT 1 0 0 1 0 14 Tm .26311 Tw 12 TL /F1 10 Tf 0 0 0 rg (Here the original function takes a single argument named ) Tj /F4 10 Tf (x) Tj /F1 10 Tf (, but the decorated function takes any number) Tj T* 0 Tw (of arguments and keyword arguments:) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 534.6236 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 48 re B*

+Q

+q

+BT 1 0 0 1 0 26 Tm 12 TL /F4 10 Tf .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj /F3 10 Tf 0 .501961 0 rg (from) Tj /F4 10 Tf 0 0 0 rg ( ) Tj /F3 10 Tf 0 0 1 rg (inspect) Tj /F4 10 Tf 0 0 0 rg ( ) Tj /F3 10 Tf 0 .501961 0 rg (import) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (getargspec) Tj  T* .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj /F3 10 Tf 0 .501961 0 rg (print) Tj /F4 10 Tf 0 0 0 rg (\() Tj (getargspec) Tj (\() Tj (f1) Tj (\)\)) Tj  T* (ArgSpec) Tj (\() Tj (args) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ([],) Tj ( ) Tj (varargs) Tj .4 .4 .4 rg (=) Tj .729412 .129412 .129412 rg ('args') Tj 0 0 0 rg (,) Tj ( ) Tj (keywords) Tj .4 .4 .4 rg (=) Tj .729412 .129412 .129412 rg ('kw') Tj 0 0 0 rg (,) Tj ( ) Tj (defaults) Tj .4 .4 .4 rg (=) Tj 0 .501961 0 rg (None) Tj 0 0 0 rg (\)) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 490.6236 cm

+q

+BT 1 0 0 1 0 26 Tm .411235 Tw 12 TL /F1 10 Tf 0 0 0 rg (This means that introspection tools such as pydoc will give wrong informations about the signature of ) Tj /F4 10 Tf (f1) Tj /F1 10 Tf (.) Tj T* 0 Tw .161654 Tw (This is pretty bad: pydoc will tell you that the function accepts a generic signature ) Tj /F4 10 Tf (*args) Tj /F1 10 Tf (, ) Tj /F4 10 Tf (**kw) Tj /F1 10 Tf (, but when) Tj T* 0 Tw (you try to call the function with more than an argument, you will get an error:) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 421.4236 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 60 re B*

+Q

+q

+BT 1 0 0 1 0 38 Tm 12 TL /F4 10 Tf .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj (f1) Tj (\() Tj .4 .4 .4 rg (0) Tj 0 0 0 rg (,) Tj ( ) Tj .4 .4 .4 rg (1) Tj 0 0 0 rg (\)) Tj  T* (Traceback) Tj ( ) Tj (\() Tj (most) Tj ( ) Tj (recent) Tj ( ) Tj (call) Tj ( ) Tj (last) Tj (\):) Tj  T* (   ) Tj .4 .4 .4 rg (...) Tj 0 0 0 rg  T* /F3 10 Tf .823529 .254902 .227451 rg (TypeError) Tj /F4 10 Tf 0 0 0 rg (:) Tj ( ) Tj (f1) Tj (\(\)) Tj ( ) Tj (takes) Tj ( ) Tj (exactly) Tj ( ) Tj .4 .4 .4 rg (1) Tj 0 0 0 rg ( ) Tj (positional) Tj ( ) Tj (argument) Tj ( ) Tj (\() Tj .4 .4 .4 rg (2) Tj 0 0 0 rg ( ) Tj (given) Tj (\)) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 388.4236 cm

+q

+BT 1 0 0 1 0 3.5 Tm 21 TL /F2 17.5 Tf 0 0 0 rg (The solution) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 346.4236 cm

+q

+BT 1 0 0 1 0 26 Tm 3.313984 Tw 12 TL /F1 10 Tf 0 0 0 rg (The solution is to provide a generic factory of generators, which hides the complexity of making) Tj T* 0 Tw 3.362976 Tw (signature-preserving decorators from the application programmer. The ) Tj /F4 10 Tf (decorator ) Tj /F1 10 Tf (function in the) Tj T* 0 Tw /F4 10 Tf (decorator ) Tj /F1 10 Tf (module is such a factory:) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 313.2236 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 24 re B*

+Q

+q

+BT 1 0 0 1 0 2 Tm 12 TL /F4 10 Tf .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj /F3 10 Tf 0 .501961 0 rg (from) Tj /F4 10 Tf 0 0 0 rg ( ) Tj /F3 10 Tf 0 0 1 rg (decorator) Tj /F4 10 Tf 0 0 0 rg ( ) Tj /F3 10 Tf 0 .501961 0 rg (import) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (decorator) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 257.2236 cm

+q

+BT 1 0 0 1 0 38 Tm 1.716412 Tw 12 TL /F4 10 Tf 0 0 0 rg (decorator ) Tj /F1 10 Tf (takes two arguments, a caller function describing the functionality of the decorator and a) Tj T* 0 Tw 2.594983 Tw (function to be decorated; it returns the decorated function. The caller function must have signature) Tj T* 0 Tw .19311 Tw /F4 10 Tf (\(f,) Tj ( ) Tj (*args,) Tj ( ) Tj (**kw\) ) Tj /F1 10 Tf (and it must call the original function ) Tj /F4 10 Tf (f ) Tj /F1 10 Tf (with arguments ) Tj /F4 10 Tf (args ) Tj /F1 10 Tf (and ) Tj /F4 10 Tf (kw) Tj /F1 10 Tf (, implementing) Tj T* 0 Tw (the wanted capability, i.e. memoization in this case:) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 104.0236 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 144 re B*

+Q

+q

+BT 1 0 0 1 0 122 Tm 12 TL /F3 10 Tf 0 .501961 0 rg (def) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 0 1 rg (_memoize) Tj 0 0 0 rg (\() Tj (func) Tj (,) Tj ( ) Tj .4 .4 .4 rg (*) Tj 0 0 0 rg (args) Tj (,) Tj ( ) Tj .4 .4 .4 rg (**) Tj 0 0 0 rg (kw) Tj (\):) Tj  T* (    ) Tj /F3 10 Tf 0 .501961 0 rg (if) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (kw) Tj (:) Tj ( ) Tj /F6 10 Tf .25098 .501961 .501961 rg (# frozenset is used to ensure hashability) Tj /F4 10 Tf 0 0 0 rg  T* (        ) Tj (key) Tj ( ) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ( ) Tj (args) Tj (,) Tj ( ) Tj 0 .501961 0 rg (frozenset) Tj 0 0 0 rg (\() Tj (kw) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (iteritems) Tj (\(\)\)) Tj  T* (    ) Tj /F3 10 Tf 0 .501961 0 rg (else) Tj /F4 10 Tf 0 0 0 rg (:) Tj  T* (        ) Tj (key) Tj ( ) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ( ) Tj (args) Tj  T* (    ) Tj (cache) Tj ( ) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ( ) Tj (func) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (cache) Tj ( ) Tj /F6 10 Tf .25098 .501961 .501961 rg (# attributed added by memoize) Tj /F4 10 Tf 0 0 0 rg  T* (    ) Tj /F3 10 Tf 0 .501961 0 rg (if) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (key) Tj ( ) Tj /F3 10 Tf .666667 .133333 1 rg (in) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (cache) Tj (:) Tj  T* (        ) Tj /F3 10 Tf 0 .501961 0 rg (return) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (cache) Tj ([) Tj (key) Tj (]) Tj  T* (    ) Tj /F3 10 Tf 0 .501961 0 rg (else) Tj /F4 10 Tf 0 0 0 rg (:) Tj  T* (        ) Tj (cache) Tj ([) Tj (key) Tj (]) Tj ( ) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ( ) Tj (result) Tj ( ) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ( ) Tj (func) Tj (\() Tj .4 .4 .4 rg (*) Tj 0 0 0 rg (args) Tj (,) Tj ( ) Tj .4 .4 .4 rg (**) Tj 0 0 0 rg (kw) Tj (\)) Tj  T* (        ) Tj /F3 10 Tf 0 .501961 0 rg (return) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (result) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 84.02362 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 2 Tm /F1 10 Tf 12 TL (At this point you can define your decorator as follows:) Tj T* ET

+Q

+Q

+ 

+endstream

+endobj

+% 'R92': class PDFStream 

+92 0 obj

+% page stream

+<< /Length 7804 >>

+stream

+1 0 0 1 0 0 cm  BT /F1 12 Tf 14.4 TL ET

+q

+1 0 0 1 62.69291 715.8236 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 48 re B*

+Q

+q

+BT 1 0 0 1 0 26 Tm 12 TL /F3 10 Tf 0 .501961 0 rg (def) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 0 1 rg (memoize) Tj 0 0 0 rg (\() Tj (f) Tj (\):) Tj  T* (    ) Tj (f) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (cache) Tj ( ) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ( ) Tj ({}) Tj  T* (    ) Tj /F3 10 Tf 0 .501961 0 rg (return) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (decorator) Tj (\() Tj (_memoize) Tj (,) Tj ( ) Tj (f) Tj (\)) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 671.8236 cm

+q

+BT 1 0 0 1 0 26 Tm .12561 Tw 12 TL /F1 10 Tf 0 0 0 rg (The difference with respect to the ) Tj /F4 10 Tf (memoize_uw ) Tj /F1 10 Tf (approach, which is based on nested functions, is that the) Tj T* 0 Tw 2.59528 Tw (decorator module forces you to lift the inner function at the outer level \() Tj /F5 10 Tf (flat is better than nested) Tj /F1 10 Tf (\).) Tj T* 0 Tw (Moreover, you are forced to pass explicitly the function you want to decorate to the caller function.) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 653.8236 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 2 Tm /F1 10 Tf 12 TL (Here is a test of usage:) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 512.6236 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 132 re B*

+Q

+q

+BT 1 0 0 1 0 110 Tm 12 TL /F4 10 Tf .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj .666667 .133333 1 rg (@memoize) Tj 0 0 0 rg  T* .4 .4 .4 rg (...) Tj 0 0 0 rg ( ) Tj /F3 10 Tf 0 .501961 0 rg (def) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 0 1 rg (heavy_computation) Tj 0 0 0 rg (\(\):) Tj  T* .4 .4 .4 rg (...) Tj 0 0 0 rg (     ) Tj (time) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (sleep) Tj (\() Tj .4 .4 .4 rg (2) Tj 0 0 0 rg (\)) Tj  T* .4 .4 .4 rg (...) Tj 0 0 0 rg (     ) Tj /F3 10 Tf 0 .501961 0 rg (return) Tj /F4 10 Tf 0 0 0 rg ( ) Tj .729412 .129412 .129412 rg ("done") Tj 0 0 0 rg  T*  T* .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj /F3 10 Tf 0 .501961 0 rg (print) Tj /F4 10 Tf 0 0 0 rg (\() Tj (heavy_computation) Tj (\(\)\)) Tj ( ) Tj /F6 10 Tf .25098 .501961 .501961 rg (# the first time it will take 2 seconds) Tj /F4 10 Tf 0 0 0 rg  T* (done) Tj  T*  T* .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj /F3 10 Tf 0 .501961 0 rg (print) Tj /F4 10 Tf 0 0 0 rg (\() Tj (heavy_computation) Tj (\(\)\)) Tj ( ) Tj /F6 10 Tf .25098 .501961 .501961 rg (# the second time it will be instantaneous) Tj /F4 10 Tf 0 0 0 rg  T* (done) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 492.6236 cm

+q

+BT 1 0 0 1 0 2 Tm 12 TL /F1 10 Tf 0 0 0 rg (The signature of ) Tj /F4 10 Tf (heavy_computation ) Tj /F1 10 Tf (is the one you would expect:) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 447.4236 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 36 re B*

+Q

+q

+BT 1 0 0 1 0 14 Tm 12 TL /F4 10 Tf .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj /F3 10 Tf 0 .501961 0 rg (print) Tj /F4 10 Tf 0 0 0 rg (\() Tj (getargspec) Tj (\() Tj (heavy_computation) Tj (\)\)) Tj  T* (ArgSpec) Tj (\() Tj (args) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ([],) Tj ( ) Tj (varargs) Tj .4 .4 .4 rg (=) Tj 0 .501961 0 rg (None) Tj 0 0 0 rg (,) Tj ( ) Tj (keywords) Tj .4 .4 .4 rg (=) Tj 0 .501961 0 rg (None) Tj 0 0 0 rg (,) Tj ( ) Tj (defaults) Tj .4 .4 .4 rg (=) Tj 0 .501961 0 rg (None) Tj 0 0 0 rg (\)) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 414.4236 cm

+q

+BT 1 0 0 1 0 3.5 Tm 21 TL /F2 17.5 Tf 0 0 0 rg (A ) Tj /F3 17.5 Tf (trace ) Tj /F2 17.5 Tf (decorator) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 384.4236 cm

+q

+BT 1 0 0 1 0 14 Tm .479398 Tw 12 TL /F1 10 Tf 0 0 0 rg (As an additional example, here is how you can define a trivial ) Tj /F4 10 Tf (trace ) Tj /F1 10 Tf (decorator, which prints a message) Tj T* 0 Tw (everytime the traced function is called:) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 315.2236 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 60 re B*

+Q

+q

+BT 1 0 0 1 0 38 Tm 12 TL /F3 10 Tf 0 .501961 0 rg (def) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 0 1 rg (_trace) Tj 0 0 0 rg (\() Tj (f) Tj (,) Tj ( ) Tj .4 .4 .4 rg (*) Tj 0 0 0 rg (args) Tj (,) Tj ( ) Tj .4 .4 .4 rg (**) Tj 0 0 0 rg (kw) Tj (\):) Tj  T* (    ) Tj (kwstr) Tj ( ) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ( ) Tj .729412 .129412 .129412 rg (', ') Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (join) Tj (\() Tj .729412 .129412 .129412 rg (') Tj /F3 10 Tf .733333 .4 .533333 rg (%r) Tj /F4 10 Tf .729412 .129412 .129412 rg (: ) Tj /F3 10 Tf .733333 .4 .533333 rg (%r) Tj /F4 10 Tf .729412 .129412 .129412 rg (') Tj 0 0 0 rg ( ) Tj .4 .4 .4 rg (%) Tj 0 0 0 rg ( ) Tj (\() Tj (k) Tj (,) Tj ( ) Tj (kw) Tj ([) Tj (k) Tj (]\)) Tj ( ) Tj /F3 10 Tf 0 .501961 0 rg (for) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (k) Tj ( ) Tj /F3 10 Tf .666667 .133333 1 rg (in) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 .501961 0 rg (sorted) Tj 0 0 0 rg (\() Tj (kw) Tj (\)\)) Tj  T* (    ) Tj /F3 10 Tf 0 .501961 0 rg (print) Tj /F4 10 Tf 0 0 0 rg (\() Tj .729412 .129412 .129412 rg ("calling ) Tj /F3 10 Tf .733333 .4 .533333 rg (%s) Tj /F4 10 Tf .729412 .129412 .129412 rg ( with args ) Tj /F3 10 Tf .733333 .4 .533333 rg (%s) Tj /F4 10 Tf .729412 .129412 .129412 rg (, {) Tj /F3 10 Tf .733333 .4 .533333 rg (%s) Tj /F4 10 Tf .729412 .129412 .129412 rg (}") Tj 0 0 0 rg ( ) Tj .4 .4 .4 rg (%) Tj 0 0 0 rg ( ) Tj (\() Tj (f) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (__name__) Tj (,) Tj ( ) Tj (args) Tj (,) Tj ( ) Tj (kwstr) Tj (\)\)) Tj  T* (    ) Tj /F3 10 Tf 0 .501961 0 rg (return) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (f) Tj (\() Tj .4 .4 .4 rg (*) Tj 0 0 0 rg (args) Tj (,) Tj ( ) Tj .4 .4 .4 rg (**) Tj 0 0 0 rg (kw) Tj (\)) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 270.0236 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 36 re B*

+Q

+q

+BT 1 0 0 1 0 14 Tm 12 TL /F3 10 Tf 0 .501961 0 rg (def) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 0 1 rg (trace) Tj 0 0 0 rg (\() Tj (f) Tj (\):) Tj  T* (    ) Tj /F3 10 Tf 0 .501961 0 rg (return) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (decorator) Tj (\() Tj (_trace) Tj (,) Tj ( ) Tj (f) Tj (\)) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 250.0236 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 2 Tm /F1 10 Tf 12 TL (Here is an example of usage:) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 192.8236 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 48 re B*

+Q

+q

+BT 1 0 0 1 0 26 Tm 12 TL /F4 10 Tf .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj .666667 .133333 1 rg (@trace) Tj 0 0 0 rg  T* .4 .4 .4 rg (...) Tj 0 0 0 rg ( ) Tj /F3 10 Tf 0 .501961 0 rg (def) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 0 1 rg (f1) Tj 0 0 0 rg (\() Tj (x) Tj (\):) Tj  T* .4 .4 .4 rg (...) Tj 0 0 0 rg (     ) Tj /F3 10 Tf 0 .501961 0 rg (pass) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 172.8236 cm

+q

+BT 1 0 0 1 0 2 Tm 12 TL /F1 10 Tf 0 0 0 rg (It is immediate to verify that ) Tj /F4 10 Tf (f1 ) Tj /F1 10 Tf (works) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 127.6236 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 36 re B*

+Q

+q

+BT 1 0 0 1 0 14 Tm 12 TL /F4 10 Tf .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj (f1) Tj (\() Tj .4 .4 .4 rg (0) Tj 0 0 0 rg (\)) Tj  T* (calling) Tj ( ) Tj (f1) Tj ( ) Tj /F3 10 Tf 0 .501961 0 rg (with) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (args) Tj ( ) Tj (\() Tj .4 .4 .4 rg (0) Tj 0 0 0 rg (,\),) Tj ( ) Tj ({}) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 107.6236 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 2 Tm /F1 10 Tf 12 TL (and it that it has the correct signature:) Tj T* ET

+Q

+Q

+ 

+endstream

+endobj

+% 'R93': class PDFStream 

+93 0 obj

+% page stream

+<< /Length 7590 >>

+stream

+1 0 0 1 0 0 cm  BT /F1 12 Tf 14.4 TL ET

+q

+1 0 0 1 62.69291 727.8236 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 36 re B*

+Q

+q

+BT 1 0 0 1 0 14 Tm 12 TL /F4 10 Tf .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj /F3 10 Tf 0 .501961 0 rg (print) Tj /F4 10 Tf 0 0 0 rg (\() Tj (getargspec) Tj (\() Tj (f1) Tj (\)\)) Tj  T* (ArgSpec) Tj (\() Tj (args) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ([) Tj .729412 .129412 .129412 rg ('x') Tj 0 0 0 rg (],) Tj ( ) Tj (varargs) Tj .4 .4 .4 rg (=) Tj 0 .501961 0 rg (None) Tj 0 0 0 rg (,) Tj ( ) Tj (keywords) Tj .4 .4 .4 rg (=) Tj 0 .501961 0 rg (None) Tj 0 0 0 rg (,) Tj ( ) Tj (defaults) Tj .4 .4 .4 rg (=) Tj 0 .501961 0 rg (None) Tj 0 0 0 rg (\)) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 707.8236 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 2 Tm /F1 10 Tf 12 TL (The same decorator works with functions of any signature:) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 579.978 cm

+q

+q

+.988825 0 0 .988825 0 0 cm

+q

+1 0 0 1 6.6 6.674587 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 474 120 re B*

+Q

+q

+BT 1 0 0 1 0 98 Tm 12 TL /F4 10 Tf .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj .666667 .133333 1 rg (@trace) Tj 0 0 0 rg  T* .4 .4 .4 rg (...) Tj 0 0 0 rg ( ) Tj /F3 10 Tf 0 .501961 0 rg (def) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 0 1 rg (f) Tj 0 0 0 rg (\() Tj (x) Tj (,) Tj ( ) Tj (y) Tj .4 .4 .4 rg (=) Tj (1) Tj 0 0 0 rg (,) Tj ( ) Tj (z) Tj .4 .4 .4 rg (=) Tj (2) Tj 0 0 0 rg (,) Tj ( ) Tj .4 .4 .4 rg (*) Tj 0 0 0 rg (args) Tj (,) Tj ( ) Tj .4 .4 .4 rg (**) Tj 0 0 0 rg (kw) Tj (\):) Tj  T* .4 .4 .4 rg (...) Tj 0 0 0 rg (     ) Tj /F3 10 Tf 0 .501961 0 rg (pass) Tj /F4 10 Tf 0 0 0 rg  T*  T* .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj (f) Tj (\() Tj .4 .4 .4 rg (0) Tj 0 0 0 rg (,) Tj ( ) Tj .4 .4 .4 rg (3) Tj 0 0 0 rg (\)) Tj  T* (calling) Tj ( ) Tj (f) Tj ( ) Tj /F3 10 Tf 0 .501961 0 rg (with) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (args) Tj ( ) Tj (\() Tj .4 .4 .4 rg (0) Tj 0 0 0 rg (,) Tj ( ) Tj .4 .4 .4 rg (3) Tj 0 0 0 rg (,) Tj ( ) Tj .4 .4 .4 rg (2) Tj 0 0 0 rg (\),) Tj ( ) Tj ({}) Tj  T*  T* .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj /F3 10 Tf 0 .501961 0 rg (print) Tj /F4 10 Tf 0 0 0 rg (\() Tj (getargspec) Tj (\() Tj (f) Tj (\)\)) Tj  T* (ArgSpec) Tj (\() Tj (args) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ([) Tj .729412 .129412 .129412 rg ('x') Tj 0 0 0 rg (,) Tj ( ) Tj .729412 .129412 .129412 rg ('y') Tj 0 0 0 rg (,) Tj ( ) Tj .729412 .129412 .129412 rg ('z') Tj 0 0 0 rg (],) Tj ( ) Tj (varargs) Tj .4 .4 .4 rg (=) Tj .729412 .129412 .129412 rg ('args') Tj 0 0 0 rg (,) Tj ( ) Tj (keywords) Tj .4 .4 .4 rg (=) Tj .729412 .129412 .129412 rg ('kw') Tj 0 0 0 rg (,) Tj ( ) Tj (defaults) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg (\() Tj .4 .4 .4 rg (1) Tj 0 0 0 rg (,) Tj ( ) Tj .4 .4 .4 rg (2) Tj 0 0 0 rg (\)\)) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 546.978 cm

+q

+BT 1 0 0 1 0 3.5 Tm 21 TL /F2 17.5 Tf 0 0 0 rg (Function annotations) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 492.978 cm

+q

+BT 1 0 0 1 0 38 Tm 1.937318 Tw 12 TL /F1 10 Tf 0 0 0 rg (Python 3 introduced the concept of ) Tj 0 0 .501961 rg (function annotations) Tj 0 0 0 rg (,i.e. the ability to annotate the signature of a) Tj T* 0 Tw 2.24816 Tw (function with additional information, stored in a dictionary named ) Tj /F4 10 Tf (__annotations__) Tj /F1 10 Tf (. The decorator) Tj T* 0 Tw 1.923735 Tw (module, starting from release 3.3, is able to understand and to preserve the annotations. Here is an) Tj T* 0 Tw (example:) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 423.778 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 60 re B*

+Q

+q

+BT 1 0 0 1 0 38 Tm 12 TL /F4 10 Tf .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj .666667 .133333 1 rg (@trace) Tj 0 0 0 rg  T* .4 .4 .4 rg (...) Tj 0 0 0 rg ( ) Tj /F3 10 Tf 0 .501961 0 rg (def) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 0 1 rg (f) Tj 0 0 0 rg (\() Tj (x) Tj (:) Tj ( ) Tj .729412 .129412 .129412 rg ('the first argument') Tj 0 0 0 rg (,) Tj ( ) Tj (y) Tj (:) Tj ( ) Tj .729412 .129412 .129412 rg ('default argument') Tj .4 .4 .4 rg (=) Tj (1) Tj 0 0 0 rg (,) Tj ( ) Tj (z) Tj .4 .4 .4 rg (=) Tj (2) Tj 0 0 0 rg (,) Tj  T* .4 .4 .4 rg (...) Tj 0 0 0 rg (       ) Tj .4 .4 .4 rg (*) Tj 0 0 0 rg (args) Tj (:) Tj ( ) Tj .729412 .129412 .129412 rg ('varargs') Tj 0 0 0 rg (,) Tj ( ) Tj .4 .4 .4 rg (**) Tj 0 0 0 rg (kw) Tj (:) Tj ( ) Tj .729412 .129412 .129412 rg ('kwargs') Tj 0 0 0 rg (\):) Tj  T* .4 .4 .4 rg (...) Tj 0 0 0 rg (     ) Tj /F3 10 Tf 0 .501961 0 rg (pass) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 391.778 cm

+q

+BT 1 0 0 1 0 14 Tm .596647 Tw 12 TL /F1 10 Tf 0 0 0 rg (In order to introspect functions with annotations, one needs the utility ) Tj /F4 10 Tf (inspect.getfullargspec) Tj /F1 10 Tf (, new) Tj T* 0 Tw (in Python 3:) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 214.578 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 168 re B*

+Q

+q

+BT 1 0 0 1 0 146 Tm 12 TL /F4 10 Tf .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj /F3 10 Tf 0 .501961 0 rg (from) Tj /F4 10 Tf 0 0 0 rg ( ) Tj /F3 10 Tf 0 0 1 rg (inspect) Tj /F4 10 Tf 0 0 0 rg ( ) Tj /F3 10 Tf 0 .501961 0 rg (import) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (getfullargspec) Tj  T* .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj (argspec) Tj ( ) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ( ) Tj (getfullargspec) Tj (\() Tj (f) Tj (\)) Tj  T* .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj (argspec) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (args) Tj  T* ([) Tj .729412 .129412 .129412 rg ('x') Tj 0 0 0 rg (,) Tj ( ) Tj .729412 .129412 .129412 rg ('y') Tj 0 0 0 rg (,) Tj ( ) Tj .729412 .129412 .129412 rg ('z') Tj 0 0 0 rg (]) Tj  T* .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj (argspec) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (varargs) Tj  T* .729412 .129412 .129412 rg ('args') Tj 0 0 0 rg  T* .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj (argspec) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (varkw) Tj  T* .729412 .129412 .129412 rg ('kw') Tj 0 0 0 rg  T* .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj (argspec) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (defaults) Tj  T* (\() Tj .4 .4 .4 rg (1) Tj 0 0 0 rg (,) Tj ( ) Tj .4 .4 .4 rg (2) Tj 0 0 0 rg (\)) Tj  T* .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj (argspec) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (kwonlyargs) Tj  T* ([]) Tj  T* .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj (argspec) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (kwonlydefaults) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 194.578 cm

+q

+BT 1 0 0 1 0 2 Tm 12 TL /F1 10 Tf 0 0 0 rg (You can also check that the ) Tj /F4 10 Tf (__annotations__ ) Tj /F1 10 Tf (dictionary is preserved:) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 149.378 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 36 re B*

+Q

+q

+BT 1 0 0 1 0 14 Tm 12 TL /F4 10 Tf .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj (f) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (__annotations__) Tj ( ) Tj .4 .4 .4 rg (==) Tj 0 0 0 rg ( ) Tj (f) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (__wrapped__) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (__annotations__) Tj  T* 0 .501961 0 rg (True) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 117.378 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 14 Tm /F1 10 Tf 12 TL .011098 Tw (Depending on the version of the decorator module, the two dictionaries can be the same object or not: you) Tj T* 0 Tw (cannot rely on object identity, but you can rely on the content being the same.) Tj T* ET

+Q

+Q

+ 

+endstream

+endobj

+% 'R94': class PDFStream 

+94 0 obj

+% page stream

+<< /Length 8795 >>

+stream

+1 0 0 1 0 0 cm  BT /F1 12 Tf 14.4 TL ET

+q

+1 0 0 1 62.69291 744.0236 cm

+q

+BT 1 0 0 1 0 3.5 Tm 21 TL /F3 17.5 Tf 0 0 0 rg (decorator ) Tj /F2 17.5 Tf (is a decorator) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 642.0236 cm

+q

+BT 1 0 0 1 0 86 Tm .643876 Tw 12 TL /F1 10 Tf 0 0 0 rg (It may be annoying to write a caller function \(like the ) Tj /F4 10 Tf (_trace ) Tj /F1 10 Tf (function above\) and then a trivial wrapper) Tj T* 0 Tw 1.510888 Tw (\() Tj /F4 10 Tf (def) Tj ( ) Tj (trace\(f\):) Tj ( ) Tj (return) Tj ( ) Tj (decorator\(_trace,) Tj ( ) Tj (f\)) Tj /F1 10 Tf (\) every time. For this reason, the ) Tj /F4 10 Tf (decorator) Tj T* 0 Tw .334269 Tw /F1 10 Tf (module provides an easy shortcut to convert the caller function into a signature-preserving decorator: you) Tj T* 0 Tw 7.364269 Tw (can just call ) Tj /F4 10 Tf (decorator ) Tj /F1 10 Tf (with a single argument. In our example you can just write) Tj T* 0 Tw .951647 Tw /F4 10 Tf (trace) Tj ( ) Tj (=) Tj ( ) Tj (decorator\(_trace\)) Tj /F1 10 Tf (. The ) Tj /F4 10 Tf (decorator ) Tj /F1 10 Tf (function can also be used as a signature-changing) Tj T* 0 Tw 1.077752 Tw (decorator, just as ) Tj /F4 10 Tf (classmethod ) Tj /F1 10 Tf (and ) Tj /F4 10 Tf (staticmethod) Tj /F1 10 Tf (. However, ) Tj /F4 10 Tf (classmethod ) Tj /F1 10 Tf (and ) Tj /F4 10 Tf (staticmethod) Tj T* 0 Tw .531797 Tw /F1 10 Tf (return generic objects which are not callable, while ) Tj /F4 10 Tf (decorator ) Tj /F1 10 Tf (returns signature-preserving decorators,) Tj T* 0 Tw (i.e. functions of a single argument. For instance, you can write directly) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 560.8236 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 72 re B*

+Q

+q

+BT 1 0 0 1 0 50 Tm 12 TL /F4 10 Tf .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj .666667 .133333 1 rg (@decorator) Tj 0 0 0 rg  T* .4 .4 .4 rg (...) Tj 0 0 0 rg ( ) Tj /F3 10 Tf 0 .501961 0 rg (def) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 0 1 rg (trace) Tj 0 0 0 rg (\() Tj (f) Tj (,) Tj ( ) Tj .4 .4 .4 rg (*) Tj 0 0 0 rg (args) Tj (,) Tj ( ) Tj .4 .4 .4 rg (**) Tj 0 0 0 rg (kw) Tj (\):) Tj  T* .4 .4 .4 rg (...) Tj 0 0 0 rg (     ) Tj (kwstr) Tj ( ) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ( ) Tj .729412 .129412 .129412 rg (', ') Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (join) Tj (\() Tj .729412 .129412 .129412 rg (') Tj /F3 10 Tf .733333 .4 .533333 rg (%r) Tj /F4 10 Tf .729412 .129412 .129412 rg (: ) Tj /F3 10 Tf .733333 .4 .533333 rg (%r) Tj /F4 10 Tf .729412 .129412 .129412 rg (') Tj 0 0 0 rg ( ) Tj .4 .4 .4 rg (%) Tj 0 0 0 rg ( ) Tj (\() Tj (k) Tj (,) Tj ( ) Tj (kw) Tj ([) Tj (k) Tj (]\)) Tj ( ) Tj /F3 10 Tf 0 .501961 0 rg (for) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (k) Tj ( ) Tj /F3 10 Tf .666667 .133333 1 rg (in) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 .501961 0 rg (sorted) Tj 0 0 0 rg (\() Tj (kw) Tj (\)\)) Tj  T* .4 .4 .4 rg (...) Tj 0 0 0 rg (     ) Tj /F3 10 Tf 0 .501961 0 rg (print) Tj /F4 10 Tf 0 0 0 rg (\() Tj .729412 .129412 .129412 rg ("calling ) Tj /F3 10 Tf .733333 .4 .533333 rg (%s) Tj /F4 10 Tf .729412 .129412 .129412 rg ( with args ) Tj /F3 10 Tf .733333 .4 .533333 rg (%s) Tj /F4 10 Tf .729412 .129412 .129412 rg (, {) Tj /F3 10 Tf .733333 .4 .533333 rg (%s) Tj /F4 10 Tf .729412 .129412 .129412 rg (}") Tj 0 0 0 rg ( ) Tj .4 .4 .4 rg (%) Tj 0 0 0 rg ( ) Tj (\() Tj (f) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (__name__) Tj (,) Tj ( ) Tj (args) Tj (,) Tj ( ) Tj (kwstr) Tj (\)\)) Tj  T* .4 .4 .4 rg (...) Tj 0 0 0 rg (     ) Tj /F3 10 Tf 0 .501961 0 rg (return) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (f) Tj (\() Tj .4 .4 .4 rg (*) Tj 0 0 0 rg (args) Tj (,) Tj ( ) Tj .4 .4 .4 rg (**) Tj 0 0 0 rg (kw) Tj (\)) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 528.8236 cm

+q

+BT 1 0 0 1 0 14 Tm 1.806654 Tw 12 TL /F1 10 Tf 0 0 0 rg (and now ) Tj /F4 10 Tf (trace ) Tj /F1 10 Tf (will be a decorator. Actually ) Tj /F4 10 Tf (trace ) Tj /F1 10 Tf (is a ) Tj /F4 10 Tf (partial ) Tj /F1 10 Tf (object which can be used as a) Tj T* 0 Tw (decorator:) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 483.6236 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 36 re B*

+Q

+q

+BT 1 0 0 1 0 14 Tm 12 TL /F4 10 Tf .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj (trace) Tj  T* .4 .4 .4 rg (<) Tj 0 0 0 rg (function) Tj ( ) Tj (trace) Tj ( ) Tj (at) Tj ( ) Tj .4 .4 .4 rg (0) Tj 0 0 0 rg (x) Tj .4 .4 .4 rg (...) Tj (>) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 463.6236 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 2 Tm /F1 10 Tf 12 TL (Here is an example of usage:) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 382.4236 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 72 re B*

+Q

+q

+BT 1 0 0 1 0 50 Tm 12 TL /F4 10 Tf .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj .666667 .133333 1 rg (@trace) Tj 0 0 0 rg  T* .4 .4 .4 rg (...) Tj 0 0 0 rg ( ) Tj /F3 10 Tf 0 .501961 0 rg (def) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 0 1 rg (func) Tj 0 0 0 rg (\(\):) Tj ( ) Tj /F3 10 Tf 0 .501961 0 rg (pass) Tj /F4 10 Tf 0 0 0 rg  T*  T* .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj (func) Tj (\(\)) Tj  T* (calling) Tj ( ) Tj (func) Tj ( ) Tj /F3 10 Tf 0 .501961 0 rg (with) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (args) Tj ( ) Tj (\(\),) Tj ( ) Tj ({}) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 350.4236 cm

+q

+BT 1 0 0 1 0 14 Tm 2.44686 Tw 12 TL /F1 10 Tf 0 0 0 rg (If you are using an old Python version \(Python 2.4\) the ) Tj /F4 10 Tf (decorator ) Tj /F1 10 Tf (module provides a poor man) Tj T* 0 Tw (replacement for ) Tj /F4 10 Tf (functools.partial) Tj /F1 10 Tf (.) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 317.4236 cm

+q

+BT 1 0 0 1 0 3.5 Tm 21 TL /F3 17.5 Tf 0 0 0 rg (blocking) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 275.4236 cm

+q

+BT 1 0 0 1 0 26 Tm 1.224692 Tw 12 TL /F1 10 Tf 0 0 0 rg (Sometimes one has to deal with blocking resources, such as ) Tj /F4 10 Tf (stdin) Tj /F1 10 Tf (, and sometimes it is best to have) Tj T* 0 Tw .266235 Tw (back a "busy" message than to block everything. This behavior can be implemented with a suitable family) Tj T* 0 Tw (of decorators, where the parameter is the busy message:) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 98.22362 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 168 re B*

+Q

+q

+BT 1 0 0 1 0 146 Tm 12 TL /F3 10 Tf 0 .501961 0 rg (def) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 0 1 rg (blocking) Tj 0 0 0 rg (\() Tj (not_avail) Tj (\):) Tj  T* (    ) Tj /F3 10 Tf 0 .501961 0 rg (def) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 0 1 rg (blocking) Tj 0 0 0 rg (\() Tj (f) Tj (,) Tj ( ) Tj .4 .4 .4 rg (*) Tj 0 0 0 rg (args) Tj (,) Tj ( ) Tj .4 .4 .4 rg (**) Tj 0 0 0 rg (kw) Tj (\):) Tj  T* (        ) Tj /F3 10 Tf 0 .501961 0 rg (if) Tj /F4 10 Tf 0 0 0 rg ( ) Tj /F3 10 Tf .666667 .133333 1 rg (not) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 .501961 0 rg (hasattr) Tj 0 0 0 rg (\() Tj (f) Tj (,) Tj ( ) Tj .729412 .129412 .129412 rg ("thread") Tj 0 0 0 rg (\):) Tj ( ) Tj /F6 10 Tf .25098 .501961 .501961 rg (# no thread running) Tj /F4 10 Tf 0 0 0 rg  T* (            ) Tj /F3 10 Tf 0 .501961 0 rg (def) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 0 1 rg (set_result) Tj 0 0 0 rg (\(\):) Tj ( ) Tj (f) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (result) Tj ( ) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ( ) Tj (f) Tj (\() Tj .4 .4 .4 rg (*) Tj 0 0 0 rg (args) Tj (,) Tj ( ) Tj .4 .4 .4 rg (**) Tj 0 0 0 rg (kw) Tj (\)) Tj  T* (            ) Tj (f) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (thread) Tj ( ) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ( ) Tj (threading) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (Thread) Tj (\() Tj 0 .501961 0 rg (None) Tj 0 0 0 rg (,) Tj ( ) Tj (set_result) Tj (\)) Tj  T* (            ) Tj (f) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (thread) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (start) Tj (\(\)) Tj  T* (            ) Tj /F3 10 Tf 0 .501961 0 rg (return) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (not_avail) Tj  T* (        ) Tj /F3 10 Tf 0 .501961 0 rg (elif) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (f) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (thread) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (isAlive) Tj (\(\):) Tj  T* (            ) Tj /F3 10 Tf 0 .501961 0 rg (return) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (not_avail) Tj  T* (        ) Tj /F3 10 Tf 0 .501961 0 rg (else) Tj /F4 10 Tf 0 0 0 rg (:) Tj ( ) Tj /F6 10 Tf .25098 .501961 .501961 rg (# the thread is ended, return the stored result) Tj /F4 10 Tf 0 0 0 rg  T* (            ) Tj /F3 10 Tf 0 .501961 0 rg (del) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (f) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (thread) Tj  T* (            ) Tj /F3 10 Tf 0 .501961 0 rg (return) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (f) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (result) Tj  T* (    ) Tj /F3 10 Tf 0 .501961 0 rg (return) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (decorator) Tj (\() Tj (blocking) Tj (\)) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+ 

+endstream

+endobj

+% 'R95': class PDFStream 

+95 0 obj

+% page stream

+<< /Length 6669 >>

+stream

+1 0 0 1 0 0 cm  BT /F1 12 Tf 14.4 TL ET

+q

+1 0 0 1 62.69291 741.0236 cm

+q

+BT 1 0 0 1 0 14 Tm 1.010651 Tw 12 TL /F1 10 Tf 0 0 0 rg (Functions decorated with ) Tj /F4 10 Tf (blocking ) Tj /F1 10 Tf (will return a busy message if the resource is unavailable, and the) Tj T* 0 Tw (intended result if the resource is available. For instance:) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 491.8236 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 240 re B*

+Q

+q

+BT 1 0 0 1 0 218 Tm 12 TL /F4 10 Tf .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj .666667 .133333 1 rg (@blocking) Tj 0 0 0 rg (\() Tj .729412 .129412 .129412 rg ("Please wait ...") Tj 0 0 0 rg (\)) Tj  T* .4 .4 .4 rg (...) Tj 0 0 0 rg ( ) Tj /F3 10 Tf 0 .501961 0 rg (def) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 0 1 rg (read_data) Tj 0 0 0 rg (\(\):) Tj  T* .4 .4 .4 rg (...) Tj 0 0 0 rg (     ) Tj (time) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (sleep) Tj (\() Tj .4 .4 .4 rg (3) Tj 0 0 0 rg (\)) Tj ( ) Tj /F6 10 Tf .25098 .501961 .501961 rg (# simulate a blocking resource) Tj /F4 10 Tf 0 0 0 rg  T* .4 .4 .4 rg (...) Tj 0 0 0 rg (     ) Tj /F3 10 Tf 0 .501961 0 rg (return) Tj /F4 10 Tf 0 0 0 rg ( ) Tj .729412 .129412 .129412 rg ("some data") Tj 0 0 0 rg  T*  T* .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj /F3 10 Tf 0 .501961 0 rg (print) Tj /F4 10 Tf 0 0 0 rg (\() Tj (read_data) Tj (\(\)\)) Tj ( ) Tj /F6 10 Tf .25098 .501961 .501961 rg (# data is not available yet) Tj /F4 10 Tf 0 0 0 rg  T* (Please) Tj ( ) Tj (wait) Tj ( ) Tj .4 .4 .4 rg (...) Tj 0 0 0 rg  T*  T* .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj (time) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (sleep) Tj (\() Tj .4 .4 .4 rg (1) Tj 0 0 0 rg (\)) Tj  T* .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj /F3 10 Tf 0 .501961 0 rg (print) Tj /F4 10 Tf 0 0 0 rg (\() Tj (read_data) Tj (\(\)\)) Tj ( ) Tj /F6 10 Tf .25098 .501961 .501961 rg (# data is not available yet) Tj /F4 10 Tf 0 0 0 rg  T* (Please) Tj ( ) Tj (wait) Tj ( ) Tj .4 .4 .4 rg (...) Tj 0 0 0 rg  T*  T* .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj (time) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (sleep) Tj (\() Tj .4 .4 .4 rg (1) Tj 0 0 0 rg (\)) Tj  T* .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj /F3 10 Tf 0 .501961 0 rg (print) Tj /F4 10 Tf 0 0 0 rg (\() Tj (read_data) Tj (\(\)\)) Tj ( ) Tj /F6 10 Tf .25098 .501961 .501961 rg (# data is not available yet) Tj /F4 10 Tf 0 0 0 rg  T* (Please) Tj ( ) Tj (wait) Tj ( ) Tj .4 .4 .4 rg (...) Tj 0 0 0 rg  T*  T* .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj (time) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (sleep) Tj (\() Tj .4 .4 .4 rg (1.1) Tj 0 0 0 rg (\)) Tj ( ) Tj /F6 10 Tf .25098 .501961 .501961 rg (# after 3.1 seconds, data is available) Tj /F4 10 Tf 0 0 0 rg  T* .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj /F3 10 Tf 0 .501961 0 rg (print) Tj /F4 10 Tf 0 0 0 rg (\() Tj (read_data) Tj (\(\)\)) Tj  T* (some) Tj ( ) Tj (data) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 458.8236 cm

+q

+BT 1 0 0 1 0 3.5 Tm 21 TL /F3 17.5 Tf 0 0 0 rg (async) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 416.8236 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 26 Tm /F1 10 Tf 12 TL 1.647485 Tw (We have just seen an examples of a simple decorator factory, implemented as a function returning a) Tj T* 0 Tw .29784 Tw (decorator. For more complex situations, it is more convenient to implement decorator factories as classes) Tj T* 0 Tw (returning callable objects that can be converted into decorators.) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 350.8236 cm

+q

+BT 1 0 0 1 0 50 Tm 2.853876 Tw 12 TL /F1 10 Tf 0 0 0 rg (As an example, here will I show a decorator which is able to convert a blocking function into an) Tj T* 0 Tw 2.477126 Tw (asynchronous function. The function, when called, is executed in a separate thread. Moreover, it is) Tj T* 0 Tw .288443 Tw (possible to set three callbacks ) Tj /F4 10 Tf (on_success) Tj /F1 10 Tf (, ) Tj /F4 10 Tf (on_failure ) Tj /F1 10 Tf (and ) Tj /F4 10 Tf (on_closing) Tj /F1 10 Tf (, to specify how to manage) Tj T* 0 Tw 1.854724 Tw (the function call \(of course the code here is just an example, it is not a recommended way of doing) Tj T* 0 Tw (multi-threaded programming\). The implementation is the following:) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 293.6236 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 48 re B*

+Q

+q

+BT 1 0 0 1 0 26 Tm 12 TL /F3 10 Tf 0 .501961 0 rg (def) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 0 1 rg (on_success) Tj 0 0 0 rg (\() Tj (result) Tj (\):) Tj ( ) Tj /F6 10 Tf .25098 .501961 .501961 rg (# default implementation) Tj /F4 10 Tf 0 0 0 rg  T* (    ) Tj .729412 .129412 .129412 rg ("Called on the result of the function") Tj 0 0 0 rg  T* (    ) Tj /F3 10 Tf 0 .501961 0 rg (return) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (result) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 236.4236 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 48 re B*

+Q

+q

+BT 1 0 0 1 0 26 Tm 12 TL /F3 10 Tf 0 .501961 0 rg (def) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 0 1 rg (on_failure) Tj 0 0 0 rg (\() Tj (exc_info) Tj (\):) Tj ( ) Tj /F6 10 Tf .25098 .501961 .501961 rg (# default implementation) Tj /F4 10 Tf 0 0 0 rg  T* (    ) Tj .729412 .129412 .129412 rg ("Called if the function fails") Tj 0 0 0 rg  T* (    ) Tj /F3 10 Tf 0 .501961 0 rg (pass) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 179.2236 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 48 re B*

+Q

+q

+BT 1 0 0 1 0 26 Tm 12 TL /F3 10 Tf 0 .501961 0 rg (def) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 0 1 rg (on_closing) Tj 0 0 0 rg (\(\):) Tj ( ) Tj /F6 10 Tf .25098 .501961 .501961 rg (# default implementation) Tj /F4 10 Tf 0 0 0 rg  T* (    ) Tj .729412 .129412 .129412 rg ("Called at the end, both in case of success and failure") Tj 0 0 0 rg  T* (    ) Tj /F3 10 Tf 0 .501961 0 rg (pass) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 86.02362 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 84 re B*

+Q

+q

+BT 1 0 0 1 0 62 Tm 12 TL /F3 10 Tf 0 .501961 0 rg (class) Tj /F4 10 Tf 0 0 0 rg ( ) Tj /F3 10 Tf 0 0 1 rg (Async) Tj /F4 10 Tf 0 0 0 rg (\() Tj 0 .501961 0 rg (object) Tj 0 0 0 rg (\):) Tj  T* (    ) Tj /F6 10 Tf .729412 .129412 .129412 rg (""") Tj T* (    A decorator converting blocking functions into asynchronous) Tj T* (    functions, by using threads or processes. Examples:) Tj T*  T* (    async_with_threads =  Async\(threading.Thread\)) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+ 

+endstream

+endobj

+% 'R96': class PDFStream 

+96 0 obj

+% page stream

+<< /Length 8071 >>

+stream

+1 0 0 1 0 0 cm  BT /F1 12 Tf 14.4 TL ET

+q

+1 0 0 1 62.69291 415.8236 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 348 re B*

+Q

+q

+BT 1 0 0 1 0 326 Tm 12 TL /F6 10 Tf .729412 .129412 .129412 rg (    async_with_processes =  Async\(multiprocessing.Process\)) Tj T* (    """) Tj /F4 10 Tf 0 0 0 rg  T*  T* (    ) Tj /F3 10 Tf 0 .501961 0 rg (def) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 0 1 rg (__init__) Tj 0 0 0 rg (\() Tj 0 .501961 0 rg (self) Tj 0 0 0 rg (,) Tj ( ) Tj (threadfactory) Tj (,) Tj ( ) Tj (on_success) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg (on_success) Tj (,) Tj  T* (                 ) Tj (on_failure) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg (on_failure) Tj (,) Tj ( ) Tj (on_closing) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg (on_closing) Tj (\):) Tj  T* (        ) Tj 0 .501961 0 rg (self) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (threadfactory) Tj ( ) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ( ) Tj (threadfactory) Tj  T* (        ) Tj 0 .501961 0 rg (self) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (on_success) Tj ( ) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ( ) Tj (on_success) Tj  T* (        ) Tj 0 .501961 0 rg (self) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (on_failure) Tj ( ) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ( ) Tj (on_failure) Tj  T* (        ) Tj 0 .501961 0 rg (self) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (on_closing) Tj ( ) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ( ) Tj (on_closing) Tj  T*  T* (    ) Tj /F3 10 Tf 0 .501961 0 rg (def) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 0 1 rg (__call__) Tj 0 0 0 rg (\() Tj 0 .501961 0 rg (self) Tj 0 0 0 rg (,) Tj ( ) Tj (func) Tj (,) Tj ( ) Tj .4 .4 .4 rg (*) Tj 0 0 0 rg (args) Tj (,) Tj ( ) Tj .4 .4 .4 rg (**) Tj 0 0 0 rg (kw) Tj (\):) Tj  T* (        ) Tj /F3 10 Tf 0 .501961 0 rg (try) Tj /F4 10 Tf 0 0 0 rg (:) Tj  T* (            ) Tj (counter) Tj ( ) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ( ) Tj (func) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (counter) Tj  T* (        ) Tj /F3 10 Tf 0 .501961 0 rg (except) Tj /F4 10 Tf 0 0 0 rg ( ) Tj /F3 10 Tf .823529 .254902 .227451 rg (AttributeError) Tj /F4 10 Tf 0 0 0 rg (:) Tj ( ) Tj /F6 10 Tf .25098 .501961 .501961 rg (# instantiate the counter at the first call) Tj /F4 10 Tf 0 0 0 rg  T* (            ) Tj (counter) Tj ( ) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ( ) Tj (func) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (counter) Tj ( ) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ( ) Tj (itertools) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (count) Tj (\() Tj .4 .4 .4 rg (1) Tj 0 0 0 rg (\)) Tj  T* (        ) Tj (name) Tj ( ) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ( ) Tj .729412 .129412 .129412 rg (') Tj /F3 10 Tf .733333 .4 .533333 rg (%s) Tj /F4 10 Tf .729412 .129412 .129412 rg (-) Tj /F3 10 Tf .733333 .4 .533333 rg (%s) Tj /F4 10 Tf .729412 .129412 .129412 rg (') Tj 0 0 0 rg ( ) Tj .4 .4 .4 rg (%) Tj 0 0 0 rg ( ) Tj (\() Tj (func) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (__name__) Tj (,) Tj ( ) Tj 0 .501961 0 rg (next) Tj 0 0 0 rg (\() Tj (counter) Tj (\)\)) Tj  T* (        ) Tj /F3 10 Tf 0 .501961 0 rg (def) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 0 1 rg (func_wrapper) Tj 0 0 0 rg (\(\):) Tj  T* (            ) Tj /F3 10 Tf 0 .501961 0 rg (try) Tj /F4 10 Tf 0 0 0 rg (:) Tj  T* (                ) Tj (result) Tj ( ) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ( ) Tj (func) Tj (\() Tj .4 .4 .4 rg (*) Tj 0 0 0 rg (args) Tj (,) Tj ( ) Tj .4 .4 .4 rg (**) Tj 0 0 0 rg (kw) Tj (\)) Tj  T* (            ) Tj /F3 10 Tf 0 .501961 0 rg (except) Tj /F4 10 Tf 0 0 0 rg (:) Tj  T* (                ) Tj 0 .501961 0 rg (self) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (on_failure) Tj (\() Tj (sys) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (exc_info) Tj (\(\)\)) Tj  T* (            ) Tj /F3 10 Tf 0 .501961 0 rg (else) Tj /F4 10 Tf 0 0 0 rg (:) Tj  T* (                ) Tj /F3 10 Tf 0 .501961 0 rg (return) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 .501961 0 rg (self) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (on_success) Tj (\() Tj (result) Tj (\)) Tj  T* (            ) Tj /F3 10 Tf 0 .501961 0 rg (finally) Tj /F4 10 Tf 0 0 0 rg (:) Tj  T* (                ) Tj 0 .501961 0 rg (self) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (on_closing) Tj (\(\)) Tj  T* (        ) Tj (thread) Tj ( ) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ( ) Tj 0 .501961 0 rg (self) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (threadfactory) Tj (\() Tj 0 .501961 0 rg (None) Tj 0 0 0 rg (,) Tj ( ) Tj (func_wrapper) Tj (,) Tj ( ) Tj (name) Tj (\)) Tj  T* (        ) Tj (thread) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (start) Tj (\(\)) Tj  T* (        ) Tj /F3 10 Tf 0 .501961 0 rg (return) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (thread) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 383.8236 cm

+q

+BT 1 0 0 1 0 14 Tm .865984 Tw 12 TL /F1 10 Tf 0 0 0 rg (The decorated function returns the current execution thread, which can be stored and checked later, for) Tj T* 0 Tw (instance to verify that the thread ) Tj /F4 10 Tf (.isAlive\(\)) Tj /F1 10 Tf (.) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 341.8236 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 26 Tm /F1 10 Tf 12 TL .691654 Tw (Here is an example of usage. Suppose one wants to write some data to an external resource which can) Tj T* 0 Tw .21683 Tw (be accessed by a single user at once \(for instance a printer\). Then the access to the writing function must) Tj T* 0 Tw (be locked. Here is a minimalistic example:) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 188.6236 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 144 re B*

+Q

+q

+BT 1 0 0 1 0 122 Tm 12 TL /F4 10 Tf .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj (async) Tj ( ) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ( ) Tj (decorator) Tj (\() Tj (Async) Tj (\() Tj (threading) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (Thread) Tj (\)\)) Tj  T*  T* .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj (datalist) Tj ( ) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ( ) Tj ([]) Tj ( ) Tj /F6 10 Tf .25098 .501961 .501961 rg (# for simplicity the written data are stored into a list.) Tj /F4 10 Tf 0 0 0 rg  T*  T* .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj .666667 .133333 1 rg (@async) Tj 0 0 0 rg  T* .4 .4 .4 rg (...) Tj 0 0 0 rg ( ) Tj /F3 10 Tf 0 .501961 0 rg (def) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 0 1 rg (write) Tj 0 0 0 rg (\() Tj (data) Tj (\):) Tj  T* .4 .4 .4 rg (...) Tj 0 0 0 rg (     ) Tj /F6 10 Tf .25098 .501961 .501961 rg (# append data to the datalist by locking) Tj /F4 10 Tf 0 0 0 rg  T* .4 .4 .4 rg (...) Tj 0 0 0 rg (     ) Tj /F3 10 Tf 0 .501961 0 rg (with) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (threading) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (Lock) Tj (\(\):) Tj  T* .4 .4 .4 rg (...) Tj 0 0 0 rg (         ) Tj (time) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (sleep) Tj (\() Tj .4 .4 .4 rg (1) Tj 0 0 0 rg (\)) Tj ( ) Tj /F6 10 Tf .25098 .501961 .501961 rg (# emulate some long running operation) Tj /F4 10 Tf 0 0 0 rg  T* .4 .4 .4 rg (...) Tj 0 0 0 rg (         ) Tj (datalist) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (append) Tj (\() Tj (data) Tj (\)) Tj  T* .4 .4 .4 rg (...) Tj 0 0 0 rg (     ) Tj /F6 10 Tf .25098 .501961 .501961 rg (# other operations not requiring a lock here) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 156.6236 cm

+q

+BT 1 0 0 1 0 14 Tm .905868 Tw 12 TL /F1 10 Tf 0 0 0 rg (Each call to ) Tj /F4 10 Tf (write ) Tj /F1 10 Tf (will create a new writer thread, but there will be no synchronization problems since) Tj T* 0 Tw /F4 10 Tf (write ) Tj /F1 10 Tf (is locked.) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 87.42362 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 60 re B*

+Q

+q

+BT 1 0 0 1 0 38 Tm 12 TL /F4 10 Tf .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj (write) Tj (\() Tj .729412 .129412 .129412 rg ("data1") Tj 0 0 0 rg (\)) Tj  T* .4 .4 .4 rg (<) Tj 0 0 0 rg (Thread) Tj (\() Tj (write) Tj .4 .4 .4 rg (-) Tj (1) Tj 0 0 0 rg (,) Tj ( ) Tj (started) Tj .4 .4 .4 rg (...) Tj 0 0 0 rg (\)) Tj .4 .4 .4 rg (>) Tj 0 0 0 rg  T*  T* .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj (time) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (sleep) Tj (\() Tj .4 .4 .4 rg (.) Tj (1) Tj 0 0 0 rg (\)) Tj ( ) Tj /F6 10 Tf .25098 .501961 .501961 rg (# wait a bit, so we are sure data2 is written after data1) Tj /F4 10 Tf 0 0 0 rg  T* ET

+Q

+Q

+Q

+Q

+Q

+ 

+endstream

+endobj

+% 'R97': class PDFStream 

+97 0 obj

+% page stream

+<< /Length 6932 >>

+stream

+1 0 0 1 0 0 cm  BT /F1 12 Tf 14.4 TL ET

+q

+1 0 0 1 62.69291 655.8236 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 108 re B*

+Q

+q

+BT 1 0 0 1 0 86 Tm 12 TL /F4 10 Tf 0 0 0 rg  T* .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj (write) Tj (\() Tj .729412 .129412 .129412 rg ("data2") Tj 0 0 0 rg (\)) Tj  T* .4 .4 .4 rg (<) Tj 0 0 0 rg (Thread) Tj (\() Tj (write) Tj .4 .4 .4 rg (-) Tj (2) Tj 0 0 0 rg (,) Tj ( ) Tj (started) Tj .4 .4 .4 rg (...) Tj 0 0 0 rg (\)) Tj .4 .4 .4 rg (>) Tj 0 0 0 rg  T*  T* .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj (time) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (sleep) Tj (\() Tj .4 .4 .4 rg (2) Tj 0 0 0 rg (\)) Tj ( ) Tj /F6 10 Tf .25098 .501961 .501961 rg (# wait for the writers to complete) Tj /F4 10 Tf 0 0 0 rg  T*  T* .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj /F3 10 Tf 0 .501961 0 rg (print) Tj /F4 10 Tf 0 0 0 rg (\() Tj (datalist) Tj (\)) Tj  T* ([) Tj .729412 .129412 .129412 rg ('data1') Tj 0 0 0 rg (,) Tj ( ) Tj .729412 .129412 .129412 rg ('data2') Tj 0 0 0 rg (]) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 622.8236 cm

+q

+BT 1 0 0 1 0 3.5 Tm 21 TL /F2 17.5 Tf 0 0 0 rg (contextmanager) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 592.8236 cm

+q

+BT 1 0 0 1 0 14 Tm 2.685984 Tw 12 TL /F1 10 Tf 0 0 0 rg (For a long time Python had in its standard library a ) Tj /F4 10 Tf (contextmanager ) Tj /F1 10 Tf (decorator, able to convert) Tj T* 0 Tw (generator functions into ) Tj /F4 10 Tf (_GeneratorContextManager ) Tj /F1 10 Tf (factories. For instance if you write) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 499.6236 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 84 re B*

+Q

+q

+BT 1 0 0 1 0 62 Tm 12 TL /F4 10 Tf .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj /F3 10 Tf 0 .501961 0 rg (from) Tj /F4 10 Tf 0 0 0 rg ( ) Tj /F3 10 Tf 0 0 1 rg (contextlib) Tj /F4 10 Tf 0 0 0 rg ( ) Tj /F3 10 Tf 0 .501961 0 rg (import) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (contextmanager) Tj  T* .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj .666667 .133333 1 rg (@contextmanager) Tj 0 0 0 rg  T* .4 .4 .4 rg (...) Tj 0 0 0 rg ( ) Tj /F3 10 Tf 0 .501961 0 rg (def) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 0 1 rg (before_after) Tj 0 0 0 rg (\() Tj (before) Tj (,) Tj ( ) Tj (after) Tj (\):) Tj  T* .4 .4 .4 rg (...) Tj 0 0 0 rg (     ) Tj /F3 10 Tf 0 .501961 0 rg (print) Tj /F4 10 Tf 0 0 0 rg (\() Tj (before) Tj (\)) Tj  T* .4 .4 .4 rg (...) Tj 0 0 0 rg (     ) Tj /F3 10 Tf 0 .501961 0 rg (yield) Tj /F4 10 Tf 0 0 0 rg  T* .4 .4 .4 rg (...) Tj 0 0 0 rg (     ) Tj /F3 10 Tf 0 .501961 0 rg (print) Tj /F4 10 Tf 0 0 0 rg (\() Tj (after) Tj (\)) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 467.6236 cm

+q

+BT 1 0 0 1 0 14 Tm .955976 Tw 12 TL /F1 10 Tf 0 0 0 rg (then ) Tj /F4 10 Tf (before_after ) Tj /F1 10 Tf (is a factory function returning ) Tj /F4 10 Tf (_GeneratorContextManager ) Tj /F1 10 Tf (objects which can) Tj T* 0 Tw (be used with the ) Tj /F4 10 Tf (with ) Tj /F1 10 Tf (statement:) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 350.4236 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 108 re B*

+Q

+q

+BT 1 0 0 1 0 86 Tm 12 TL /F4 10 Tf .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj (ba) Tj ( ) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ( ) Tj (before_after) Tj (\() Tj .729412 .129412 .129412 rg ('BEFORE') Tj 0 0 0 rg (,) Tj ( ) Tj .729412 .129412 .129412 rg ('AFTER') Tj 0 0 0 rg (\)) Tj  T* .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj 0 .501961 0 rg (type) Tj 0 0 0 rg (\() Tj (ba) Tj (\)) Tj  T* .4 .4 .4 rg (<) Tj /F3 10 Tf 0 .501961 0 rg (class) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (') Tj /F3 10 Tf 0 0 1 rg (contextlib) Tj /F4 10 Tf .4 .4 .4 rg (.) Tj 0 0 0 rg (_GeneratorContextManager) Tj .729412 .129412 .129412 rg (') Tj (>) Tj 0 0 0 rg  T* .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj /F3 10 Tf 0 .501961 0 rg (with) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (ba) Tj (:) Tj  T* .4 .4 .4 rg (...) Tj 0 0 0 rg (     ) Tj /F3 10 Tf 0 .501961 0 rg (print) Tj /F4 10 Tf 0 0 0 rg (\() Tj .729412 .129412 .129412 rg ('hello') Tj 0 0 0 rg (\)) Tj  T* (BEFORE) Tj  T* (hello) Tj  T* (AFTER) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 306.4236 cm

+q

+BT 1 0 0 1 0 26 Tm .462488 Tw 12 TL /F1 10 Tf 0 0 0 rg (Basically, it is as if the content of the ) Tj /F4 10 Tf (with ) Tj /F1 10 Tf (block was executed in the place of the ) Tj /F4 10 Tf (yield ) Tj /F1 10 Tf (expression in) Tj T* 0 Tw 2.146342 Tw (the generator function. In Python 3.2 ) Tj /F4 10 Tf (_GeneratorContextManager ) Tj /F1 10 Tf (objects were enhanced with a) Tj T* 0 Tw /F4 10 Tf (__call__ ) Tj /F1 10 Tf (method, so that they can be used as decorators as in this example:) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 189.2236 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 108 re B*

+Q

+q

+BT 1 0 0 1 0 86 Tm 12 TL /F4 10 Tf .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj .666667 .133333 1 rg (@ba) Tj 0 0 0 rg  T* .4 .4 .4 rg (...) Tj 0 0 0 rg ( ) Tj /F3 10 Tf 0 .501961 0 rg (def) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 0 1 rg (hello) Tj 0 0 0 rg (\(\):) Tj  T* .4 .4 .4 rg (...) Tj 0 0 0 rg (     ) Tj /F3 10 Tf 0 .501961 0 rg (print) Tj /F4 10 Tf 0 0 0 rg (\() Tj .729412 .129412 .129412 rg ('hello') Tj 0 0 0 rg (\)) Tj  T* .4 .4 .4 rg (...) Tj 0 0 0 rg  T* .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj (hello) Tj (\(\)) Tj  T* (BEFORE) Tj  T* (hello) Tj  T* (AFTER) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 85.22362 cm

+q

+BT 1 0 0 1 0 86 Tm .20561 Tw 12 TL /F1 10 Tf 0 0 0 rg (The ) Tj /F4 10 Tf (ba ) Tj /F1 10 Tf (decorator is basically inserting a ) Tj /F4 10 Tf (with) Tj ( ) Tj (ba: ) Tj /F1 10 Tf (block inside the function. However there two issues: ) Tj T* 0 Tw .973555 Tw (the first is that ) Tj /F4 10 Tf (_GeneratorContextManager ) Tj /F1 10 Tf (objects are callable only in Python 3.2, so the previous ) Tj T* 0 Tw 2.758314 Tw (example will break in older versions of Python; the second is that ) Tj /F4 10 Tf (_GeneratorContextManager ) Tj T* 0 Tw .503318 Tw /F1 10 Tf (objects do not preserve the signature of the decorated functions: the decorated ) Tj /F4 10 Tf (hello ) Tj /F1 10 Tf (function here will ) Tj T* 0 Tw 1.07784 Tw (have a generic signature ) Tj /F4 10 Tf (hello\(*args,) Tj ( ) Tj (**kwargs\) ) Tj /F1 10 Tf (but will break when called with more than zero ) Tj T* 0 Tw 7.708314 Tw (arguments. For such reasons the decorator module, starting with release 3.4, offers a ) Tj T* 0 Tw .616647 Tw /F4 10 Tf (decorator.contextmanager ) Tj /F1 10 Tf (decorator that solves both problems and works even in Python 2.5. The ) Tj T* 0 Tw .34998 Tw (usage is the same and factories decorated with ) Tj /F4 10 Tf (decorator.contextmanager ) Tj /F1 10 Tf (will returns instances of) Tj T* 0 Tw ET

+Q

+Q

+ 

+endstream

+endobj

+% 'R98': class PDFStream 

+98 0 obj

+% page stream

+<< /Length 8146 >>

+stream

+1 0 0 1 0 0 cm  BT /F1 12 Tf 14.4 TL ET

+q

+1 0 0 1 62.69291 741.0236 cm

+q

+BT 1 0 0 1 0 14 Tm 3.295681 Tw 12 TL /F4 10 Tf 0 0 0 rg (ContextManager) Tj /F1 10 Tf (, a subclass of ) Tj /F4 10 Tf (contextlib._GeneratorContextManager ) Tj /F1 10 Tf (with a ) Tj /F4 10 Tf (__call__) Tj T* 0 Tw /F1 10 Tf (method acting as a signature-preserving decorator.) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 708.0236 cm

+q

+BT 1 0 0 1 0 3.5 Tm 21 TL /F2 17.5 Tf 0 0 0 rg (The ) Tj /F3 17.5 Tf (FunctionMaker ) Tj /F2 17.5 Tf (class) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 642.0236 cm

+q

+BT 1 0 0 1 0 50 Tm 2.241412 Tw 12 TL /F1 10 Tf 0 0 0 rg (You may wonder about how the functionality of the ) Tj /F4 10 Tf (decorator ) Tj /F1 10 Tf (module is implemented. The basic) Tj T* 0 Tw 1.545868 Tw (building block is a ) Tj /F4 10 Tf (FunctionMaker ) Tj /F1 10 Tf (class which is able to generate on the fly functions with a given) Tj T* 0 Tw .047485 Tw (name and signature from a function template passed as a string. Generally speaking, you should not need) Tj T* 0 Tw 1.164983 Tw (to resort to ) Tj /F4 10 Tf (FunctionMaker ) Tj /F1 10 Tf (when writing ordinary decorators, but it is handy in some circumstances.) Tj T* 0 Tw (You will see an example shortly, in the implementation of a cool decorator utility \() Tj /F4 10 Tf (decorator_apply) Tj /F1 10 Tf (\).) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 600.0236 cm

+q

+BT 1 0 0 1 0 26 Tm .414597 Tw 12 TL /F4 10 Tf 0 0 0 rg (FunctionMaker ) Tj /F1 10 Tf (provides a ) Tj /F4 10 Tf (.create ) Tj /F1 10 Tf (classmethod which takes as input the name, signature, and body) Tj T* 0 Tw .632927 Tw (of the function we want to generate as well as the execution environment were the function is generated) Tj T* 0 Tw (by ) Tj /F4 10 Tf (exec) Tj /F1 10 Tf (. Here is an example:) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 506.8236 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 84 re B*

+Q

+q

+BT 1 0 0 1 0 62 Tm 12 TL /F4 10 Tf .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj /F3 10 Tf 0 .501961 0 rg (def) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 0 1 rg (f) Tj 0 0 0 rg (\() Tj .4 .4 .4 rg (*) Tj 0 0 0 rg (args) Tj (,) Tj ( ) Tj .4 .4 .4 rg (**) Tj 0 0 0 rg (kw) Tj (\):) Tj ( ) Tj /F6 10 Tf .25098 .501961 .501961 rg (# a function with a generic signature) Tj /F4 10 Tf 0 0 0 rg  T* .4 .4 .4 rg (...) Tj 0 0 0 rg (     ) Tj /F3 10 Tf 0 .501961 0 rg (print) Tj /F4 10 Tf 0 0 0 rg (\() Tj (args) Tj (,) Tj ( ) Tj (kw) Tj (\)) Tj  T*  T* .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj (f1) Tj ( ) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ( ) Tj (FunctionMaker) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (create) Tj (\() Tj .729412 .129412 .129412 rg ('f1\(a, b\)') Tj 0 0 0 rg (,) Tj ( ) Tj .729412 .129412 .129412 rg ('f\(a, b\)') Tj 0 0 0 rg (,) Tj ( ) Tj 0 .501961 0 rg (dict) Tj 0 0 0 rg (\() Tj (f) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg (f) Tj (\)\)) Tj  T* .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj (f1) Tj (\() Tj .4 .4 .4 rg (1) Tj 0 0 0 rg (,) Tj .4 .4 .4 rg (2) Tj 0 0 0 rg (\)) Tj  T* (\() Tj .4 .4 .4 rg (1) Tj 0 0 0 rg (,) Tj ( ) Tj .4 .4 .4 rg (2) Tj 0 0 0 rg (\)) Tj ( ) Tj ({}) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 474.8236 cm

+q

+BT 1 0 0 1 0 14 Tm .226654 Tw 12 TL /F1 10 Tf 0 0 0 rg (It is important to notice that the function body is interpolated before being executed, so be careful with the) Tj T* 0 Tw /F4 10 Tf (% ) Tj /F1 10 Tf (sign!) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 432.8236 cm

+q

+BT 1 0 0 1 0 26 Tm 1.995433 Tw 12 TL /F4 10 Tf 0 0 0 rg (FunctionMaker.create ) Tj /F1 10 Tf (also accepts keyword arguments and such arguments are attached to the) Tj T* 0 Tw 1.64686 Tw (resulting function. This is useful if you want to set some function attributes, for instance the docstring) Tj T* 0 Tw /F4 10 Tf (__doc__) Tj /F1 10 Tf (.) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 390.8236 cm

+q

+BT 1 0 0 1 0 26 Tm .605318 Tw 12 TL /F1 10 Tf 0 0 0 rg (For debugging/introspection purposes it may be useful to see the source code of the generated function;) Tj T* 0 Tw 2.246235 Tw (to do that, just pass the flag ) Tj /F4 10 Tf (addsource=True ) Tj /F1 10 Tf (and a ) Tj /F4 10 Tf (__source__ ) Tj /F1 10 Tf (attribute will be added to the) Tj T* 0 Tw (generated function:) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 297.6236 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 84 re B*

+Q

+q

+BT 1 0 0 1 0 62 Tm 12 TL /F4 10 Tf .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj (f1) Tj ( ) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ( ) Tj (FunctionMaker) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (create) Tj (\() Tj  T* .4 .4 .4 rg (...) Tj 0 0 0 rg (     ) Tj .729412 .129412 .129412 rg ('f1\(a, b\)') Tj 0 0 0 rg (,) Tj ( ) Tj .729412 .129412 .129412 rg ('f\(a, b\)') Tj 0 0 0 rg (,) Tj ( ) Tj 0 .501961 0 rg (dict) Tj 0 0 0 rg (\() Tj (f) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg (f) Tj (\),) Tj ( ) Tj (addsource) Tj .4 .4 .4 rg (=) Tj 0 .501961 0 rg (True) Tj 0 0 0 rg (\)) Tj  T* .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj /F3 10 Tf 0 .501961 0 rg (print) Tj /F4 10 Tf 0 0 0 rg (\() Tj (f1) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (__source__) Tj (\)) Tj  T* /F3 10 Tf 0 .501961 0 rg (def) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 0 1 rg (f1) Tj 0 0 0 rg (\() Tj (a) Tj (,) Tj ( ) Tj (b) Tj (\):) Tj  T* (    ) Tj (f) Tj (\() Tj (a) Tj (,) Tj ( ) Tj (b) Tj (\)) Tj  T* .4 .4 .4 rg (<) Tj 0 0 0 rg (BLANKLINE) Tj .4 .4 .4 rg (>) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 157.6236 cm

+q

+BT 1 0 0 1 0 122 Tm .870651 Tw 12 TL /F4 10 Tf 0 0 0 rg (FunctionMaker.create ) Tj /F1 10 Tf (can take as first argument a string, as in the examples before, or a function.) Tj T* 0 Tw .224985 Tw (This is the most common usage, since typically you want to decorate a pre-existing function. A framework) Tj T* 0 Tw 1.606136 Tw (author may want to use directly ) Tj /F4 10 Tf (FunctionMaker.create ) Tj /F1 10 Tf (instead of ) Tj /F4 10 Tf (decorator) Tj /F1 10 Tf (, since it gives you) Tj T* 0 Tw 1.36686 Tw (direct access to the body of the generated function. For instance, suppose you want to instrument the) Tj T* 0 Tw .372209 Tw /F4 10 Tf (__init__ ) Tj /F1 10 Tf (methods of a set of classes, by preserving their signature \(such use case is not made up; this) Tj T* 0 Tw .673828 Tw (is done in SQAlchemy and in other frameworks\). When the first argument of ) Tj /F4 10 Tf (FunctionMaker.create) Tj T* 0 Tw 3.405814 Tw /F1 10 Tf (is a function, a ) Tj /F4 10 Tf (FunctionMaker ) Tj /F1 10 Tf (object is instantiated internally, with attributes ) Tj /F4 10 Tf (args) Tj /F1 10 Tf (, ) Tj /F4 10 Tf (varargs) Tj /F1 10 Tf (,) Tj T* 0 Tw 5.509982 Tw /F4 10 Tf (keywords ) Tj /F1 10 Tf (and ) Tj /F4 10 Tf (defaults ) Tj /F1 10 Tf (which are the the return values of the standard library function) Tj T* 0 Tw .561318 Tw /F4 10 Tf (inspect.getargspec) Tj /F1 10 Tf (. For each argument in the ) Tj /F4 10 Tf (args ) Tj /F1 10 Tf (\(which is a list of strings containing the names) Tj T* 0 Tw 1.599985 Tw (of the mandatory arguments\) an attribute ) Tj /F4 10 Tf (arg0) Tj /F1 10 Tf (, ) Tj /F4 10 Tf (arg1) Tj /F1 10 Tf (, ..., ) Tj /F4 10 Tf (argN ) Tj /F1 10 Tf (is also generated. Finally, there is a) Tj T* 0 Tw /F4 10 Tf (signature ) Tj /F1 10 Tf (attribute, a string with the signature of the original function.) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 79.62362 cm

+q

+BT 1 0 0 1 0 62 Tm 4.63311 Tw 12 TL /F1 10 Tf 0 0 0 rg (Notice that while I do not have plans to change or remove the functionality provided in the) Tj T* 0 Tw 1.00936 Tw /F4 10 Tf (FunctionMaker ) Tj /F1 10 Tf (class, I do not guarantee that it will stay unchanged forever. For instance, right now I) Tj T* 0 Tw .791318 Tw (am using the traditional string interpolation syntax for function templates, but Python 2.6 and Python 3.0) Tj T* 0 Tw .712093 Tw (provide a newer interpolation syntax and I may use the new syntax in the future. On the other hand, the) Tj T* 0 Tw .639985 Tw (functionality provided by ) Tj /F4 10 Tf (decorator ) Tj /F1 10 Tf (has been there from version 0.1 and it is guaranteed to stay there) Tj T* 0 Tw (forever.) Tj T* ET

+Q

+Q

+ 

+endstream

+endobj

+% 'R99': class PDFStream 

+99 0 obj

+% page stream

+<< /Length 7325 >>

+stream

+1 0 0 1 0 0 cm  BT /F1 12 Tf 14.4 TL ET

+q

+1 0 0 1 62.69291 744.0236 cm

+q

+BT 1 0 0 1 0 3.5 Tm 21 TL /F2 17.5 Tf 0 0 0 rg (Getting the source code) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 666.0236 cm

+q

+BT 1 0 0 1 0 62 Tm 5.045529 Tw 12 TL /F1 10 Tf 0 0 0 rg (Internally ) Tj /F4 10 Tf (FunctionMaker.create ) Tj /F1 10 Tf (uses ) Tj /F4 10 Tf (exec ) Tj /F1 10 Tf (to generate the decorated function. Therefore) Tj T* 0 Tw 2.542126 Tw /F4 10 Tf (inspect.getsource ) Tj /F1 10 Tf (will not work for decorated functions. That means that the usual '??' trick in) Tj T* 0 Tw 26.45775 Tw (IPython will give you the \(right on the spot\) message) Tj T* 0 Tw .261647 Tw /F4 10 Tf (Dynamically) Tj ( ) Tj (generated) Tj ( ) Tj (function.) Tj ( ) Tj (No) Tj ( ) Tj (source) Tj ( ) Tj (code available) Tj /F1 10 Tf (. In the past I have considered) Tj T* 0 Tw .945366 Tw (this acceptable, since ) Tj /F4 10 Tf (inspect.getsource ) Tj /F1 10 Tf (does not really work even with regular decorators. In that) Tj T* 0 Tw (case ) Tj /F4 10 Tf (inspect.getsource ) Tj /F1 10 Tf (gives you the wrapper source code which is probably not what you want:) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 596.8236 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 60 re B*

+Q

+q

+BT 1 0 0 1 0 38 Tm 12 TL /F3 10 Tf 0 .501961 0 rg (def) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 0 1 rg (identity_dec) Tj 0 0 0 rg (\() Tj (func) Tj (\):) Tj  T* (    ) Tj /F3 10 Tf 0 .501961 0 rg (def) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 0 1 rg (wrapper) Tj 0 0 0 rg (\() Tj .4 .4 .4 rg (*) Tj 0 0 0 rg (args) Tj (,) Tj ( ) Tj .4 .4 .4 rg (**) Tj 0 0 0 rg (kw) Tj (\):) Tj  T* (        ) Tj /F3 10 Tf 0 .501961 0 rg (return) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (func) Tj (\() Tj .4 .4 .4 rg (*) Tj 0 0 0 rg (args) Tj (,) Tj ( ) Tj .4 .4 .4 rg (**) Tj 0 0 0 rg (kw) Tj (\)) Tj  T* (    ) Tj /F3 10 Tf 0 .501961 0 rg (return) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (wrapper) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 491.6236 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 96 re B*

+Q

+q

+BT 1 0 0 1 0 74 Tm 12 TL /F4 10 Tf .666667 .133333 1 rg (@identity_dec) Tj 0 0 0 rg  T* /F3 10 Tf 0 .501961 0 rg (def) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 0 1 rg (example) Tj 0 0 0 rg (\(\):) Tj ( ) Tj /F3 10 Tf 0 .501961 0 rg (pass) Tj /F4 10 Tf 0 0 0 rg  T*  T* .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj /F3 10 Tf 0 .501961 0 rg (print) Tj /F4 10 Tf 0 0 0 rg (\() Tj (inspect) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (getsource) Tj (\() Tj (example) Tj (\)\)) Tj  T* (    ) Tj /F3 10 Tf 0 .501961 0 rg (def) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 0 1 rg (wrapper) Tj 0 0 0 rg (\() Tj .4 .4 .4 rg (*) Tj 0 0 0 rg (args) Tj (,) Tj ( ) Tj .4 .4 .4 rg (**) Tj 0 0 0 rg (kw) Tj (\):) Tj  T* (        ) Tj /F3 10 Tf 0 .501961 0 rg (return) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (func) Tj (\() Tj .4 .4 .4 rg (*) Tj 0 0 0 rg (args) Tj (,) Tj ( ) Tj .4 .4 .4 rg (**) Tj 0 0 0 rg (kw) Tj (\)) Tj  T* .4 .4 .4 rg (<) Tj 0 0 0 rg (BLANKLINE) Tj .4 .4 .4 rg (>) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 435.6236 cm

+q

+BT 1 0 0 1 0 38 Tm 1.471235 Tw 12 TL /F1 10 Tf 0 0 0 rg (\(see bug report ) Tj 0 0 .501961 rg (1764286 ) Tj 0 0 0 rg (for an explanation of what is happening\). Unfortunately the bug is still there,) Tj T* 0 Tw 1.541235 Tw (even in Python 2.7 and 3.1. There is however a workaround. The decorator module adds an attribute) Tj T* 0 Tw .103984 Tw /F4 10 Tf (.__wrapped__ ) Tj /F1 10 Tf (to the decorated function, containing a reference to the original function. The easy way to) Tj T* 0 Tw (get the source code is to call ) Tj /F4 10 Tf (inspect.getsource ) Tj /F1 10 Tf (on the undecorated function:) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 330.4236 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 96 re B*

+Q

+q

+BT 1 0 0 1 0 74 Tm 12 TL /F4 10 Tf .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj /F3 10 Tf 0 .501961 0 rg (print) Tj /F4 10 Tf 0 0 0 rg (\() Tj (inspect) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (getsource) Tj (\() Tj (factorial) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (__wrapped__) Tj (\)\)) Tj  T* .666667 .133333 1 rg (@tail_recursive) Tj 0 0 0 rg  T* /F3 10 Tf 0 .501961 0 rg (def) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 0 1 rg (factorial) Tj 0 0 0 rg (\() Tj (n) Tj (,) Tj ( ) Tj (acc) Tj .4 .4 .4 rg (=) Tj (1) Tj 0 0 0 rg (\):) Tj  T* (    ) Tj .729412 .129412 .129412 rg ("The good old factorial") Tj 0 0 0 rg  T* (    ) Tj /F3 10 Tf 0 .501961 0 rg (if) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (n) Tj ( ) Tj .4 .4 .4 rg (==) Tj 0 0 0 rg ( ) Tj .4 .4 .4 rg (0) Tj 0 0 0 rg (:) Tj ( ) Tj /F3 10 Tf 0 .501961 0 rg (return) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (acc) Tj  T* (    ) Tj /F3 10 Tf 0 .501961 0 rg (return) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (factorial) Tj (\() Tj (n) Tj .4 .4 .4 rg (-) Tj (1) Tj 0 0 0 rg (,) Tj ( ) Tj (n) Tj .4 .4 .4 rg (*) Tj 0 0 0 rg (acc) Tj (\)) Tj  T* .4 .4 .4 rg (<) Tj 0 0 0 rg (BLANKLINE) Tj .4 .4 .4 rg (>) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 297.4236 cm

+q

+BT 1 0 0 1 0 3.5 Tm 21 TL /F2 17.5 Tf 0 0 0 rg (Dealing with third party decorators) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 243.4236 cm

+q

+BT 1 0 0 1 0 38 Tm .321654 Tw 12 TL /F1 10 Tf 0 0 0 rg (Sometimes you find on the net some cool decorator that you would like to include in your code. However,) Tj T* 0 Tw .50061 Tw (more often than not the cool decorator is not signature-preserving. Therefore you may want an easy way) Tj T* 0 Tw 1.814597 Tw (to upgrade third party decorators to signature-preserving decorators without having to rewrite them in) Tj T* 0 Tw (terms of ) Tj /F4 10 Tf (decorator) Tj /F1 10 Tf (. You can use a ) Tj /F4 10 Tf (FunctionMaker ) Tj /F1 10 Tf (to implement that functionality as follows:) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 126.2236 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 108 re B*

+Q

+q

+BT 1 0 0 1 0 86 Tm 12 TL /F3 10 Tf 0 .501961 0 rg (def) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 0 1 rg (decorator_apply) Tj 0 0 0 rg (\() Tj (dec) Tj (,) Tj ( ) Tj (func) Tj (\):) Tj  T* (    ) Tj /F6 10 Tf .729412 .129412 .129412 rg (""") Tj T* (    Decorate a function by preserving the signature even if dec) Tj T* (    is not a signature-preserving decorator.) Tj T* (    """) Tj /F4 10 Tf 0 0 0 rg  T* (    ) Tj /F3 10 Tf 0 .501961 0 rg (return) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (FunctionMaker) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (create) Tj (\() Tj  T* (        ) Tj (func) Tj (,) Tj ( ) Tj .729412 .129412 .129412 rg ('return decorated\() Tj /F3 10 Tf .733333 .4 .533333 rg (%\(signature\)s) Tj /F4 10 Tf .729412 .129412 .129412 rg (\)') Tj 0 0 0 rg (,) Tj  T* (        ) Tj 0 .501961 0 rg (dict) Tj 0 0 0 rg (\() Tj (decorated) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg (dec) Tj (\() Tj (func) Tj (\)\),) Tj ( ) Tj (__wrapped__) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg (func) Tj (\)) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 94.22362 cm

+q

+BT 1 0 0 1 0 14 Tm .698314 Tw 12 TL /F4 10 Tf 0 0 0 rg (decorator_apply ) Tj /F1 10 Tf (sets the attribute ) Tj /F4 10 Tf (.__wrapped__ ) Tj /F1 10 Tf (of the generated function to the original function,) Tj T* 0 Tw (so that you can get the right source code.) Tj T* ET

+Q

+Q

+ 

+endstream

+endobj

+% 'R100': class PDFStream 

+100 0 obj

+% page stream

+<< /Length 7498 >>

+stream

+1 0 0 1 0 0 cm  BT /F1 12 Tf 14.4 TL ET

+q

+1 0 0 1 62.69291 729.0236 cm

+q

+BT 1 0 0 1 0 26 Tm .13104 Tw 12 TL /F1 10 Tf 0 0 0 rg (Notice that I am not providing this functionality in the ) Tj /F4 10 Tf (decorator ) Tj /F1 10 Tf (module directly since I think it is best to) Tj T* 0 Tw 2.070751 Tw (rewrite the decorator rather than adding an additional level of indirection. However, practicality beats) Tj T* 0 Tw (purity, so you can add ) Tj /F4 10 Tf (decorator_apply ) Tj /F1 10 Tf (to your toolbox and use it if you need to.) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 675.0236 cm

+q

+BT 1 0 0 1 0 38 Tm 1.74881 Tw 12 TL /F1 10 Tf 0 0 0 rg (In order to give an example of usage of ) Tj /F4 10 Tf (decorator_apply) Tj /F1 10 Tf (, I will show a pretty slick decorator that) Tj T* 0 Tw 1.276651 Tw (converts a tail-recursive function in an iterative function. I have shamelessly stolen the basic idea from) Tj T* 0 Tw 43.62829 Tw (Kay Schluehr's recipe in the Python Cookbook,) Tj T* 0 Tw 0 0 .501961 rg (http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/496691) Tj 0 0 0 rg (.) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 305.8236 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 360 re B*

+Q

+q

+BT 1 0 0 1 0 338 Tm 12 TL /F3 10 Tf 0 .501961 0 rg (class) Tj /F4 10 Tf 0 0 0 rg ( ) Tj /F3 10 Tf 0 0 1 rg (TailRecursive) Tj /F4 10 Tf 0 0 0 rg (\() Tj 0 .501961 0 rg (object) Tj 0 0 0 rg (\):) Tj  T* (    ) Tj /F6 10 Tf .729412 .129412 .129412 rg (""") Tj T* (    tail_recursive decorator based on Kay Schluehr's recipe) Tj T* (    http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/496691) Tj T* (    with improvements by me and George Sakkis.) Tj T* (    """) Tj /F4 10 Tf 0 0 0 rg  T*  T* (    ) Tj /F3 10 Tf 0 .501961 0 rg (def) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 0 1 rg (__init__) Tj 0 0 0 rg (\() Tj 0 .501961 0 rg (self) Tj 0 0 0 rg (,) Tj ( ) Tj (func) Tj (\):) Tj  T* (        ) Tj 0 .501961 0 rg (self) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (func) Tj ( ) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ( ) Tj (func) Tj  T* (        ) Tj 0 .501961 0 rg (self) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (firstcall) Tj ( ) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ( ) Tj 0 .501961 0 rg (True) Tj 0 0 0 rg  T* (        ) Tj 0 .501961 0 rg (self) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (CONTINUE) Tj ( ) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ( ) Tj 0 .501961 0 rg (object) Tj 0 0 0 rg (\(\)) Tj ( ) Tj /F6 10 Tf .25098 .501961 .501961 rg (# sentinel) Tj /F4 10 Tf 0 0 0 rg  T*  T* (    ) Tj /F3 10 Tf 0 .501961 0 rg (def) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 0 1 rg (__call__) Tj 0 0 0 rg (\() Tj 0 .501961 0 rg (self) Tj 0 0 0 rg (,) Tj ( ) Tj .4 .4 .4 rg (*) Tj 0 0 0 rg (args) Tj (,) Tj ( ) Tj .4 .4 .4 rg (**) Tj 0 0 0 rg (kwd) Tj (\):) Tj  T* (        ) Tj (CONTINUE) Tj ( ) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ( ) Tj 0 .501961 0 rg (self) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (CONTINUE) Tj  T* (        ) Tj /F3 10 Tf 0 .501961 0 rg (if) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 .501961 0 rg (self) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (firstcall) Tj (:) Tj  T* (            ) Tj (func) Tj ( ) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ( ) Tj 0 .501961 0 rg (self) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (func) Tj  T* (            ) Tj 0 .501961 0 rg (self) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (firstcall) Tj ( ) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ( ) Tj 0 .501961 0 rg (False) Tj 0 0 0 rg  T* (            ) Tj /F3 10 Tf 0 .501961 0 rg (try) Tj /F4 10 Tf 0 0 0 rg (:) Tj  T* (                ) Tj /F3 10 Tf 0 .501961 0 rg (while) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 .501961 0 rg (True) Tj 0 0 0 rg (:) Tj  T* (                    ) Tj (result) Tj ( ) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ( ) Tj (func) Tj (\() Tj .4 .4 .4 rg (*) Tj 0 0 0 rg (args) Tj (,) Tj ( ) Tj .4 .4 .4 rg (**) Tj 0 0 0 rg (kwd) Tj (\)) Tj  T* (                    ) Tj /F3 10 Tf 0 .501961 0 rg (if) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (result) Tj ( ) Tj /F3 10 Tf .666667 .133333 1 rg (is) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (CONTINUE) Tj (:) Tj ( ) Tj /F6 10 Tf .25098 .501961 .501961 rg (# update arguments) Tj /F4 10 Tf 0 0 0 rg  T* (                        ) Tj (args) Tj (,) Tj ( ) Tj (kwd) Tj ( ) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ( ) Tj 0 .501961 0 rg (self) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (argskwd) Tj  T* (                    ) Tj /F3 10 Tf 0 .501961 0 rg (else) Tj /F4 10 Tf 0 0 0 rg (:) Tj ( ) Tj /F6 10 Tf .25098 .501961 .501961 rg (# last call) Tj /F4 10 Tf 0 0 0 rg  T* (                        ) Tj /F3 10 Tf 0 .501961 0 rg (return) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (result) Tj  T* (            ) Tj /F3 10 Tf 0 .501961 0 rg (finally) Tj /F4 10 Tf 0 0 0 rg (:) Tj  T* (                ) Tj 0 .501961 0 rg (self) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (firstcall) Tj ( ) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ( ) Tj 0 .501961 0 rg (True) Tj 0 0 0 rg  T* (        ) Tj /F3 10 Tf 0 .501961 0 rg (else) Tj /F4 10 Tf 0 0 0 rg (:) Tj ( ) Tj /F6 10 Tf .25098 .501961 .501961 rg (# return the arguments of the tail call) Tj /F4 10 Tf 0 0 0 rg  T* (            ) Tj 0 .501961 0 rg (self) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (argskwd) Tj ( ) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ( ) Tj (args) Tj (,) Tj ( ) Tj (kwd) Tj  T* (            ) Tj /F3 10 Tf 0 .501961 0 rg (return) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (CONTINUE) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 285.8236 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 2 Tm /F1 10 Tf 12 TL (Here the decorator is implemented as a class returning callable objects.) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 240.6236 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 36 re B*

+Q

+q

+BT 1 0 0 1 0 14 Tm 12 TL /F3 10 Tf 0 .501961 0 rg (def) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 0 1 rg (tail_recursive) Tj 0 0 0 rg (\() Tj (func) Tj (\):) Tj  T* (    ) Tj /F3 10 Tf 0 .501961 0 rg (return) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (decorator_apply) Tj (\() Tj (TailRecursive) Tj (,) Tj ( ) Tj (func) Tj (\)) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 220.6236 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 2 Tm /F1 10 Tf 12 TL (Here is how you apply the upgraded decorator to the good old factorial:) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 139.4236 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 72 re B*

+Q

+q

+BT 1 0 0 1 0 50 Tm 12 TL /F4 10 Tf .666667 .133333 1 rg (@tail_recursive) Tj 0 0 0 rg  T* /F3 10 Tf 0 .501961 0 rg (def) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 0 1 rg (factorial) Tj 0 0 0 rg (\() Tj (n) Tj (,) Tj ( ) Tj (acc) Tj .4 .4 .4 rg (=) Tj (1) Tj 0 0 0 rg (\):) Tj  T* (    ) Tj .729412 .129412 .129412 rg ("The good old factorial") Tj 0 0 0 rg  T* (    ) Tj /F3 10 Tf 0 .501961 0 rg (if) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (n) Tj ( ) Tj .4 .4 .4 rg (==) Tj 0 0 0 rg ( ) Tj .4 .4 .4 rg (0) Tj 0 0 0 rg (:) Tj ( ) Tj /F3 10 Tf 0 .501961 0 rg (return) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (acc) Tj  T* (    ) Tj /F3 10 Tf 0 .501961 0 rg (return) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (factorial) Tj (\() Tj (n) Tj .4 .4 .4 rg (-) Tj (1) Tj 0 0 0 rg (,) Tj ( ) Tj (n) Tj .4 .4 .4 rg (*) Tj 0 0 0 rg (acc) Tj (\)) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 94.22362 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 36 re B*

+Q

+q

+BT 1 0 0 1 0 14 Tm 12 TL /F4 10 Tf .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj /F3 10 Tf 0 .501961 0 rg (print) Tj /F4 10 Tf 0 0 0 rg (\() Tj (factorial) Tj (\() Tj .4 .4 .4 rg (4) Tj 0 0 0 rg (\)\)) Tj  T* .4 .4 .4 rg (24) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+ 

+endstream

+endobj

+% 'R101': class PDFStream 

+101 0 obj

+% page stream

+<< /Length 4932 >>

+stream

+1 0 0 1 0 0 cm  BT /F1 12 Tf 14.4 TL ET

+q

+1 0 0 1 62.69291 717.0236 cm

+q

+BT 1 0 0 1 0 38 Tm .188935 Tw 12 TL /F1 10 Tf 0 0 0 rg (This decorator is pretty impressive, and should give you some food for your mind ;\) Notice that there is no) Tj T* 0 Tw 1.339983 Tw (recursion limit now, and you can easily compute ) Tj /F4 10 Tf (factorial\(1001\) ) Tj /F1 10 Tf (or larger without filling the stack) Tj T* 0 Tw .909431 Tw (frame. Notice also that the decorator will not work on functions which are not tail recursive, such as the) Tj T* 0 Tw (following) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 659.8236 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 48 re B*

+Q

+q

+BT 1 0 0 1 0 26 Tm 12 TL /F3 10 Tf 0 .501961 0 rg (def) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 0 1 rg (fact) Tj 0 0 0 rg (\() Tj (n) Tj (\):) Tj ( ) Tj /F6 10 Tf .25098 .501961 .501961 rg (# this is not tail-recursive) Tj /F4 10 Tf 0 0 0 rg  T* (    ) Tj /F3 10 Tf 0 .501961 0 rg (if) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (n) Tj ( ) Tj .4 .4 .4 rg (==) Tj 0 0 0 rg ( ) Tj .4 .4 .4 rg (0) Tj 0 0 0 rg (:) Tj ( ) Tj /F3 10 Tf 0 .501961 0 rg (return) Tj /F4 10 Tf 0 0 0 rg ( ) Tj .4 .4 .4 rg (1) Tj 0 0 0 rg  T* (    ) Tj /F3 10 Tf 0 .501961 0 rg (return) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (n) Tj ( ) Tj .4 .4 .4 rg (*) Tj 0 0 0 rg ( ) Tj (fact) Tj (\() Tj (n) Tj .4 .4 .4 rg (-) Tj (1) Tj 0 0 0 rg (\)) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 627.8236 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 14 Tm /F1 10 Tf 12 TL .541098 Tw (\(reminder: a function is tail recursive if it either returns a value without making a recursive call, or returns) Tj T* 0 Tw (directly the result of a recursive call\).) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 594.8236 cm

+q

+BT 1 0 0 1 0 3.5 Tm 21 TL /F2 17.5 Tf 0 0 0 rg (Caveats and limitations) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 564.8236 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 14 Tm /F1 10 Tf 12 TL .474987 Tw (The first thing you should be aware of, it the fact that decorators have a performance penalty. The worse) Tj T* 0 Tw (case is shown by the following example:) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 339.6236 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 216 re B*

+Q

+q

+0 0 0 rg

+BT 1 0 0 1 0 194 Tm /F4 10 Tf 12 TL ($ cat performance.sh) Tj T* (python3 -m timeit -s ") Tj T* (from decorator import decorator) Tj T*  T* (@decorator) Tj T* (def do_nothing\(func, *args, **kw\):) Tj T* (    return func\(*args, **kw\)) Tj T*  T* (@do_nothing) Tj T* (def f\(\):) Tj T* (    pass) Tj T* (" "f\(\)") Tj T*  T* (python3 -m timeit -s ") Tj T* (def f\(\):) Tj T* (    pass) Tj T* (" "f\(\)") Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 307.6236 cm

+q

+BT 1 0 0 1 0 14 Tm .266235 Tw 12 TL /F1 10 Tf 0 0 0 rg (On my MacBook, using the ) Tj /F4 10 Tf (do_nothing ) Tj /F1 10 Tf (decorator instead of the plain function is more than three times) Tj T* 0 Tw (slower:) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 250.4236 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 48 re B*

+Q

+q

+0 0 0 rg

+BT 1 0 0 1 0 26 Tm /F4 10 Tf 12 TL ($ bash performance.sh) Tj T* (1000000 loops, best of 3: 0.669 usec per loop) Tj T* (1000000 loops, best of 3: 0.181 usec per loop) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 206.4236 cm

+q

+BT 1 0 0 1 0 26 Tm 1.25832 Tw 12 TL /F1 10 Tf 0 0 0 rg (It should be noted that a real life function would probably do something more useful than ) Tj /F4 10 Tf (f ) Tj /F1 10 Tf (here, and) Tj T* 0 Tw .91811 Tw (therefore in real life the performance penalty could be completely negligible. As always, the only way to) Tj T* 0 Tw (know if there is a penalty in your specific use case is to measure it.) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 176.4236 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 14 Tm /F1 10 Tf 12 TL .867984 Tw (You should be aware that decorators will make your tracebacks longer and more difficult to understand.) Tj T* 0 Tw (Consider this example:) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 119.2236 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 48 re B*

+Q

+q

+BT 1 0 0 1 0 26 Tm 12 TL /F4 10 Tf .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj .666667 .133333 1 rg (@trace) Tj 0 0 0 rg  T* .4 .4 .4 rg (...) Tj 0 0 0 rg ( ) Tj /F3 10 Tf 0 .501961 0 rg (def) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 0 1 rg (f) Tj 0 0 0 rg (\(\):) Tj  T* .4 .4 .4 rg (...) Tj 0 0 0 rg (     ) Tj .4 .4 .4 rg (1) Tj (/) Tj (0) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 87.22362 cm

+q

+BT 1 0 0 1 0 14 Tm .583318 Tw 12 TL /F1 10 Tf 0 0 0 rg (Calling ) Tj /F4 10 Tf (f\(\) ) Tj /F1 10 Tf (will give you a ) Tj /F4 10 Tf (ZeroDivisionError) Tj /F1 10 Tf (, but since the function is decorated the traceback will) Tj T* 0 Tw (be longer:) Tj T* ET

+Q

+Q

+ 

+endstream

+endobj

+% 'R102': class PDFStream 

+102 0 obj

+% page stream

+<< /Length 8009 >>

+stream

+1 0 0 1 0 0 cm  BT /F1 12 Tf 14.4 TL ET

+q

+1 0 0 1 62.69291 643.8236 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 120 re B*

+Q

+q

+BT 1 0 0 1 0 98 Tm 12 TL /F4 10 Tf .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj (f) Tj (\(\)) Tj  T* (Traceback) Tj ( ) Tj (\() Tj (most) Tj ( ) Tj (recent) Tj ( ) Tj (call) Tj ( ) Tj (last) Tj (\):) Tj  T* (  ) Tj .4 .4 .4 rg (...) Tj 0 0 0 rg  T* (     ) Tj (File) Tj ( ) Tj .729412 .129412 .129412 rg (") Tj (<) Tj (string) Tj (>) Tj (") Tj 0 0 0 rg (,) Tj ( ) Tj (line) Tj ( ) Tj .4 .4 .4 rg (2) Tj 0 0 0 rg (,) Tj ( ) Tj /F3 10 Tf .666667 .133333 1 rg (in) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (f) Tj  T* (     ) Tj (File) Tj ( ) Tj .729412 .129412 .129412 rg (") Tj (<) Tj (doctest __main__[22]) Tj (>) Tj (") Tj 0 0 0 rg (,) Tj ( ) Tj (line) Tj ( ) Tj .4 .4 .4 rg (4) Tj 0 0 0 rg (,) Tj ( ) Tj /F3 10 Tf .666667 .133333 1 rg (in) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (trace) Tj  T* (       ) Tj /F3 10 Tf 0 .501961 0 rg (return) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (f) Tj (\() Tj .4 .4 .4 rg (*) Tj 0 0 0 rg (args) Tj (,) Tj ( ) Tj .4 .4 .4 rg (**) Tj 0 0 0 rg (kw) Tj (\)) Tj  T* (     ) Tj (File) Tj ( ) Tj .729412 .129412 .129412 rg (") Tj (<) Tj (doctest __main__[51]) Tj (>) Tj (") Tj 0 0 0 rg (,) Tj ( ) Tj (line) Tj ( ) Tj .4 .4 .4 rg (3) Tj 0 0 0 rg (,) Tj ( ) Tj /F3 10 Tf .666667 .133333 1 rg (in) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (f) Tj  T* (       ) Tj .4 .4 .4 rg (1) Tj (/) Tj (0) Tj 0 0 0 rg  T* /F3 10 Tf .823529 .254902 .227451 rg (ZeroDivisionError) Tj /F4 10 Tf 0 0 0 rg (:) Tj ( ) Tj .4 .4 .4 rg (...) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 575.8236 cm

+q

+BT 1 0 0 1 0 50 Tm 1.05528 Tw 12 TL /F1 10 Tf 0 0 0 rg (You see here the inner call to the decorator ) Tj /F4 10 Tf (trace) Tj /F1 10 Tf (, which calls ) Tj /F4 10 Tf (f\(*args,) Tj ( ) Tj (**kw\)) Tj /F1 10 Tf (, and a reference to) Tj T* 0 Tw .076457 Tw /F4 10 Tf (File) Tj ( ) Tj (") Tj (<) Tj (string) Tj (>) Tj (",) Tj ( ) Tj (line) Tj ( ) Tj (2,) Tj ( ) Tj (in) Tj ( ) Tj (f) Tj /F1 10 Tf (. This latter reference is due to the fact that internally the decorator) Tj T* 0 Tw 2.053318 Tw (module uses ) Tj /F4 10 Tf (exec ) Tj /F1 10 Tf (to generate the decorated function. Notice that ) Tj /F4 10 Tf (exec ) Tj /F1 10 Tf (is ) Tj /F5 10 Tf (not ) Tj /F1 10 Tf (responsibile for the) Tj T* 0 Tw 1.507485 Tw (performance penalty, since is the called ) Tj /F5 10 Tf (only once ) Tj /F1 10 Tf (at function decoration time, and not every time the) Tj T* 0 Tw (decorated function is called.) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 497.8236 cm

+q

+BT 1 0 0 1 0 62 Tm .932209 Tw 12 TL /F1 10 Tf 0 0 0 rg (At present, there is no clean way to avoid ) Tj /F4 10 Tf (exec) Tj /F1 10 Tf (. A clean solution would require to change the CPython) Tj T* 0 Tw .777485 Tw (implementation of functions and add an hook to make it possible to change their signature directly. That) Tj T* 0 Tw .74186 Tw (could happen in future versions of Python \(see PEP ) Tj 0 0 .501961 rg (362) Tj 0 0 0 rg (\) and then the decorator module would become) Tj T* 0 Tw 2.385318 Tw (obsolete. However, at present, even in Python 3.2 it is impossible to change the function signature) Tj T* 0 Tw .931751 Tw (directly, therefore the ) Tj /F4 10 Tf (decorator ) Tj /F1 10 Tf (module is still useful. Actually, this is one of the main reasons why I) Tj T* 0 Tw (keep maintaining the module and releasing new versions.) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 455.8236 cm

+q

+BT 1 0 0 1 0 26 Tm 1.043828 Tw 12 TL /F1 10 Tf 0 0 0 rg (In the present implementation, decorators generated by ) Tj /F4 10 Tf (decorator ) Tj /F1 10 Tf (can only be used on user-defined) Tj T* 0 Tw .152485 Tw (Python functions or methods, not on generic callable objects, nor on built-in functions, due to limitations of) Tj T* 0 Tw (the ) Tj /F4 10 Tf (inspect ) Tj /F1 10 Tf (module in the standard library.) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 425.8236 cm

+q

+BT 1 0 0 1 0 14 Tm .785777 Tw 12 TL /F1 10 Tf 0 0 0 rg (There is a restriction on the names of the arguments: for instance, if try to call an argument ) Tj /F4 10 Tf (_call_ ) Tj /F1 10 Tf (or) Tj T* 0 Tw /F4 10 Tf (_func_ ) Tj /F1 10 Tf (you will get a ) Tj /F4 10 Tf (NameError) Tj /F1 10 Tf (:) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 308.6236 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 108 re B*

+Q

+q

+BT 1 0 0 1 0 86 Tm 12 TL /F4 10 Tf .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj .666667 .133333 1 rg (@trace) Tj 0 0 0 rg  T* .4 .4 .4 rg (...) Tj 0 0 0 rg ( ) Tj /F3 10 Tf 0 .501961 0 rg (def) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 0 1 rg (f) Tj 0 0 0 rg (\() Tj (_func_) Tj (\):) Tj ( ) Tj /F3 10 Tf 0 .501961 0 rg (print) Tj /F4 10 Tf 0 0 0 rg (\() Tj (f) Tj (\)) Tj  T* .4 .4 .4 rg (...) Tj 0 0 0 rg  T* (Traceback) Tj ( ) Tj (\() Tj (most) Tj ( ) Tj (recent) Tj ( ) Tj (call) Tj ( ) Tj (last) Tj (\):) Tj  T* (  ) Tj .4 .4 .4 rg (...) Tj 0 0 0 rg  T* /F3 10 Tf .823529 .254902 .227451 rg (NameError) Tj /F4 10 Tf 0 0 0 rg (:) Tj ( ) Tj (_func_) Tj ( ) Tj /F3 10 Tf .666667 .133333 1 rg (is) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (overridden) Tj ( ) Tj /F3 10 Tf .666667 .133333 1 rg (in) Tj /F4 10 Tf 0 0 0 rg  T* /F3 10 Tf 0 .501961 0 rg (def) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 0 1 rg (f) Tj 0 0 0 rg (\() Tj (_func_) Tj (\):) Tj  T* (    ) Tj /F3 10 Tf 0 .501961 0 rg (return) Tj /F4 10 Tf 0 0 0 rg ( ) Tj (_call_) Tj (\() Tj (_func_) Tj (,) Tj ( ) Tj (_func_) Tj (\)) Tj T* ET

+Q

+Q

+Q

+Q

+Q

+q

+1 0 0 1 62.69291 276.6236 cm

+q

+BT 1 0 0 1 0 14 Tm 1.533318 Tw 12 TL /F1 10 Tf 0 0 0 rg (Finally, the implementation is such that the decorated function contains a ) Tj /F5 10 Tf (copy ) Tj /F1 10 Tf (of the original function) Tj T* 0 Tw (dictionary \() Tj /F4 10 Tf (vars\(decorated_f\)) Tj ( ) Tj (is) Tj ( ) Tj (not) Tj ( ) Tj (vars\(f\)) Tj /F1 10 Tf (\):) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 123.4236 cm

+q

+q

+1 0 0 1 0 0 cm

+q

+1 0 0 1 6.6 6.6 cm

+q

+.662745 .662745 .662745 RG

+.5 w

+.960784 .960784 .862745 rg

+n -6 -6 468.6898 144 re B*

+Q

+q

+BT 1 0 0 1 0 122 Tm 12 TL /F4 10 Tf .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj /F3 10 Tf 0 .501961 0 rg (def) Tj /F4 10 Tf 0 0 0 rg ( ) Tj 0 0 1 rg (f) Tj 0 0 0 rg (\(\):) Tj ( ) Tj /F3 10 Tf 0 .501961 0 rg (pass) Tj /F4 10 Tf 0 0 0 rg ( ) Tj /F6 10 Tf .25098 .501961 .501961 rg (# the original function) Tj /F4 10 Tf 0 0 0 rg  T* .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj (f) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (attr1) Tj ( ) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ( ) Tj .729412 .129412 .129412 rg ("something") Tj 0 0 0 rg ( ) Tj /F6 10 Tf .25098 .501961 .501961 rg (# setting an attribute) Tj /F4 10 Tf 0 0 0 rg  T* .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj (f) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (attr2) Tj ( ) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ( ) Tj .729412 .129412 .129412 rg ("something else") Tj 0 0 0 rg ( ) Tj /F6 10 Tf .25098 .501961 .501961 rg (# setting another attribute) Tj /F4 10 Tf 0 0 0 rg  T*  T* .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj (traced_f) Tj ( ) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ( ) Tj (trace) Tj (\() Tj (f) Tj (\)) Tj ( ) Tj /F6 10 Tf .25098 .501961 .501961 rg (# the decorated function) Tj /F4 10 Tf 0 0 0 rg  T*  T* .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj (traced_f) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (attr1) Tj  T* .729412 .129412 .129412 rg ('something') Tj 0 0 0 rg  T* .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj (traced_f) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (attr2) Tj ( ) Tj .4 .4 .4 rg (=) Tj 0 0 0 rg ( ) Tj .729412 .129412 .129412 rg ("something different") Tj 0 0 0 rg ( ) Tj /F6 10 Tf .25098 .501961 .501961 rg (# setting attr) Tj /F4 10 Tf 0 0 0 rg  T* .4 .4 .4 rg (>) Tj (>) Tj (>) Tj 0 0 0 rg ( ) Tj (f) Tj .4 .4 .4 rg (.) Tj 0 0 0 rg (attr2) Tj ( ) Tj /F6 10 Tf .25098 .501961 .501961 rg (# the original attribute did not change) Tj /F4 10 Tf 0 0 0 rg  T* .729412 .129412 .129412 rg ('something else') Tj T* ET

+Q

+Q

+Q

+Q

+Q

+ 

+endstream

+endobj

+% 'R103': class PDFStream 

+103 0 obj

+% page stream

+<< /Length 6552 >>

+stream

+1 0 0 1 0 0 cm  BT /F1 12 Tf 14.4 TL ET

+q

+1 0 0 1 62.69291 744.0236 cm

+q

+BT 1 0 0 1 0 3.5 Tm 21 TL /F2 17.5 Tf 0 0 0 rg (Compatibility notes) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 678.0236 cm

+q

+BT 1 0 0 1 0 50 Tm 1.404985 Tw 12 TL /F1 10 Tf 0 0 0 rg (Version 3.3 is the first version of the ) Tj /F4 10 Tf (decorator ) Tj /F1 10 Tf (module to fully support Python 3, including ) Tj 0 0 .501961 rg (function) Tj T* 0 Tw .07881 Tw (annotations) Tj 0 0 0 rg (. Version 3.2 was the first version to support Python 3 via the ) Tj /F4 10 Tf (2to3 ) Tj /F1 10 Tf (conversion tool invoked in) Tj T* 0 Tw .373555 Tw (the build process by the ) Tj 0 0 .501961 rg (distribute ) Tj 0 0 0 rg (project, the Python 3-compatible replacement of easy_install. The hard) Tj T* 0 Tw .326235 Tw (work \(for me\) has been converting the documentation and the doctests. This has been possible only after) Tj T* 0 Tw (that ) Tj 0 0 .501961 rg (docutils ) Tj 0 0 0 rg (and ) Tj 0 0 .501961 rg (pygments ) Tj 0 0 0 rg (have been ported to Python 3.) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 600.0236 cm

+q

+BT 1 0 0 1 0 62 Tm .793984 Tw 12 TL /F1 10 Tf 0 0 0 rg (Version 3 of the ) Tj /F4 10 Tf (decorator ) Tj /F1 10 Tf (module do not contain any backward incompatible change, apart from the) Tj T* 0 Tw 3.63498 Tw (removal of the functions ) Tj /F4 10 Tf (get_info ) Tj /F1 10 Tf (and ) Tj /F4 10 Tf (new_wrapper) Tj /F1 10 Tf (, which have been deprecated for years.) Tj T* 0 Tw .293672 Tw /F4 10 Tf (get_info ) Tj /F1 10 Tf (has been removed since it was little used and since it had to be changed anyway to work with) Tj T* 0 Tw 2.298555 Tw (Python 3.0; ) Tj /F4 10 Tf (new_wrapper ) Tj /F1 10 Tf (has been removed since it was useless: its major use case \(converting) Tj T* 0 Tw 7.136976 Tw (signature changing decorators to signature preserving decorators\) has been subsumed by) Tj T* 0 Tw /F4 10 Tf (decorator_apply) Tj /F1 10 Tf (, whereas the other use case can be managed with the ) Tj /F4 10 Tf (FunctionMaker) Tj /F1 10 Tf (.) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 558.0236 cm

+q

+BT 1 0 0 1 0 26 Tm 1.329213 Tw 12 TL /F1 10 Tf 0 0 0 rg (There are a few changes in the documentation: I removed the ) Tj /F4 10 Tf (decorator_factory ) Tj /F1 10 Tf (example, which) Tj T* 0 Tw 2.562927 Tw (was confusing some of my users, and I removed the part about exotic signatures in the Python 3) Tj T* 0 Tw (documentation, since Python 3 does not support them.) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 492.0236 cm

+q

+BT 1 0 0 1 0 50 Tm .942651 Tw 12 TL /F1 10 Tf 0 0 0 rg (Finally ) Tj /F4 10 Tf (decorator ) Tj /F1 10 Tf (cannot be used as a class decorator and the ) Tj 0 0 .501961 rg (functionality introduced in version 2.3) Tj T* 0 Tw .241163 Tw 0 0 0 rg (has been removed. That means that in order to define decorator factories with classes you need to define) Tj T* 0 Tw 1.122126 Tw (the ) Tj /F4 10 Tf (__call__ ) Tj /F1 10 Tf (method explicitly \(no magic anymore\). All these changes should not cause any trouble,) Tj T* 0 Tw .601163 Tw (since they were all rarely used features. Should you have any trouble, you can always downgrade to the) Tj T* 0 Tw (2.3 version.) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 426.0236 cm

+q

+BT 1 0 0 1 0 50 Tm .196098 Tw 12 TL /F1 10 Tf 0 0 0 rg (The examples shown here have been tested with Python 2.6. Python 2.4 is also supported - of course the) Tj T* 0 Tw 1.649398 Tw (examples requiring the ) Tj /F4 10 Tf (with ) Tj /F1 10 Tf (statement will not work there. Python 2.5 works fine, but if you run the) Tj T* 0 Tw 1.41784 Tw (examples in the interactive interpreter you will notice a few differences since ) Tj /F4 10 Tf (getargspec ) Tj /F1 10 Tf (returns an) Tj T* 0 Tw .909982 Tw /F4 10 Tf (ArgSpec ) Tj /F1 10 Tf (namedtuple instead of a regular tuple. That means that running the file ) Tj /F4 10 Tf (documentation.py) Tj T* 0 Tw /F1 10 Tf (under Python 2.5 will print a few errors, but they are not serious.) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 393.0236 cm

+q

+BT 1 0 0 1 0 3.5 Tm 21 TL /F2 17.5 Tf 0 0 0 rg (LICENCE) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 375.0236 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 2 Tm /F1 10 Tf 12 TL (Copyright \(c\) 2005-2012, Michele Simionato All rights reserved.) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 345.0236 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 14 Tm /F1 10 Tf 12 TL 1.328555 Tw (Redistribution and use in source and binary forms, with or without modification, are permitted provided) Tj T* 0 Tw (that the following conditions are met:) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 339.0236 cm

+Q

+q

+1 0 0 1 62.69291 291.0236 cm

+0 0 0 rg

+BT /F1 10 Tf 12 TL ET

+BT 1 0 0 1 0 2 Tm  T* ET

+q

+1 0 0 1 20 0 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 38 Tm /F1 10 Tf 12 TL .830651 Tw (Redistributions of source code must retain the above copyright notice, this list of conditions and the) Tj T* 0 Tw .161647 Tw (following disclaimer. Redistributions in bytecode form must reproduce the above copyright notice, this) Tj T* 0 Tw 1.259213 Tw (list of conditions and the following disclaimer in the documentation and/or other materials provided) Tj T* 0 Tw (with the distribution.) Tj T* ET

+Q

+Q

+q

+Q

+Q

+q

+1 0 0 1 62.69291 291.0236 cm

+Q

+q

+1 0 0 1 62.69291 165.0236 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 110 Tm /F1 10 Tf 12 TL .17998 Tw (THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND) Tj T* 0 Tw 2.911797 Tw (ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED) Tj T* 0 Tw 5.165529 Tw (WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE) Tj T* 0 Tw 1.395433 Tw (DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE) Tj T* 0 Tw 5.53122 Tw (FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL) Tj T* 0 Tw 2.705976 Tw (DAMAGES \(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR) Tj T* 0 Tw 3.868976 Tw (SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION\) HOWEVER) Tj T* 0 Tw 1.326647 Tw (CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR) Tj T* 0 Tw 1.525366 Tw (TORT \(INCLUDING NEGLIGENCE OR OTHERWISE\) ARISING IN ANY WAY OUT OF THE USE OF) Tj T* 0 Tw (THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.) Tj T* ET

+Q

+Q

+q

+1 0 0 1 62.69291 135.0236 cm

+q

+0 0 0 rg

+BT 1 0 0 1 0 14 Tm /F1 10 Tf 12 TL .407132 Tw (If you use this software and you are happy with it, consider sending me a note, just to gratify my ego. On) Tj T* 0 Tw (the other hand, if you use this software and you are unhappy with it, send me a patch!) Tj T* ET

+Q

+Q

+ 

+endstream

+endobj

+% 'R104': class PDFPageLabels 

+104 0 obj

+% Document Root

+<< /Nums [ 0

+ 105 0 R

+ 1

+ 106 0 R

+ 2

+ 107 0 R

+ 3

+ 108 0 R

+ 4

+ 109 0 R

+ 5

+ 110 0 R

+ 6

+ 111 0 R

+ 7

+ 112 0 R

+ 8

+ 113 0 R

+ 9

+ 114 0 R

+ 10

+ 115 0 R

+ 11

+ 116 0 R

+ 12

+ 117 0 R

+ 13

+ 118 0 R

+ 14

+ 119 0 R ] >>

+endobj

+% 'R105': class PDFPageLabel 

+105 0 obj

+% None

+<< /S /D

+ /St 1 >>

+endobj

+% 'R106': class PDFPageLabel 

+106 0 obj

+% None

+<< /S /D

+ /St 2 >>

+endobj

+% 'R107': class PDFPageLabel 

+107 0 obj

+% None

+<< /S /D

+ /St 3 >>

+endobj

+% 'R108': class PDFPageLabel 

+108 0 obj

+% None

+<< /S /D

+ /St 4 >>

+endobj

+% 'R109': class PDFPageLabel 

+109 0 obj

+% None

+<< /S /D

+ /St 5 >>

+endobj

+% 'R110': class PDFPageLabel 

+110 0 obj

+% None

+<< /S /D

+ /St 6 >>

+endobj

+% 'R111': class PDFPageLabel 

+111 0 obj

+% None

+<< /S /D

+ /St 7 >>

+endobj

+% 'R112': class PDFPageLabel 

+112 0 obj

+% None

+<< /S /D

+ /St 8 >>

+endobj

+% 'R113': class PDFPageLabel 

+113 0 obj

+% None

+<< /S /D

+ /St 9 >>

+endobj

+% 'R114': class PDFPageLabel 

+114 0 obj

+% None

+<< /S /D

+ /St 10 >>

+endobj

+% 'R115': class PDFPageLabel 

+115 0 obj

+% None

+<< /S /D

+ /St 11 >>

+endobj

+% 'R116': class PDFPageLabel 

+116 0 obj

+% None

+<< /S /D

+ /St 12 >>

+endobj

+% 'R117': class PDFPageLabel 

+117 0 obj

+% None

+<< /S /D

+ /St 13 >>

+endobj

+% 'R118': class PDFPageLabel 

+118 0 obj

+% None

+<< /S /D

+ /St 14 >>

+endobj

+% 'R119': class PDFPageLabel 

+119 0 obj

+% None

+<< /S /D

+ /St 15 >>

+endobj

+xref

+0 120

+0000000000 65535 f

+0000000113 00000 n

+0000000271 00000 n

+0000000436 00000 n

+0000000611 00000 n

+0000000794 00000 n

+0000001046 00000 n

+0000001295 00000 n

+0000001469 00000 n

+0000001710 00000 n

+0000001951 00000 n

+0000002193 00000 n

+0000002435 00000 n

+0000002677 00000 n

+0000002919 00000 n

+0000003162 00000 n

+0000003405 00000 n

+0000003648 00000 n

+0000003891 00000 n

+0000004133 00000 n

+0000004375 00000 n

+0000004618 00000 n

+0000004861 00000 n

+0000005104 00000 n

+0000005347 00000 n

+0000005590 00000 n

+0000005833 00000 n

+0000006076 00000 n

+0000006319 00000 n

+0000006562 00000 n

+0000006805 00000 n

+0000007048 00000 n

+0000007291 00000 n

+0000007534 00000 n

+0000007777 00000 n

+0000008020 00000 n

+0000008263 00000 n

+0000008506 00000 n

+0000008749 00000 n

+0000008992 00000 n

+0000009219 00000 n

+0000009815 00000 n

+0000010010 00000 n

+0000010266 00000 n

+0000010457 00000 n

+0000010717 00000 n

+0000011027 00000 n

+0000011307 00000 n

+0000011602 00000 n

+0000011845 00000 n

+0000012146 00000 n

+0000012426 00000 n

+0000012706 00000 n

+0000012986 00000 n

+0000013267 00000 n

+0000013562 00000 n

+0000013803 00000 n

+0000014119 00000 n

+0000014387 00000 n

+0000014690 00000 n

+0000014986 00000 n

+0000015231 00000 n

+0000015548 00000 n

+0000015808 00000 n

+0000016068 00000 n

+0000016326 00000 n

+0000016578 00000 n

+0000016818 00000 n

+0000017125 00000 n

+0000017473 00000 n

+0000017633 00000 n

+0000017918 00000 n

+0000018044 00000 n

+0000018217 00000 n

+0000018404 00000 n

+0000018604 00000 n

+0000018792 00000 n

+0000018985 00000 n

+0000019180 00000 n

+0000019380 00000 n

+0000019564 00000 n

+0000019745 00000 n

+0000019936 00000 n

+0000020136 00000 n

+0000020336 00000 n

+0000020548 00000 n

+0000020748 00000 n

+0000020944 00000 n

+0000021096 00000 n

+0000021331 00000 n

+0000030688 00000 n

+0000038447 00000 n

+0000046641 00000 n

+0000054544 00000 n

+0000062233 00000 n

+0000071127 00000 n

+0000077895 00000 n

+0000086065 00000 n

+0000093096 00000 n

+0000101341 00000 n

+0000108766 00000 n

+0000116365 00000 n

+0000121398 00000 n

+0000129508 00000 n

+0000136165 00000 n

+0000136462 00000 n

+0000136541 00000 n

+0000136620 00000 n

+0000136699 00000 n

+0000136778 00000 n

+0000136857 00000 n

+0000136936 00000 n

+0000137015 00000 n

+0000137094 00000 n

+0000137173 00000 n

+0000137253 00000 n

+0000137333 00000 n

+0000137413 00000 n

+0000137493 00000 n

+0000137573 00000 n

+trailer

+<< /ID 

+ % ReportLab generated PDF document -- digest (http://www.reportlab.com) 

+ [(GkM\035\327P\251\240\010\276P *\252E\027) (GkM\035\327P\251\240\010\276P *\252E\027)] 

+

+ /Info 70 0 R

+ /Root 69 0 R

+ /Size 120 >>

+startxref

+137622

+%%EOF

diff --git a/documentation3.py b/documentation3.py
new file mode 100644
index 0000000..bd86cc6
--- /dev/null
+++ b/documentation3.py
@@ -0,0 +1,1170 @@
+r"""
+The ``decorator`` module
+=============================================================
+
+:Author: Michele Simionato
+:E-mail: michele.simionato@gmail.com
+:Version: $VERSION ($DATE)
+:Requires: Python 2.4+
+:Download page: http://pypi.python.org/pypi/decorator/$VERSION
+: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):
+
+$$memoize_uw
+
+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: http://www.python.org/doc/2.5.2/lib/module-functools.html
+
+The implementation above works in the sense that the decorator 
+can accept functions with generic signatures; unfortunately this
+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) # doctest: +IGNORE_EXCEPTION_DETAIL
+ 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:
+
+$$_memoize
+
+At this point you can define your decorator as follows:
+
+$$memoize
+
+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:
+
+$$_trace
+
+$$trace
+
+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 # doctest: +ELLIPSIS
+ <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:
+
+$$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:
+
+$$on_success
+$$on_failure
+$$on_closing
+$$Async
+
+The decorated function returns 
+the current execution thread, which can be stored and checked later, for 
+instance to verify that the thread ``.isAlive()``.
+
+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") # doctest: +ELLIPSIS
+ <Thread(write-1, started...)>
+ 
+ >>> time.sleep(.1) # wait a bit, so we are sure data2 is written after data1
+ 
+ >>> write("data2") # doctest: +ELLIPSIS
+ <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 # doctest: +SKIP
+ ... def hello():
+ ...     print('hello')
+ ...
+ >>> hello() # doctest: +SKIP
+ 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:
+
+$$identity_dec
+
+.. 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:
+
+$$decorator_apply
+
+``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.
+
+$$TailRecursive
+
+Here the decorator is implemented as a class returning callable
+objects.
+
+$$tail_recursive
+
+Here is how you apply the upgraded decorator to the good old factorial:
+
+$$factorial
+
+.. 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
+
+$$fact
+
+(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() # doctest: +ELLIPSIS
+ 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.3 is 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-2012, 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!
+"""
+from __future__ import with_statement
+import sys, threading, time, functools, inspect, itertools  
+from decorator import *
+from functools import partial
+from setup import VERSION
+
+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 
+    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
+    "Called on the result of the function"
+    return result
+
+def on_failure(exc_info): # default implementation
+    "Called if the function fails"
+    pass
+
+def on_closing(): # default implementation
+    "Called at the end, both in case of success and failure"
+    pass
+
+class Async(object):
+    """
+    A decorator converting blocking functions into asynchronous
+    functions, by using threads or processes. Examples:
+
+    async_with_threads =  Async(threading.Thread)
+    async_with_processes =  Async(multiprocessing.Process)
+    """
+
+    def __init__(self, threadfactory, 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
+
+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
+            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)
+
+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
+
+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)
+            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)
+
+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"
+        userclass = get_userclass()
+        if issubclass(userclass, user_class):
+            return func(*args, **kw)
+        else:
+            raise PermissionError(
+                '%s does not have the permission to run %s!'
+                % (userclass.__name__, func.__name__))
+    return decorator(restricted)
+
+class Action(object):
+    """
+    >>> a = Action()
+    >>> a.view() # ok
+    >>> a.insert() # err
+    Traceback (most recent call last):
+       ...
+    PermissionError: User does not have the permission to run insert!
+
+    """
+    @restricted(User)
+    def view(self):
+        pass
+
+    @restricted(PowerUser)
+    def insert(self):
+        pass
+
+    @restricted(Admin)
+    def delete(self):
+        pass
+
+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
+
+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
+    return factorial(n-1, n*acc)
+
+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
+    object, thus breaking Pylons. That must not happen again.
+
+    >>> decorator(_memoize).__name__
+    '_memoize'
+
+    Here is another bug of version 3.1.1 missing the docstring:
+
+    >>> factorial.__doc__
+    'The good old factorial'
+    """
+
+def test_kwonlydefaults():
+    """
+    >>> @trace
+    ... def f(arg, defarg=1, *args, kwonly=2): pass
+    ...
+    >>> f.__kwdefaults__ 
+    {'kwonly': 2}
+    """
+
+def test_kwonlyargs():
+    """
+    >>> @trace
+    ... def func(a, b, *args, y=2, z=3, **kwargs):
+    ...     return y, z
+    ...
+    >>> func('a', 'b', 'c', 'd', 'e', y='y', z='z', cat='dog')
+    calling func with args ('a', 'b', 'c', 'd', 'e'), {'cat': 'dog', 'y': 'y', 'z': 'z'}
+    ('y', 'z')
+    """
+
+def test_kwonly_no_args():
+    """# this was broken with decorator 3.3.3
+    >>> @trace
+    ... def f(**kw): pass
+    ...
+    >>> f()
+    calling f with args (), {}
+    """
+def test_kwonly_star_notation():
+    """
+    >>> @trace
+    ... def f(*, a=1, **kw): pass
+    ...
+    >>> inspect.getfullargspec(f)
+    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
+def hello(user):
+    """
+    >>> ba.__class__.__name__
+    'ContextManager'
+    >>> hello('michele')
+    BEFORE
+    hello michele
+    AFTER
+    """
+    print('hello %s' % user)
+
+if __name__ == '__main__':
+    import doctest; doctest.testmod()
diff --git a/index.html b/index.html
new file mode 100644
index 0000000..d7ab764
--- /dev/null
+++ b/index.html
@@ -0,0 +1,387 @@
+<?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>Decorator module</title>
+<meta name="author" content="Michele Simionato" />
+<style type="text/css">
+
+/*
+:Author: David Goodger (goodger@python.org)
+:Id: $Id: html4css1.css 7056 2011-06-17 10:50:48Z milde $
+:Copyright: This stylesheet has been placed in the public domain.
+
+Default cascading style sheet for the HTML output of Docutils.
+
+See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
+customize this style sheet.
+*/
+
+/* used to remove borders from tables and images */
+.borderless, table.borderless td, table.borderless th {
+  border: 0 }
+
+table.borderless td, table.borderless th {
+  /* Override padding for "table.docutils td" with "! important".
+     The right padding separates the table cells. */
+  padding: 0 0.5em 0 0 ! important }
+
+.first {
+  /* Override more specific margin styles with "! important". */
+  margin-top: 0 ! important }
+
+.last, .with-subtitle {
+  margin-bottom: 0 ! important }
+
+.hidden {
+  display: none }
+
+a.toc-backref {
+  text-decoration: none ;
+  color: black }
+
+blockquote.epigraph {
+  margin: 2em 5em ; }
+
+dl.docutils dd {
+  margin-bottom: 0.5em }
+
+object[type="image/svg+xml"], object[type="application/x-shockwave-flash"] {
+  overflow: hidden;
+}
+
+/* Uncomment (and remove this text!) to get bold-faced definition list terms
+dl.docutils dt {
+  font-weight: bold }
+*/
+
+div.abstract {
+  margin: 2em 5em }
+
+div.abstract p.topic-title {
+  font-weight: bold ;
+  text-align: center }
+
+div.admonition, div.attention, div.caution, div.danger, div.error,
+div.hint, div.important, div.note, div.tip, div.warning {
+  margin: 2em ;
+  border: medium outset ;
+  padding: 1em }
+
+div.admonition p.admonition-title, div.hint p.admonition-title,
+div.important p.admonition-title, div.note p.admonition-title,
+div.tip p.admonition-title {
+  font-weight: bold ;
+  font-family: sans-serif }
+
+div.attention p.admonition-title, div.caution p.admonition-title,
+div.danger p.admonition-title, div.error p.admonition-title,
+div.warning p.admonition-title {
+  color: red ;
+  font-weight: bold ;
+  font-family: sans-serif }
+
+/* Uncomment (and remove this text!) to get reduced vertical space in
+   compound paragraphs.
+div.compound .compound-first, div.compound .compound-middle {
+  margin-bottom: 0.5em }
+
+div.compound .compound-last, div.compound .compound-middle {
+  margin-top: 0.5em }
+*/
+
+div.dedication {
+  margin: 2em 5em ;
+  text-align: center ;
+  font-style: italic }
+
+div.dedication p.topic-title {
+  font-weight: bold ;
+  font-style: normal }
+
+div.figure {
+  margin-left: 2em ;
+  margin-right: 2em }
+
+div.footer, div.header {
+  clear: both;
+  font-size: smaller }
+
+div.line-block {
+  display: block ;
+  margin-top: 1em ;
+  margin-bottom: 1em }
+
+div.line-block div.line-block {
+  margin-top: 0 ;
+  margin-bottom: 0 ;
+  margin-left: 1.5em }
+
+div.sidebar {
+  margin: 0 0 0.5em 1em ;
+  border: medium outset ;
+  padding: 1em ;
+  background-color: #ffffee ;
+  width: 40% ;
+  float: right ;
+  clear: right }
+
+div.sidebar p.rubric {
+  font-family: sans-serif ;
+  font-size: medium }
+
+div.system-messages {
+  margin: 5em }
+
+div.system-messages h1 {
+  color: red }
+
+div.system-message {
+  border: medium outset ;
+  padding: 1em }
+
+div.system-message p.system-message-title {
+  color: red ;
+  font-weight: bold }
+
+div.topic {
+  margin: 2em }
+
+h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
+h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
+  margin-top: 0.4em }
+
+h1.title {
+  text-align: center }
+
+h2.subtitle {
+  text-align: center }
+
+hr.docutils {
+  width: 75% }
+
+img.align-left, .figure.align-left, object.align-left {
+  clear: left ;
+  float: left ;
+  margin-right: 1em }
+
+img.align-right, .figure.align-right, object.align-right {
+  clear: right ;
+  float: right ;
+  margin-left: 1em }
+
+img.align-center, .figure.align-center, object.align-center {
+  display: block;
+  margin-left: auto;
+  margin-right: auto;
+}
+
+.align-left {
+  text-align: left }
+
+.align-center {
+  clear: both ;
+  text-align: center }
+
+.align-right {
+  text-align: right }
+
+/* reset inner alignment in figures */
+div.align-right {
+  text-align: inherit }
+
+/* div.align-center * { */
+/*   text-align: left } */
+
+ol.simple, ul.simple {
+  margin-bottom: 1em }
+
+ol.arabic {
+  list-style: decimal }
+
+ol.loweralpha {
+  list-style: lower-alpha }
+
+ol.upperalpha {
+  list-style: upper-alpha }
+
+ol.lowerroman {
+  list-style: lower-roman }
+
+ol.upperroman {
+  list-style: upper-roman }
+
+p.attribution {
+  text-align: right ;
+  margin-left: 50% }
+
+p.caption {
+  font-style: italic }
+
+p.credits {
+  font-style: italic ;
+  font-size: smaller }
+
+p.label {
+  white-space: nowrap }
+
+p.rubric {
+  font-weight: bold ;
+  font-size: larger ;
+  color: maroon ;
+  text-align: center }
+
+p.sidebar-title {
+  font-family: sans-serif ;
+  font-weight: bold ;
+  font-size: larger }
+
+p.sidebar-subtitle {
+  font-family: sans-serif ;
+  font-weight: bold }
+
+p.topic-title {
+  font-weight: bold }
+
+pre.address {
+  margin-bottom: 0 ;
+  margin-top: 0 ;
+  font: inherit }
+
+pre.literal-block, pre.doctest-block, pre.math {
+  margin-left: 2em ;
+  margin-right: 2em }
+
+span.classifier {
+  font-family: sans-serif ;
+  font-style: oblique }
+
+span.classifier-delimiter {
+  font-family: sans-serif ;
+  font-weight: bold }
+
+span.interpreted {
+  font-family: sans-serif }
+
+span.option {
+  white-space: nowrap }
+
+span.pre {
+  white-space: pre }
+
+span.problematic {
+  color: red }
+
+span.section-subtitle {
+  /* font-size relative to parent (h1..h6 element) */
+  font-size: 80% }
+
+table.citation {
+  border-left: solid 1px gray;
+  margin-left: 1px }
+
+table.docinfo {
+  margin: 2em 4em }
+
+table.docutils {
+  margin-top: 0.5em ;
+  margin-bottom: 0.5em }
+
+table.footnote {
+  border-left: solid 1px black;
+  margin-left: 1px }
+
+table.docutils td, table.docutils th,
+table.docinfo td, table.docinfo th {
+  padding-left: 0.5em ;
+  padding-right: 0.5em ;
+  vertical-align: top }
+
+table.docutils th.field-name, table.docinfo th.docinfo-name {
+  font-weight: bold ;
+  text-align: left ;
+  white-space: nowrap ;
+  padding-left: 0 }
+
+h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
+h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
+  font-size: 100% }
+
+ul.auto-toc {
+  list-style-type: none }
+
+</style>
+</head>
+<body>
+<div class="document" id="decorator-module">
+<h1 class="title">Decorator 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&#64;gmail.com">michele.simionato&#64;gmail.com</a></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">http://pypi.python.org/pypi/decorator</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="section" id="installation">
+<h1>Installation</h1>
+<p>If you are lazy, just perform</p>
+<p>$ easy_install decorator</p>
+<p>which will install just the module on your system. Notice that
+Python 3 requires the easy_install version of the <a class="reference external" href="http://packages.python.org/distribute/">distribute</a> project.</p>
+<p>If you prefer to install the full distribution from source, including
+the documentation, download the <a class="reference external" href="http://pypi.python.org/pypi/decorator">tarball</a>, unpack it and run</p>
+<p>$ python setup.py install</p>
+<p>in the main directory, possibly as superuser.</p>
+</div>
+<div class="section" id="testing">
+<h1>Testing</h1>
+<p>For Python 2.5, 2.6, 2.7 run</p>
+<p>$ python documentation.py</p>
+<p>for Python 3.X run</p>
+<p>$ python documentation3.py</p>
+<p>You will see a few innocuous errors with Python 2.5, because some
+inner details such as the introduction of the ArgSpec namedtuple and
+Thread.__repr__ changed. You may safely ignore them.</p>
+<p>You cannot run the tests in Python 2.4, since there is a test using
+the with statement, but the decorator module is expected to work
+anyway (it has been used in production with Python 2.4 for years). My
+plan is to keep supporting all Python versions &gt;= 2.4 in the core
+module, but I will keep the documentation and the tests updated only
+for the latest Python versions in both the 2.X and 3.X branches.</p>
+<p>Finally, notice that you may run into trouble if in your system there
+is an older version of the decorator module; in such a case remove the
+old version.</p>
+</div>
+<div class="section" id="documentation">
+<h1>Documentation</h1>
+<p>There are various versions of the documentation:</p>
+<ul class="simple">
+<li><a class="reference external" href="http://micheles.googlecode.com/hg/decorator/documentation.html">HTML version (Python 2)</a></li>
+<li><a class="reference external" href="http://micheles.googlecode.com/hg/decorator/documentation.pdf">PDF version (Python 2)</a></li>
+<li><a class="reference external" href="http://micheles.googlecode.com/hg/decorator/documentation3.html">HTML version (Python 3)</a></li>
+<li><a class="reference external" href="http://micheles.googlecode.com/hg/decorator/documentation3.pdf">PDF version (Python 3)</a></li>
+</ul>
+</div>
+<div class="section" id="repository">
+<h1>Repository</h1>
+<p>The project is hosted on GoogleCode as a Mercurial repository. You
+can look at the source here:</p>
+<blockquote>
+<a class="reference external" href="http://code.google.com/p/micheles/source/browse/#hg%2Fdecorator">http://code.google.com/p/micheles/source/browse/#hg%2Fdecorator</a></blockquote>
+</div>
+</div>
+</body>
+</html>
diff --git a/setup.py b/setup.py
new file mode 100644
index 0000000..8190acd
--- /dev/null
+++ b/setup.py
@@ -0,0 +1,41 @@
+try:
+    from setuptools import setup
+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"""
+    for line in open(fname):
+        if line.startswith('__version__'):
+            return eval(line[13:])
+    raise NameError('Missing __version__ in decorator.py')
+
+VERSION = getversion(
+    os.path.join(os.path.dirname(__file__), 'src/decorator.py'))
+
+if __name__ == '__main__':
+    setup(name='decorator',
+          version=VERSION,
+          description='Better living through Python with decorators',
+          long_description=open('README.txt').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'],
+          keywords="decorators generic utility",
+          platforms=["All"],
+          classifiers=['Development Status :: 5 - Production/Stable',
+                       'Intended Audience :: Developers',
+                       'License :: OSI Approved :: BSD License',
+                       'Natural Language :: English',
+                       'Operating System :: OS Independent',
+                       'Programming Language :: Python',
+                       'Programming Language :: Python :: 3',
+                       'Topic :: Software Development :: Libraries',
+                       'Topic :: Utilities'],
+          use_2to3=True,
+          zip_safe=False)
diff --git a/src/decorator.py b/src/decorator.py
new file mode 100644
index 0000000..e1187bd
--- /dev/null
+++ b/src/decorator.py
@@ -0,0 +1,258 @@
+##########################     LICENCE     ###############################
+
+# Copyright (c) 2005-2012, 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.
+
+"""
+Decorator module, see http://pypi.python.org/pypi/decorator
+for the documentation.
+"""
+
+__version__ = '3.4.1'
+
+__all__ = ["decorator", "FunctionMaker", "contextmanager"]
+
+import sys, re, inspect
+if sys.version >= '3':
+    from inspect import getfullargspec
+    def get_init(cls):
+        return cls.__init__
+else:
+    class getfullargspec(object):
+        "A quick and dirty replacement for getfullargspec for Python 2.X"
+        def __init__(self, f):
+            self.args, self.varargs, self.varkw, self.defaults = \
+                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):
+    """
+    An object with the ability to create functions with a given signature.
+    It has attributes name, doc, module, signature, defaults, dict and
+    methods update and make.
+    """
+    def __init__(self, func=None, name=None, signature=None,
+                 defaults=None, doc=None, module=None, funcdict=None):
+        self.shortsignature = signature
+        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_' 
+            self.doc = func.__doc__
+            self.module = func.__module__
+            if inspect.isfunction(func):
+                argspec = getfullargspec(func)
+                self.annotations = getattr(func, '__annotations__', {})
+                for a in ('args', 'varargs', 'varkw', 'defaults', 'kwonlyargs',
+                          'kwonlydefaults'):
+                    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 = \
+                        inspect.formatargspec(
+                        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
+                    for a in self.kwonlyargs:
+                        allargs.append('%s=None' % a)
+                        allshortargs.append('%s=%s' % (a, a))
+                    if self.varkw:
+                        allargs.append('**' + self.varkw)
+                        allshortargs.append('**' + self.varkw)
+                    self.signature = ', '.join(allargs)
+                    self.shortsignature = ', '.join(allshortargs)
+                self.dict = func.__dict__
+        # func=None happens when decorating a caller
+        if name:
+            self.name = name
+        if signature is not None:
+            self.signature = signature
+        if defaults:
+            self.defaults = defaults
+        if doc:
+            self.doc = doc
+        if module:
+            self.module = module
+        if funcdict:
+            self.dict = funcdict
+        # check existence required attributes
+        assert hasattr(self, 'name')
+        if not hasattr(self, 'signature'):
+            raise TypeError('You are decorating a non function: %s' % func)
+
+    def update(self, func, **kw):
+        "Update the signature of func with the data in self"
+        func.__name__ = self.name
+        func.__doc__ = getattr(self, 'doc', None)
+        func.__dict__ = getattr(self, 'dict', {})
+        func.func_defaults = getattr(self, 'defaults', ())
+        func.__kwdefaults__ = getattr(self, 'kwonlydefaults', None)
+        func.__annotations__ = getattr(self, 'annotations', None)
+        callermodule = sys._getframe(3).f_globals.get('__name__', '?')
+        func.__module__ = getattr(self, 'module', callermodule)
+        func.__dict__.update(kw)
+
+    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
+        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(',')])
+        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
+        try:
+            code = compile(src, '<string>', 'single')
+            # print >> sys.stderr, 'Compiling %s' % src
+            exec code in evaldict
+        except:
+            print >> sys.stderr, 'Error in generated code:'
+            print >> sys.stderr, src
+            raise
+        func = evaldict[name]
+        if addsource:
+            attrs['__source__'] = src
+        self.update(func, **attrs)
+        return func
+
+    @classmethod
+    def create(cls, obj, body, evaldict, defaults=None,
+               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.
+        """
+        if isinstance(obj, str): # "name(signature)"
+            name, rest = obj.strip().split('(', 1)
+            signature = rest[:-1] #strip a right parens            
+            func = None
+        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)
+  
+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
+        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
+        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
+        elif inspect.isfunction(caller):
+            if caller.__name__ == '<lambda>':
+                name = '_lambda_'
+            else:
+                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
+            name = caller.__class__.__name__.lower()
+            callerfunc = caller.__call__.im_func
+            doc = caller.__call__.__doc__
+            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), 
+            'return decorator(_call_, %s)' % fun,
+            evaldict, call=caller, doc=doc, module=caller.__module__)
+
+######################### contextmanager ########################
+
+def __call__(self, func):
+    'Context manager decorator'
+    return FunctionMaker.create(
+        func, "with _self_: return _func_(%(shortsignature)s)",
+        dict(_self_=self, _func_=func), __wrapped__=func)
+
+try: # Python >= 3.2
+
+    from contextlib import _GeneratorContextManager 
+    class ContextManager(_GeneratorContextManager):
+        __call__=__call__
+
+except ImportError: # Python >= 2.5
+
+    try:
+        from contextlib import GeneratorContextManager
+    except ImportError: # Python 2.4
+        class ContextManager(object):
+            def __init__(self, g, *a, **k):
+                raise RuntimeError(
+                    'You cannot used contextmanager in Python 2.4!')
+    else:
+        class ContextManager(GeneratorContextManager):
+            def __init__(self, g, *a, **k):
+                return GeneratorContextManager.__init__(self, g(*a, **k))
+            __call__ = __call__
+
+contextmanager = decorator(ContextManager)
diff --git a/test.py b/test.py
new file mode 100644
index 0000000..460c36a
--- /dev/null
+++ b/test.py
@@ -0,0 +1,34 @@
+"""
+Some simple tests
+"""
+
+import os
+from decorator import decorator
+
+@decorator
+def identity(f, *a, **k):
+    "do nothing decorator"
+    return f(*a, **k)
+
+@identity
+def f1():
+    "f1"
+
+def getfname(func):
+    fname = os.path.basename(func.__globals__['__file__'])
+    return os.path.splitext(fname)[0] + '.py'
+
+def test0():
+    this = getfname(identity)
+    assert this == 'test.py', this
+    print(identity.__doc__)
+
+def test1():
+    this = getfname(f1)
+    assert this == 'test.py', this
+    print(f1.__doc__)
+
+if __name__ == '__main__':
+    for name, test in list(globals().items()):
+        if name.startswith('test'):
+            test()