python-aspects 1.3-5build1 / usr / share / pyshared / aspects.py

# aspects.py - Tools for AOP in Python
# Version 1.3
#
# Copyright (C) 2003-2008 Antti Kervinen (ask@cs.tut.fi)
#
# This library is free software; you can redistribute it and/or
# modify it under the terms of the GNU Lesser General Public
# License as published by the Free Software Foundation; either
# version 2.1 of the License, or (at your option) any later version.
#
# This library is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
# Lesser General Public License for more details.
#
# You should have received a copy of the GNU Lesser General Public
# License along with this library; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

"""
Aspects library allows wrapping and removing wraps on methods and
functions. Wraps are functions which are called before the wrapped
functions. A wrap may or may not call the wrapped function at some
point of their execution.

There are two kinds of wraps: new-style and old-style. New-style wraps
can be used in Python 2.5 and later, old-style wraps work in Python
2.1 and later. Support for old-style wraps is continued for
compatibility reasons, but they will be deprecated when stable Python
2.5 compatible Jython is released. For instance, arbitrary old-style
wraps cannot be removed.

1. Wrapping a method or function:

   new-style: wrap_ids = aspects.with_wrap(new_style_wrap, func1, ...)

              funcs can be in module-level or in class-level (that is,
              a method)

   old-style: wrap_id = aspects.wrap_around(method, old_style_wrap)

              method cannot be a module-level function

   In both cases, adding 'instances=[obj1, obj2, ...]' keyword
   argument causes the wrap to be executed only in the case that it is
   called through objects obj1, obj2, etc.

   wrap_around and with_wrap return identifiers for the added wraps
   (or a list of identifiers if many functions are wrapped at once in
   with_wrap). The identifiers can be used in enabling and disabling
   the wrap.

   There can be a number of wraps on the same function. When it is
   called, the topmost wrap is executed first and the wrap below is
   executed when the wrap above tries to call the original
   function. There can be both old-style and new-style wraps on the
   same function.

2. Removing a wrap:

   removed_wrap = aspects.without_wrap(new_style_wrap, method)

   or

   removed_wrap = aspects.without_wrap(wrap_id, method)

   Removed wraps can be rewrapped to the same or other methods.

   For compatibility, there is the peel_around method for removing the
   topmost wrap. It should not be used anymore.

   topmost_wrap = aspects.peel_around(func)

3. Enabling / disabling a wrap:

   both styles: enable_wrap(func, wrap_id) enables the wrap
                disable_wrap(func, wrap_id) disables the wrap
                wrap_is_enabled(func, wrap_id) returns the status

   Only enabled wraps are executed when the function is called.

4. New-style wraps

   New-style wraps are generators. Inside a wrap, the original
   function can be called with the original call arguments:

   orig_retval = yield aspects.proceed

   or with new arguments:

   orig_retval = yield aspects.proceed(args_here)

   If wanted, the original function can be called many times.
   Exceptions raised by the original method can be caught in the wrap
   if the yield statement is inside a try-except block.

   The wrap passes the original return value by default (if it does
   not yield anything but aspects.proceed), or by yielding

   yield aspects.return_stop

   The return value can be changed by yielding

   yield aspects.return_stop(value_here)

   Yielding return_stop with a new return value before the original
   method is executed causes skipping the execution.

   If the value is returned by either of the above ways, the execution
   of the wrap is restarted when the wrapped function is called next
   time. However, the value can also be returned with return_cont. In
   that case, the execution of the wrap is not restarted, which
   results in remarkably faster execution.

   (args, kw_args) = yield aspects.return_cont

   returns the original return value, and

   (args, kw_args) = yield aspects.return_cont(value_here)

   returns the given value. When the wrapped function is called next
   time, the call arguments are stored to args and kw_args, and the
   execution of the wrap is continued from the yield point.

   The wrap can access the wrapped method by yielding get_wrapped
   class.

   wrapped_method = yield get_wrapped
"""

version_info=(1,3)

import re

import thread

import types

import inspect

import sys
_python_version=sys.version_info[:2]

_permission_to_touch_wraps=thread.allocate_lock()

class AspectsException(Exception):
    pass

if _python_version < (2,3):
    class object: pass

class proceed(object):
    """
    Yielding a proceed object from a generator advice causes
    (re)invokation of the wrapped function with the given arguments.
    """
    def __init__(self,*args,**kwargs):
        self.args=args
        self.kwargs=kwargs

class return_stop(object):
    """
    Yielding a return_stop object from a generator advice causes passing
    the given argument as a return value to the caller of the wrapped
    function.
    """
    def __init__(self,retval):
        self.retval=retval

