File: README.txt

package info (click to toggle)
decoratortools 1.8-4
  • links: PTS, VCS
  • area: main
  • in suites: buster
  • size: 196 kB
  • sloc: python: 667; makefile: 4
file content (871 lines) | stat: -rw-r--r-- 32,299 bytes parent folder | download | duplicates (4)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
Class, Function, and Assignment Decorators, Metaclasses, and Related Tools
==========================================================================

Want to use decorators, but still need to support Python 2.3?  Wish you could
have class decorators, decorate arbitrary assignments, or match decorated
function signatures to their original functions?  Want to get metaclass
features without creating metaclasses?  How about synchronized methods?

"DecoratorTools" gets you all of this and more.  Some quick examples::

    # Method decorator example
    from peak.util.decorators import decorate

    class Demo1(object):
        decorate(classmethod)   # equivalent to @classmethod
        def example(cls):
            print "hello from", cls


    # Class decorator example
    from peak.util.decorators import decorate_class

    def my_class_decorator():
        def decorator(cls):
            print "decorating", cls
            return cls
        decorate_class(decorator)

    class Demo2:
        my_class_decorator()

    # "decorating <class Demo2>" will be printed when execution gets here


Installing DecoratorTools (using ``"easy_install DecoratorTools"`` or
``"setup.py install"``) gives you access to the ``peak.util.decorators``
module.  The tools in this module have been bundled for years inside of PEAK,
PyProtocols, RuleDispatch, and the zope.interface package, so they have been
widely used and tested.  (Unit tests are also included, of course.)

This standalone version is backward-compatible with the bundled versions, so you
can mix and match decorators from this package with those provided by
zope.interface, TurboGears, etc.

For complete documentation, see the `DecoratorTools manual`_.

Changes since version 1.7:

  * The ``@template_function`` decorator now supports using a return value
    instead of a docstring, in order to work with the "-OO" option to Python;
    it's highly recommended that you update your template functions to use
    a return value instead of a docstring.  (The error message has also been
    improved for the missing docstring case.)

  * Fixed metaclass collisions in ``classy`` subclasses that mix in abstract
    classes (e.g. ``collections.Sequence``) in Python 2.6+.

Changes since version 1.6:

  * Added ``synchronized`` decorator to support locking objects during method
    execution.

Changes since version 1.5:

  * Added ``classy`` base class that allows you to do the most often-needed
    metaclass behviors *without* needing an actual metaclass.

Changes since version 1.4:

  * Added ``enclosing_frame()`` function, so that complex decorators that call
    DecoratorTools functions while being called *by* DecoratorTools functions,
    will work correctly.

Changes since version 1.3:

  * Added support for debugging generated code, including the code generated
    by ``rewrap()`` and ``template_function``.

Changes since version 1.2:

  * Added ``rewrap()`` function and ``template_function`` decorator to support
    signature matching for decorated functions.  (These features are similar to
    the ones provided by Michele Simionato's "decorator" package, but do not
    require Python 2.4 and don't change the standard idioms for creating
    decorator functions.)

  * ``decorate_class()`` will no longer apply duplicate class decorator
    callbacks unless the ``allow_duplicates`` argument is true.

Changes since version 1.1:

  * Fixed a problem where instances of different struct types could equal each
    other

Changes since version 1.0:

  * The ``struct()`` decorator makes it easy to create tuple-like data
    structure types, by decorating a constructor function.

.. _DecoratorTools Manual: http://peak.telecommunity.com/DevCenter/DecoratorTools#toc

.. _toc:

.. contents:: **Table of Contents**

You may access any of the following APIs by importing them from
``peak.util.decorators``:


Simple Decorators
-----------------

decorate(\*decorators)
    Apply `decorators` to the subsequent function definition or assignment
    statement, thereby allowing you to conviently use standard decorators with
    Python 2.3 and up (i.e., no ``@`` syntax required), as shown in the
    following table of examples::

        Python 2.4+               DecoratorTools
        ------------              --------------
        @classmethod              decorate(classmethod)
        def blah(cls):            def blah(cls):
            pass                      pass

        @foo
        @bar(baz)                 decorate(foo, bar(baz))
        def spam(bing):           def spam(bing):
            """whee"""                """whee"""

