module to implement Abstract Base Class

[emin.shopper]

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 AbstractBaseCla ss class and the Abstract
decorator
to allow you to define abstract base classes in python. See the
documentation
for AbstractBaseCla ss for instructions.
"""

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

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

def __init__(cls, name, bases, dict):
"""Initiali ze 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_abs tract__ is True, then the
class is instantiated and no checks are done.
"""

if (__debug__ and not getattr(cls,'__ allow_abstract_ _',False)
and not _AbstractMetaCl ass._IsSupposed ToBeAbstract(cl s)):
abstractMethods = _AbstractMetaCl ass._GetAbstrac tMethods(
cls.__bases__)
for name in abstractMethods :
if ( getattr(getattr (cls,name),'__a bstract__',Fals e)):
klasses =
_AbstractMetaCl ass._GetParents Requiring(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,klass es))

super(_Abstract MetaClass,cls). __init__(name,b ases,dict)

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

If there are methods that are still abstract and
__allow_abstrac t__
is not set to True, raise an assertion error. Otherwise,
instantiate the class.
"""
if (__debug__):
stillAbstract = [
name for name in
_AbstractMetaCl ass._GetAbstrac tMethods([self])
if (getattr(getatt r(self,name),'_ _abstract__',Fa lse))]
assert (getattr(self,' __allow_abstrac t__',False)
or len(stillAbstra ct) == 0), (
"""Cannot instantiate abstract base class %s
because the follwoing methods are still abstract:\n%s"" " %
(str(self),stil lAbstract))
return type.__call__(s elf,*args,**kw)

def _IsSupposedToBe Abstract(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 AbstractBaseCla ss. Due to metaclass
magic, the easiest way to check this is to look for the
__intended_abst ract__ attribute which only AbstractBaseCla ss
should have.
"""
for parent in cls.__bases__:
if (parent.__dict_ _.get('__intend ed_abstract__', False)):
return True

@staticmethod
def _GetAbstractMet hods(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,nam e)
if (callable(metho d) and
getattr(method, '__abstract__', False)):
abstractMethods[name] = True
_AbstractMetaCl ass._GetAbstrac tMethods(cls.__ bases__,
abstractMethods )
return abstractMethods .keys()

@staticmethod
def _GetParentsRequ iring(methodNam e,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,Fal se) and

getattr(getattr (parent,methodN ame),'__abstrac t__',False)):
result.append(p arent)
return result
class AbstractBaseCla ss(object):
"""
The AbstractBaseCla ss represents a class that defines some methods
which must be implemented by non-abstract children. To use it, have
your
class inhereit from AbstractBaseCla ss 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 AbstractBaseCla ss.

If any class which does not DIRECTLY inherit from
AbstractBaseCla ss, but
does INDIRECTLY inherit from AbstractBaseCla ss 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_a bstract__ =
True
and klass will no longer enforce the Abstract limitations.

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

>>class abstract(Abstra ctBaseClass): # this will be the AbstractBaseCla ss

.... @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__.abstr act'>].

>>class concrete(abstra ct): # 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(Abs tractBaseClass) :

.... @Abstract
.... def Drive(self): pass
....

>>class AbstractFastCar (AbstractCar,Ab stractBaseClass ):# 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(Abstract FastCar):
.... def DriveFast(self) : pass
.... except AssertionError, e:
.... print str(e)
Class <class '__main__.BadCa r'must override Drive to implement:
[<class '__main__.Abstr actFastCar'>].

>>try:#breaks since you don't implement DriveFast required by AbstractFastCar

.... class BadCar(Abstract FastCar):
.... def Drive(self): pass
.... except AssertionError, e:
.... print str(e)
Class <class '__main__.BadCa r'must override DriveFast to implement:
[<class '__main__.Abstr actFastCar'>].

>>class FastCar(Abstrac tFastCar): # 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(Abstra ctBaseClass):

.... @Abstract
.... def foo(self,x): pass

>>abstract.__al low_abstract__ = True # turn of all checking
class fails(abstract) : pass # define a class failing requirements
fails().foo(' ignore') # call its abstract method
abstract.__al low_abstract__ = False # turn checking back on
try:

.... class bad(abstract): pass
.... except AssertionError, e:
.... print str(e)
Class <class '__main__.bad'm ust override foo to implement:
[<class '__main__.abstr act'>].
You can even use multiple inheritence to combine abstractions:

>>class AbstractCar(Abs tractBaseClass) :

.... @Abstract
.... def Drive(self): pass
....

>>class AbstractPlane(A bstractBaseClas s):

.... @Abstract
.... def Fly(self): pass
....

>>class AbstractFlyingC ar(AbstractCar, AbstractPlane,A bstractBaseClas s): pass
try:

.... class Car(AbstractFly ingCar):
.... def Drive(self): pass
.... except AssertionError, e:
.... print 'not right'
not right

>>class FlyingCar(Abstr actFlyingCar):

.... 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 AbstractFlyingC ar.
class FlyingCar(Abstr actCar,Abstract Plane):

.... def Fly(self): pass
.... def Drive(self): pass

"""
__metaclass__ = _AbstractMetaCl ass
__intended_abst ract__ = 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 AbstractBaseCla ss for how to use this
decorator.
"""
if (__debug__):
def wrapper(*_args, **_kw):
result = func(*_args,**_ kw)
assert getattr(_args[0],'__allow_abstr act__',False), (
'Called Abstract method %s. Override %s; %s.' % (
func.__name__,f unc.__name__,"d on't call it directly"))
return result
wrapper.__dict_ _ = func.__dict__
wrapper.__name_ _ = func.__name__
wrapper.__doc__ = func.__doc__
wrapper.__abstr act__ = True
return wrapper
else:
return func

def _regr_test_chil dren():
"""
Regression test to make sure things work properly with more
complicated inheritence for AbstractBaseCla ss.

>>class abstract(Abstra ctBaseClass): # this will be the AbstractBaseCla ss

.... @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(partia l,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_wrap ping():
"""
Regression test to make sure that @Abstract decorator works
properly.

>>class abstract(Abstra ctBaseClass):

.... @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__.abstr act'>
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.__al low_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.'