git.maemo.org Git - gonvert/blob - src/util/misc.py

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