decorate_class(decorator [, depth=2, frame=None])
    Set up `decorator` to be passed the containing class after its creation.

    This function is designed to be called by a decorator factory function
    executed in a class suite.  It is not used directly; instead you simply
    give your users a "magic function" to call in the body of the appropriate
    class.  Your "magic function" (i.e. a decorator factory function) then
    calls ``decorate_class`` to register the decorator to be called when the
    class is created.  Multiple decorators may be used within a single class,
    although they must all appear *after* the ``__metaclass__`` declaration, if
    there is one.

    The registered decorator will be given one argument: the newly created
    containing class.  The return value of the decorator will be used in place
    of the original class, so the decorator should return the input class if it
    does not wish to replace it.  Example::

        >>> from peak.util.decorators import decorate_class

        >>> def demo_class_decorator():
        ...     def decorator(cls):
        ...         print "decorating", cls
        ...         return cls
        ...     decorate_class(decorator)

        >>> class Demo:
        ...     demo_class_decorator()
        decorating __builtin__.Demo

    In the above example, ``demo_class_decorator()`` is the decorator factory
    function, and its inner function ``decorator`` is what gets called to
    actually decorate the class.  Notice that the factory function has to be
    called within the class body, even if it doesn't take any arguments.

    If you are just creating simple class decorators, you don't need to worry
    about the `depth` or `frame` arguments here.  However, if you are creating
    routines that are intended to be used within other class or method
    decorators, you will need to pay attention to these arguments to ensure
    that ``decorate_class()`` can find the frame where the class is being
    defined.  In general, the simplest way to do this is for the function
    that's called in the class body to get its caller's frame with
    ``sys._getframe(1)``, and then pass that frame down to whatever code will
    be calling ``decorate_class()``.  Alternately, you can specify the `depth`
    that ``decorate_class()`` should call ``sys._getframe()`` with, but this
    can be a bit trickier to compute correctly.

    Note, by the way that ``decorate_class()`` ignores duplicate callbacks::

        >>> def hello(cls):
        ...     print "decorating", cls
        ...     return cls

        >>> def do_hello():
        ...     decorate_class(hello)

        >>> class Demo:
        ...     do_hello()
        ...     do_hello()
        decorating __builtin__.Demo

    Unless the ``allow_duplicates`` argument is set to a true value::

        >>> def do_hello():
        ...     decorate_class(hello, allow_duplicates=True)

        >>> class Demo:
        ...     do_hello()
        ...     do_hello()
        decorating __builtin__.Demo
        decorating __builtin__.Demo

    
The ``synchronized`` Decorator
------------------------------

When writing multithreaded programs, it's often useful to define certain
operations as being protected by a lock on an object.  The ``synchronized``
decorator lets you do this by decorating object methods, e.g.::

    >>> from peak.util.decorators import synchronized

    >>> class TryingToBeThreadSafe(object):
    ...     synchronized()      # could be just ``@synchronized`` for 2.4+
    ...     def method1(self, arg):
    ...         print "in method 1"
    ...         self.method2()
    ...         print "back in method 1"
    ...         return arg
    ...
    ...     synchronized()      # could be just ``@synchronized`` for 2.4+
    ...     def method2(self):
    ...         print "in method 2"
    ...         return 42

    >>> TryingToBeThreadSafe().method1(99)
    in method 1
    in method 2
    back in method 1
    99

What you can't tell from this example is that a ``__lock__`` attribute is being
acquired and released around each of those calls.  Let's take a closer look::

    >>> class DemoLock:
    ...     def __init__(self, name):
    ...         self.name = name
    ...     def acquire(self):
    ...         print "acquiring", self.name
    ...     def release(self):
    ...         print "releasing", self.name

    >>> ts = TryingToBeThreadSafe()
    >>> ts.__lock__ = DemoLock("lock 1")

    >>> ts.method2()
    acquiring lock 1
    in method 2
    releasing lock 1
    42

    >>> ts.method1(27)
    acquiring lock 1
    in method 1
    acquiring lock 1
    in method 2
    releasing lock 1
    back in method 1
    releasing lock 1
    27