class return_cont(object):
    """
    Yielding a return_cont object from a generator advice causes
    passing the given argument as a return value of the original
    method to the caller. The execution of the advice will be
    continued from the yield point when the wrapped function is called
    next time.
    """
    def __init__(self,retval):
        self.retval=retval

class get_wrapped(object):
    """
    Yielding a get_wrapped_function class from a generator advice causes
    the wrapped function object to be sent to the advice.
    """
    pass

def wrap_around_re(aClass, wildcard, advice):
    """
    Same as wrap_around but works with regular expression based
    wildcards to map which methods are going to be used.
    """
    matcher = re.compile(wildcard)
    for aMember in dir(aClass):
        realMember = getattr(aClass, aMember)
        if callable(realMember) and aMember[:6]!="__wrap" and \
           aMember[:9]!="__proceed" and \
           matcher.match(aMember):
            wrap_around(realMember, advice)

def with_wrap(advice, *methods, **kwargs):
    insts = kwargs.get('instances', [])
    retval = []
    for m in methods:
        if getattr(m, 'im_self', None) != None:
            # Method m is a bound method. It will be wrapped equally
            # to the corresponding unbound method with argument
            # instances=[m.im_self].
            try:
                unbound_m = getattr(m.im_class, m.im_func.func_name)
            except:
                raise AspectsException("Could not find the unbound version of method %s" % (m,))
            retval.append(_with_wrap(advice, unbound_m, instances=[m.im_self]))
        else: 
            # Method m is a function or an unbound method.
            retval.append(_with_wrap(advice, m, instances=insts))
    if len(retval) == 1:
        return retval[0]
    else:
        return retval

_next_wrap_id = 0

def _with_wrap(advice, method, instances=[]):
    """
    with_wrap wraps the execution of method inside given
    generator. When the method is called, the generator is invoked
    with the parameters the method call contains. If the generator
    yields, the yielded values define the new parameters to the
    method. The return value of the method is sent to the generator
    with .send method. If then generator yields again, the yielded
    value is passed as a return value that the caller of the method
    sees. If it does not, the return value is passed to the caller as
    is.

    If the first yield returns None instead of a pair of new
    arguments, the arguments are given to the original method.

    Usage:

    >>> def g_adv(*args,**kwargs):
    ...     print 'g_adv received arguments',args,kwargs
    ...     retval = yield aspects.proceed
    ...     print 'method returned',retval
    ...     yield aspects.return_stop(retval + 1)
    ...
    >>> class c:
    ...     def inc(number):
    ...         return number+1
    ...
    >>> aspects.with_wrap(c.inc, g_adv)
    >>> o=c()
    >>> o.inc(41)
    g_adv received arguments ((41,), {})
    method returned 42
    43
    """

    global _next_wrap_id

    _permission_to_touch_wraps.acquire()

    wrap_id = _next_wrap_id
    _next_wrap_id += 1
        
    methods_name = method.__name__

    orig_method = method

    # Information on the original method and the advice will be
    # plugged to the new method (that is, the new middleman) later on.
    new_method = _create_middleman()

    try: 
        # Older Pythons do not accept try-except-finally, so there is
        # outer try-finally here just to make sure that
        # _permission_to_touch_wraps lock will be released
        try:
            # Already wrapped method's namespace can be found from
            # aspects-orig-method-namespace
            replace_method = getattr(method, '__aspects_rmf')
        except AttributeError:
            if hasattr(method, 'im_class'): # is this a method of a class?
                replace_method = \
                    lambda orig, new: setattr(method.im_class, orig, new)
            elif hasattr(method, 'func_globals'): # is this a normal function?
                replace_method = \
                    lambda orig, new: method.func_globals.__setitem__(orig, new)
            else:
                m = inspect.getmodule(method.__module__)
                if m == None:
                    if method.__module__ in ['nt', 'posix']:
                        # os module has funny names, but we need to
                        # modify the dict of os module, not nt's or posix's.
                        m = __import__('os', [], [], '')
                    else: 
                        # sometimes inspect fails to return a module
                        m = __import__(method.__module__, [], [], '')
                if not type(m) == types.ModuleType:
                    raise AspectsException("Module of %s not found" % (method,))
                replace_method = \
                    lambda orig, new: m.__dict__.__setitem__(orig, new)
    
        replace_method(methods_name, new_method)
        new_method.__name__ = method.__name__
        new_method.__aspects_wrapid = wrap_id
        new_method.__aspects_rmf = replace_method
        new_method.__aspects_cont = None # generator to be continued
        new_method.__aspects_instances = set([id(i) for i in instances])
        new_method.__aspects_enabled = 1
        new_method.__aspects_orig = orig_method
        new_method.__aspects_adv = advice
        return wrap_id
    finally: _permission_to_touch_wraps.release()


