~ubuntu-branches/debian/squeeze/python-decorator/squeeze

Viewing changes to decorator.egg-info/PKG-INFO

Committer: Bazaar Package Importer
Author(s): Oleksandr Moskalenko, Sandro Tosi
Date: 2009-09-21 21:57:40 UTC
mfrom: (1.1.4 upstream) (3.1.2 squeeze)
Revision ID: james.westby@ubuntu.com-20090921215740-na96kqoqhud29tzt

* New upstream release.
* debian/docs: Removed documentation.txt.
* debian/copyright: Changed (C) to copyright and updated copyright years.
* debian/doc-base: Added a doc-base control file for registration of the
  documentation.
* debian/control:
  - Updated Standards-Version to 3.8.3.
  - Moved python-support build-deps to Build-Depends-Indep.
[Sandro Tosi]
* debian/control
  - switch Vcs-Browser field to viewsvn.

files removed:
Makefile

files modified:
CHANGES.txt *

MANIFEST.in

PKG-INFO

README.txt *

debian/changelog

debian/control

debian/copyright

debian/docs

debian/watch

decorator.egg-info/PKG-INFO

decorator.egg-info/SOURCES.txt

decorator.py *

documentation.html

documentation.pdf

documentation.py

setup.py

Show diffs side-by-side

added added

removed removed

decorator.egg-info/PKG-INFO

Metadata-Version: 1.0

Name: decorator

Version: 3.0.0

Version: 3.1.2

Summary: Better living through Python with decorators

Home-page: http://pypi.python.org/pypi/decorator

Author: Michele Simionato

Author-email: michele.simionato@gmail.com

License: BSD License

Description: <?xml version="1.0" encoding="utf-8" ?>

Description: </pre><?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">

<head>

<title>The decorator module</title>

<tr><th class="docinfo-name">Author:</th>

<td>Michele Simionato</td></tr>

<tr class="field"><th class="docinfo-name">E-mail:</th><td class="field-body"><a class="reference" href="mailto:michele.simionato@gmail.com">michele.simionato@gmail.com</a></td>

<tr class="field"><th class="docinfo-name">E-mail:</th><td class="field-body"><a class="reference external" href="mailto:michele.simionato@gmail.com">michele.simionato@gmail.com</a></td>

</tr>

<tr><th class="docinfo-name">Version:</th>

<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" href="http://pypi.python.org/pypi/decorator">http://pypi.python.org/pypi/decorator</a></td>

<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.1.1">http://pypi.python.org/pypi/decorator/3.1.1</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>

100

</tr>

102

</tr>

103

</tbody>

104

</table>

105

106

<a id="contents" name="contents">Contents</a>

105

106

Contents

107

108

<li><a class="reference" href="#introduction" id="id3" name="id3">Introduction</a></li>

109

<li><a class="reference" href="#definitions" id="id4" name="id4">Definitions</a></li>

110

<li><a class="reference" href="#statement-of-the-problem" id="id5" name="id5">Statement of the problem</a></li>

111

<li><a class="reference" href="#the-solution" id="id6" name="id6">The solution</a></li>

112

<li><a class="reference" href="#a-trace-decorator" id="id7" name="id7">A <tt class="docutils literal">trace</tt> decorator</a></li>

113

<li><a class="reference" href="#decorator-is-a-decorator" id="id8" name="id8"><tt class="docutils literal">decorator</tt> is a decorator</a></li>

114

<li><a class="reference" href="#blocking" id="id9" name="id9"><tt class="docutils literal">blocking</tt></a></li>

115

<li><a class="reference" href="#async" id="id10" name="id10"><tt class="docutils literal">async</tt></a></li>

116

<li><a class="reference" href="#the-functionmaker-class" id="id11" name="id11">The <tt class="docutils literal">FunctionMaker</tt> class</a></li>

117

<li><a class="reference" href="#getting-the-source-code" id="id12" name="id12">Getting the source code</a></li>

118

<li><a class="reference" href="#dealing-with-third-party-decorators" id="id13" name="id13">Dealing with third party decorators</a></li>

119

<li><a class="reference" href="#caveats-and-limitations" id="id14" name="id14">Caveats and limitations</a></li>

120

<li><a class="reference" href="#compatibility-notes" id="id15" name="id15">Compatibility notes</a></li>

121

<li><a class="reference" href="#licence" id="id16" name="id16">LICENCE</a></li>

