hooke/util/callback.py

   1 # Copyright (C) 2010 W. Trevor King <wking@drexel.edu>
   2 #
   3 # This file is part of Hooke.
   4 #
   5 # Hooke is free software: you can redistribute it and/or modify it
   6 # under the terms of the GNU Lesser General Public License as
   7 # published by the Free Software Foundation, either version 3 of the
   8 # License, or (at your option) any later version.
   9 #
  10 # Hooke is distributed in the hope that it will be useful, but WITHOUT
  11 # ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  12 # or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General
  13 # Public License for more details.
  14 #
  15 # You should have received a copy of the GNU Lesser General Public
  16 # License along with Hooke.  If not, see
  17 # <http://www.gnu.org/licenses/>.
  18
  19 """Define the `@callback` decorator.
  20
  21 See :pep:`318` for an introduction to decorators.
  22 """
  23
  24 import logging
  25
  26 from .caller import caller_name
  27
  28
  29 def is_iterable(x):
  30     """Return `True` if `x` is iterable.
  31
  32     Examples
  33     --------
  34     >>> is_iterable('abc')
  35     True
  36     >>> is_iterable((1,2,3))
  37     True
  38     >>> is_iterable(5)
  39     False
  40     >>> def c():
  41     ...     for i in range(5):
  42     ...         yield i
  43     >>> is_iterable(c())
  44     True
  45     """
  46     try:
  47         iter(x)
  48         return True
  49     except TypeError:
  50         return False
  51
  52 def callback(method):
  53     """Enable callbacks on `method`.
  54
  55     This decorator should make it easy to setup callbacks in a rich
  56     GUI.  You only need to decorate potential hooks, and maintain a
  57     single dict with all the callbacks for the class.  This beats
  58     passing each of the callbacks into the class' `__init__` function
  59     individually.
  60
  61     Examples
  62     --------
  63
  64     Callbacks are called with the class instance, method instance, and
  65     returned arguments of the method they're attached to.
  66
  67     >>> def c(self, method, *args):
  68     ...     print '\\n  '.join([
  69     ...             'callback:',
  70     ...             'class:    %s' % self,
  71     ...             'method:   %s' % method,
  72     ...             'returned: %s' % args])
  73
  74     For some class, decorate any functions you're interested in
  75     attaching callbacks too.  Also, add a `_callbacks` attribute
  76     holding the callbacks, keyed by function name.
  77
  78     >>> class X (object):
  79     ...     def __init__(self):
  80     ...         self._callbacks = {'xyz': c}
  81     ...
  82     ...     @callback
  83     ...     def xyz(self):
  84     ...         "xyz's docstring"
  85     ...         print 'usual xyz business'
  86     ...         return (0, 1, 1, 2, 3, 5)
  87     ...
  88     ...     @callback
  89     ...     def abc(self):
  90     ...         "abc's docstring"
  91     ...         print 'usual abc business'
  92     ...
  93     >>> x = X()
  94
  95     Here's our callback on `xyz`.
  96
  97     >>> r = x.xyz()  # doctest: +ELLIPSIS
  98     usual xyz business
  99     callback:
 100       class:    <hooke.util.callback.X object at 0x...>
 101       method:   <bound method X.xyz of <hooke.util.callback.X object at 0x...>>
 102       returned: (0, 1, 1, 2, 3, 5)
 103     >>> r
 104     (0, 1, 1, 2, 3, 5)
 105
 106     The decorated method preserves the original docstring.
 107
 108     >>> print x.xyz.__doc__
 109     xyz's docstring
 110
 111     So far, we haven't attached a callback to `abc`.
 112
 113     >>> r = x.abc()
 114     usual abc business
 115
 116     Now we attach the callback to `abc`.
 117
 118     >>> x._callbacks['abc'] = c
 119     >>> r = x.abc()  # doctest: +ELLIPSIS
 120     usual abc business
 121     callback:
 122       class:    <hooke.util.callback.X object at 0x...>
 123       method:   <bound method X.abc of <hooke.util.callback.X object at 0x...>>
 124       returned: None
 125
 126     You can also place an iterable in the `_callbacks` dict to run an
 127     array of callbacks in series.
 128
 129     >>> def d(self, method, *args):
 130     ...     print 'callback d'
 131     >>> x._callbacks['abc'] = [d, c, d]
 132     >>> r = x.abc()  # doctest: +ELLIPSIS
 133     usual abc business
 134     callback d
 135     callback:
 136       class:    <hooke.util.callback.X object at 0x...>
 137       method:   <bound method X.abc of <hooke.util.callback.X object at 0x...>>
 138       returned: None
 139     callback d
 140     """
 141     def new_m(self, *args, **kwargs):
 142         result = method(self, *args, **kwargs)
 143         callback = self._callbacks.get(method.func_name, None)
 144         mn = getattr(self, method.func_name)
 145         log = logging.getLogger('hooke')
 146         log.debug('callback: %s (%s) calling %s' % (method.func_name, mn, callback))
 147         if is_iterable(callback):
 148             for cb in callback:
 149                 cb(self, mn, result)
 150         elif callback != None:
 151             callback(self, mn, result)
 152         return result
 153     new_m.func_name = method.func_name
 154     new_m.func_doc = method.func_doc
 155     new_m.original_method = method
 156     return new_m
 157
 158 def in_callback(self, *args, **kwargs):
 159     """Enable callbacks inside methods.
 160
 161     Sometimes :func:`callback` isn't granular enough.  This function
 162     can accomplish the same thing from inside your method, giving you
 163     control over the arguments passed and the time at which the call
 164     is made.  It draws from the same `._callbacks` dictionary.
 165
 166     Examples
 167     --------
 168
 169     Callbacks are called with the class instance, method instance, and
 170     returned arguments of the method they're attached to.
 171
 172     >>> def c(self, method, *args, **kwargs):
 173     ...     print '\\n  '.join([
 174     ...             'callback:',
 175     ...             'class:    %s' % self,
 176     ...             'method:   %s' % method,
 177     ...             'args:     %s' % (args,),
 178     ...             'kwargs:   %s' % kwargs])
 179
 180     Now place `in_callback` calls inside any interesting methods.
 181
 182     >>> class X (object):
 183     ...     def __init__(self):
 184     ...         self._callbacks = {'xyz': c}
 185     ...
 186     ...     def xyz(self):
 187     ...         "xyz's docstring"
 188     ...         print 'usual xyz business'
 189     ...         in_callback(self, 5, my_kw=17)
 190     ...         return (0, 1, 1, 2, 3, 5)
 191     ...
 192     ...     def abc(self):
 193     ...         "abc's docstring"
 194     ...         in_callback(self, p1=3.14, p2=159)
 195     ...         print 'usual abc business'
 196     ...
 197     >>> x = X()
 198
 199     Here's our callback in `xyz`.
 200
 201     >>> r = x.xyz()  # doctest: +ELLIPSIS
 202     usual xyz business
 203     callback:
 204       class:    <hooke.util.callback.X object at 0x...>
 205       method:   <bound method X.xyz of <hooke.util.callback.X object at 0x...>>
 206       args:     (5,)
 207       kwargs:   {'my_kw': 17}
 208     >>> r
 209     (0, 1, 1, 2, 3, 5)
 210
 211     Note that we haven't attached a callback to `abc`.
 212
 213     >>> r = x.abc()
 214     usual abc business
 215
 216     Now we attach the callback to `abc`.
 217
 218     >>> x._callbacks['abc'] = c
 219     >>> r = x.abc()  # doctest: +ELLIPSIS
 220     callback:
 221       class:    <hooke.util.callback.X object at 0x...>
 222       method:   <bound method X.abc of <hooke.util.callback.X object at 0x...>>
 223       args:     ()
 224       kwargs:   {'p2': 159, 'p1': 3.1400000000000001}
 225     usual abc business
 226
 227     You can also place an iterable in the `_callbacks` dict to run an
 228     array of callbacks in series.
 229
 230     >>> def d(self, method, *args, **kwargs):
 231     ...     print 'callback d'
 232     >>> x._callbacks['abc'] = [d, c, d]
 233     >>> r = x.abc()  # doctest: +ELLIPSIS
 234     callback d
 235     callback:
 236       class:    <hooke.util.callback.X object at 0x...>
 237       method:   <bound method X.abc of <hooke.util.callback.X object at 0x...>>
 238       args:     ()
 239       kwargs:   {'p2': 159, 'p1': 3.14...}
 240     callback d
 241     usual abc business
 242     """
 243     method_name = caller_name(depth=2)
 244     callback = self._callbacks.get(method_name, None)
 245     mn = getattr(self, method_name)
 246     log = logging.getLogger('hooke')
 247     log.debug('callback: %s (%s) calling %s' % (method_name, mn, callback))
 248     if is_iterable(callback):
 249         for cb in callback:
 250             cb(self, mn, *args, **kwargs)
 251     elif callback != None:
 252         callback(self, mn, *args, **kwargs)