# function_class.py -- Library for making python classes from a set

#                      of functions. 

#

# Copyright (C) 2008 ParIT Worker Co-operative <paritinfo@parit.ca>

# This program is free software; you can redistribute it and/or

# modify it under the terms of the GNU General Public License as

# published by the Free Software Foundation; either version 2 of

# the License, or (at your option) any later version.

#

# This program 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 General Public License for more details.

#

# You should have received a copy of the GNU General Public License

# along with this program; if not, contact:

# Free Software Foundation           Voice:  +1-617-542-5942

# 51 Franklin Street, Fifth Floor    Fax:    +1-617-542-2652

# Boston, MA  02110-1301,  USA       gnu@gnu.org

#

# @author Mark Jenkins, ParIT Worker Co-operative <mark@parit.ca>

##  @file

#   @brief Library for making python classes from a set of functions.

#   @author Mark Jenkins, ParIT Worker Co-operative <mark@parit.ca>

#   @author Jeff Green,   ParIT Worker Co-operative <jeff@parit.ca>

#   @ingroup python_bindings

INSTANCE_ARGUMENT = "instance"

class ClassFromFunctions(object):

    """Inherit this class to give yourself a python class that wraps a set of

    functions that together constitute the methods of the class.

    The method functions must all have as a first argument an object

    holding the instance data. There must also be a function that

    returns a new instance of the class, the constructor.

    Your subclass must define

    _module - The module where the method functions, including the

    constructor can be found

    _new_instance - The name of a function that serves as a constructor,

    returning the instance data.

    To access the instance data, use the read-only property instance.

    To add some functions from _module as methods, call classmethods like

    add_method and add_methods_with_prefix.

    """

    def __new__(cls, *args, **kargs):

        # why reimpliment __new__? Because later on we're going to

        # use new to avoid creating new instances when existing instances

        # already exist with the same __instance value, or equivalent __instance

        # values, where this is desirable...

        return super(ClassFromFunctions, cls).__new__(cls)

    def __init__(self, *args, **kargs):

        """Construct a new instance, using either the function

        self._module[self._new_instance] or using existing instance

        data. (specified with the keyword argument, instance)

        Pass the arguments that should be passed on to

        self._module[self._new_instance] . Any arguments of that

        are instances of ClassFromFunctions will be switched with the instance

        data. (by calling the .instance property)

        """

        if INSTANCE_ARGUMENT in kargs:

            self.__instance = kargs[INSTANCE_ARGUMENT]

        else:

            self.__instance = getattr(self._module, self._new_instance)(

                *process_list_convert_to_instance(args) )

    def get_instance(self):

        """Get the instance data.

        You can also call the instance property

        """

        return self.__instance

    instance = property(get_instance)

    # CLASS METHODS

    @classmethod

    def add_method(cls, function_name, method_name):

        """Add the function, method_name to this class as a method named name

        """

        def method_function(self, *meth_func_args):

            return getattr(self._module, function_name)(

                self.instance,

                *process_list_convert_to_instance(meth_func_args) )

        setattr(cls, method_name, method_function)

        setattr(method_function, "__name__", method_name)

        return method_function

    @classmethod

    def ya_add_classmethod(cls, function_name, method_name):

        """Add the function, method_name to this class as a classmethod named name

        Taken from function_class and slightly modified.

        """

        def method_function(self, *meth_func_args):

            return getattr(self._module, function_name)(

                self,

                *process_list_convert_to_instance(meth_func_args) )

        setattr(cls, method_name, classmethod(method_function))

        setattr(method_function, "__name__", method_name)

        return method_function    

    @classmethod

    def ya_add_method(cls, function_name, method_name):

        """Add the function, method_name to this class as a method named name

        Taken from function_class and slightly modified.

        """

        def method_function(self, *meth_func_args):

            return getattr(self._module, function_name)(

                self,

                *process_list_convert_to_instance(meth_func_args) )

        setattr(cls, method_name, method_function)

        setattr(method_function, "__name__", method_name)

        return method_function

    @classmethod

    def add_methods_with_prefix(cls, prefix):

        """Add a group of functions with the same prefix 

        """

        for function_name, function_value, after_prefix in \

            extract_attributes_with_prefix(cls._module, prefix):

                cls.add_method(function_name, after_prefix)

    @classmethod

    def add_constructor_and_methods_with_prefix(cls, prefix, constructor):

        """Add a group of functions with the same prefix, and set the

        _new_instance attribute to prefix + constructor

        """

        cls.add_methods_with_prefix(prefix)

        cls._new_instance = prefix + constructor

    @classmethod

    def decorate_functions(cls, decorator, *args):

        for function_name in args:

            setattr( cls, function_name,

                     decorator( getattr(cls, function_name) ) )

def method_function_returns_instance(method_function, cls):

    """A function decorator that is used to decorate method functions that

    return instance data, to return instances instead.

    You can't use this decorator with @, because this function has a second

    argument.

    """

    assert( 'instance' == INSTANCE_ARGUMENT )

    def new_function(*args):

        kargs = { INSTANCE_ARGUMENT : method_function(*args) }

        if kargs['instance'] == None:

            return None

        else:

            return cls( **kargs )

    return new_function

def method_function_returns_instance_list(method_function, cls):

    def new_function(*args):

        return [ cls( **{INSTANCE_ARGUMENT: item} )

                 for item in method_function(*args) ]

    return new_function

def methods_return_instance_lists(cls, function_dict):

    for func_name, instance_name in function_dict.iteritems():

        setattr(cls, func_name,

                method_function_returns_instance_list(

                getattr(cls, func_name), instance_name))

def default_arguments_decorator(function, *args):

    """Decorates a function to give it default, positional arguments

    You can't use this decorator with @, because this function has more

    than one argument.

    """

    def new_function(*function_args):

        new_argset = list(function_args)

        new_argset.extend( args[ len(function_args): ] )

        return function( *new_argset )

    return new_function

def return_instance_if_value_has_it(value):

    """Return value.instance if value is an instance of ClassFromFunctions,

    else return value

    """

    if isinstance(value, ClassFromFunctions):

        return value.instance

    else:

        return value

def process_list_convert_to_instance( value_list ):

    """Return a list built from value_list, where if a value is in an instance

    of ClassFromFunctions, we put value.instance in the list instead.

    Things that are not instances of ClassFromFunctions are returned to

    the new list unchanged.

    """

    return [ return_instance_if_value_has_it(value)

             for value in value_list ]

def extract_attributes_with_prefix(obj, prefix):

    """Generator that iterates through the attributes of an object and

    for any attribute that matches a prefix, this yields

    the attribute name, the attribute value, and the text that appears

    after the prefix in the name

    """

    for attr_name, attr_value in obj.__dict__.iteritems():

        if attr_name.startswith(prefix):

            after_prefix = attr_name[ len(prefix): ]

            yield attr_name, attr_value, after_prefix

def methods_return_instance(cls, function_dict):

    """Iterates through a dictionary of function name strings and instance names

    and sets the function to return the associated instance 

    """

    for func_name, instance_name in function_dict.iteritems():

        setattr(cls, func_name, 

            method_function_returns_instance( getattr(cls, func_name), instance_name))