def _create_middleman():
    def generator_middleman(*args,**kwargs):
        # Generator_advice is not executed if the advice is not
        # enabled or if we are dealing with an incorrect instance
        method = generator_middleman.__aspects_orig
        if generator_middleman.__aspects_enabled==0 or \
           (generator_middleman.__aspects_instances and not
            id(args[0]) in generator_middleman.__aspects_instances):
            return method(*args,**kwargs)
        generator_advice = generator_middleman.__aspects_adv
        # If a generator is waiting for call, continue its execution
        # with send(). Otherwise, create a new generator advice.
        
        if generator_middleman.__aspects_cont==None:
            g=generator_advice(*args,**kwargs)
            if type(g)!=types.GeneratorType:
                raise AspectsException("Advice is not a generator")
            try: rv=g.next()
            except StopIteration: return None
        else:
            g=generator_middleman.__aspects_cont
            generator_middleman.__aspects_cont=None
            try: rv=g.send((args,kwargs))
            except StopIteration: return None
            
        # Continue execution in the generator to the first yield.
        # yielded value => affect
        
        # proceed (class) => wrapped method is called with orig
        # parameters, may raise exceptions

        # proceed (object) => wrapped method is called with given
        # parameters, may raise exceptions
        
        # return_stop (class) => the return value of the original
        # method is passed to the caller. Execution of the generator
        # advice starts from the beginning when the method is called
        # next time.

        # return_stop (object) => the given return value is passed to
        # the caller. Execution of the generator advice starts from
        # the beginning when the method is called next time.

        # return_cont (class) => the return value of the original
        # method is passed to the caller. Execution of the generator
        # advice continues from the yielding row when the method is
        # called next time.

        # return_cont (object) => the given return value is passed to
        # the caller. Execution of the generator advice continues from
        # the yielding row when the method is called next time.

        # get_wrapped (class) => sends the lower level wrap to the current wrap

        # FUTURE DEVELOPMENT
        # getorig (class) => sends the original method to the wrap

        orig_retval_available=0
        while 1:
            # Reset the arguments for the original method, if new ones are
            # given with yield
            if rv==proceed:
                pass # args and kwargs are as they are
            elif type(rv)==proceed:
                args,kwargs=rv.args,rv.kwargs
            elif rv==return_stop:
                if orig_retval_available==0:
                    raise AspectsException("Original return value not available.")
                return method_rv
            elif type(rv)==return_stop:
                return rv.retval
            elif rv==return_cont:
                if orig_retval_available==0:
                    raise AspectsException("Original return value not available.")
                generator_middleman.__aspects_cont=g
                return method_rv
            elif type(rv)==return_cont:
                generator_middleman.__aspects_cont=g
                return rv.retval
            elif rv==get_wrapped:
                try: rv=g.send(method)
                except StopIteration: return None
                continue
            else:
                raise AspectsException("Advice yielded an illegal value: '%s'" % str(rv))
            # Call the original method. Its return value will be sent to
            # the generator. If the method raises an exception, the same
            # exception is raised in the generator.
            method_rv=None
            try:
                method_rv=method(*args,**kwargs)
                orig_retval_available=1
                raised_exception=None
            except Exception,e:
                raised_exception=e
                # last orig method call did not return a value:
                orig_retval_available=0
            # Continue execution in the generator advice by sending it the
            # return value or raising the catched exception. 
            try:
                if not raised_exception: rv=g.send(method_rv)
                else: rv=g.throw(e)
            except StopIteration:
                return method_rv
    # end of generator_middleman
    return generator_middleman
    
            
