E
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 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:
.... @Abstract
.... def foo(self,x): pass # declared abstract even though we def it
here.... class fails(abstract): # an erroneous implementation of
abstract
.... pass # since it doesn't implment foo
.... except AssertionError, e:
.... print e
.... 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:
.... @Abstract
.... def Drive(self): pass
........ @Abstract # so that
interpreter
.... def DriveFast(self): pass # doesn't
worry about
.... # Drive being
abstract.... class BadCar(AbstractFastCar):
.... def DriveFast(self): pass
.... except AssertionError, e:
.... print str(e)
.... class BadCar(AbstractFastCar):
.... def Drive(self): pass
.... except AssertionError, e:
.... print str(e)
.... def Drive(self): pass
.... def DriveFast(self): pass
If you don't like someone elses abstraction requirements, you
can
easily turn checking of the @Abstract requirements on and off.
.... @Abstract
.... def foo(self,x): pass.... 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:
.... @Abstract
.... def Drive(self): pass
........ @Abstract
.... def Fly(self): pass
........ class Car(AbstractFlyingCar):
.... def Drive(self): pass
.... except AssertionError, e:
.... print 'not right'
not right.... def Fly(self): pass
.... def Drive(self): pass.... 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.
.... @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.').... def foo(self,x):
.... return x+2.... def bar(self,y):
.... return y+3.... 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.
.... @Abstract
.... def foo(self,x):
.... 'docstring for foo'
........ a = abstract()
.... except AssertionError, e:
.... print str(e)
Cannot instantiate abstract base class <class '__main__.abstract'>
because the follwoing methods are still abstract:
['foo'].... a = object.__new__(abstract)
.... a.foo(1)
.... except AssertionError, e:
.... print str(e)
Called Abstract method foo. Override foo; don't call it directly. """
def _test():
import doctest
doctest.testmod()
if __name__ == "__main__":
_test()
print 'Test finished.'
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:
.... @Abstract
.... def foo(self,x): pass # declared abstract even though we def it
here.... class fails(abstract): # an erroneous implementation of
abstract
.... pass # since it doesn't implment foo
.... except AssertionError, e:
.... print e
.... 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:
.... @Abstract
.... def Drive(self): pass
........ @Abstract # so that
interpreter
.... def DriveFast(self): pass # doesn't
worry about
.... # Drive being
abstract.... class BadCar(AbstractFastCar):
.... def DriveFast(self): pass
.... except AssertionError, e:
.... print str(e)
.... class BadCar(AbstractFastCar):
.... def Drive(self): pass
.... except AssertionError, e:
.... print str(e)
.... def Drive(self): pass
.... def DriveFast(self): pass
If you don't like someone elses abstraction requirements, you
can
easily turn checking of the @Abstract requirements on and off.
.... @Abstract
.... def foo(self,x): pass.... 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:
.... @Abstract
.... def Drive(self): pass
........ @Abstract
.... def Fly(self): pass
........ class Car(AbstractFlyingCar):
.... def Drive(self): pass
.... except AssertionError, e:
.... print 'not right'
not right.... def Fly(self): pass
.... def Drive(self): pass.... 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.
.... @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.').... def foo(self,x):
.... return x+2.... def bar(self,y):
.... return y+3.... 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.
.... @Abstract
.... def foo(self,x):
.... 'docstring for foo'
........ a = abstract()
.... except AssertionError, e:
.... print str(e)
Cannot instantiate abstract base class <class '__main__.abstract'>
because the follwoing methods are still abstract:
['foo'].... a = object.__new__(abstract)
.... a.foo(1)
.... except AssertionError, e:
.... print str(e)
Called Abstract method foo. Override foo; don't call it directly. """
def _test():
import doctest
doctest.testmod()
if __name__ == "__main__":
_test()
print 'Test finished.'