Acknowledgements

Talin wrote the Rationale below[1] as well as most of the section onABCs vs. Interfaces. For that alone he deserves co-authorship. Therest of the PEP uses “I” referring to the first author.

Overloadingisinstance() andissubclass()

During the development of this PEP and of its companion,PEP 3141, werepeatedly faced the choice between standardizing more, fine-grainedABCs or fewer, coarse-grained ones. For example, at one stage, PEP3141 introduced the following stack of base classes used for complexnumbers: MonoidUnderPlus, AdditiveGroup, Ring, Field, Complex (eachderived from the previous). And the discussion mentioned severalother algebraic categorizations that were left out: Algebraic,Transcendental, and IntegralDomain, and PrincipalIdealDomain. Inearlier versions of the current PEP, we considered the use cases forseparate classes like Set, ComposableSet, MutableSet, HashableSet,MutableComposableSet, HashableComposableSet.

The dilemma here is that we’d rather have fewer ABCs, but then whatshould a user do who needs a less refined ABC? Consider e.g. theplight of a mathematician who wants to define their own kind ofTranscendental numbers, but also wants float and int to be consideredTranscendental.PEP 3141 originally proposed to patch float.__bases__for that purpose, but there are some good reasons to keep the built-intypes immutable (for one, they are shared between all Pythoninterpreters running in the same address space, as is used bymod_python[16]).

Another example would be someone who wants to define a genericfunction (PEP 3124) for any sequence that has anappend() method.TheSequence ABC (see below) doesn’t promise theappend()method, whileMutableSequence requires not onlyappend() butalso various other mutating methods.

To solve these and similar dilemmas, the next section will propose ametaclass for use with ABCs that will allow us to add an ABC as a“virtual base class” (not the same concept as in C++) to any class,including to another ABC. This allows the standard library to defineABCsSequence andMutableSequence and register these asvirtual base classes for built-in types likebasestring,tupleandlist, so that for example the following conditions are alltrue:

isinstance([],Sequence)issubclass(list,Sequence)issubclass(list,MutableSequence)isinstance((),Sequence)notissubclass(tuple,MutableSequence)isinstance("",Sequence)issubclass(bytearray,MutableSequence)

The primary mechanism proposed here is to allow overloading thebuilt-in functionsisinstance() andissubclass(). Theoverloading works as follows: The callisinstance(x,C) firstchecks whetherC.__instancecheck__ exists, and if so, callsC.__instancecheck__(x) instead of its normal implementation.Similarly, the callissubclass(D,C) first checks whetherC.__subclasscheck__ exists, and if so, callsC.__subclasscheck__(D) instead of its normal implementation.

Note that the magic names are not__isinstance__ and__issubclass__; this is because the reversal of the argumentscould cause confusion, especially for theissubclass() overloader.

A prototype implementation of this is given in[12].

Here is an example with (naively simple) implementations of__instancecheck__ and__subclasscheck__:

classABCMeta(type):def__instancecheck__(cls,inst):"""Implement isinstance(inst, cls)."""returnany(cls.__subclasscheck__(c)forcin{type(inst),inst.__class__})def__subclasscheck__(cls,sub):"""Implement issubclass(sub, cls)."""candidates=cls.__dict__.get("__subclass__",set())|{cls}returnany(cincandidatesforcinsub.mro())classSequence(metaclass=ABCMeta):__subclass__={list,tuple}assertissubclass(list,Sequence)assertissubclass(tuple,Sequence)classAppendableSequence(Sequence):__subclass__={list}assertissubclass(list,AppendableSequence)assertisinstance([],AppendableSequence)assertnotissubclass(tuple,AppendableSequence)assertnotisinstance((),AppendableSequence)

The next section proposes a full-fledged implementation.

Theabc Module: an ABC Support Framework

The new standard library moduleabc, written in pure Python,serves as an ABC support framework. It defines a metaclassABCMeta and decorators@abstractmethod and@abstractproperty. A sample implementation is given by[13].

TheABCMeta class overrides__instancecheck__ and__subclasscheck__ and defines aregister method. Theregister method takes one argument, which must be a class; afterthe callB.register(C), the callissubclass(C,B) will returnTrue, by virtue ofB.__subclasscheck__(C) returning True.Also,isinstance(x,B) is equivalent toissubclass(x.__class__,B)orissubclass(type(x),B). (It is possibletype(x) andx.__class__ are not the same object, e.g. when x is a proxyobject.)