108

<li><a class="reference internal" href="#introduction" id="id3">Introduction</a></li>

109

<li><a class="reference internal" href="#definitions" id="id4">Definitions</a></li>

110

<li><a class="reference internal" href="#statement-of-the-problem" id="id5">Statement of the problem</a></li>

111

<li><a class="reference internal" href="#the-solution" id="id6">The solution</a></li>

112

<li><a class="reference internal" href="#a-trace-decorator" id="id7">A <tt class="docutils literal">trace</tt> decorator</a></li>

113

<li><a class="reference internal" href="#decorator-is-a-decorator" id="id8"><tt class="docutils literal">decorator</tt> is a decorator</a></li>

114

<li><a class="reference internal" href="#blocking" id="id9"><tt class="docutils literal">blocking</tt></a></li>

115

<li><a class="reference internal" href="#async" id="id10"><tt class="docutils literal">async</tt></a></li>

116

<li><a class="reference internal" href="#the-functionmaker-class" id="id11">The <tt class="docutils literal">FunctionMaker</tt> class</a></li>

117

<li><a class="reference internal" href="#getting-the-source-code" id="id12">Getting the source code</a></li>

118

<li><a class="reference internal" href="#dealing-with-third-party-decorators" id="id13">Dealing with third party decorators</a></li>

119

<li><a class="reference internal" href="#caveats-and-limitations" id="id14">Caveats and limitations</a></li>

120

<li><a class="reference internal" href="#compatibility-notes" id="id15">Compatibility notes</a></li>

121

<li><a class="reference internal" href="#licence" id="id16">LICENCE</a></li>

122

</ul>

123

</div>

124

125

<h1><a class="toc-backref" href="#id3" id="introduction" name="introduction">Introduction</a></h1>

124

125

<h1><a class="toc-backref" href="#id3">Introduction</a></h1>

126

Python decorators are an interesting example of why syntactic sugar

127

matters. In principle, their introduction in Python 2.4 changed

128

nothing, since they do not provide any new functionality which was not

149

discussed here in the <tt class="docutils literal">documentation.py</tt> file, which contains

150

this documentation in the form of doctests.

151

</div>

152

153

<h1><a class="toc-backref" href="#id4" id="definitions" name="definitions">Definitions</a></h1>

152

153

<h1><a class="toc-backref" href="#id4">Definitions</a></h1>

154

Technically speaking, any Python object which can be called with one argument

155

can be used as a decorator. However, this definition is somewhat too large

156

to be really useful. It is more convenient to split the generic class of

175

can accept functions with any signature. A simple example will clarify

176

the issue.

177

</div>

178

179

<h1><a class="toc-backref" href="#id5" id="statement-of-the-problem" name="statement-of-the-problem">Statement of the problem</a></h1>

178

179

<h1><a class="toc-backref" href="#id5">Statement of the problem</a></h1>

180

A very common use case for decorators is the memoization of functions.

181

A <tt class="docutils literal">memoize</tt> decorator works by caching

182

the result of the function call in a dictionary, so that the next time

183

the function is called with the same input parameters the result is retrieved

184

from the cache and not recomputed. There are many implementations of

185

<tt class="docutils literal">memoize</tt> in <a class="reference" href="http://www.python.org/moin/PythonDecoratorLibrary">http://www.python.org/moin/PythonDecoratorLibrary</a>,

185

<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>,

186

but they do not preserve the signature.

187