As you can see, if an object already has a ``__lock__`` attribute, its
``acquire()`` and ``release()`` methods are called around the execution of the
wrapped method.  (Note that this means the lock must be re-entrant: that is,
you must use a ``threading.RLock`` or something similar to it, if you
explicitly create your own ``__lock__`` attribute.)

If the object has no ``__lock__``, the decorator creates a ``threading.RLock``
and tries to add it to the object's ``__dict__``::

    >>> del ts.__lock__

    >>> ts.method1(27)
    in method 1
    in method 2
    back in method 1
    27

    >>> ts.__lock__
    <_RLock(None, 0)>

(This means, by the way, that if you want to use synchronized methods on an
object with no ``__dict__``, you must explicitly include a ``__lock__`` slot
and initialize it yourself when the object is created.)


The ``struct()`` Decorator
--------------------------

The ``struct()`` decorator creates a tuple subclass with the same name and
docstring as the decorated function.  The class will have read-only properties
with the same names as the function's arguments, and the ``repr()`` of its
instances will look like a call to the original function::

    >>> from peak.util.decorators import struct

    >>> def X(a,b,c):
    ...     """Demo type"""
    ...     return a,b,c

    >>> X = struct()(X)    # can't use decorators above functions in doctests

    >>> v = X(1,2,3)
    >>> v
    X(1, 2, 3)
    >>> v.a
    1
    >>> v.b
    2
    >>> v.c
    3

    >>> help(X) # doctest: +NORMALIZE_WHITESPACE
    Help on class X:
    <BLANKLINE>
    class X(__builtin__.tuple)
     |  Demo type
     |
     |  Method resolution order:
     |      X
     |      __builtin__.tuple
     |      __builtin__.object
     |
     |  Methods defined here:
     |
     |  __repr__(self)
     |
     |  ----------------------------------------------------------------------
     |  Static methods defined here:
     |
     |  __new__(cls, *args, **kw)
     |
     |  ----------------------------------------------------------------------
     |  ...s defined here:
     |
     |  a...
     |
     |  b...
     |
     |  c...
     |
     |  ----------------------------------------------------------------------
     |  Data and other attributes defined here:
     |
     |  __args__ = ['a', 'b', 'c']...
     |
     |  __star__ = None
     |
     |  ...

The function should return a tuple of values in the same order as its argument
names, as it will be used by the class' constructor. The function can perform
validation, add defaults, and/or do type conversions on the values.

If the function takes a ``*``, argument, it should flatten this argument
into the result tuple, e.g.::

    >>> def pair(first, *rest):
    ...     return (first,) + rest
    >>> pair = struct()(pair)

    >>> p = pair(1,2,3,4)
    >>> p
    pair(1, 2, 3, 4)
    >>> p.first
    1
    >>> p.rest
    (2, 3, 4)

Internally, ``struct`` types are actually tuples::

    >>> print tuple.__repr__(X(1,2,3))
    (<class 'X'>, 1, 2, 3)

The internal representation contains the struct's type object, so that structs
of different types will not compare equal to each other::

    >>> def Y(a,b,c):
    ...     return a,b,c
    >>> Y = struct()(Y)

    >>> X(1,2,3) == X(1,2,3)
    True
    >>> Y(1,2,3) == Y(1,2,3)
    True
    >>> X(1,2,3) == Y(1,2,3)
    False

Note, however, that this means that if you want to unpack them or otherwise
access members directly, you must include the type entry, or use a slice::

    >>> a, b, c = X(1,2,3)  # wrong
    Traceback (most recent call last):
      ...
    ValueError: too many values to unpack

    >>> t, a, b, c = X(1,2,3)       # right
    >>> a, b, c    = X(1,2,3)[1:]   # ok, if perhaps a bit unintuitive

