git.maemo.org Git - ejpi/blob - src/libraries/recipes/misc.py

   1 #!/usr/bin/env python
   2
   3 from __future__ import with_statement
   4
   5 import sys
   6 import cPickle
   7
   8 import functools
   9 import itertools
  10 import contextlib
  11 import inspect
  12
  13 import optparse
  14 import traceback
  15 import warnings
  16 import string
  17
  18
  19 def printfmt(template):
  20         """
  21         This hides having to create the Template object and call substitute/safe_substitute on it. For example:
  22
  23         >>> num = 10
  24         >>> word = "spam"
  25         >>> printfmt("I would like to order $num units of $word, please") #doctest: +SKIP
  26         I would like to order 10 units of spam, please
  27         """
  28         frame = inspect.stack()[-1][0]
  29         try:
  30                 print string.Template(template).safe_substitute(frame.f_locals)
  31         finally:
  32                 del frame
  33
  34
  35 def is_special(name):
  36         return name.startswith("__") and name.endswith("__")
  37
  38
  39 def is_private(name):
  40         return name.startswith("_") and not is_special(name)
  41
  42
  43 def privatize(clsName, attributeName):
  44         """
  45         At runtime, make an attributeName private
  46
  47         Example:
  48         >>> class Test(object):
  49         ...     pass
  50         ...
  51         >>> try:
  52         ...     dir(Test).index("_Test__me")
  53         ...     print dir(Test)
  54         ... except:
  55         ...     print "Not Found"
  56         Not Found
  57         >>> setattr(Test, privatize(Test.__name__, "me"), "Hello World")
  58         >>> try:
  59         ...     dir(Test).index("_Test__me")
  60         ...     print "Found"
  61         ... except:
  62         ...     print dir(Test)
  63         0
  64         Found
  65         >>> print getattr(Test, obfuscate(Test.__name__, "__me"))
  66         Hello World
  67         >>>
  68         >>> is_private(privatize(Test.__name__, "me"))
  69         True
  70         >>> is_special(privatize(Test.__name__, "me"))
  71         False
  72         """
  73         return "".join(["_", clsName, "__", attributeName])
  74
  75
  76 def obfuscate(clsName, attributeName):
  77         """
  78         At runtime, turn a private name into the obfuscated form
  79
  80         Example:
  81         >>> class Test(object):
  82         ...     __me = "Hello World"
  83         ...
  84         >>> try:
  85         ...     dir(Test).index("_Test__me")
  86         ...     print "Found"
  87         ... except:
  88         ...     print dir(Test)
  89         0
  90         Found
  91         >>> print getattr(Test, obfuscate(Test.__name__, "__me"))
  92         Hello World
  93         >>> is_private(obfuscate(Test.__name__, "__me"))
  94         True
  95         >>> is_special(obfuscate(Test.__name__, "__me"))
  96         False
  97         """
  98         return "".join(["_", clsName, attributeName])
  99
 100
 101 class PAOptionParser(optparse.OptionParser, object):
 102         """
 103         >>> if __name__ == '__main__':
 104         ...     #parser = PAOptionParser("My usage str")
 105         ...     parser = PAOptionParser()
 106         ...     parser.add_posarg("Foo", help="Foo usage")
 107         ...     parser.add_posarg("Bar", dest="bar_dest")
 108         ...     parser.add_posarg("Language", dest='tr_type', type="choice", choices=("Python", "Other"))
 109         ...     parser.add_option('--stocksym', dest='symbol')
 110         ...     values, args = parser.parse_args()
 111         ...     print values, args
 112         ...
 113
 114         python mycp.py  -h
 115         python mycp.py
 116         python mycp.py  foo
 117         python mycp.py  foo bar
 118
 119         python mycp.py foo bar lava
 120         Usage: pa.py <Foo> <Bar> <Language> [options]
 121
 122         Positional Arguments:
 123         Foo: Foo usage
 124         Bar:
 125         Language:
 126
 127         pa.py: error: option --Language: invalid choice: 'lava' (choose from 'Python', 'Other'
 128         """
 129
 130         def __init__(self, *args, **kw):
 131                 self.posargs = []
 132                 super(PAOptionParser, self).__init__(*args, **kw)
 133
 134         def add_posarg(self, *args, **kw):
 135                 pa_help = kw.get("help", "")
 136                 kw["help"] = optparse.SUPPRESS_HELP
 137                 o = self.add_option("--%s" % args[0], *args[1:], **kw)
 138                 self.posargs.append((args[0], pa_help))
 139
 140         def get_usage(self, *args, **kwargs):
 141                 params = (' '.join(["<%s>" % arg[0] for arg in self.posargs]), '\n '.join(["%s: %s" % (arg) for arg in self.posargs]))
 142                 self.usage = "%%prog %s [options]\n\nPositional Arguments:\n %s" % params
 143                 return super(PAOptionParser, self).get_usage(*args, **kwargs)
 144
 145         def parse_args(self, *args, **kwargs):
 146                 args = sys.argv[1:]
 147                 args0 = []
 148                 for p, v in zip(self.posargs, args):
 149                         args0.append("--%s" % p[0])
 150                         args0.append(v)
 151                 args = args0 + args
 152                 options, args = super(PAOptionParser, self).parse_args(args, **kwargs)
 153                 if len(args) < len(self.posargs):
 154                         msg = 'Missing value(s) for "%s"\n' % ", ".join([arg[0] for arg in self.posargs][len(args):])
 155                         self.error(msg)
 156                 return options, args
 157
 158
 159 def explicitly(name, stackadd=0):
 160         """
 161         This is an alias for adding to '__all__'.  Less error-prone than using
 162         __all__ itself, since setting __all__ directly is prone to stomping on
 163         things implicitly exported via L{alias}.
 164
 165         @note Taken from PyExport (which could turn out pretty cool):
 166         @li @a http://codebrowse.launchpad.net/~glyph/
 167         @li @a http://glyf.livejournal.com/74356.html
 168         """
 169         packageVars = sys._getframe(1+stackadd).f_locals
 170         globalAll = packageVars.setdefault('__all__', [])
 171         globalAll.append(name)
 172
 173
 174 def public(thunk):
 175         """
 176         This is a decorator, for convenience.  Rather than typing the name of your
 177         function twice, you can decorate a function with this.
 178
 179         To be real, @public would need to work on methods as well, which gets into
 180         supporting types...
 181
 182         @note Taken from PyExport (which could turn out pretty cool):
 183         @li @a http://codebrowse.launchpad.net/~glyph/
 184         @li @a http://glyf.livejournal.com/74356.html
 185         """
 186         explicitly(thunk.__name__, 1)
 187         return thunk
 188
 189
 190 def _append_docstring(obj, message):
 191         if obj.__doc__ is None:
 192                 obj.__doc__ = message
 193         else:
 194                 obj.__doc__ += message
 195
 196
 197 def validate_decorator(decorator):
 198
 199         def simple(x):
 200                 return x
 201
 202         f = simple
 203         f.__name__ = "name"
 204         f.__doc__ = "doc"
 205         f.__dict__["member"] = True
 206
 207         g = decorator(f)
 208
 209         if f.__name__ != g.__name__:
 210                 print f.__name__, "!=", g.__name__
 211
 212         if g.__doc__ is None:
 213                 print decorator.__name__, "has no doc string"
 214         elif not g.__doc__.startswith(f.__doc__):
 215                 print g.__doc__, "didn't start with", f.__doc__
 216
 217         if not ("member" in g.__dict__ and g.__dict__["member"]):
 218                 print "'member' not in ", g.__dict__
 219
 220
 221 def deprecated(func):
 222         """
 223         This is a decorator which can be used to mark functions
 224         as deprecated. It will result in a warning being emitted
 225         when the function is used.
 226
 227         >>> validate_decorator(deprecated)
 228         """
 229
 230         @functools.wraps(func)
 231         def newFunc(*args, **kwargs):
 232                 warnings.warn("Call to deprecated function %s." % func.__name__, category=DeprecationWarning)
 233                 return func(*args, **kwargs)
 234         _append_docstring(newFunc, "\n@deprecated")
 235         return newFunc
 236
 237
 238 def enabled(func):
 239         """
 240         This decorator doesn't add any behavior
 241
 242         >>> validate_decorator(enabled)
 243         """
 244         return func
 245
 246
 247 def disabled(func):
 248         """
 249         This decorator disables the provided function, and does nothing
 250
 251         >>> validate_decorator(disabled)
 252         """
 253
 254         @functools.wraps(func)
 255         def emptyFunc(*args, **kargs):
 256                 pass
 257         _append_docstring(emptyFunc, "\n@note Temporarily Disabled")
 258         return emptyFunc
 259
 260
 261 def metadata(document=True, **kwds):
 262         """
 263         >>> validate_decorator(metadata(author="Ed"))
 264         """
 265
 266         def decorate(func):
 267                 for k, v in kwds.iteritems():
 268                         setattr(func, k, v)
 269                         if document:
 270                                 _append_docstring(func, "\n@"+k+" "+v)
 271                 return func
 272         return decorate
 273
 274
 275 def prop(func):
 276         """Function decorator for defining property attributes
 277
 278         The decorated function is expected to return a dictionary
 279         containing one or more of the following pairs:
 280                 fget - function for getting attribute value
 281                 fset - function for setting attribute value
 282                 fdel - function for deleting attribute
 283         This can be conveniently constructed by the locals() builtin
 284         function; see:
 285         http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/205183
 286         @author http://kbyanc.blogspot.com/2007/06/python-property-attribute-tricks.html
 287
 288         Example:
 289         >>> #Due to transformation from function to property, does not need to be validated
 290         >>> #validate_decorator(prop)
 291         >>> class MyExampleClass(object):
 292         ...     @prop
 293         ...     def foo():
 294         ...             "The foo property attribute's doc-string"
 295         ...             def fget(self):
 296         ...                     print "GET"
 297         ...                     return self._foo
 298         ...             def fset(self, value):
 299         ...                     print "SET"
 300         ...                     self._foo = value
 301         ...             return locals()
 302         ...
 303         >>> me = MyExampleClass()
 304         >>> me.foo = 10
 305         SET
 306         >>> print me.foo
 307         GET
 308         10
 309         """
 310         return property(doc=func.__doc__, **func())
 311
 312
 313 def print_handler(e):
 314         """
 315         @see ExpHandler
 316         """
 317         print "%s: %s" % (type(e).__name__, e)
 318
 319
 320 def print_ignore(e):
 321         """
 322         @see ExpHandler
 323         """
 324         print 'Ignoring %s exception: %s' % (type(e).__name__, e)
 325
 326
 327 def print_traceback(e):
 328         """
 329         @see ExpHandler
 330         """
 331         #print sys.exc_info()
 332         traceback.print_exc(file=sys.stdout)
 333
 334
 335 def ExpHandler(handler = print_handler, *exceptions):
 336         """
 337         An exception handling idiom using decorators
 338         Examples
 339         Specify exceptions in order, first one is handled first
 340         last one last.
 341
 342         >>> validate_decorator(ExpHandler())
 343         >>> @ExpHandler(print_ignore, ZeroDivisionError)
 344         ... @ExpHandler(None, AttributeError, ValueError)
 345         ... def f1():
 346         ...     1/0
 347         >>> @ExpHandler(print_traceback, ZeroDivisionError)
 348         ... def f2():
 349         ...     1/0
 350         >>> @ExpHandler()
 351         ... def f3(*pargs):
 352         ...     l = pargs
 353         ...     return l[10]
 354         >>> @ExpHandler(print_traceback, ZeroDivisionError)
 355         ... def f4():
 356         ...     return 1
 357         >>>
 358         >>>
 359         >>> f1()
 360         Ignoring ZeroDivisionError exception: integer division or modulo by zero
 361         >>> f2() # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE
 362         Traceback (most recent call last):
 363         ...
 364         ZeroDivisionError: integer division or modulo by zero
 365         >>> f3()
 366         IndexError: tuple index out of range
 367         >>> f4()
 368         1
 369         """
 370
 371         def wrapper(f):
 372                 localExceptions = exceptions
 373                 if not localExceptions:
 374                         localExceptions = [Exception]
 375                 t = [(ex, handler) for ex in localExceptions]
 376                 t.reverse()
 377
 378                 def newfunc(t, *args, **kwargs):
 379                         ex, handler = t[0]
 380                         try:
 381                                 if len(t) == 1:
 382                                         return f(*args, **kwargs)
 383                                 else:
 384                                         #Recurse for embedded try/excepts
 385                                         dec_func = functools.partial(newfunc, t[1:])
 386                                         dec_func = functools.update_wrapper(dec_func, f)
 387                                         return dec_func(*args, **kwargs)
 388                         except ex, e:
 389                                 return handler(e)
 390
 391                 dec_func = functools.partial(newfunc, t)
 392                 dec_func = functools.update_wrapper(dec_func, f)
 393                 return dec_func
 394         return wrapper
 395
 396
 397 class bindclass(object):
 398         """
 399         >>> validate_decorator(bindclass)
 400         >>> class Foo(BoundObject):
 401         ...      @bindclass
 402         ...      def foo(this_class, self):
 403         ...              return this_class, self
 404         ...
 405         >>> class Bar(Foo):
 406         ...      @bindclass
 407         ...      def bar(this_class, self):
 408         ...              return this_class, self
 409         ...
 410         >>> f = Foo()
 411         >>> b = Bar()
 412         >>>
 413         >>> f.foo() # doctest: +ELLIPSIS
 414         (<class '...Foo'>, <...Foo object at ...>)
 415         >>> b.foo() # doctest: +ELLIPSIS
 416         (<class '...Foo'>, <...Bar object at ...>)
 417         >>> b.bar() # doctest: +ELLIPSIS
 418         (<class '...Bar'>, <...Bar object at ...>)
 419         """
 420
 421         def __init__(self, f):
 422                 self.f = f
 423                 self.__name__ = f.__name__
 424                 self.__doc__ = f.__doc__
 425                 self.__dict__.update(f.__dict__)
 426                 self.m = None
 427
 428         def bind(self, cls, attr):
 429
 430                 def bound_m(*args, **kwargs):
 431                         return self.f(cls, *args, **kwargs)
 432                 bound_m.__name__ = attr
 433                 self.m = bound_m
 434
 435         def __get__(self, obj, objtype=None):
 436                 return self.m.__get__(obj, objtype)
 437
 438
 439 class ClassBindingSupport(type):
 440         "@see bindclass"
 441
 442         def __init__(mcs, name, bases, attrs):
 443                 type.__init__(mcs, name, bases, attrs)
 444                 for attr, val in attrs.iteritems():
 445                         if isinstance(val, bindclass):
 446                                 val.bind(mcs, attr)
 447
 448
 449 class BoundObject(object):
 450         "@see bindclass"
 451         __metaclass__ = ClassBindingSupport
 452
 453
 454 def bindfunction(f):
 455         """
 456         >>> validate_decorator(bindfunction)
 457         >>> @bindfunction
 458         ... def factorial(thisfunction, n):
 459         ...      # Within this function the name 'thisfunction' refers to the factorial
 460         ...      # function(with only one argument), even after 'factorial' is bound
 461         ...      # to another object
 462         ...      if n > 0:
 463         ...              return n * thisfunction(n - 1)
 464         ...      else:
 465         ...              return 1
 466         ...
 467         >>> factorial(3)
 468         6
 469         """
 470
 471         @functools.wraps(f)
 472         def bound_f(*args, **kwargs):
 473                 return f(bound_f, *args, **kwargs)
 474         return bound_f
 475
 476
 477 class Memoize(object):
 478         """
 479         Memoize(fn) - an instance which acts like fn but memoizes its arguments
 480         Will only work on functions with non-mutable arguments
 481         @note Source: http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/52201
 482
 483         >>> validate_decorator(Memoize)
 484         """
 485
 486         def __init__(self, fn):
 487                 self.fn = fn
 488                 self.__name__ = fn.__name__
 489                 self.__doc__ = fn.__doc__
 490                 self.__dict__.update(fn.__dict__)
 491                 self.memo = {}
 492
 493         def __call__(self, *args):
 494                 if args not in self.memo:
 495                         self.memo[args] = self.fn(*args)
 496                 return self.memo[args]
 497
 498
 499 class MemoizeMutable(object):
 500         """Memoize(fn) - an instance which acts like fn but memoizes its arguments
 501         Will work on functions with mutable arguments(slower than Memoize)
 502         @note Source: http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/52201
 503
 504         >>> validate_decorator(MemoizeMutable)
 505         """
 506
 507         def __init__(self, fn):
 508                 self.fn = fn
 509                 self.__name__ = fn.__name__
 510                 self.__doc__ = fn.__doc__
 511                 self.__dict__.update(fn.__dict__)
 512                 self.memo = {}
 513
 514         def __call__(self, *args, **kw):
 515                 text = cPickle.dumps((args, kw))
 516                 if text not in self.memo:
 517                         self.memo[text] = self.fn(*args, **kw)
 518                 return self.memo[text]
 519
 520
 521 callTraceIndentationLevel = 0
 522
 523
 524 def call_trace(f):
 525         """
 526         Synchronization decorator.
 527
 528         >>> validate_decorator(call_trace)
 529         >>> @call_trace
 530         ... def a(a, b, c):
 531         ...     pass
 532         >>> a(1, 2, c=3)
 533         Entering a((1, 2), {'c': 3})
 534         Exiting a((1, 2), {'c': 3})
 535         """
 536
 537         @functools.wraps(f)
 538         def verboseTrace(*args, **kw):
 539                 global callTraceIndentationLevel
 540
 541                 print "%sEntering %s(%s, %s)" % ("\t"*callTraceIndentationLevel, f.__name__, args, kw)
 542                 callTraceIndentationLevel += 1
 543                 try:
 544                         result = f(*args, **kw)
 545                 except:
 546                         callTraceIndentationLevel -= 1
 547                         print "%sException %s(%s, %s)" % ("\t"*callTraceIndentationLevel, f.__name__, args, kw)
 548                         raise
 549                 callTraceIndentationLevel -= 1
 550                 print "%sExiting %s(%s, %s)" % ("\t"*callTraceIndentationLevel, f.__name__, args, kw)
 551                 return result
 552
 553         @functools.wraps(f)
 554         def smallTrace(*args, **kw):
 555                 global callTraceIndentationLevel
 556
 557                 print "%sEntering %s" % ("\t"*callTraceIndentationLevel, f.__name__)
 558                 callTraceIndentationLevel += 1
 559                 try:
 560                         result = f(*args, **kw)
 561                 except:
 562                         callTraceIndentationLevel -= 1
 563                         print "%sException %s" % ("\t"*callTraceIndentationLevel, f.__name__)
 564                         raise
 565                 callTraceIndentationLevel -= 1
 566                 print "%sExiting %s" % ("\t"*callTraceIndentationLevel, f.__name__)
 567                 return result
 568
 569         #return smallTrace
 570         return verboseTrace
 571
 572
 573 @contextlib.contextmanager
 574 def lexical_scope(*args):
 575         """
 576         @note Source: http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/520586
 577         Example:
 578         >>> b = 0
 579         >>> with lexical_scope(1) as (a):
 580         ...     print a
 581         ...
 582         1
 583         >>> with lexical_scope(1,2,3) as (a,b,c):
 584         ...     print a,b,c
 585         ...
 586         1 2 3
 587         >>> with lexical_scope():
 588         ...     d = 10
 589         ...     def foo():
 590         ...             pass
 591         ...
 592         >>> print b
 593         2
 594         """
 595
 596         frame = inspect.currentframe().f_back.f_back
 597         saved = frame.f_locals.keys()
 598         try:
 599                 if not args:
 600                         yield
 601                 elif len(args) == 1:
 602                         yield args[0]
 603                 else:
 604                         yield args
 605         finally:
 606                 f_locals = frame.f_locals
 607                 for key in (x for x in f_locals.keys() if x not in saved):
 608                         del f_locals[key]
 609                 del frame