module to implement Abstract Base Class

[emin.shopper at gmail.com]

I had a need recently to check if my subclasses properly implemented
the desired interface and wished that I could use something like an
abstract base class in python. After reading up on metaclass magic, I
wrote the following module. It is mainly useful as a light weight tool
to help programmers catch mistakes at definition time (e.g., forgetting
to implement a method required by the given interface). This is handy
when unit tests or running the actual program take a while.

Comments and suggestions are welcome.

Thanks,
-Emin


###############  Abstract Base Class Module
Follows########################

"""
This module provides the AbstractBaseClass class and the Abstract
decorator
to allow you to define abstract base classes in python. See the
documentation
for AbstractBaseClass for instructions.
"""

class _AbstractMetaClass(type):
    """
    This is a metaclass designed to act as an AbstractBaseClass.
    You should rarely need to use this directly. Inheret from
    the class (not metaclass) AbstractBaseClass instead.

    Feel free to skip reading this metaclass and go on to the
    documentation for AbstractBaseClass.
    """

    def __init__(cls, name, bases, dict):
        """Initialize the class if Abstract requirements are met.

        If the class is supposed to be abstract or it is concrete and
        implements all @Abstract methods, then instantiate it.
Otherwise, an
        AssertionError is raised.

        Alternatively, if cls.__allow_abstract__ is True, then the
        class is instantiated and no checks are done.
        """

        if (__debug__ and not getattr(cls,'__allow_abstract__',False)
            and not _AbstractMetaClass._IsSupposedToBeAbstract(cls)):
            abstractMethods = _AbstractMetaClass._GetAbstractMethods(
                cls.__bases__)
            for name in abstractMethods:
                if ( getattr(getattr(cls,name),'__abstract__',False)):
                    klasses =
_AbstractMetaClass._GetParentsRequiring(name,cls)
                    if (len(klasses)==0):
                        klasses = '(Unknown); all parents are %s.' % (
                            cls.__bases__)
                    else:
                        klasses = str(klasses)
                    raise AssertionError(
                        'Class %s must override %s to implement:\n%s.'
                        % (cls,name,klasses))

        super(_AbstractMetaClass,cls).__init__(name,bases,dict)

    def __call__(self, *args, **kw):
        """Only allow instantiation if Abstract requirements are met.

        If there are methods that are still abstract and
__allow_abstract__
        is not set to True, raise an assertion error. Otherwise,
        instantiate the class.
        """
        if (__debug__):
            stillAbstract = [
                name for name in
_AbstractMetaClass._GetAbstractMethods([self])
                if (getattr(getattr(self,name),'__abstract__',False))]
            assert (getattr(self,'__allow_abstract__',False)
                    or len(stillAbstract) == 0), (
                """Cannot instantiate abstract base class %s
because the follwoing methods are still abstract:\n%s""" %
                (str(self),stillAbstract))
        return type.__call__(self,*args,**kw)

    def _IsSupposedToBeAbstract(cls):
        """Return true if cls is supposed to be an abstract class.

        A class which is ''supposed to be abstract'' is one which
        directly inherits from AbstractBaseClass. Due to metaclass
        magic, the easiest way to check this is to look for the
        __intended_abstract__ attribute which only AbstractBaseClass
        should have.
        """
        for parent in cls.__bases__:
            if (parent.__dict__.get('__intended_abstract__',False)):
                return True

    @staticmethod
    def _GetAbstractMethods(classList,abstractMethods=None):
        """Returns all abstract methods in a list of classes.

        Takes classList which is a list of classes to look through and
        optinally takes abstractMethods which is a dict containing
names
        of abstract methods already found.
        """
        if (None == abstractMethods):
            abstractMethods = {}
        for cls in classList:
            for name in cls.__dict__:
                method = getattr(cls,name)
                if (callable(method) and
getattr(method,'__abstract__',False)):
                    abstractMethods[name] = True
            _AbstractMetaClass._GetAbstractMethods(cls.__bases__,
                                                   abstractMethods)
        return abstractMethods.keys()

    @staticmethod
    def _GetParentsRequiring(methodName,cls):
        """Return list of parents that have a method defined as
abstract.

        Arguments are methodName (string representing name of method to
check)
        and cls (the class whose parents should be checked).
        """
        result = []
        for parent in cls.__bases__:
            if (getattr(parent,methodName,False) and

getattr(getattr(parent,methodName),'__abstract__',False)):
                result.append(parent)
        return result