The ``struct()`` decorator takes optional mixin classes (as positional
arguments), and dictionary entries (as keyword arguments).  The mixin
classes will be placed before ``tuple`` in the resulting class' bases, and
the dictionary entries will be placed in the class' dictionary.  These
entries take precedence over any default entries (e.g. methods, properties,
docstring, etc.) that are created by the ``struct()`` decorator::

    >>> class Mixin(object):
    ...     __slots__ = []
    ...     def foo(self): print "bar"

    >>> def demo(a, b):
    ...     return a, b

    >>> demo = struct(Mixin, reversed=property(lambda self: self[:0:-1]))(demo)
    >>> demo(1,2).foo()
    bar
    >>> demo(3,4).reversed
    (4, 3)
    >>> demo.__mro__
    (<class 'demo'>, <class ...Mixin...>, <type 'tuple'>, <type 'object'>)

Note that using mixin classes will result in your new class' instances having
a ``__dict__`` attribute, unless they are new-style classes that set
``__slots__`` to an empty list.  And if they have any slots other than
``__weakref__`` or ``__dict__``, this will cause a type error due to layout
conflicts.  In general, it's best to use mixins only for adding methods, not
data.

Finally, note that if your function returns a non-tuple result, it will be
returned from the class' constructor.  This is sometimes useful::

    >>> def And(a, b):
    ...     if a is None: return b
    ...     return a, b
    >>> And = struct()(And)

    >>> And(1,2)
    And(1, 2)

    >>> And(None, 27)
    27


Signature Matching
------------------

One of the drawbacks to using function decorators is that using ``help()`` or
other documentation tools on a decorated function usually produces unhelpful
results::

    >>> def before_and_after(message):
    ...     def decorator(func):
    ...         def decorated(*args, **kw):
    ...             print "before", message
    ...             try:
    ...                 return func(*args, **kw)
    ...             finally:
    ...                 print "after", message
    ...         return decorated
    ...     return decorator

    >>> def foo(bar, baz):
    ...     """Here's some doc"""

    >>> foo(1,2)
    >>> help(foo)               # doctest: -NORMALIZE_WHITESPACE
    Help on function foo:
    ...
    foo(bar, baz)
        Here's some doc
    ...

    >>> decorated_foo = before_and_after("hello")(foo)
    >>> decorated_foo(1,2)
    before hello
    after hello

    >>> help(decorated_foo)     # doctest: -NORMALIZE_WHITESPACE
    Help on function decorated:
    ...
    decorated(*args, **kw)
    ...

So DecoratorTools provides you with two tools to improve this situation.
First, the ``rewrap()`` function provides a simple way to match the signature,
module, and other characteristics of the original function::

    >>> from peak.util.decorators import rewrap

    >>> def before_and_after(message):
    ...     def decorator(func):
    ...         def before_and_after(*args, **kw):
    ...             print "before", message
    ...             try:
    ...                 return func(*args, **kw)
    ...             finally:
    ...                 print "after", message
    ...         return rewrap(func, before_and_after)
    ...     return decorator

    >>> decorated_foo = before_and_after("hello")(foo)
    >>> decorated_foo(1,2)
    before hello
    after hello

    >>> help(decorated_foo)     # doctest: -NORMALIZE_WHITESPACE
    Help on function foo:
    ...
    foo(bar, baz)
        Here's some doc
    ...

The ``rewrap()`` function returns you a new function object with the same
attributes (including ``__doc__``, ``__dict__``, ``__name__``, ``__module__``,
etc.) as the original function, but which calls the decorated function.

If you want the same signature but don't want the overhead of another calling
level at runtime, you can use the ``@template_function`` decorator instead.
The downside to this approach, however, is that it is more complex to use.  So,
this approach is only recommended for more performance-intensive decorators,
that you've already debugged using the ``rewrap()`` approach.  But if you need
to use it, the appropriate usage looks something like this::

    >>> from peak.util.decorators import template_function

    >>> def before_and_after2(message):
    ...     def decorator(func):
    ...         [template_function()]   # could also be @template_function in 2.4
    ...         def before_and_after2(__func, __message):
    ...             return '''
    ...                 print "before", __message
    ...                 try:
    ...                     return __func($args)
    ...                 finally:
    ...                     print "after", __message
    ...             '''
    ...         return before_and_after2(func, message)
    ...     return decorator

    >>> decorated_foo = before_and_after2("hello")(foo)
    >>> decorated_foo(1,2)
    before hello
    after hello

    >>> help(decorated_foo)     # doctest: -NORMALIZE_WHITESPACE
    Help on function foo:
    ...
    foo(bar, baz)
        Here's some doc
    ...