A simple implementation for Python 2.5 could be the following (notice

188

that in general it is impossible to memoize correctly something

205

</pre></div>

206

207

</div>

208

Here we used the <a class="reference" href="http://www.python.org/doc/2.5.2/lib/module-functools.html">functools.update_wrapper</a> utility, which has

208

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

209

been added in Python 2.5 expressly to simplify the definition of decorators

210

(in older versions of Python you need to copy the function attributes

211

<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>

228

but the decorated function takes any number of arguments and

229

keyword arguments:

230

231

<div class="highlight"><pre>>>> from inspect import getargspec

231

<div class="highlight"><pre>>>> from inspect import getargspec

232

>>> print getargspec(f1)

233

([], 'args', 'kw', None)

234

</pre></div>

248

249

</div>

250

</div>

251

252

<h1><a class="toc-backref" href="#id6" id="the-solution" name="the-solution">The solution</a></h1>

251

252

<h1><a class="toc-backref" href="#id6">The solution</a></h1>

253

The solution is to provide a generic factory of generators, which

254

hides the complexity of making signature-preserving decorators

255

from the application programmer. The <tt class="docutils literal">decorator</tt> function in

256

the <tt class="docutils literal">decorator</tt> module is such a factory:

257

258

<div class="highlight"><pre>>>> from decorator import decorator

258

<div class="highlight"><pre>>>> from decorator import decorator

259

</pre></div>

260

261

</div>

316

317

</div>

318

</div>

319

320

<h1><a class="toc-backref" href="#id7" id="a-trace-decorator" name="a-trace-decorator">A <tt class="docutils literal">trace</tt> decorator</a></h1>

319

320

<h1><a class="toc-backref" href="#id7">A <tt class="docutils literal">trace</tt> decorator</a></h1>

321

As an additional example, here is how you can define a trivial

322

<tt class="docutils literal">trace</tt> decorator, which prints a message everytime the traced

323

function is called:

386

Notice that the support for exotic signatures has been deprecated

387

in Python 2.6 and removed in Python 3.0.

388

</div>

389

390

<h1><a class="toc-backref" href="#id8" id="decorator-is-a-decorator" name="decorator-is-a-decorator"><tt class="docutils literal">decorator</tt> is a decorator</a></h1>

389

390

<h1><a class="toc-backref" href="#id8"><tt class="docutils literal">decorator</tt> is a decorator</a></h1>

391

It may be annoying to write a caller function (like the <tt class="docutils literal">_trace</tt>

392

function above) and then a trivial wrapper

393

(<tt class="docutils literal">def trace(f): return decorator(_trace, f)</tt>) every time. For this reason,

409

</pre></div>

410

411

</div>

412

and now <tt class="docutils literal">trace</tt> will be a decorator. You

413

can easily check that the signature has changed:

412

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>

413

object which can be used as a decorator:

414

415

<div class="highlight"><pre>>>> print getargspec(trace)

416

(['f'], None, None, None)

415

<div class="highlight"><pre>>>> trace

416

417

</pre></div>

418

419

</div>

420

Therefore now <tt class="docutils literal">trace</tt> can be used as a decorator and

421

the following will work:

420

Here is an example of usage:

422

421

423

422

<div class="highlight"><pre>>>> @trace

424

423

... def func(): pass

428

427

</pre></div>

429

428

430

429

</div>

431

For the rest of this document, I will discuss examples of useful

432

decorators built on top of <tt class="docutils literal">decorator</tt>.

433

</div>

434

435

<h1><a class="toc-backref" href="#id9" id="blocking" name="blocking"><tt class="docutils literal">blocking</tt></a></h1>

430

If you are using an old Python version (Python 2.4) the

431

<tt class="docutils literal">decorator</tt> module provides a poor man replacement for

432

<tt class="docutils literal">functools.partial</tt>.

433

There is also an easy way to create one-parameter factories of

434

decorators, based on the following

435

<tt class="docutils literal">decorator_factory</tt> utility:

436

437

<div class="highlight"><pre>def decorator_factory(decfac): # partial is functools.partial

438

"decorator_factory(decfac) returns a one-parameter family of decorators"

439

return partial(lambda df, param: decorator(partial(df, param)), decfac)

440

</pre></div>

441

442

</div>

443

<tt class="docutils literal">decorator_factory</tt> converts a function with signature

444

<tt class="docutils literal">(param, func, *args, **kw)</tt> into a one-parameter family

445

of decorators. Suppose for instance you want to generated different

446

tracing generator, with different tracing messages.

447

Here is how to do it:

448

449

<div class="highlight"><pre>>>> @decorator_factory

450

... def trace_factory(message_template, f, *args, **kw):

451

... name = f.func_name

452

... print message_template % locals()

453

... return f(*args, **kw)

454

</pre></div>

455

456

</div>

457

458

<div class="highlight"><pre>>>> trace_factory

459

<functools.partial object at 0x...>

460

461

>>> trace = trace_factory('Calling %(name)s with args %(args)s '

462

... 'and keywords %(kw)s')

463

</pre></div>

464

465

</div>

466

In this example the parameter (<tt class="docutils literal">message_template</tt>) is

467

just a string, but in general it can be a tuple, a dictionary, or

468

a generic object, so there is no real restriction (for instance,

469

if you want to define a two-parameter family of decorators just

470

use a tuple with two arguments as parameter).

471

Here is an example of usage:

472

473

<div class="highlight"><pre>>>> @trace

474

... def func(): pass

475

476

>>> func()

477

Calling func with args () and keywords {}

478

</pre></div>

479

480

</div>

481

</div>

482

483

<h1><a class="toc-backref" href="#id9"><tt class="docutils literal">blocking</tt></a></h1>

436

484

Sometimes one has to deal with blocking resources, such as <tt class="docutils literal">stdin</tt>, and

437

485

sometimes it is best to have back a "busy" message than to block everything.

438

This behavior can be implemented with a suitable decorator:

486

This behavior can be implemented with a suitable family of decorators,

487

where the parameter is the busy message:

439

488

440

<div class="highlight"><pre>def blocking(not_avail="Not Available"):

441

def _blocking(f, *args, **kw):

489

<div class="highlight"><pre>@decorator_factory

490

def blocking(not_avail, f, *args, **kw):

442

491

if not hasattr(f, "thread"): # no thread running

443

492

def set_result(): f.result = f(*args, **kw)

444

493

f.thread = threading.Thread(None, set_result)

449

498

else: # the thread is ended, return the stored result

450

499

del f.thread

451

500

return f.result

452

return decorator(_blocking)

453

501

</pre></div>

454

502

455

503

</div>

456

(notice that without the help of <tt class="docutils literal">decorator</tt>, an additional level of

457

nesting would have been needed). This is actually an example

458

of a one-parameter family of decorators.

459

504

Functions decorated with <tt class="docutils literal">blocking</tt> will return a busy message if

460

505

the resource is unavailable, and the intended result if the resource is

461

506

available. For instance:

483

528

484

529

</div>

485

530

</div>

486

487

<h1><a class="toc-backref" href="#id10" id="async" name="async"><tt class="docutils literal">async</tt></a></h1>

531

532

<h1><a class="toc-backref" href="#id10"><tt class="docutils literal">async</tt></a></h1>

488

533

We have just seen an examples of a simple decorator factory,

489

534

implemented as a function returning a decorator.

490

535

For more complex situations, it is more

586

631

be no synchronization problems since <tt class="docutils literal">write</tt> is locked.

587

632

588

633

>>> write("data1")

589

<Thread(write-1, started)>

634

<Thread(write-1, started...)>

590

635

</pre>

591

636

592

637

>>> time.sleep(.1) # wait a bit, so we are sure data2 is written after data1

593

638

</pre>

594

639

595

640

>>> write("data2")

596

<Thread(write-2, started)>

641

<Thread(write-2, started...)>

597

642

</pre>

598

643

599

644

>>> time.sleep(2) # wait for the writers to complete

603

648

['data1', 'data2']

604

649

</pre>

605

650

</div>

606

607

<h1><a class="toc-backref" href="#id11" id="the-functionmaker-class" name="the-functionmaker-class">The <tt class="docutils literal">FunctionMaker</tt> class</a></h1>

651

652

<h1><a class="toc-backref" href="#id11">The <tt class="docutils literal">FunctionMaker</tt> class</a></h1>

608

653

You may wonder about how the functionality of the <tt class="docutils literal">decorator</tt> module

609

654

is implemented. The basic building block is

610

655

a <tt class="docutils literal">FunctionMaker</tt> class which is able to generate on the fly

611

656

functions with a given name and signature from a function template

612

657

passed as a string. Generally speaking, you should not need to

613

658

resort to <tt class="docutils literal">FunctionMaker</tt> when writing ordinary decorators, but

614

it is handy in some circumstances. We will see an example in two

615

paragraphs, when implementing a custom decorator factory

616

(<tt class="docutils literal">decorator_apply</tt>).

617

Notice that while I do not have plans

618

to change or remove the functionality provided in the

619

<tt class="docutils literal">FunctionMaker</tt> class, I do not guarantee that it will stay

620

unchanged forever. For instance, right now I am using the traditional

621

string interpolation syntax for function templates, but Python 2.6

622

and Python 3.0 provide a newer interpolation syntax and I may use

623

the new syntax in the future.

624

On the other hand, the functionality provided by

625

<tt class="docutils literal">decorator</tt> has been there from version 0.1 and it is guaranteed to

626

stay there forever.

627

<tt class="docutils literal">FunctionMaker</tt> takes the name and the signature (as a string) of a

628

function in input, or a whole function. Then, it creates a new

629

function (actually a closure) from a function template (the function

630

template must begin with <tt class="docutils literal">def</tt> with no comments before and you cannot

631

use a <tt class="docutils literal">lambda</tt>) via its

632

<tt class="docutils literal">.make</tt> method: the name and the signature of the resulting function

633

are determinated by the specified name and signature. For instance,

634

here is an example of how to restrict the signature of a function:

659

it is handy in some circumstances. You will see an example shortly, in

660

the implementation of a cool decorator utility (<tt class="docutils literal">decorator_apply</tt>).

661

<tt class="docutils literal">FunctionMaker</tt> provides a <tt class="docutils literal">.create</tt> classmethod which

662

takes as input the name, signature, and body of the function

663

we want to generate as well as the execution environment

664

were the function is generated by <tt class="docutils literal">exec</tt>. Here is an example:

635

665

636

666

<div class="highlight"><pre>>>> def f(*args, **kw): # a function with a generic signature

637

667

... print args, kw

638

668

639

>>> fun = FunctionMaker(name="f1", signature="a,b")

640

>>> f1 = fun.make('''\

641

... def %(name)s(%(signature)s):

642

... f(%(signature)s)''', dict(f=f))

643

...

669

>>> f1 = FunctionMaker.create('f1(a, b)', 'f(a, b)', dict(f=f))

644

670

>>> f1(1,2)

645

671

(1, 2) {}

646

672

</pre></div>

647

673

648

674

</div>

649

The dictionary passed in this example (<tt class="docutils literal">dict(f=f)</tt>) is the

650

execution environment: <tt class="docutils literal">FunctionMaker.make</tt> actually returns a

651

closure, and the original function <tt class="docutils literal">f</tt> is a variable in the

652

closure environment.

653

<tt class="docutils literal">FunctionMaker.make</tt> also accepts keyword arguments and such

675

It is important to notice that the function body is interpolated

676

before being executed, so be careful with the <tt class="docutils literal">%</tt> sign!

677

<tt class="docutils literal">FunctionMaker.create</tt> also accepts keyword arguments and such

654

678

arguments are attached to the resulting function. This is useful

655

679

if you want to set some function attributes, for instance the

656

680

docstring <tt class="docutils literal">__doc__</tt>.

657

681

For debugging/introspection purposes it may be useful to see

658

682

the source code of the generated function; to do that, just

659

683

pass the flag <tt class="docutils literal">addsource=True</tt> and a <tt class="docutils literal">__source__</tt> attribute will

660

be added to the decorated function:

684

be added to the generated function:

661

685

662

<div class="highlight"><pre>>>> f1 = fun.make('''\

663

... def %(name)s(%(signature)s):

664

665

...

686

<div class="highlight"><pre>>>> f1 = FunctionMaker.create(

687

... 'f1(a, b)', 'f(a, b)', dict(f=f), addsource=True)

666

688

>>> print f1.__source__

667

def f1(a,b):

668

f(a,b)

689

def f1(a, b):

690

f(a, b)

669

691

670

692

</pre></div>

671

693

672

694

</div>

695

<tt class="docutils literal">FunctionMaker.create</tt> can take as first argument a string,

696

as in the examples before, or a function. This is the most common

697

usage, since typically you want to decorate a pre-existing

698

function. A framework author may want to use directly <tt class="docutils literal">FunctionMaker.create</tt>

699

instead of <tt class="docutils literal">decorator</tt>, since it gives you direct access to the body

700

of the generated function. For instance, suppose you want to instrument

701

the <tt class="docutils literal">__init__</tt> methods of a set of classes, by preserving their

702

signature (such use case is not made up; this is done in SQAlchemy

703

and in other frameworks). When the first argument of <tt class="docutils literal">FunctionMaker.create</tt>

704

is a function, a <tt class="docutils literal">FunctionMaker</tt> object is instantiated internally,

705

with attributes <tt class="docutils literal">args</tt>, <tt class="docutils literal">varargs</tt>,

706

<tt class="docutils literal">keywords</tt> and <tt class="docutils literal">defaults</tt> which are the

707

the return values of the standard library function <tt class="docutils literal">inspect.getargspec</tt>.

708

For each argument in the <tt class="docutils literal">args</tt> (which is a list of strings containing

709

the names of the mandatory arguments) an attribute <tt class="docutils literal">arg0</tt>, <tt class="docutils literal">arg1</tt>,

710

..., <tt class="docutils literal">argN</tt> is also generated. Finally, there is a <tt class="docutils literal">signature</tt>

711

attribute, a string with the signature of the original function.

712

Notice that while I do not have plans

713

to change or remove the functionality provided in the

714

<tt class="docutils literal">FunctionMaker</tt> class, I do not guarantee that it will stay

715

unchanged forever. For instance, right now I am using the traditional

716

string interpolation syntax for function templates, but Python 2.6

717

and Python 3.0 provide a newer interpolation syntax and I may use

718

the new syntax in the future.

719

On the other hand, the functionality provided by

720

<tt class="docutils literal">decorator</tt> has been there from version 0.1 and it is guaranteed to

721

stay there forever.

673

722

</div>

674

675

<h1><a class="toc-backref" href="#id12" id="getting-the-source-code" name="getting-the-source-code">Getting the source code</a></h1>

676

Internally <tt class="docutils literal">FunctionMaker.make</tt> uses <tt class="docutils literal">exec</tt> to generate the

723

724

<h1><a class="toc-backref" href="#id12">Getting the source code</a></h1>

725

Internally <tt class="docutils literal">FunctionMaker.create</tt> uses <tt class="docutils literal">exec</tt> to generate the

677

726

decorated function. Therefore

678

727

<tt class="docutils literal">inspect.getsource</tt> will not work for decorated functions. That

679

728

means that the usual '??' trick in IPython will give you the (right on

694

743

<div class="highlight"><pre>@identity_dec

695

744

def example(): pass

696

745

697

>>> print getsource(example)

746

>>> print inspect.getsource(example)

698

747

def wrapper(*args, **kw):

699

748

return func(*args, **kw)

700

749

701

750

</pre></div>

702

751

703

752

</div>

704

(see bug report <a class="reference" href="http://bugs.python.org/issue1764286">1764286</a> for an explanation of what is happening).

753

(see bug report <a class="reference external" href="http://bugs.python.org/issue1764286">1764286</a> for an explanation of what is happening).

705

754

Unfortunately the bug is still there, even in Python 2.6 and 3.0.

706

755

There is however a workaround. The decorator module adds an

707

756

attribute <tt class="docutils literal">.undecorated</tt> to the decorated function, containing

709

758

the source code is to call <tt class="docutils literal">inspect.getsource</tt> on the

710

759

undecorated function:

711

760

712

<div class="highlight"><pre>>>> print getsource(factorial.undecorated)

761

<div class="highlight"><pre>>>> print inspect.getsource(factorial.undecorated)

713

762

@tail_recursive

714

763

def factorial(n, acc=1):

715

764

"The good old factorial"

720

769

721

770

</div>

722

771

</div>

723

724

<h1><a class="toc-backref" href="#id13" id="dealing-with-third-party-decorators" name="dealing-with-third-party-decorators">Dealing with third party decorators</a></h1>

772

773

<h1><a class="toc-backref" href="#id13">Dealing with third party decorators</a></h1>

725

774

Sometimes you find on the net some cool decorator that you would

726

775

like to include in your code. However, more often than not the cool

727

776

decorator is not signature-preserving. Therefore you may want an easy way to

730

779

<tt class="docutils literal">FunctionMaker</tt> to implement that functionality as follows:

731

780

732

781

<div class="highlight"><pre>def decorator_apply(dec, func):

733

"Decorate a function using a signature-non-preserving decorator"

734

fun = FunctionMaker(func)

735

src = '''def %(name)s(%(signature)s):

736

return decorated(%(signature)s)'''

737

return fun.make(src, dict(decorated=dec(func)), undecorated=func)

782

"""

783

Decorate a function by preserving the signature even if dec

784

is not a signature-preserving decorator.

785

"""

786

return FunctionMaker.create(

787

func, 'return decorated(%(signature)s)',

788

dict(decorated=dec(func)), undecorated=func)

738

789

</pre></div>

739

790

740

791

</div>

750

801

pretty slick decorator that converts a tail-recursive function in an iterative

751

802

function. I have shamelessly stolen the basic idea from Kay Schluehr's recipe

752

803

in the Python Cookbook,

753

<a class="reference" href="http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/496691">http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/496691</a>.

804

<a class="reference external" href="http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/496691">http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/496691</a>.

754

805

755

806

<div class="highlight"><pre>class TailRecursive(object):

756

807

"""

757

808

tail_recursive decorator based on Kay Schluehr's recipe

758

809

http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/496691

810

with improvements by me and George Sakkis.

759

811

"""

760

CONTINUE = object() # sentinel

761

812

762

813

def __init__(self, func):

763

814

self.func = func

764

815

self.firstcall = True

816

self.CONTINUE = object() # sentinel

765

817

766

818

def __call__(self, *args, **kwd):

767

try:

768

if self.firstcall: # start looping

819

CONTINUE = self.CONTINUE

820

if self.firstcall:

821

func = self.func

769

822

self.firstcall = False

823

try:

770

824

while True:

771

result = self.func(*args, **kwd)

772

if result is self.CONTINUE: # update arguments

825

result = func(*args, **kwd)

826

if result is CONTINUE: # update arguments

773

827

args, kwd = self.argskwd

774

828

else: # last call

775

break

829

return result

830

finally:

831

self.firstcall = True

776

832

else: # return the arguments of the tail call

777

833

self.argskwd = args, kwd

778

return self.CONTINUE

779

except: # reset and re-raise

780

self.firstcall = True

781

raise

782

else: # reset and exit

783

self.firstcall = True

784

return result

834

return CONTINUE

785

835

</pre></div>

786

836

787

837

</div>

825

875

making a recursive call, or returns directly the result of a recursive

826

876

call).

827

877

</div>

828

829

<h1><a class="toc-backref" href="#id14" id="caveats-and-limitations" name="caveats-and-limitations">Caveats and limitations</a></h1>

878

879

<h1><a class="toc-backref" href="#id14">Caveats and limitations</a></h1>

830

880

The first thing you should be aware of, it the fact that decorators

831

881

have a performance penalty.

832

882

The worse case is shown by the following example:

874

924

function is decorated the traceback will be longer:

875

925

876

926

<div class="highlight"><pre>>>> f()

877

calling f with args (), {}

878

927

Traceback (most recent call last):

879

File "<stdin>", line 1, in <module>

928

...

880

929

File "<string>", line 2, in f

881

File "documentation.py", line 799, in _trace

930

File "<doctest __main__[18]>", line 4, in trace

882

931

return f(*args, **kw)

883

File "<stdin>", line 3, in f

932

File "<doctest __main__[47]>", line 3, in f

933

1/0

884

934

ZeroDivisionError: integer division or modulo by zero

885

935

</pre></div>

886

936

895

945

At present, there is no clean way to avoid <tt class="docutils literal">exec</tt>. A clean solution

896

946

would require to change the CPython implementation of functions and

897

947

add an hook to make it possible to change their signature directly.

898

That could happen in future versions of Python (see PEP <a class="reference" href="http://www.python.org/dev/peps/pep-0362">362</a>) and

948

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

899

949

then the decorator module would become obsolete. However, at present,

900

even in Python 3.0 it is impossible to change the function signature

950

even in Python 3.1 it is impossible to change the function signature

901

951

directly, therefore the <tt class="docutils literal">decorator</tt> module is still useful.

902

Actually, this is one of the main reasons why I am releasing version 3.0.

952

Actually, this is one of the main reasons why I keep maintaining

953

the module and releasing new versions.

903

954

In the present implementation, decorators generated by <tt class="docutils literal">decorator</tt>

904

955

can only be used on user-defined Python functions or methods, not on generic

905

956

callable objects, nor on built-in functions, due to limitations of the

906

<tt class="docutils literal">inspect</tt> module in the standard library.

957

<tt class="docutils literal">inspect</tt> module in the standard library. Moreover, notice

958

that you can decorate a method, but only before if becomes a bound or unbound

959

method, i.e. inside the class.

960

Here is an example of valid decoration:

961

962

<div class="highlight"><pre>>>> class C(object):

963

... @trace

964

... def meth(self):

965

... pass

966

</pre></div>

967

968

</div>

969

Here is an example of invalid decoration, when the decorator in

970

called too late:

971

972

<div class="highlight"><pre>>>> class C(object):

973

... def meth(self):

974

... pass

975

...

976

>>> trace(C.meth)

977

Traceback (most recent call last):

978

...

979

TypeError: You are decorating a non function: <unbound method C.meth>

980

</pre></div>

981

982

</div>

983

The solution is to extract the inner function from the unbound method:

984

985

<div class="highlight"><pre>>>> trace(C.meth.im_func)

986

987

</pre></div>

988

989

</div>

907

990

There is a restriction on the names of the arguments: for instance,

908

991

if try to call an argument <tt class="docutils literal">_call_</tt> or <tt class="docutils literal">_func_</tt>

909

992

you will get a <tt class="docutils literal">NameError</tt>:

938

1021

939

1022

</div>

940

1023

</div>

941

942

<h1><a class="toc-backref" href="#id15" id="compatibility-notes" name="compatibility-notes">Compatibility notes</a></h1>

1024

1025

<h1><a class="toc-backref" href="#id15">Compatibility notes</a></h1>

943

1026

Version 3.0 is a complete rewrite of the original implementation.

944

1027

It is mostly compatible with the past, a part for a few differences.

945

1028

First of all, the utilites <tt class="docutils literal">get_info</tt> and <tt class="docutils literal">new_wrapper</tt>, available

966

1049

has been subsumed by <tt class="docutils literal">decorator_apply</tt>

967

1050

and the other use case can be managed with the <tt class="docutils literal">FunctionMaker</tt>.

968

1051

Finally <tt class="docutils literal">decorator</tt> cannot be used as a class decorator and the

969

<a class="reference" 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

1052

<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

970

1053

means that in order to define decorator factories with classes you

971

need to define the <tt class="docutils literal">__call__</tt> method explicitly (no magic anymore).

1054

need to define the <tt class="docutils literal">__call__</tt> method explicitly (no magic anymore).

1055

Since there is

1056

an easy way to define decorator factories by using <tt class="docutils literal">decorator_factory</tt>,

1057

there is less need to use classes to implement decorator factories.

972

1058

All these changes should not cause any trouble, since they were

973

1059

all rarely used features. Should you have any trouble, you can always

974

1060

downgrade to the 2.3 version.

976

1062

is also supported - of course the examples requiring the <tt class="docutils literal">with</tt>

977

1063

statement will not work there. Python 2.6 works fine, but if you

978

1064

run the examples here in the interactive interpreter

979

you will notice a couple of minor differences since

1065

you will notice a few differences since

980

1066

<tt class="docutils literal">getargspec</tt> returns an <tt class="docutils literal">ArgSpec</tt> namedtuple instead of a regular

981

tuple, and the string representation of a thread object returns a

982

thread identifier number. That means that running the file

1067

tuple. That means that running the file

983

1068

<tt class="docutils literal">documentation.py</tt> under Python 2.5 will a few errors, but

984

1069

they are not serious. Python 3.0 is kind of supported too.

985

1070

Simply run the script <tt class="docutils literal">2to3</tt> on the module

986

1071

<tt class="docutils literal">decorator.py</tt> and you will get a version of the code running

987

1072

with Python 3.0 (at least, I did some simple checks and it seemed

988

to work). However there is no support for <a class="reference" href="http://www.python.org/dev/peps/pep-3107/">function annotations</a> yet

1073

to work). However there is no support for <a class="reference external" href="http://www.python.org/dev/peps/pep-3107/">function annotations</a> yet

989

1074

since it seems premature at this moment (most people are

990

1075

still using Python 2.5).

991

1076

</div>

992

993

<h1><a class="toc-backref" href="#id16" id="licence" name="licence">LICENCE</a></h1>

1077

1078

<h1><a class="toc-backref" href="#id16">LICENCE</a></h1>

994

1079

Redistribution and use in source and binary forms, with or without

995

1080

modification, are permitted provided that the following conditions are

996

1081

met:

997

1082

1083

1084

1085

998

1086

Redistributions of source code must retain the above copyright

999

1087

notice, this list of conditions and the following disclaimer.

1000

1088

Redistributions in bytecode form must reproduce the above copyright

1022

1110

</div>

1023

1111

1024

1112

1025

<a class="reference" href="documentation.rst">View document source</a>.

1026

Generated on: 2008-12-14 06:10 UTC.

1027

Generated by <a class="reference" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.

1113

<a class="reference external" href="documentation.rst">View document source</a>.

1114

Generated on: 2009-08-25 12:37 UTC.

1115

Generated by <a class="reference external" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference external" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.

1028

1116

1029

1117

</div>

1030

1118

</body>

1031

1119

</html>

1032

1120

<pre>

1033

1121

Keywords: decorators generic utility

1034

1122

Platform: All

1035

1123

Classifier: Development Status :: 5 - Production/Stable

Older »