These methods are intended to be called on classes whose metaclassis (derived from)ABCMeta; for example:

fromabcimportABCMetaclassMyABC(metaclass=ABCMeta):passMyABC.register(tuple)assertissubclass(tuple,MyABC)assertisinstance((),MyABC)

The last two asserts are equivalent to the following two:

assertMyABC.__subclasscheck__(tuple)assertMyABC.__instancecheck__(())

Of course, you can also directly subclass MyABC:

classMyClass(MyABC):passassertissubclass(MyClass,MyABC)assertisinstance(MyClass(),MyABC)

Also, of course, a tuple is not aMyClass:

assertnotissubclass(tuple,MyClass)assertnotisinstance((),MyClass)

You can register another class as a subclass ofMyClass:

MyClass.register(list)assertissubclass(list,MyClass)assertissubclass(list,MyABC)

You can also register another ABC:

classAnotherClass(metaclass=ABCMeta):passAnotherClass.register(basestring)MyClass.register(AnotherClass)assertisinstance(str,MyABC)

That last assert requires tracing the following superclass-subclassrelationships:

MyABC->MyClass(usingregularsubclassing)MyClass->AnotherClass(usingregistration)AnotherClass->basestring(usingregistration)basestring->str(usingregularsubclassing)

Theabc module also defines a new decorator,@abstractmethod,to be used to declare abstract methods. A class containing at leastone method declared with this decorator that hasn’t been overriddenyet cannot be instantiated. Such methods may be called from theoverriding method in the subclass (usingsuper or directinvocation). For example:

fromabcimportABCMeta,abstractmethodclassA(metaclass=ABCMeta):@abstractmethoddeffoo(self):passA()# raises TypeErrorclassB(A):passB()# raises TypeErrorclassC(A):deffoo(self):print(42)C()# works

Note: The@abstractmethod decorator should only be usedinside a class body, and only for classes whose metaclass is (derivedfrom)ABCMeta. Dynamically adding abstract methods to a class, orattempting to modify the abstraction status of a method or class onceit is created, are not supported. The@abstractmethod onlyaffects subclasses derived using regular inheritance; “virtualsubclasses” registered with theregister() method are not affected.

Implementation: The@abstractmethod decorator sets thefunction attribute__isabstractmethod__ to the valueTrue.TheABCMeta.__new__ method computes the type attribute__abstractmethods__ as the set of all method names that have an__isabstractmethod__ attribute whose value is true. It does thisby combining the__abstractmethods__ attributes of the baseclasses, adding the names of all methods in the new class dict thathave a true__isabstractmethod__ attribute, and removing the namesof all methods in the new class dict that don’t have a true__isabstractmethod__ attribute. If the resulting__abstractmethods__ set is non-empty, the class is consideredabstract, and attempts to instantiate it will raiseTypeError.(If this were implemented in CPython, an internal flagPy_TPFLAGS_ABSTRACT could be used to speed up this check[6].)

Discussion: Unlike Java’s abstract methods or C++’s pure abstractmethods, abstract methods as defined here may have an implementation.This implementation can be called via thesuper mechanism from theclass that overrides it. This could be useful as an end-point for asuper-call in framework using cooperative multiple-inheritance[7],[8].

A second decorator,@abstractproperty, is defined in order todefine abstract data attributes. Its implementation is a subclass ofthe built-inproperty class that adds an__isabstractmethod__attribute:

classabstractproperty(property):__isabstractmethod__=True

It can be used in two ways:

classC(metaclass=ABCMeta):# A read-only property:@abstractpropertydefreadonly(self):returnself.__x# A read-write property (cannot use decorator syntax):defgetx(self):returnself.__xdefsetx(self,value):self.__x=valuex=abstractproperty(getx,setx)

Similar to abstract methods, a subclass inheriting an abstractproperty (declared using either the decorator syntax or the longerform) cannot be instantiated unless it overrides that abstractproperty with a concrete property.

ABCs for Containers and Iterators

Thecollections module will define ABCs necessary and sufficientto work with sets, mappings, sequences, and some helper types such asiterators and dictionary views. All ABCs have the above-mentionedABCMeta as their metaclass.

The ABCs provide implementations of their abstract methods that aretechnically valid but fairly useless; e.g.__hash__ returns 0, and__iter__ returns an empty iterator. In general, the abstractmethods represent the behavior of an empty container of the indicatedtype.