As you can see, the process is somewhat more complex.  Any values you wish
the generated function to be able to access (aside from builtins) must be
declared as arguments to the decorating function, and all arguments must be
named so as not to conflict with the names of any of the decorated function's
arguments.

The function template must return a static string that will be compiled into
a new function by DecoratorTools.  The returned string must either fit on one
line, or begin with a newline and have its contents indented by at least two
spaces.  The string ``$args`` may be used one or more times in the returned
string, whenever calling the original function.  The first argument of the
decorating function must always be the original function.

Note, however, that function template is only called *once*, in order to get
this string, and it's called with dummy arguments.  So the function must not
attempt to actually *use* any of its arguments, and must **always return a
static string**.  Any attempt to insert the supplied arguments into the
template will result in an error::

    >>> def broken_decorator(func):
    ...     [template_function()]
    ...     def broken_template(__func, __message):
    ...         # This doesn't work; don't do this:
    ...         return '''
    ...             print "before %(__message)s"
    ...             try:
    ...                 return __func($args)
    ...             finally:
    ...                 print "after %(__message)s"
    ...         ''' % locals()
    ...     return broken_template(func, "test")

    >>> broken_decorator(foo)
    Traceback (most recent call last):
      ...
    RuntimeError: template functions must return a static string!


Debugging Generated Code
------------------------

Both ``rewrap()`` and ``template_function`` are implemented using code
generation and runtime compile/exec operations.  Normally, such things are
frowned on in Python because Python's debugging tools don't work on generated
code.  In particular, tracebacks and pdb don't show the source code of
functions compiled from strings...   or do they?  Let's see::

    >>> def raiser(x, y="blah"):
    ...     raise TypeError(y)

    >>> def call_and_print_error(func, *args, **kw):
    ...     # This function is necessary because we want to test the error
    ...     # output, but doctest ignores a lot of exception detail, and
    ...     # won't show the non-errror output unless we do it this way
    ...     #
    ...     try:
    ...         func(*args, **kw)
    ...     except:
    ...         import sys, traceback
    ...         print ''.join(traceback.format_exception(*sys.exc_info()))

    >>> call_and_print_error(before_and_after("error")(raiser), 99)
    before error
    after error
    Traceback (most recent call last):
      File "<doctest README.txt[...]>", line ..., in call_and_print_error
        func(*args, **kw)
      File "<peak.util.decorators.rewrap wrapping raiser at 0x...>", line 3, in raiser
        def raiser(x, y): return __decorated(x, y)
      File ..., line ..., in before_and_after
        return func(*args, **kw)
      File "<doctest README.txt[...]>", line 2, in raiser
        raise TypeError(y)
    TypeError: blah

    >>> call_and_print_error(before_and_after2("error")(raiser), 99)
    before error
    after error
    Traceback (most recent call last):
      File "<doctest README.txt[...]>", line ..., in call_and_print_error
        func(*args, **kw)
      File "<before_and_after2 wrapping raiser at 0x...>", line 6, in raiser
        return __func(x, y)
      File "<doctest README.txt[...]>", line 2, in raiser
        raise TypeError(y)
    TypeError: blah

As you can see, both decorators' tracebacks include lines from the pseudo-files
"<peak.util.decorators.rewrap wrapping raiser at 0x...>" and "<before_and_after2
wrapping raiser at 0x...>" (the hex id's of the corresponding objects are
omitted here).  This is because DecoratorTools adds information to the Python
``linecache`` module, and tracebacks and pdb both use the ``linecache`` module
to get source lines.  Any tools that use ``linecache``, either directly or
indirectly, will therefore be able to display this information for generated
code.

If you'd like to be able to use this feature for your own code generation or
non-file-based code (e.g. Python source loaded from a database, etc.), you can
use the ``cache_source()`` function::

    >>> from peak.util.decorators import cache_source
    >>> from linecache import getline

    >>> demo_source = "line 1\nline 2\nline 3"

    >>> cache_source("<dummy filename 1>", demo_source)
    >>> getline("<dummy filename 1>", 3)
    'line 3'

