1 # License for code in this file that was taken from Python 2.5.

     2 

     3 # PYTHON SOFTWARE FOUNDATION LICENSE VERSION 2

     4 # --------------------------------------------

     5 #

     6 # 1. This LICENSE AGREEMENT is between the Python Software Foundation

     7 # ("PSF"), and the Individual or Organization ("Licensee") accessing and

     8 # otherwise using this software ("Python") in source or binary form and

     9 # its associated documentation.

    10 #

    11 # 2. Subject to the terms and conditions of this License Agreement, PSF

    12 # hereby grants Licensee a nonexclusive, royalty-free, world-wide

    13 # license to reproduce, analyze, test, perform and/or display publicly,

    14 # prepare derivative works, distribute, and otherwise use Python

    15 # alone or in any derivative version, provided, however, that PSF's

    16 # License Agreement and PSF's notice of copyright, i.e., "Copyright (c)

    17 # 2001, 2002, 2003, 2004, 2005, 2006, 2007 Python Software Foundation;

    18 # All Rights Reserved" are retained in Python alone or in any derivative

    19 # version prepared by Licensee.

    20 #

    21 # 3. In the event Licensee prepares a derivative work that is based on

    22 # or incorporates Python or any part thereof, and wants to make

    23 # the derivative work available to others as provided herein, then

    24 # Licensee hereby agrees to include in any such work a brief summary of

    25 # the changes made to Python.

    26 #

    27 # 4. PSF is making Python available to Licensee on an "AS IS"

    28 # basis.  PSF MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR

    29 # IMPLIED.  BY WAY OF EXAMPLE, BUT NOT LIMITATION, PSF MAKES NO AND

    30 # DISCLAIMS ANY REPRESENTATION OR WARRANTY OF MERCHANTABILITY OR FITNESS

    31 # FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF PYTHON WILL NOT

    32 # INFRINGE ANY THIRD PARTY RIGHTS.

    33 #

    34 # 5. PSF SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF PYTHON

    35 # FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS AS

    36 # A RESULT OF MODIFYING, DISTRIBUTING, OR OTHERWISE USING PYTHON,

    37 # OR ANY DERIVATIVE THEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF.

    38 #

    39 # 6. This License Agreement will automatically terminate upon a material

    40 # breach of its terms and conditions.

    41 #

    42 # 7. Nothing in this License Agreement shall be deemed to create any

    43 # relationship of agency, partnership, or joint venture between PSF and

    44 # Licensee.  This License Agreement does not grant permission to use PSF

    45 # trademarks or trade name in a trademark sense to endorse or promote

    46 # products or services of Licensee, or any third party.

    47 #

    48 # 8. By copying, installing or otherwise using Python, Licensee

    49 # agrees to be bound by the terms and conditions of this License

    50 # Agreement.

    51 

    52 

    53 def curry(_curried_func, *args, **kwargs):

    54     def _curried(*moreargs, **morekwargs):

    55         return _curried_func(*(args+moreargs), **dict(kwargs, **morekwargs))

    56     return _curried

    57 

    58 ### Begin from Python 2.5 functools.py ########################################

    59 

    60 # Summary of changes made to the Python 2.5 code below:

    61 #   * swapped ``partial`` for ``curry`` to maintain backwards-compatibility

    62 #     in Django.

    63 #   * Wrapped the ``setattr`` call in ``update_wrapper`` with a try-except

    64 #     block to make it compatible with Python 2.3, which doesn't allow

    65 #     assigning to ``__name__``.

    66 

    67 # Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007 Python Software Foundation.

    68 # All Rights Reserved.

    69 

    70 ###############################################################################

    71 

    72 # update_wrapper() and wraps() are tools to help write

    73 # wrapper functions that can handle naive introspection

    74 

    75 WRAPPER_ASSIGNMENTS = ('__module__', '__name__', '__doc__')

    76 WRAPPER_UPDATES = ('__dict__',)

    77 def update_wrapper(wrapper,

    78                    wrapped,

    79                    assigned = WRAPPER_ASSIGNMENTS,

    80                    updated = WRAPPER_UPDATES):

    81     """Update a wrapper function to look like the wrapped function

    82 

    83        wrapper is the function to be updated

    84        wrapped is the original function

    85        assigned is a tuple naming the attributes assigned directly

    86        from the wrapped function to the wrapper function (defaults to

    87        functools.WRAPPER_ASSIGNMENTS)

    88        updated is a tuple naming the attributes off the wrapper that

    89        are updated with the corresponding attribute from the wrapped

    90        function (defaults to functools.WRAPPER_UPDATES)

    91     """

    92     for attr in assigned:

    93         try:

    94             setattr(wrapper, attr, getattr(wrapped, attr))

    95         except TypeError: # Python 2.3 doesn't allow assigning to __name__.

    96             pass

    97     for attr in updated:

    98         getattr(wrapper, attr).update(getattr(wrapped, attr))

    99     # Return the wrapper so this can be used as a decorator via curry()

   100     return wrapper

   101 

   102 def wraps(wrapped,

   103           assigned = WRAPPER_ASSIGNMENTS,

   104           updated = WRAPPER_UPDATES):

   105     """Decorator factory to apply update_wrapper() to a wrapper function

   106 

   107        Returns a decorator that invokes update_wrapper() with the decorated

   108        function as the wrapper argument and the arguments to wraps() as the

   109        remaining arguments. Default arguments are as for update_wrapper().

   110        This is a convenience function to simplify applying curry() to

   111        update_wrapper().

   112     """

   113     return curry(update_wrapper, wrapped=wrapped,

   114                  assigned=assigned, updated=updated)

   115 

   116 ### End from Python 2.5 functools.py ##########################################

   117 

   118 def memoize(func, cache, num_args):

   119     """

   120     Wrap a function so that results for any argument tuple are stored in

   121     'cache'. Note that the args to the function must be usable as dictionary

   122     keys.

   123 

   124     Only the first num_args are considered when creating the key.

   125     """

   126     def wrapper(*args):

   127         mem_args = args[:num_args]

   128         if mem_args in cache:

   129             return cache[mem_args]

   130         result = func(*args)

   131         cache[mem_args] = result

   132         return result

   133     return wraps(func)(wrapper)

   134 

   135 class Promise(object):

   136     """

   137     This is just a base class for the proxy class created in

   138     the closure of the lazy function. It can be used to recognize

   139     promises in code.

   140     """

   141     pass

   142 

   143 def lazy(func, *resultclasses):

   144     """

   145     Turns any callable into a lazy evaluated callable. You need to give result

   146     classes or types -- at least one is needed so that the automatic forcing of

   147     the lazy evaluation code is triggered. Results are not memoized; the

   148     function is evaluated on every access.

   149     """

   150     class __proxy__(Promise):

   151         # This inner class encapsulates the code that should be evaluated

   152         # lazily. On calling of one of the magic methods it will force

   153         # the evaluation and store the result. Afterwards, the result

   154         # is delivered directly. So the result is memoized.

   155         def __init__(self, args, kw):

   156             self.__func = func

   157             self.__args = args

   158             self.__kw = kw

   159             self.__dispatch = {}

   160             for resultclass in resultclasses:

   161                 self.__dispatch[resultclass] = {}

   162                 for (k, v) in resultclass.__dict__.items():

   163                     setattr(self, k, self.__promise__(resultclass, k, v))

   164             self._delegate_str = str in resultclasses

   165             self._delegate_unicode = unicode in resultclasses

   166             assert not (self._delegate_str and self._delegate_unicode), "Cannot call lazy() with both str and unicode return types."

   167             if self._delegate_unicode:

   168                 # Each call to lazy() makes a new __proxy__ object, so this

   169                 # doesn't interfere with any other lazy() results.

   170                 __proxy__.__unicode__ = __proxy__.__unicode_cast

   171             elif self._delegate_str:

   172                 __proxy__.__str__ = __proxy__.__str_cast

   173 

   174         def __promise__(self, klass, funcname, func):

   175             # Builds a wrapper around some magic method and registers that magic

   176             # method for the given type and method name.

   177             def __wrapper__(*args, **kw):

   178                 # Automatically triggers the evaluation of a lazy value and

   179                 # applies the given magic method of the result type.

   180                 res = self.__func(*self.__args, **self.__kw)

   181                 return self.__dispatch[type(res)][funcname](res, *args, **kw)

   182 

   183             if klass not in self.__dispatch:

   184                 self.__dispatch[klass] = {}

   185             self.__dispatch[klass][funcname] = func

   186             return __wrapper__

   187 

   188         def __unicode_cast(self):

   189             return self.__func(*self.__args, **self.__kw)

   190 

   191         def __str_cast(self):

   192             return str(self.__func(*self.__args, **self.__kw))

   193 

   194         def __cmp__(self, rhs):

   195             if self._delegate_str:

   196                 s = str(self.__func(*self.__args, **self.__kw))

   197             elif self._delegate_unicode:

   198                 s = unicode(self.__func(*self.__args, **self.__kw))

   199             else:

   200                 s = self.__func(*self.__args, **self.__kw)

   201             if isinstance(rhs, Promise):

   202                 return -cmp(rhs, s)

   203             else:

   204                 return cmp(s, rhs)

   205 

   206         def __mod__(self, rhs):

   207             if self._delegate_str:

   208                 return str(self) % rhs

   209             elif self._delegate_unicode:

   210                 return unicode(self) % rhs

   211             else:

   212                 raise AssertionError('__mod__ not supported for non-string types')

   213 

   214         def __deepcopy__(self, memo):

   215             # Instances of this class are effectively immutable. It's just a

   216             # collection of functions. So we don't need to do anything

   217             # complicated for copying.

   218             memo[id(self)] = self

   219             return self

   220 

   221     def __wrapper__(*args, **kw):

   222         # Creates the proxy object, instead of the actual value.

   223         return __proxy__(args, kw)

   224 

   225     return wraps(func)(__wrapper__)

   226 

   227 def allow_lazy(func, *resultclasses):

   228     """

   229     A decorator that allows a function to be called with one or more lazy

   230     arguments. If none of the args are lazy, the function is evaluated

   231     immediately, otherwise a __proxy__ is returned that will evaluate the

   232     function when needed.

   233     """

   234     def wrapper(*args, **kwargs):

   235         for arg in list(args) + kwargs.values():

   236             if isinstance(arg, Promise):

   237                 break

   238         else:

   239             return func(*args, **kwargs)

   240         return lazy(func, *resultclasses)(*args, **kwargs)

   241     return wraps(func)(wrapper)