Some ABCs also provide concrete (i.e. non-abstract) methods; forexample, theIterator class has an__iter__ method returningitself, fulfilling an important invariant of iterators (which inPython 2 has to be implemented anew by each iterator class). TheseABCs can be considered “mix-in” classes.

No ABCs defined in the PEP override__init__,__new__,__str__ or__repr__. Defining a standard constructorsignature would unnecessarily constrain custom container types, forexample Patricia trees or gdbm files. Defining a specific stringrepresentation for a collection is similarly left up to individualimplementations.

Note: There are no ABCs for ordering operations (__lt__,__le__,__ge__,__gt__). Defining these in a base class(abstract or not) runs into problems with the accepted type for thesecond operand. For example, if classOrdering defined__lt__, one would assume that for anyOrdering instancesxandy,x<y would be defined (even if it just defines apartial ordering). But this cannot be the case: If bothlist andstr derived fromOrdering, this would imply that[1,2]<(1,2) should be defined (and presumably return False), while infact (in Python 3000!) such “mixed-mode comparisons” operations areexplicitly forbidden and raiseTypeError. SeePEP 3100 and[14]for more information. (This is a special case of a more general issuewith operations that take another argument of the same type).

classSized(metaclass=ABCMeta):@abstractmethoddef__hash__(self):return0@classmethoddef__instancecheck__(cls,x):returnhasattr(x,"__len__")@classmethoddef__subclasscheck__(cls,C):returnhasattr(C,"__bases__")andhasattr(C,"__len__")

Strings

Python 3000 will likely have at least two built-in string types: bytestrings (bytes), deriving fromMutableSequence, and (Unicode)character strings (str), deriving fromSequence andHashable.

Open issues: define the base interfaces for these so alternativeimplementations and subclasses know what they are in for. This may bethe subject of a new PEP or PEPs (PEP 358 should be co-opted for thebytes type).

ABCs vs. Duck Typing

Does the introduction of ABCs mean the end of Duck Typing? I don’tthink so. Python will not require that a class derives fromBasicMapping orSequence when it defines a__getitem__method, nor will thex[y] syntax require thatx is an instanceof either ABC. You will still be able to assign any “file-like”object tosys.stdout, as long as it has awrite method.

Of course, there will be some carrots to encourage users to derivefrom the appropriate base classes; these vary from defaultimplementations for certain functionality to an improved ability todistinguish between mappings and sequences. But there are no sticks.Ifhasattr(x,"__len__") works for you, great! ABCs are intended tosolve problems that don’t have a good solution at all in Python 2,such as distinguishing between mappings and sequences.

ABCs vs. Generic Functions

ABCs are compatible with Generic Functions (GFs). For example, my ownGeneric Functions implementation[4] uses the classes (types) of thearguments as the dispatch key, allowing derived classes to overridebase classes. Since (from Python’s perspective) ABCs are quiteordinary classes, using an ABC in the default implementation for a GFcan be quite appropriate. For example, if I have an overloadedprettyprint function, it would make total sense to definepretty-printing of sets like this:

@prettyprint.register(Set)defpp_set(s):return"{"+...+"}"# Details left as an exercise

and implementations for specific subclasses of Set could be addedeasily.

I believe ABCs also won’t present any problems for RuleDispatch,Phillip Eby’s GF implementation in PEAK[5].

Of course, GF proponents might claim that GFs (and concrete, orimplementation, classes) are all you need. But even they will notdeny the usefulness of inheritance; and one can easily consider theABCs proposed in this PEP as optional implementation base classes;there is no requirement that all user-defined mappings derive fromBasicMapping.

ABCs vs. Interfaces

ABCs are not intrinsically incompatible with Interfaces, but there isconsiderable overlap. For now, I’ll leave it to proponents ofInterfaces to explain why Interfaces are better. I expect that muchof the work that went into e.g. defining the various shades of“mapping-ness” and the nomenclature could easily be adapted for aproposal to use Interfaces instead of ABCs.

“Interfaces” in this context refers to a set of proposals foradditional metadata elements attached to a class which are not part ofthe regular class hierarchy, but do allow for certain types ofinheritance testing.

Such metadata would be designed, at least in some proposals, so as tobe easily mutable by an application, allowing application writers tooverride the normal classification of an object.

The drawback to this idea of attaching mutable metadata to a class isthat classes are shared state, and mutating them may lead to conflictsof intent. Additionally, the need to override the classification ofan object can be done more cleanly using generic functions: In thesimplest case, one can define a “category membership” generic functionthat simply returns False in the base implementation, and then provideoverrides that return True for any classes of interest.