The function requires a dummy filename, which must be globally unique.  An easy
way to ensure uniqueness is to include the ``id()`` of an object that will
exist at least as long as the source code being cached.

Also, if you have such an object, and it is weak-referenceable, you can supply
it as a third argument to ``cache_source()``, and when that object is garbage
collected the source will be removed from the ``linecache`` cache.  If you're
generating a function from the source, the function object itself is ideal for
this purpose (and it's what ``rewrap()`` and ``template_function`` do)::

    >>> def a_function(): pass  # just an object to "own" the source

    >>> cache_source("<dummy filename 2>", demo_source, a_function)
    >>> getline("<dummy filename 2>", 1)
    'line 1\n'

    >>> del a_function  # GC should now clean up the cache

    >>> getline("<dummy filename 2>", 1)
    ''  


Advanced Decorators
-------------------

The ``decorate_assignment()`` function can be used to create standalone "magic"
decorators that work in Python 2.3 and up, and which can also be used to
decorate arbitrary assignments as well as function/method definitions.  For
example, if you wanted to create an ``info(**kwargs)`` decorator that could be
used either with or without an ``@``, you could do something like::

    from peak.util.decorators import decorate_assignment

    def info(**kw):
        def callback(frame, name, func, old_locals):
            func.__dict__.update(kw)
            return func
        return decorate_assignment(callback)

    info(foo="bar")     # will set dummy.foo="bar"; @info() would also work
    def dummy(blah):
        pass

As you can see, this ``info()`` decorator can be used without an ``@`` sign
for backward compatibility with Python 2.3.  It can also be used *with* an
``@`` sign, for forward compatibility with Python 2.4 and up.

Here's a more detailed reference for the ``decorate_assignment()`` API:

decorate_assignment(callback [, depth=2, frame=None])
    Call `callback(frame, name, value, old_locals)` on next assign in `frame`.

    If a `frame` isn't supplied, a frame is obtained using
    ``sys._getframe(depth)``.  `depth` defaults to 2 so that the correct frame
    is found when ``decorate_assignment()`` is called from a decorator factory
    that was called in the target usage context.

    When `callback` is invoked, `old_locals` contains the frame's local
    variables as they were *before* the assignment, thus allowing the callback
    to access the previous value of the assigned variable, if any.

    The callback's return value will become the new value of the variable.
    `name` will contain the name of the variable being created or modified,
    and `value` will be the thing being decorated.  `frame` is the Python frame
    in which the assignment occurred.

    This function also returns a decorator function for forward-compatibility
    with Python 2.4 ``@`` syntax.  Note, however, that if the returned decorator
    is used with Python 2.4 ``@`` syntax, the callback `name` argument may be
    ``None`` or incorrect, if the `value` is not the original function (e.g.
    when multiple decorators are used).


"Meta-less" Classes
-------------------

Sometimes, you want to create a base class in a library or program that will
use the data defined in subclasses in some way, or that needs to customize
the way instances are created (*without* overriding ``__new__``).

Since Python 2.2, the standard way to accomplish these things is by creating
a custom metaclass and overriding ``__new__``, ``__init__``, or ``__call__``.

Unfortunately, however, metaclasses don't play well with others.  If two
frameworks define independent metaclasses, and a library or application mixes
classes from those frameworks, the user will have to create a *third* metaclass
to sort out the differences.  For this reason, it's best to minimize the number
of distinct metaclasses in use.

``peak.util.decorators`` therefore provides a kind of "one-size-fits-all"
metaclass, so that most of the common use cases for metaclasses can be handled
with just one metaclass.  In PEAK and elsewhere, metaclasses are most commonly
used to perform some sort of operations during class creation (metaclass
``__new__`` and ``__init__``), or instance creation (metaclass ``__call__``,
wrapping the class-level ``__new__`` and ``__init__``).

Therefore, the ``classy`` base class allows subclasses to implement one or more
of the three classmethods ``__class_new__``, ``__class_init__``, and
``__class_call__``.  The "one-size-fits-all" metaclass delegates these
operations to the class, so that you don't need a custom metaclass for every
class with these behaviors.

Thus, as long as all your custom metaclasses derive from ``classy.__class__``,
you can avoid any metaclass conflicts during multiple inheritance.

Here's an example of ``classy`` in use::

    >>> from peak.util.decorators import classy, decorate

    >>> class Demo(classy):
    ...     """Look, ma!  No metaclass!"""
    ...
    ...     def __class_new__(meta, name, bases, cdict, supr):
    ...         cls = supr()(meta, name, bases, cdict, supr)
    ...         print "My metaclass is", meta
    ...         print "And I am", cls
    ...         return cls
    ...
    ...     def __class_init__(cls, name, bases, cdict, supr):
    ...         supr()(cls, name, bases, cdict, supr)
    ...         print "Initializing", cls
    ...
    ...     decorate(classmethod)   # could be just @classmethod for 2.4+
    ...     def __class_call__(cls, *args, **kw):
    ...         print "before creating instance"
    ...         ob = super(Demo, cls).__class_call__(*args, **kw)
    ...         print "after creating instance"
    ...         return ob
    ...
    ...     def __new__(cls, *args, **kw):
    ...         print "new called with", args, kw
    ...         return super(Demo, cls).__new__(cls)
    ...
    ...     def __init__(self, *args, **kw):
    ...         print "init called with", args, kw
    My metaclass is <class 'peak.util.decorators.classy_class'>
    And I am <class 'Demo'>
    Initializing <class 'Demo'>

    >>> d = Demo(1,2,a="b")
    before creating instance
    new called with (1, 2) {'a': 'b'}
    init called with (1, 2) {'a': 'b'}
    after creating instance

Note that because ``__class_new__`` and ``__class_init__`` are called *before*
the name ``Demo`` has been bound to the class under creation, ``super()``
cannot be used in these methods.  So, they use a special calling convention,
where the last argument (``supr``) is the ``next()`` method of an iterator
that yields base class methods in mro order.  In other words, calling
``supr()(..., supr)`` invokes the previous definition of the method.  You MUST
call this exactly *once* in your methods -- no more, no less.

``__class_call__`` is different, because it is called after the class already
exists.  Thus, it can be a normal ``classmethod`` and use ``super()`` in the
standard way.

Finally, note that any given ``classy`` subclass does NOT need to define all
three methods; you can mix and match methods as needed.  Just be sure to always
use the ``supr`` argument (or ``super()`` in the case of ``__class_call__``).


Utility/Introspection Functions
-------------------------------

``peak.util.decorators`` also exposes these additional utility and
introspection functions that it uses internally:

frameinfo(frame)
    Return a ``(kind, module, locals, globals)`` tuple for a frame

    The `kind` returned is a string, with one of the following values:

    * ``"exec"``
    * ``"module"``
    * ``"class"``
    * ``"function call"``
    * ``"unknown"``

    The `module` returned is the Python module object whose globals are in
    effect for the frame, or ``None`` if the globals don't include a value for
    ``__name__``.

metaclass_is_decorator(mc)
    Return truth if the given metaclass is a class decorator metaclass inserted
    into a class by ``decorate_class()``, or by another class decorator
    implementation that follows the same protocol (such as the one in
    ``zope.interface``).

metaclass_for_bases(bases, explicit_mc=None)
    Given a sequence of 1 or more base classes and an optional explicit
    ``__metaclass__``, return the metaclass that should be used.  This
    routine basically emulates what Python does to determine the metaclass
    when creating a class, except that it does *not* take a module-level
    ``__metaclass__`` into account, only the arguments as given.  If there
    are no base classes, you should just directly use the module-level
    ``__metaclass__`` or ``types.ClassType`` if there is none.

enclosing_frame(frame=None, level=3)
    Given a frame and/or stack level, skip upward past any DecoratorTools code
    frames.  This function is used by ``decorate_class()`` and
    ``decorate_assignment()`` to ensure that any decorators calling them that
    were themselves invoked using ``decorate()``, won't end up looking at
    DecoratorTools code instead of the target.  If you have a function that
    needs to be callable via ``decorate()`` and which inspects stack frames,
    you may need to use this function to access the right frame.


Mailing List
------------

Please direct questions regarding this package to the PEAK mailing list; see
http://www.eby-sarna.com/mailman/listinfo/PEAK/ for details.