class AbstractBaseClass(object):
    """
    The AbstractBaseClass represents a class that defines some methods
    which must be implemented by non-abstract children. To use it, have
your
    class inhereit from AbstractBaseClass and use the @Abstract
decorator
    on the methods you want to be abstract. You can have many
generations
    of abstract base classes inheriting from each other and adding
@Abstract
    methods as long as they all inherit from AbstractBaseClass.

    If any class which does not DIRECTLY inherit from
AbstractBaseClass, but
    does INDIRECTLY inherit from AbstractBaseClass must override all
    abstract methods. Otherwise, an AssertionError will be raised when
    the offending class is defined.

    What if you decide you want to turn of all checking and really do
want to
    instantiate an abstract class? Just do klass.__allow_abstract__ =
True
    and klass will no longer enforce the Abstract limitations.

        The following is an example of how this pattern can be used:

>>> class abstract(AbstractBaseClass): # this will be the AbstractBaseClass
...     @Abstract
...     def foo(self,x): pass # declared abstract even though we def it
here
>>> try: # illustrate what happens when you don't implement @Abstract methods
...     class fails(abstract): # an erroneous implementation of
abstract
...             pass           # since it doesn't implment foo
... except AssertionError, e:
...     print e
Class <class '__main__.fails'> must override foo to implement:
[<class '__main__.abstract'>].
>>> class concrete(abstract): # will be a concrete class implementing abstract
...     def foo(self,x):
...             return x+2

            You can even create abstract classes that inherit from
other
            abstract classes to gradually build up abstractions as
shown below:

>>> class AbstractCar(AbstractBaseClass):
...     @Abstract
...     def Drive(self): pass
...
>>> class AbstractFastCar(AbstractCar,AbstractBaseClass):# inherit from ABC
...     @Abstract                                        # so that
interpreter
...     def DriveFast(self): pass                        # doesn't
worry about
...                                                      # Drive being
abstract
>>> # Note that children of AbstractFastCar which are not abstract, must
>>> # implement both DriveFast as requied by AbstractFastCar as well as
>>> # Drive as required by AbstractCar.
>>> try: # breaks since you don't implement Drive as requiered by AbstractCar
...     class BadCar(AbstractFastCar):
...             def DriveFast(self): pass
... except AssertionError, e:
...     print str(e)
Class <class '__main__.BadCar'> must override Drive to implement:
[<class '__main__.AbstractFastCar'>].
>>> try:#breaks since you don't implement DriveFast required by AbstractFastCar
...     class BadCar(AbstractFastCar):
...             def Drive(self): pass
... except AssertionError, e:
...     print str(e)
Class <class '__main__.BadCar'> must override DriveFast to implement:
[<class '__main__.AbstractFastCar'>].
>>> class FastCar(AbstractFastCar): # this works since you implement both
...     def Drive(self): pass
...     def DriveFast(self): pass
>>> c = FastCar()

        If you don't like someone elses abstraction requirements, you
can
        easily turn checking of the @Abstract requirements on and off.

>>> class abstract(AbstractBaseClass):
...     @Abstract
...     def foo(self,x): pass
>>> abstract.__allow_abstract__ = True  # turn of all checking
>>> class fails(abstract): pass         # define a class failing requirements
>>> fails().foo('ignore')               # call its abstract method
>>> abstract.__allow_abstract__ = False # turn checking back on
>>> try:
...     class bad(abstract): pass
... except AssertionError, e:
...     print str(e)
Class <class '__main__.bad'> must override foo to implement:
[<class '__main__.abstract'>].


        You can even use multiple inheritence to combine abstractions:

>>> class AbstractCar(AbstractBaseClass):
...     @Abstract
...     def Drive(self): pass
...
>>> class AbstractPlane(AbstractBaseClass):
...     @Abstract
...     def Fly(self): pass
...
>>> class AbstractFlyingCar(AbstractCar,AbstractPlane,AbstractBaseClass): pass
>>> try:
...     class Car(AbstractFlyingCar):
...             def Drive(self): pass
... except AssertionError, e:
...     print 'not right'
not right
>>> class FlyingCar(AbstractFlyingCar):
...     def Fly(self): pass
...     def Drive(self): pass
>>> # You can also define something which inherits both the car and plane
>>> # abstractions without the extra layer of AbstractFlyingCar.
>>> class FlyingCar(AbstractCar,AbstractPlane):
...     def Fly(self): pass
...     def Drive(self): pass

    """
    __metaclass__ = _AbstractMetaClass
    __intended_abstract__ = True