def wrap_around(method, advice, instances=[]):
    """
    This function will be deprecated.

    wrap_around wraps an unbound method (the first argument)
    inside an advice (function given as the second argument). When the
    method is called, the code of the advice is executed to the point
    of 'self.__proceed(*args,**keyw)'. Then the original method is
    executed after which the control returns to the advice.

    Keyword parameter instances is a container. When it is not empty,
    it specifies a set of id:s of instances with which the advice is
    executed. If the wrapped method is bound to an instance not in the
    set, the advice is omitted.

    Returns the number of the added wrap. The number can be used later
    on for enabling and disabling the wrap.
    """
    _permission_to_touch_wraps.acquire()
    try:
        methods_name, methods_class, _ = _names_mce(method)

        if methods_name[:2]=="__" and not hasattr(methods_class,methods_name):
            methods_name="_"+methods_class.__name__+methods_name

        # Check if __proceed method is implemented in the class
        try:
            getattr(methods_class,'__proceed')
        except:
            setattr(methods_class, '__proceed_stack', _proceed_stack_method)
            setattr(methods_class,'__proceed', _proceed_method)

        # Check how many times this method has been wrapped
        methodwrapcount = wrap_count(method)

        # Rename the original method: it will be __wrapped/n/origmethodname
        # where /n/ is the number of wraps around it
        wrapped_method_name = "__wrapped" + str(methodwrapcount) + methods_name
        orig_method = getattr( methods_class, methods_name)
        setattr(methods_class, wrapped_method_name, orig_method)

        # Add the wrap (that is, the advice) as a new method
        wrapper_method_name = "__wrap" + str(methodwrapcount) + methods_name
        setattr(methods_class, wrapper_method_name, advice)

        # Add __wrap_enabled/n/methodname attribute that is used for
        # enabling and disabling the wrap on the fly. By default the wrap
        # is enabled.
        enabled_attr_name = "__wrap_enabled" + str(methodwrapcount) + methods_name
        setattr(methods_class, enabled_attr_name, 1)

        # Generate condition: should this wrap be executed when the method is called
        cond_execute_wrap="self." + enabled_attr_name
        if len(instances)>0:
            instanceids_attr_name="__wrap_instanceids"+str(methodwrapcount)+methods_name
            if _python_version >= (2,4):
                setattr(methods_class,instanceids_attr_name,set([id(i) for i in instances]))
            else: # slower implementation for older pythons
                setattr(methods_class,instanceids_attr_name,[id(i) for i in instances])
            cond_execute_wrap="("+cond_execute_wrap+")" + \
                               "and (id(self) in self."+instanceids_attr_name+")"

        # Replace the original method by a method that
        # 1) sets which method should be executed in the next proceed call
        # 2) calls the wrap (advice)

        new_code = "def " + methods_name + "(self,*args,**keyw):\n" +\
                   "\tif not (" + cond_execute_wrap + "):\n" +\
                   "\t\treturn self." + wrapped_method_name + "(*args,**keyw)\n" +\
                   "\tstack=self.__proceed_stack()\n" +\
                   "\tstack.append( _Proceed_stack_entry(self." + wrapped_method_name + ",'" + methods_class.__name__ + "." + methods_name + "'))\n" +\
                   "\ttry: retval = self." + wrapper_method_name + "(*args,**keyw)\n" +\
                   "\tfinally:\n" +\
                   "\t\tstack.pop()\n" +\
                   "\t\tif len(stack)==0: _remove_proceed_stack(self)\n" +\
                   "\treturn retval\n"
        new_method = _create_function(new_code, methods_name)
        new_method.__aspects_wrapid=methodwrapcount
        new_method.__aspects_orig=orig_method
        # setattr(new_method,'__aspects_enabled',1)
        # new_method.__name__=methods_name
        setattr(methods_class, methods_name, new_method)
        return methodwrapcount
    finally: _permission_to_touch_wraps.release()

def without_wrap(advice_or_wrapid, method):
    _permission_to_touch_wraps.acquire()
    # 1. Search the wrap to be removed in the wrap stack
    #    and store it to the middleman variable
    if isinstance(advice_or_wrapid, int): # wrap is referenced by id
        # cannot use _find_wrap, because prev_middleman is needed, too
        wrapid = advice_or_wrapid
        prev_middleman = None
        middleman = method
        try:
            while middleman.__aspects_wrapid != wrapid:
                prev_middleman = middleman
                middleman = middleman.__aspects_orig
        except AttributeError:
            _permission_to_touch_wraps.release()
            raise AspectsException("Method '%s' has no wrap '%s'"
                                   % (method, wrapid))
    else: # removed wrap is referenced the advice function
        advice = advice_or_wrapid
        prev_middleman = None
        middleman = method
        try:
            while middleman.__aspects_adv != advice:
                prev_middleman = middleman
                middleman = middleman.__aspects_orig
        except AttributeError:
            _permission_to_touch_wraps.release()
            raise AspectsException("Method '%s' has no wrap '%s'"
                                   % (method, advice))
    retval = middleman.__aspects_adv

    # 2. Remove the current middleman
    if prev_middleman == None:
        # Must replace the method. This may be a poor solution,
        # because it may not change callbacks. A better solution might
        # be to switch the advice code between middlemen, keep the
        # topmost middleman the same, and remove the next middleman
        # from the chain.
        middleman.__aspects_rmf(middleman.__aspects_orig.__name__,
                                middleman.__aspects_orig)
    else:
        # Drop the middleman from the list.
        prev_middleman.__aspects_orig = middleman.__aspects_orig
    _permission_to_touch_wraps.release()
    return retval

def peel_around(method):
    """
    This function will be deprecated.

    Removes one wrap around the method (given as a parameter) and
    returns the wrap. If the method is not wrapped, returns None.
    """
    _permission_to_touch_wraps.acquire() # released in finally part
    try:
        if hasattr(method,'__aspects_enabled'): # new-style aspect, easy!
            method.__aspects_rmf(method.__name__,method.__aspects_orig)
            return method.__aspects_adv
        
        methods_name = method.__name__
        methods_class = method.im_class

        wc = wrap_count(method)-1

        if wc==-1: return None

        wrapped = getattr(methods_class, '__wrapped' + str(wc) + methods_name)
        setattr(methods_class, methods_name, wrapped)

        removed_adv = getattr(methods_class, '__wrap'+str(wc)+methods_name)
        del methods_class.__dict__['__wrapped'+str(wc)+methods_name]
        del methods_class.__dict__['__wrap'+str(wc)+methods_name]

        return removed_adv
    finally: _permission_to_touch_wraps.release()

def _find_wrap(method, wrap_number):
    wrapid = getattr(method, '__aspects_wrapid', None)
    while wrapid != wrap_number:
        if wrapid == None: 
            raise AspectsException("Wrap %s on method %s not found."
                                   % (wrap_number, method.__name__))
        method = method.__aspects_orig
        wrapid = getattr(method, '__aspects_wrapid', None)
    return method

def enable_wrap(method, wrap_number):
    wrap=_find_wrap(method, wrap_number)
    if hasattr(wrap,'__aspects_enabled'):
        setattr(wrap,'__aspects_enabled',1)
    else:
        _, methods_class, enabled_attr_name = _names_mce(method, wrap_number)
        setattr(methods_class, enabled_attr_name, 1)

def disable_wrap(method, wrap_number):
    wrap=_find_wrap(method, wrap_number)
    if hasattr(wrap,'__aspects_enabled'):
        setattr(wrap,'__aspects_enabled',0)
    else:
        _, methods_class, enabled_attr_name = _names_mce(method, wrap_number)
        setattr(methods_class, enabled_attr_name, 0)

def wrap_is_enabled(method, wrap_number):
    wrap=_find_wrap(method, wrap_number)
    if hasattr(wrap,'__aspects_enabled'):
        return getattr(wrap,'__aspects_enabled')
    else:
        _, methods_class, enabled_attr_name = _names_mce(method, wrap_number)
        return getattr(methods_class, enabled_attr_name)
    
def wrap_count(method):
    """
    Returns number of wraps around given method.
    """
    number = 0
    while hasattr(method, '__aspects_orig'):
        number += 1
        method = method.__aspects_orig
    return number

def _names_mce(method, wrap_number=None):
    """
    Returns triplet of names: Method, it's Class and wrap's Enabled
    attr name.  If enabled attr name does not exist (that is, there is
    no wrap wrap_number on the method), AspectsException is raised.
    """
    methods_name = method.__name__
    methods_class = method.im_class
    if wrap_number!=None:
        enabled_attr_name = "__wrap_enabled" + str(wrap_number) + methods_name
        if not hasattr(methods_class, enabled_attr_name):
            raise AspectsException("Method %s does not have wrap with number %s"
                                   % (methods_name, wrap_number))
    else: enabled_attr_name=None
    return methods_name, methods_class, enabled_attr_name


def _proceed_method(self, *args, **keyw):
    method=self.__proceed_stack()[-1].method
    return method(*args, **keyw)

def _remove_proceed_stack(self):
    stackname='__proceed_stack' + str(thread.get_ident())
    delattr(self,stackname)

def _proceed_stack_method(self):
    stackname='__proceed_stack' + str(thread.get_ident())
    try:
        return getattr(self,stackname)
    except:
        setattr(self,stackname,[])
        return getattr(self,stackname)

def _create_function(function_code, function_name, thread_lib=1):
    # import thread if it is required
    # if thread_lib and not 'thread' in globals(): import thread
    codeobj = compile(function_code, "", "exec")
    gl = {'_Proceed_stack_entry':_Proceed_stack_entry,
          '_remove_proceed_stack': _remove_proceed_stack}
    lo = {}
    exec(codeobj,gl,lo)
    return eval(function_name,gl,lo)

class _Proceed_stack_entry:
    def __init__(self, method, name):
        self.method = method
        self.name = name