def Abstract(func):
    """
    This is a function decorator that adds the attribute __abstract__
to
    a method function with the attribute having the value True.
    See documentation for AbstractBaseClass for how to use this
decorator.
    """
    if (__debug__):
        def wrapper(*_args,**_kw):
            result = func(*_args,**_kw)
            assert getattr(_args[0],'__allow_abstract__',False), (
                'Called Abstract method %s. Override %s; %s.' % (
                func.__name__,func.__name__,"don't call it directly"))
            return result
        wrapper.__dict__ = func.__dict__
        wrapper.__name__ = func.__name__
        wrapper.__doc__ = func.__doc__
        wrapper.__abstract__ = True
        return wrapper
    else:
        return func

def _regr_test_children():
    """
    Regression test to make sure things work properly with more
    complicated inheritence for AbstractBaseClass.

>>> class abstract(AbstractBaseClass): # this will be the AbstractBaseClass
...     @Abstract
...     def foo(self,x): # this is declared abstract even though we def
it here
...             raise Exception('You must override this method.')
...     @Abstract
...     def bar(self,x): # this is declared abstract even though we def
it here
...             raise Exception('You must override this method.')
>>> class partial: # will be a partial implementation so don't inherit
...     def foo(self,x):
...             return x+2
>>> class concrete(partial,abstract): #provides concrete implementation
...     def bar(self,y):
...             return y+3
>>> try:
...     class switch(abstract,partial): # order matters!
...             pass
... except AssertionError, a:
...     print 'order matters!'
order matters!
    """

def _regr_test_wrapping():
    """
    Regression test to make sure that @Abstract decorator works
properly.

>>> class abstract(AbstractBaseClass):
...     @Abstract
...     def foo(self,x):
...             'docstring for foo'
...
>>> assert abstract.foo.__doc__ == 'docstring for foo'
>>> assert abstract.foo.__name__ == 'foo'
>>> try: # verify that you can't instantiate an abstract class
...     a = abstract()
... except AssertionError, e:
...     print str(e)
Cannot instantiate abstract base class <class '__main__.abstract'>
because the follwoing methods are still abstract:
['foo']
>>> try: # even if programmer instantiate abstract, can't call abstract methods
...     a = object.__new__(abstract)
...     a.foo(1)
... except AssertionError, e:
...     print str(e)
Called Abstract method foo. Override foo; don't call it directly.
>>> abstract.__allow_abstract__ = True # turn of all checking
>>> class x(abstract): pass
>>> y = x()
>>> y.foo(1)
    """


def _test():
    import doctest
    doctest.testmod()

if __name__ == "__main__":
    _test()
    print 'Test finished.'