CINXE.COM

<!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <meta name="color-scheme" content="light dark"> <title>PEP 3119 – Introducing Abstract Base Classes | peps.python.org</title> <link rel="shortcut icon" href="../_static/py.png"> <link rel="canonical" href="https://peps.python.org/pep-3119/"> <link rel="stylesheet" href="../_static/style.css" type="text/css"> <link rel="stylesheet" href="../_static/mq.css" type="text/css"> <link rel="stylesheet" href="../_static/pygments.css" type="text/css" media="(prefers-color-scheme: light)" id="pyg-light"> <link rel="stylesheet" href="../_static/pygments_dark.css" type="text/css" media="(prefers-color-scheme: dark)" id="pyg-dark"> <link rel="alternate" type="application/rss+xml" title="Latest PEPs" href="https://peps.python.org/peps.rss"> <meta property="og:title" content='PEP 3119 – Introducing Abstract Base Classes | peps.python.org'> <meta property="og:description" content="This is a proposal to add Abstract Base Class (ABC) support to Python 3000. It proposes:"> <meta property="og:type" content="website"> <meta property="og:url" content="https://peps.python.org/pep-3119/"> <meta property="og:site_name" content="Python Enhancement Proposals (PEPs)"> <meta property="og:image" content="https://peps.python.org/_static/og-image.png"> <meta property="og:image:alt" content="Python PEPs"> <meta property="og:image:width" content="200"> <meta property="og:image:height" content="200"> <meta name="description" content="This is a proposal to add Abstract Base Class (ABC) support to Python 3000. It proposes:"> <meta name="theme-color" content="#3776ab"> </head> <body> <svg xmlns="http://www.w3.org/2000/svg" style="display: none;"> <symbol id="svg-sun-half" viewBox="0 0 24 24" pointer-events="all"> <title>Following system colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <circle cx="12" cy="12" r="9"></circle> <path d="M12 3v18m0-12l4.65-4.65M12 14.3l7.37-7.37M12 19.6l8.85-8.85"></path> </svg> </symbol> <symbol id="svg-moon" viewBox="0 0 24 24" pointer-events="all"> <title>Selected dark colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <path stroke="none" d="M0 0h24v24H0z" fill="none"></path> <path d="M12 3c.132 0 .263 0 .393 0a7.5 7.5 0 0 0 7.92 12.446a9 9 0 1 1 -8.313 -12.454z"></path> </svg> </symbol> <symbol id="svg-sun" viewBox="0 0 24 24" pointer-events="all"> <title>Selected light colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <circle cx="12" cy="12" r="5"></circle> <line x1="12" y1="1" x2="12" y2="3"></line> <line x1="12" y1="21" x2="12" y2="23"></line> <line x1="4.22" y1="4.22" x2="5.64" y2="5.64"></line> <line x1="18.36" y1="18.36" x2="19.78" y2="19.78"></line> <line x1="1" y1="12" x2="3" y2="12"></line> <line x1="21" y1="12" x2="23" y2="12"></line> <line x1="4.22" y1="19.78" x2="5.64" y2="18.36"></line> <line x1="18.36" y1="5.64" x2="19.78" y2="4.22"></line> </svg> </symbol> </svg> <script> document.documentElement.dataset.colour_scheme = localStorage.getItem("colour_scheme") || "auto" </script> <section id="pep-page-section"> <header> <h1>Python Enhancement Proposals</h1> <ul class="breadcrumbs"> <li><a href="https://www.python.org/" title="The Python Programming Language">Python</a> » </li> <li><a href="../pep-0000/">PEP Index</a> » </li> <li>PEP 3119</li> </ul> <button id="colour-scheme-cycler" onClick="setColourScheme(nextColourScheme())"> <svg aria-hidden="true" class="colour-scheme-icon-when-auto"><use href="#svg-sun-half"></use></svg> <svg aria-hidden="true" class="colour-scheme-icon-when-dark"><use href="#svg-moon"></use></svg> <svg aria-hidden="true" class="colour-scheme-icon-when-light"><use href="#svg-sun"></use></svg> Toggle light / dark / auto colour theme </button> </header> <article> <section id="pep-content"> <h1 class="page-title">PEP 3119 – Introducing Abstract Base Classes</h1> <dl class="rfc2822 field-list simple"> <dt class="field-odd">Author:</dt> <dd class="field-odd">Guido van Rossum <guido at python.org>, Talin <viridia at gmail.com></dd> <dt class="field-even">Status:</dt> <dd class="field-even"><abbr title="Accepted and implementation complete, or no longer active">Final</abbr></dd> <dt class="field-odd">Type:</dt> <dd class="field-odd"><abbr title="Normative PEP with a new feature for Python, implementation change for CPython or interoperability standard for the ecosystem">Standards Track</abbr></dd> <dt class="field-even">Created:</dt> <dd class="field-even">18-Apr-2007</dd> <dt class="field-odd">Python-Version:</dt> <dd class="field-odd">3.0</dd> <dt class="field-even">Post-History:</dt> <dd class="field-even">26-Apr-2007, 11-May-2007</dd> </dl> <hr class="docutils" /> <section id="contents"> <details><summary>Table of Contents</summary><ul class="simple"> <li><a class="reference internal" href="#abstract">Abstract</a><ul> <li><a class="reference internal" href="#acknowledgements">Acknowledgements</a></li> </ul> </li> <li><a class="reference internal" href="#rationale">Rationale</a></li> <li><a class="reference internal" href="#specification">Specification</a><ul> <li><a class="reference internal" href="#overloading-isinstance-and-issubclass">Overloading <code class="docutils literal notranslate">isinstance()</code> and <code class="docutils literal notranslate">issubclass()</code></a></li> <li><a class="reference internal" href="#the-abc-module-an-abc-support-framework">The <code class="docutils literal notranslate">abc</code> Module: an ABC Support Framework</a></li> <li><a class="reference internal" href="#abcs-for-containers-and-iterators">ABCs for Containers and Iterators</a><ul> <li><a class="reference internal" href="#one-trick-ponies">One Trick Ponies</a></li> <li><a class="reference internal" href="#sets">Sets</a></li> <li><a class="reference internal" href="#mappings">Mappings</a></li> <li><a class="reference internal" href="#sequences">Sequences</a></li> </ul> </li> <li><a class="reference internal" href="#strings">Strings</a></li> </ul> </li> <li><a class="reference internal" href="#abcs-vs-alternatives">ABCs vs. Alternatives</a><ul> <li><a class="reference internal" href="#abcs-vs-duck-typing">ABCs vs. Duck Typing</a></li> <li><a class="reference internal" href="#abcs-vs-generic-functions">ABCs vs. Generic Functions</a></li> <li><a class="reference internal" href="#abcs-vs-interfaces">ABCs vs. Interfaces</a></li> </ul> </li> <li><a class="reference internal" href="#references">References</a></li> <li><a class="reference internal" href="#copyright">Copyright</a></li> </ul> </details></section> <section id="abstract"> <h2><a class="toc-backref" href="#abstract" role="doc-backlink">Abstract</a></h2> This is a proposal to add Abstract Base Class (ABC) support to Python 3000. It proposes: <ul class="simple"> <li>A way to overload <code class="docutils literal notranslate">isinstance()</code> and <code class="docutils literal notranslate">issubclass()</code>.</li> <li>A new module <code class="docutils literal notranslate">abc</code> which serves as an “ABC support framework”. It defines a metaclass for use with ABCs and a decorator that can be used to define abstract methods.</li> <li>Specific ABCs for containers and iterators, to be added to the collections module.</li> </ul> Much of the thinking that went into the proposal is not about the specific mechanism of ABCs, as contrasted with Interfaces or Generic Functions (GFs), but about clarifying philosophical issues like “what makes a set”, “what makes a mapping” and “what makes a sequence”. There’s also a companion <a class="pep reference internal" href="../pep-3141/" title="PEP 3141 – A Type Hierarchy for Numbers">PEP 3141</a>, which defines ABCs for numeric types. <section id="acknowledgements"> <h3><a class="toc-backref" href="#acknowledgements" role="doc-backlink">Acknowledgements</a></h3> Talin wrote the Rationale below <a class="footnote-reference brackets" href="#id13" id="id1">[1]</a> as well as most of the section on ABCs vs. Interfaces. For that alone he deserves co-authorship. The rest of the PEP uses “I” referring to the first author. </section> </section> <section id="rationale"> <h2><a class="toc-backref" href="#rationale" role="doc-backlink">Rationale</a></h2> In the domain of object-oriented programming, the usage patterns for interacting with an object can be divided into two basic categories, which are ‘invocation’ and ‘inspection’. Invocation means interacting with an object by invoking its methods. Usually this is combined with polymorphism, so that invoking a given method may run different code depending on the type of an object. Inspection means the ability for external code (outside of the object’s methods) to examine the type or properties of that object, and make decisions on how to treat that object based on that information. Both usage patterns serve the same general end, which is to be able to support the processing of diverse and potentially novel objects in a uniform way, but at the same time allowing processing decisions to be customized for each different type of object. In classical OOP theory, invocation is the preferred usage pattern, and inspection is actively discouraged, being considered a relic of an earlier, procedural programming style. However, in practice this view is simply too dogmatic and inflexible, and leads to a kind of design rigidity that is very much at odds with the dynamic nature of a language like Python. In particular, there is often a need to process objects in a way that wasn’t anticipated by the creator of the object class. It is not always the best solution to build in to every object methods that satisfy the needs of every possible user of that object. Moreover, there are many powerful dispatch philosophies that are in direct contrast to the classic OOP requirement of behavior being strictly encapsulated within an object, examples being rule or pattern-match driven logic. On the other hand, one of the criticisms of inspection by classic OOP theorists is the lack of formalisms and the ad hoc nature of what is being inspected. In a language such as Python, in which almost any aspect of an object can be reflected and directly accessed by external code, there are many different ways to test whether an object conforms to a particular protocol or not. For example, if asking ‘is this object a mutable sequence container?’, one can look for a base class of ‘list’, or one can look for a method named ‘__getitem__’. But note that although these tests may seem obvious, neither of them are correct, as one generates false negatives, and the other false positives. The generally agreed-upon remedy is to standardize the tests, and group them into a formal arrangement. This is most easily done by associating with each class a set of standard testable properties, either via the inheritance mechanism or some other means. Each test carries with it a set of promises: it contains a promise about the general behavior of the class, and a promise as to what other class methods will be available. This PEP proposes a particular strategy for organizing these tests known as Abstract Base Classes, or ABC. ABCs are simply Python classes that are added into an object’s inheritance tree to signal certain features of that object to an external inspector. Tests are done using <code class="docutils literal notranslate">isinstance()</code>, and the presence of a particular ABC means that the test has passed. In addition, the ABCs define a minimal set of methods that establish the characteristic behavior of the type. Code that discriminates objects based on their ABC type can trust that those methods will always be present. Each of these methods are accompanied by an generalized abstract semantic definition that is described in the documentation for the ABC. These standard semantic definitions are not enforced, but are strongly recommended. Like all other things in Python, these promises are in the nature of a friendly agreement, which in this case means that while the language does enforce some of the promises made in the ABC, it is up to the implementer of the concrete class to insure that the remaining ones are kept. </section> <section id="specification"> <h2><a class="toc-backref" href="#specification" role="doc-backlink">Specification</a></h2> The specification follows the categories listed in the abstract: <ul class="simple"> <li>A way to overload <code class="docutils literal notranslate">isinstance()</code> and <code class="docutils literal notranslate">issubclass()</code>.</li> <li>A new module <code class="docutils literal notranslate">abc</code> which serves as an “ABC support framework”. It defines a metaclass for use with ABCs and a decorator that can be used to define abstract methods.</li> <li>Specific ABCs for containers and iterators, to be added to the collections module.</li> </ul> <section id="overloading-isinstance-and-issubclass"> <h3><a class="toc-backref" href="#overloading-isinstance-and-issubclass" role="doc-backlink">Overloading <code class="docutils literal notranslate">isinstance()</code> and <code class="docutils literal notranslate">issubclass()</code></a></h3> During the development of this PEP and of its companion, <a class="pep reference internal" href="../pep-3141/" title="PEP 3141 – A Type Hierarchy for Numbers">PEP 3141</a>, we repeatedly faced the choice between standardizing more, fine-grained ABCs or fewer, coarse-grained ones. For example, at one stage, PEP 3141 introduced the following stack of base classes used for complex numbers: MonoidUnderPlus, AdditiveGroup, Ring, Field, Complex (each derived from the previous). And the discussion mentioned several other algebraic categorizations that were left out: Algebraic, Transcendental, and IntegralDomain, and PrincipalIdealDomain. In earlier versions of the current PEP, we considered the use cases for separate classes like Set, ComposableSet, MutableSet, HashableSet, MutableComposableSet, HashableComposableSet. The dilemma here is that we’d rather have fewer ABCs, but then what should a user do who needs a less refined ABC? Consider e.g. the plight of a mathematician who wants to define their own kind of Transcendental numbers, but also wants float and int to be considered Transcendental. <a class="pep reference internal" href="../pep-3141/" title="PEP 3141 – A Type Hierarchy for Numbers">PEP 3141</a> originally proposed to patch float.__bases__ for that purpose, but there are some good reasons to keep the built-in types immutable (for one, they are shared between all Python interpreters running in the same address space, as is used by mod_python <a class="footnote-reference brackets" href="#id24" id="id2">[16]</a>). Another example would be someone who wants to define a generic function (<a class="pep reference internal" href="../pep-3124/" title="PEP 3124 – Overloading, Generic Functions, Interfaces, and Adaptation">PEP 3124</a>) for any sequence that has an <code class="docutils literal notranslate">append()</code> method. The <code class="docutils literal notranslate">Sequence</code> ABC (see below) doesn’t promise the <code class="docutils literal notranslate">append()</code> method, while <code class="docutils literal notranslate">MutableSequence</code> requires not only <code class="docutils literal notranslate">append()</code> but also various other mutating methods. To solve these and similar dilemmas, the next section will propose a metaclass 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 define ABCs <code class="docutils literal notranslate">Sequence</code> and <code class="docutils literal notranslate">MutableSequence</code> and register these as virtual base classes for built-in types like <code class="docutils literal notranslate">basestring</code>, <code class="docutils literal notranslate">tuple</code> and <code class="docutils literal notranslate">list</code>, so that for example the following conditions are all true: <div class="highlight-default notranslate"><div class="highlight"><pre>isinstance([], Sequence) issubclass(list, Sequence) issubclass(list, MutableSequence) isinstance((), Sequence) not issubclass(tuple, MutableSequence) isinstance("", Sequence) issubclass(bytearray, MutableSequence) </pre></div> </div> The primary mechanism proposed here is to allow overloading the built-in functions <code class="docutils literal notranslate">isinstance()</code> and <code class="docutils literal notranslate">issubclass()</code>. The overloading works as follows: The call <code class="docutils literal notranslate">isinstance(x, C)</code> first checks whether <code class="docutils literal notranslate">C.__instancecheck__</code> exists, and if so, calls <code class="docutils literal notranslate">C.__instancecheck__(x)</code> instead of its normal implementation. Similarly, the call <code class="docutils literal notranslate">issubclass(D, C)</code> first checks whether <code class="docutils literal notranslate">C.__subclasscheck__</code> exists, and if so, calls <code class="docutils literal notranslate">C.__subclasscheck__(D)</code> instead of its normal implementation. Note that the magic names are not <code class="docutils literal notranslate">__isinstance__</code> and <code class="docutils literal notranslate">__issubclass__</code>; this is because the reversal of the arguments could cause confusion, especially for the <code class="docutils literal notranslate">issubclass()</code> overloader. A prototype implementation of this is given in <a class="footnote-reference brackets" href="#id20" id="id3">[12]</a>. Here is an example with (naively simple) implementations of <code class="docutils literal notranslate">__instancecheck__</code> and <code class="docutils literal notranslate">__subclasscheck__</code>: <div class="highlight-default notranslate"><div class="highlight"><pre>class ABCMeta(type): def __instancecheck__(cls, inst): """Implement isinstance(inst, cls).""" return any(cls.__subclasscheck__(c) for c in {type(inst), inst.__class__}) def __subclasscheck__(cls, sub): """Implement issubclass(sub, cls).""" candidates = cls.__dict__.get("__subclass__", set()) | {cls} return any(c in candidates for c in sub.mro()) class Sequence(metaclass=ABCMeta): __subclass__ = {list, tuple} assert issubclass(list, Sequence) assert issubclass(tuple, Sequence) class AppendableSequence(Sequence): __subclass__ = {list} assert issubclass(list, AppendableSequence) assert isinstance([], AppendableSequence) assert not issubclass(tuple, AppendableSequence) assert not isinstance((), AppendableSequence) </pre></div> </div> The next section proposes a full-fledged implementation. </section> <section id="the-abc-module-an-abc-support-framework"> <h3><a class="toc-backref" href="#the-abc-module-an-abc-support-framework" role="doc-backlink">The <code class="docutils literal notranslate">abc</code> Module: an ABC Support Framework</a></h3> The new standard library module <code class="docutils literal notranslate">abc</code>, written in pure Python, serves as an ABC support framework. It defines a metaclass <code class="docutils literal notranslate">ABCMeta</code> and decorators <code class="docutils literal notranslate">@abstractmethod</code> and <code class="docutils literal notranslate">@abstractproperty</code>. A sample implementation is given by <a class="footnote-reference brackets" href="#id21" id="id4">[13]</a>. The <code class="docutils literal notranslate">ABCMeta</code> class overrides <code class="docutils literal notranslate">__instancecheck__</code> and <code class="docutils literal notranslate">__subclasscheck__</code> and defines a <code class="docutils literal notranslate">register</code> method. The <code class="docutils literal notranslate">register</code> method takes one argument, which must be a class; after the call <code class="docutils literal notranslate">B.register(C)</code>, the call <code class="docutils literal notranslate">issubclass(C, B)</code> will return True, by virtue of <code class="docutils literal notranslate">B.__subclasscheck__(C)</code> returning True. Also, <code class="docutils literal notranslate">isinstance(x, B)</code> is equivalent to <code class="docutils literal notranslate">issubclass(x.__class__, B) or issubclass(type(x), B)</code>. (It is possible <code class="docutils literal notranslate">type(x)</code> and <code class="docutils literal notranslate">x.__class__</code> are not the same object, e.g. when x is a proxy object.) These methods are intended to be called on classes whose metaclass is (derived from) <code class="docutils literal notranslate">ABCMeta</code>; for example: <div class="highlight-default notranslate"><div class="highlight"><pre>from abc import ABCMeta class MyABC(metaclass=ABCMeta): pass MyABC.register(tuple) assert issubclass(tuple, MyABC) assert isinstance((), MyABC) </pre></div> </div> The last two asserts are equivalent to the following two: <div class="highlight-default notranslate"><div class="highlight"><pre>assert MyABC.__subclasscheck__(tuple) assert MyABC.__instancecheck__(()) </pre></div> </div> Of course, you can also directly subclass MyABC: <div class="highlight-default notranslate"><div class="highlight"><pre>class MyClass(MyABC): pass assert issubclass(MyClass, MyABC) assert isinstance(MyClass(), MyABC) </pre></div> </div> Also, of course, a tuple is not a <code class="docutils literal notranslate">MyClass</code>: <div class="highlight-default notranslate"><div class="highlight"><pre>assert not issubclass(tuple, MyClass) assert not isinstance((), MyClass) </pre></div> </div> You can register another class as a subclass of <code class="docutils literal notranslate">MyClass</code>: <div class="highlight-default notranslate"><div class="highlight"><pre>MyClass.register(list) assert issubclass(list, MyClass) assert issubclass(list, MyABC) </pre></div> </div> You can also register another ABC: <div class="highlight-default notranslate"><div class="highlight"><pre>class AnotherClass(metaclass=ABCMeta): pass AnotherClass.register(basestring) MyClass.register(AnotherClass) assert isinstance(str, MyABC) </pre></div> </div> That last assert requires tracing the following superclass-subclass relationships: <div class="highlight-default notranslate"><div class="highlight"><pre>MyABC -> MyClass (using regular subclassing) MyClass -> AnotherClass (using registration) AnotherClass -> basestring (using registration) basestring -> str (using regular subclassing) </pre></div> </div> The <code class="docutils literal notranslate">abc</code> module also defines a new decorator, <code class="docutils literal notranslate">@abstractmethod</code>, to be used to declare abstract methods. A class containing at least one method declared with this decorator that hasn’t been overridden yet cannot be instantiated. Such methods may be called from the overriding method in the subclass (using <code class="docutils literal notranslate">super</code> or direct invocation). For example: <div class="highlight-default notranslate"><div class="highlight"><pre>from abc import ABCMeta, abstractmethod class A(metaclass=ABCMeta): @abstractmethod def foo(self): pass A() # raises TypeError class B(A): pass B() # raises TypeError class C(A): def foo(self): print(42) C() # works </pre></div> </div> Note: The <code class="docutils literal notranslate">@abstractmethod</code> decorator should only be used inside a class body, and only for classes whose metaclass is (derived from) <code class="docutils literal notranslate">ABCMeta</code>. Dynamically adding abstract methods to a class, or attempting to modify the abstraction status of a method or class once it is created, are not supported. The <code class="docutils literal notranslate">@abstractmethod</code> only affects subclasses derived using regular inheritance; “virtual subclasses” registered with the <code class="docutils literal notranslate">register()</code> method are not affected. Implementation: The <code class="docutils literal notranslate">@abstractmethod</code> decorator sets the function attribute <code class="docutils literal notranslate">__isabstractmethod__</code> to the value <code class="docutils literal notranslate">True</code>. The <code class="docutils literal notranslate">ABCMeta.__new__</code> method computes the type attribute <code class="docutils literal notranslate">__abstractmethods__</code> as the set of all method names that have an <code class="docutils literal notranslate">__isabstractmethod__</code> attribute whose value is true. It does this by combining the <code class="docutils literal notranslate">__abstractmethods__</code> attributes of the base classes, adding the names of all methods in the new class dict that have a true <code class="docutils literal notranslate">__isabstractmethod__</code> attribute, and removing the names of all methods in the new class dict that don’t have a true <code class="docutils literal notranslate">__isabstractmethod__</code> attribute. If the resulting <code class="docutils literal notranslate">__abstractmethods__</code> set is non-empty, the class is considered abstract, and attempts to instantiate it will raise <code class="docutils literal notranslate">TypeError</code>. (If this were implemented in CPython, an internal flag <code class="docutils literal notranslate">Py_TPFLAGS_ABSTRACT</code> could be used to speed up this check <a class="footnote-reference brackets" href="#id16" id="id5">[6]</a>.) Discussion: Unlike Java’s abstract methods or C++’s pure abstract methods, abstract methods as defined here may have an implementation. This implementation can be called via the <code class="docutils literal notranslate">super</code> mechanism from the class that overrides it. This could be useful as an end-point for a super-call in framework using cooperative multiple-inheritance <a class="footnote-reference brackets" href="#id17" id="id6">[7]</a>, <a class="footnote-reference brackets" href="#id18" id="id7">[8]</a>. A second decorator, <code class="docutils literal notranslate">@abstractproperty</code>, is defined in order to define abstract data attributes. Its implementation is a subclass of the built-in <code class="docutils literal notranslate">property</code> class that adds an <code class="docutils literal notranslate">__isabstractmethod__</code> attribute: <div class="highlight-default notranslate"><div class="highlight"><pre>class abstractproperty(property): __isabstractmethod__ = True </pre></div> </div> It can be used in two ways: <div class="highlight-default notranslate"><div class="highlight"><pre>class C(metaclass=ABCMeta): # A read-only property: @abstractproperty def readonly(self): return self.__x # A read-write property (cannot use decorator syntax): def getx(self): return self.__x def setx(self, value): self.__x = value x = abstractproperty(getx, setx) </pre></div> </div> Similar to abstract methods, a subclass inheriting an abstract property (declared using either the decorator syntax or the longer form) cannot be instantiated unless it overrides that abstract property with a concrete property. </section> <section id="abcs-for-containers-and-iterators"> <h3><a class="toc-backref" href="#abcs-for-containers-and-iterators" role="doc-backlink">ABCs for Containers and Iterators</a></h3> The <code class="docutils literal notranslate">collections</code> module will define ABCs necessary and sufficient to work with sets, mappings, sequences, and some helper types such as iterators and dictionary views. All ABCs have the above-mentioned <code class="docutils literal notranslate">ABCMeta</code> as their metaclass. The ABCs provide implementations of their abstract methods that are technically valid but fairly useless; e.g. <code class="docutils literal notranslate">__hash__</code> returns 0, and <code class="docutils literal notranslate">__iter__</code> returns an empty iterator. In general, the abstract methods represent the behavior of an empty container of the indicated type. Some ABCs also provide concrete (i.e. non-abstract) methods; for example, the <code class="docutils literal notranslate">Iterator</code> class has an <code class="docutils literal notranslate">__iter__</code> method returning itself, fulfilling an important invariant of iterators (which in Python 2 has to be implemented anew by each iterator class). These ABCs can be considered “mix-in” classes. No ABCs defined in the PEP override <code class="docutils literal notranslate">__init__</code>, <code class="docutils literal notranslate">__new__</code>, <code class="docutils literal notranslate">__str__</code> or <code class="docutils literal notranslate">__repr__</code>. Defining a standard constructor signature would unnecessarily constrain custom container types, for example Patricia trees or gdbm files. Defining a specific string representation for a collection is similarly left up to individual implementations. Note: There are no ABCs for ordering operations (<code class="docutils literal notranslate">__lt__</code>, <code class="docutils literal notranslate">__le__</code>, <code class="docutils literal notranslate">__ge__</code>, <code class="docutils literal notranslate">__gt__</code>). Defining these in a base class (abstract or not) runs into problems with the accepted type for the second operand. For example, if class <code class="docutils literal notranslate">Ordering</code> defined <code class="docutils literal notranslate">__lt__</code>, one would assume that for any <code class="docutils literal notranslate">Ordering</code> instances <code class="docutils literal notranslate">x</code> and <code class="docutils literal notranslate">y</code>, <code class="docutils literal notranslate">x < y</code> would be defined (even if it just defines a partial ordering). But this cannot be the case: If both <code class="docutils literal notranslate">list</code> and <code class="docutils literal notranslate">str</code> derived from <code class="docutils literal notranslate">Ordering</code>, this would imply that <code class="docutils literal notranslate">[1, 2] < (1, 2)</code> should be defined (and presumably return False), while in fact (in Python 3000!) such “mixed-mode comparisons” operations are explicitly forbidden and raise <code class="docutils literal notranslate">TypeError</code>. See <a class="pep reference internal" href="../pep-3100/" title="PEP 3100 – Miscellaneous Python 3.0 Plans">PEP 3100</a> and <a class="footnote-reference brackets" href="#id22" id="id8">[14]</a> for more information. (This is a special case of a more general issue with operations that take another argument of the same type). <section id="one-trick-ponies"> <h4><a class="toc-backref" href="#one-trick-ponies" role="doc-backlink">One Trick Ponies</a></h4> These abstract classes represent single methods like <code class="docutils literal notranslate">__iter__</code> or <code class="docutils literal notranslate">__len__</code>. <dl> <dt><code class="docutils literal notranslate">Hashable</code></dt><dd>The base class for classes defining <code class="docutils literal notranslate">__hash__</code>. The <code class="docutils literal notranslate">__hash__</code> method should return an integer. The abstract <code class="docutils literal notranslate">__hash__</code> method always returns 0, which is a valid (albeit inefficient) implementation. Invariant: If classes <code class="docutils literal notranslate">C1</code> and <code class="docutils literal notranslate">C2</code> both derive from <code class="docutils literal notranslate">Hashable</code>, the condition <code class="docutils literal notranslate">o1 == o2</code> must imply <code class="docutils literal notranslate">hash(o1) == hash(o2)</code> for all instances <code class="docutils literal notranslate">o1</code> of <code class="docutils literal notranslate">C1</code> and all instances <code class="docutils literal notranslate">o2</code> of <code class="docutils literal notranslate">C2</code>. In other words, two objects should never compare equal if they have different hash values.Another constraint is that hashable objects, once created, should never change their value (as compared by <code class="docutils literal notranslate">==</code>) or their hash value. If a class cannot guarantee this, it should not derive from <code class="docutils literal notranslate">Hashable</code>; if it cannot guarantee this for certain instances, <code class="docutils literal notranslate">__hash__</code> for those instances should raise a <code class="docutils literal notranslate">TypeError</code> exception. Note: being an instance of this class does not imply that an object is immutable; e.g. a tuple containing a list as a member is not immutable; its <code class="docutils literal notranslate">__hash__</code> method raises <code class="docutils literal notranslate">TypeError</code>. (This is because it recursively tries to compute the hash of each member; if a member is unhashable it raises <code class="docutils literal notranslate">TypeError</code>.) </dd> <dt><code class="docutils literal notranslate">Iterable</code></dt><dd>The base class for classes defining <code class="docutils literal notranslate">__iter__</code>. The <code class="docutils literal notranslate">__iter__</code> method should always return an instance of <code class="docutils literal notranslate">Iterator</code> (see below). The abstract <code class="docutils literal notranslate">__iter__</code> method returns an empty iterator.</dd> <dt><code class="docutils literal notranslate">Iterator</code></dt><dd>The base class for classes defining <code class="docutils literal notranslate">__next__</code>. This derives from <code class="docutils literal notranslate">Iterable</code>. The abstract <code class="docutils literal notranslate">__next__</code> method raises <code class="docutils literal notranslate">StopIteration</code>. The concrete <code class="docutils literal notranslate">__iter__</code> method returns <code class="docutils literal notranslate">self</code>. Note the distinction between <code class="docutils literal notranslate">Iterable</code> and <code class="docutils literal notranslate">Iterator</code>: an <code class="docutils literal notranslate">Iterable</code> can be iterated over, i.e. supports the <code class="docutils literal notranslate">__iter__</code> methods; an <code class="docutils literal notranslate">Iterator</code> is what the built-in function <code class="docutils literal notranslate">iter()</code> returns, i.e. supports the <code class="docutils literal notranslate">__next__</code> method.</dd> <dt><code class="docutils literal notranslate">Sized</code></dt><dd>The base class for classes defining <code class="docutils literal notranslate">__len__</code>. The <code class="docutils literal notranslate">__len__</code> method should return an <code class="docutils literal notranslate">Integer</code> (see “Numbers” below) >= 0. The abstract <code class="docutils literal notranslate">__len__</code> method returns 0. Invariant: If a class <code class="docutils literal notranslate">C</code> derives from <code class="docutils literal notranslate">Sized</code> as well as from <code class="docutils literal notranslate">Iterable</code>, the invariant <code class="docutils literal notranslate">sum(1 for x in c) == len(c)</code> should hold for any instance <code class="docutils literal notranslate">c</code> of <code class="docutils literal notranslate">C</code>.</dd> <dt><code class="docutils literal notranslate">Container</code></dt><dd>The base class for classes defining <code class="docutils literal notranslate">__contains__</code>. The <code class="docutils literal notranslate">__contains__</code> method should return a <code class="docutils literal notranslate">bool</code>. The abstract <code class="docutils literal notranslate">__contains__</code> method returns <code class="docutils literal notranslate">False</code>. Invariant: If a class <code class="docutils literal notranslate">C</code> derives from <code class="docutils literal notranslate">Container</code> as well as from <code class="docutils literal notranslate">Iterable</code>, then <code class="docutils literal notranslate">(x in c for x in c)</code> should be a generator yielding only True values for any instance <code class="docutils literal notranslate">c</code> of <code class="docutils literal notranslate">C</code>.</dd> </dl> Open issues: Conceivably, instead of using the ABCMeta metaclass, these classes could override <code class="docutils literal notranslate">__instancecheck__</code> and <code class="docutils literal notranslate">__subclasscheck__</code> to check for the presence of the applicable special method; for example: <div class="highlight-default notranslate"><div class="highlight"><pre>class Sized(metaclass=ABCMeta): @abstractmethod def __hash__(self): return 0 @classmethod def __instancecheck__(cls, x): return hasattr(x, "__len__") @classmethod def __subclasscheck__(cls, C): return hasattr(C, "__bases__") and hasattr(C, "__len__") </pre></div> </div> This has the advantage of not requiring explicit registration. However, the semantics are hard to get exactly right given the confusing semantics of instance attributes vs. class attributes, and that a class is an instance of its metaclass; the check for <code class="docutils literal notranslate">__bases__</code> is only an approximation of the desired semantics. Strawman: Let’s do it, but let’s arrange it in such a way that the registration API also works. </section> <section id="sets"> <h4><a class="toc-backref" href="#sets" role="doc-backlink">Sets</a></h4> These abstract classes represent read-only sets and mutable sets. The most fundamental set operation is the membership test, written as <code class="docutils literal notranslate">x in s</code> and implemented by <code class="docutils literal notranslate">s.__contains__(x)</code>. This operation is already defined by the <code class="docutils literal notranslate">Container</code> class defined above. Therefore, we define a set as a sized, iterable container for which certain invariants from mathematical set theory hold. The built-in type <code class="docutils literal notranslate">set</code> derives from <code class="docutils literal notranslate">MutableSet</code>. The built-in type <code class="docutils literal notranslate">frozenset</code> derives from <code class="docutils literal notranslate">Set</code> and <code class="docutils literal notranslate">Hashable</code>. <dl> <dt><code class="docutils literal notranslate">Set</code></dt><dd>This is a sized, iterable container, i.e., a subclass of <code class="docutils literal notranslate">Sized</code>, <code class="docutils literal notranslate">Iterable</code> and <code class="docutils literal notranslate">Container</code>. Not every subclass of those three classes is a set though! Sets have the additional invariant that each element occurs only once (as can be determined by iteration), and in addition sets define concrete operators that implement the inequality operations as subset/superset tests. In general, the invariants for finite sets in mathematics hold. <a class="footnote-reference brackets" href="#id19" id="id9">[11]</a>Sets with different implementations can be compared safely, (usually) efficiently and correctly using the mathematical definitions of the subset/supeset operations for finite sets. The ordering operations have concrete implementations; subclasses may override these for speed but should maintain the semantics. Because <code class="docutils literal notranslate">Set</code> derives from <code class="docutils literal notranslate">Sized</code>, <code class="docutils literal notranslate">__eq__</code> may take a shortcut and return <code class="docutils literal notranslate">False</code> immediately if two sets of unequal length are compared. Similarly, <code class="docutils literal notranslate">__le__</code> may return <code class="docutils literal notranslate">False</code> immediately if the first set has more members than the second set. Note that set inclusion implements only a partial ordering; e.g. <code class="docutils literal notranslate">{1, 2}</code> and <code class="docutils literal notranslate">{1, 3}</code> are not ordered (all three of <code class="docutils literal notranslate"><</code>, <code class="docutils literal notranslate">==</code> and <code class="docutils literal notranslate">></code> return <code class="docutils literal notranslate">False</code> for these arguments). Sets cannot be ordered relative to mappings or sequences, but they can be compared to those for equality (and then they always compare unequal). This class also defines concrete operators to compute union, intersection, symmetric and asymmetric difference, respectively <code class="docutils literal notranslate">__or__</code>, <code class="docutils literal notranslate">__and__</code>, <code class="docutils literal notranslate">__xor__</code> and <code class="docutils literal notranslate">__sub__</code>. These operators should return instances of <code class="docutils literal notranslate">Set</code>. The default implementations call the overridable class method <code class="docutils literal notranslate">_from_iterable()</code> with an iterable argument. This factory method’s default implementation returns a <code class="docutils literal notranslate">frozenset</code> instance; it may be overridden to return another appropriate <code class="docutils literal notranslate">Set</code> subclass. Finally, this class defines a concrete method <code class="docutils literal notranslate">_hash</code> which computes the hash value from the elements. Hashable subclasses of <code class="docutils literal notranslate">Set</code> can implement <code class="docutils literal notranslate">__hash__</code> by calling <code class="docutils literal notranslate">_hash</code> or they can reimplement the same algorithm more efficiently; but the algorithm implemented should be the same. Currently the algorithm is fully specified only by the source code <a class="footnote-reference brackets" href="#id23" id="id10">[15]</a>. Note: the <code class="docutils literal notranslate">issubset</code> and <code class="docutils literal notranslate">issuperset</code> methods found on the set type in Python 2 are not supported, as these are mostly just aliases for <code class="docutils literal notranslate">__le__</code> and <code class="docutils literal notranslate">__ge__</code>. </dd> <dt><code class="docutils literal notranslate">MutableSet</code></dt><dd>This is a subclass of <code class="docutils literal notranslate">Set</code> implementing additional operations to add and remove elements. The supported methods have the semantics known from the <code class="docutils literal notranslate">set</code> type in Python 2 (except for <code class="docutils literal notranslate">discard</code>, which is modeled after Java):<dl class="simple"> <dt><code class="docutils literal notranslate">.add(x)</code></dt><dd>Abstract method returning a <code class="docutils literal notranslate">bool</code> that adds the element <code class="docutils literal notranslate">x</code> if it isn’t already in the set. It should return <code class="docutils literal notranslate">True</code> if <code class="docutils literal notranslate">x</code> was added, <code class="docutils literal notranslate">False</code> if it was already there. The abstract implementation raises <code class="docutils literal notranslate">NotImplementedError</code>.</dd> <dt><code class="docutils literal notranslate">.discard(x)</code></dt><dd>Abstract method returning a <code class="docutils literal notranslate">bool</code> that removes the element <code class="docutils literal notranslate">x</code> if present. It should return <code class="docutils literal notranslate">True</code> if the element was present and <code class="docutils literal notranslate">False</code> if it wasn’t. The abstract implementation raises <code class="docutils literal notranslate">NotImplementedError</code>.</dd> <dt><code class="docutils literal notranslate">.pop()</code></dt><dd>Concrete method that removes and returns an arbitrary item. If the set is empty, it raises <code class="docutils literal notranslate">KeyError</code>. The default implementation removes the first item returned by the set’s iterator.</dd> <dt><code class="docutils literal notranslate">.toggle(x)</code></dt><dd>Concrete method returning a <code class="docutils literal notranslate">bool</code> that adds x to the set if it wasn’t there, but removes it if it was there. It should return <code class="docutils literal notranslate">True</code> if <code class="docutils literal notranslate">x</code> was added, <code class="docutils literal notranslate">False</code> if it was removed.</dd> <dt><code class="docutils literal notranslate">.clear()</code></dt><dd>Concrete method that empties the set. The default implementation repeatedly calls <code class="docutils literal notranslate">self.pop()</code> until <code class="docutils literal notranslate">KeyError</code> is caught. (Note: this is likely much slower than simply creating a new set, even if an implementation overrides it with a faster approach; but in some cases object identity is important.)</dd> </dl> This also supports the in-place mutating operations <code class="docutils literal notranslate">|=</code>, <code class="docutils literal notranslate">&=</code>, <code class="docutils literal notranslate">^=</code>, <code class="docutils literal notranslate">-=</code>. These are concrete methods whose right operand can be an arbitrary <code class="docutils literal notranslate">Iterable</code>, except for <code class="docutils literal notranslate">&=</code>, whose right operand must be a <code class="docutils literal notranslate">Container</code>. This ABC does not provide the named methods present on the built-in concrete <code class="docutils literal notranslate">set</code> type that perform (almost) the same operations. </dd> </dl> </section> <section id="mappings"> <h4><a class="toc-backref" href="#mappings" role="doc-backlink">Mappings</a></h4> These abstract classes represent read-only mappings and mutable mappings. The <code class="docutils literal notranslate">Mapping</code> class represents the most common read-only mapping API. The built-in type <code class="docutils literal notranslate">dict</code> derives from <code class="docutils literal notranslate">MutableMapping</code>. <dl> <dt><code class="docutils literal notranslate">Mapping</code></dt><dd>A subclass of <code class="docutils literal notranslate">Container</code>, <code class="docutils literal notranslate">Iterable</code> and <code class="docutils literal notranslate">Sized</code>. The keys of a mapping naturally form a set. The (key, value) pairs (which must be tuples) are also referred to as items. The items also form a set. Methods:<dl class="simple"> <dt><code class="docutils literal notranslate">.__getitem__(key)</code></dt><dd>Abstract method that returns the value corresponding to <code class="docutils literal notranslate">key</code>, or raises <code class="docutils literal notranslate">KeyError</code>. The implementation always raises <code class="docutils literal notranslate">KeyError</code>.</dd> <dt><code class="docutils literal notranslate">.get(key, default=None)</code></dt><dd>Concrete method returning <code class="docutils literal notranslate">self[key]</code> if this does not raise <code class="docutils literal notranslate">KeyError</code>, and the <code class="docutils literal notranslate">default</code> value if it does.</dd> <dt><code class="docutils literal notranslate">.__contains__(key)</code></dt><dd>Concrete method returning <code class="docutils literal notranslate">True</code> if <code class="docutils literal notranslate">self[key]</code> does not raise <code class="docutils literal notranslate">KeyError</code>, and <code class="docutils literal notranslate">False</code> if it does.</dd> <dt><code class="docutils literal notranslate">.__len__()</code></dt><dd>Abstract method returning the number of distinct keys (i.e., the length of the key set).</dd> <dt><code class="docutils literal notranslate">.__iter__()</code></dt><dd>Abstract method returning each key in the key set exactly once.</dd> <dt><code class="docutils literal notranslate">.keys()</code></dt><dd>Concrete method returning the key set as a <code class="docutils literal notranslate">Set</code>. The default concrete implementation returns a “view” on the key set (meaning if the underlying mapping is modified, the view’s value changes correspondingly); subclasses are not required to return a view but they should return a <code class="docutils literal notranslate">Set</code>.</dd> <dt><code class="docutils literal notranslate">.items()</code></dt><dd>Concrete method returning the items as a <code class="docutils literal notranslate">Set</code>. The default concrete implementation returns a “view” on the item set; subclasses are not required to return a view but they should return a <code class="docutils literal notranslate">Set</code>.</dd> <dt><code class="docutils literal notranslate">.values()</code></dt><dd>Concrete method returning the values as a sized, iterable container (not a set!). The default concrete implementation returns a “view” on the values of the mapping; subclasses are not required to return a view but they should return a sized, iterable container.</dd> </dl> The following invariants should hold for any mapping <code class="docutils literal notranslate">m</code>: <div class="highlight-default notranslate"><div class="highlight"><pre>len(m.values()) == len(m.keys()) == len(m.items()) == len(m) [value for value in m.values()] == [m[key] for key in m.keys()] [item for item in m.items()] == [(key, m[key]) for key in m.keys()] </pre></div> </div> i.e. iterating over the items, keys and values should return results in the same order. </dd> <dt><code class="docutils literal notranslate">MutableMapping</code></dt><dd>A subclass of <code class="docutils literal notranslate">Mapping</code> that also implements some standard mutating methods. Abstract methods include <code class="docutils literal notranslate">__setitem__</code>, <code class="docutils literal notranslate">__delitem__</code>. Concrete methods include <code class="docutils literal notranslate">pop</code>, <code class="docutils literal notranslate">popitem</code>, <code class="docutils literal notranslate">clear</code>, <code class="docutils literal notranslate">update</code>. Note: <code class="docutils literal notranslate">setdefault</code> is not included. Open issues: Write out the specs for the methods.</dd> </dl> </section> <section id="sequences"> <h4><a class="toc-backref" href="#sequences" role="doc-backlink">Sequences</a></h4> These abstract classes represent read-only sequences and mutable sequences. The built-in <code class="docutils literal notranslate">list</code> and <code class="docutils literal notranslate">bytes</code> types derive from <code class="docutils literal notranslate">MutableSequence</code>. The built-in <code class="docutils literal notranslate">tuple</code> and <code class="docutils literal notranslate">str</code> types derive from <code class="docutils literal notranslate">Sequence</code> and <code class="docutils literal notranslate">Hashable</code>. <dl> <dt><code class="docutils literal notranslate">Sequence</code></dt><dd>A subclass of <code class="docutils literal notranslate">Iterable</code>, <code class="docutils literal notranslate">Sized</code>, <code class="docutils literal notranslate">Container</code>. It defines a new abstract method <code class="docutils literal notranslate">__getitem__</code> that has a somewhat complicated signature: when called with an integer, it returns an element of the sequence or raises <code class="docutils literal notranslate">IndexError</code>; when called with a <code class="docutils literal notranslate">slice</code> object, it returns another <code class="docutils literal notranslate">Sequence</code>. The concrete <code class="docutils literal notranslate">__iter__</code> method iterates over the elements using <code class="docutils literal notranslate">__getitem__</code> with integer arguments 0, 1, and so on, until <code class="docutils literal notranslate">IndexError</code> is raised. The length should be equal to the number of values returned by the iterator.Open issues: Other candidate methods, which can all have default concrete implementations that only depend on <code class="docutils literal notranslate">__len__</code> and <code class="docutils literal notranslate">__getitem__</code> with an integer argument: <code class="docutils literal notranslate">__reversed__</code>, <code class="docutils literal notranslate">index</code>, <code class="docutils literal notranslate">count</code>, <code class="docutils literal notranslate">__add__</code>, <code class="docutils literal notranslate">__mul__</code>. </dd> <dt><code class="docutils literal notranslate">MutableSequence</code></dt><dd>A subclass of <code class="docutils literal notranslate">Sequence</code> adding some standard mutating methods. Abstract mutating methods: <code class="docutils literal notranslate">__setitem__</code> (for integer indices as well as slices), <code class="docutils literal notranslate">__delitem__</code> (ditto), <code class="docutils literal notranslate">insert</code>. Concrete mutating methods: <code class="docutils literal notranslate">append</code>, <code class="docutils literal notranslate">reverse</code>, <code class="docutils literal notranslate">extend</code>, <code class="docutils literal notranslate">pop</code>, <code class="docutils literal notranslate">remove</code>. Concrete mutating operators: <code class="docutils literal notranslate">+=</code>, <code class="docutils literal notranslate">*=</code> (these mutate the object in place). Note: this does not define <code class="docutils literal notranslate">sort()</code> – that is only required to exist on genuine <code class="docutils literal notranslate">list</code> instances.</dd> </dl> </section> </section> <section id="strings"> <h3><a class="toc-backref" href="#strings" role="doc-backlink">Strings</a></h3> Python 3000 will likely have at least two built-in string types: byte strings (<code class="docutils literal notranslate">bytes</code>), deriving from <code class="docutils literal notranslate">MutableSequence</code>, and (Unicode) character strings (<code class="docutils literal notranslate">str</code>), deriving from <code class="docutils literal notranslate">Sequence</code> and <code class="docutils literal notranslate">Hashable</code>. Open issues: define the base interfaces for these so alternative implementations and subclasses know what they are in for. This may be the subject of a new PEP or PEPs (<a class="pep reference internal" href="../pep-0358/" title="PEP 358 – The “bytes” Object">PEP 358</a> should be co-opted for the <code class="docutils literal notranslate">bytes</code> type). </section> </section> <section id="abcs-vs-alternatives"> <h2><a class="toc-backref" href="#abcs-vs-alternatives" role="doc-backlink">ABCs vs. Alternatives</a></h2> In this section I will attempt to compare and contrast ABCs to other approaches that have been proposed. <section id="abcs-vs-duck-typing"> <h3><a class="toc-backref" href="#abcs-vs-duck-typing" role="doc-backlink">ABCs vs. Duck Typing</a></h3> Does the introduction of ABCs mean the end of Duck Typing? I don’t think so. Python will not require that a class derives from <code class="docutils literal notranslate">BasicMapping</code> or <code class="docutils literal notranslate">Sequence</code> when it defines a <code class="docutils literal notranslate">__getitem__</code> method, nor will the <code class="docutils literal notranslate">x[y]</code> syntax require that <code class="docutils literal notranslate">x</code> is an instance of either ABC. You will still be able to assign any “file-like” object to <code class="docutils literal notranslate">sys.stdout</code>, as long as it has a <code class="docutils literal notranslate">write</code> method. Of course, there will be some carrots to encourage users to derive from the appropriate base classes; these vary from default implementations for certain functionality to an improved ability to distinguish between mappings and sequences. But there are no sticks. If <code class="docutils literal notranslate">hasattr(x, "__len__")</code> works for you, great! ABCs are intended to solve problems that don’t have a good solution at all in Python 2, such as distinguishing between mappings and sequences. </section> <section id="abcs-vs-generic-functions"> <h3><a class="toc-backref" href="#abcs-vs-generic-functions" role="doc-backlink">ABCs vs. Generic Functions</a></h3> ABCs are compatible with Generic Functions (GFs). For example, my own Generic Functions implementation <a class="footnote-reference brackets" href="#id14" id="id11">[4]</a> uses the classes (types) of the arguments as the dispatch key, allowing derived classes to override base classes. Since (from Python’s perspective) ABCs are quite ordinary classes, using an ABC in the default implementation for a GF can be quite appropriate. For example, if I have an overloaded <code class="docutils literal notranslate">prettyprint</code> function, it would make total sense to define pretty-printing of sets like this: <div class="highlight-default notranslate"><div class="highlight"><pre>@prettyprint.register(Set) def pp_set(s): return "{" + ... + "}" # Details left as an exercise </pre></div> </div> and implementations for specific subclasses of Set could be added easily. I believe ABCs also won’t present any problems for RuleDispatch, Phillip Eby’s GF implementation in PEAK <a class="footnote-reference brackets" href="#id15" id="id12">[5]</a>. Of course, GF proponents might claim that GFs (and concrete, or implementation, classes) are all you need. But even they will not deny the usefulness of inheritance; and one can easily consider the ABCs proposed in this PEP as optional implementation base classes; there is no requirement that all user-defined mappings derive from <code class="docutils literal notranslate">BasicMapping</code>. </section> <section id="abcs-vs-interfaces"> <h3><a class="toc-backref" href="#abcs-vs-interfaces" role="doc-backlink">ABCs vs. Interfaces</a></h3> ABCs are not intrinsically incompatible with Interfaces, but there is considerable overlap. For now, I’ll leave it to proponents of Interfaces to explain why Interfaces are better. I expect that much of the work that went into e.g. defining the various shades of “mapping-ness” and the nomenclature could easily be adapted for a proposal to use Interfaces instead of ABCs. “Interfaces” in this context refers to a set of proposals for additional metadata elements attached to a class which are not part of the regular class hierarchy, but do allow for certain types of inheritance testing. Such metadata would be designed, at least in some proposals, so as to be easily mutable by an application, allowing application writers to override the normal classification of an object. The drawback to this idea of attaching mutable metadata to a class is that classes are shared state, and mutating them may lead to conflicts of intent. Additionally, the need to override the classification of an object can be done more cleanly using generic functions: In the simplest case, one can define a “category membership” generic function that simply returns False in the base implementation, and then provide overrides that return True for any classes of interest. </section> </section> <section id="references"> <h2><a class="toc-backref" href="#references" role="doc-backlink">References</a></h2> <aside class="footnote-list brackets"> <aside class="footnote brackets" id="id13" role="doc-footnote"> <dt class="label" id="id13">[<a href="#id1">1</a>]</dt> <dd>An Introduction to ABC’s, by Talin (<a class="reference external" href="https://mail.python.org/pipermail/python-3000/2007-April/006614.html">https://mail.python.org/pipermail/python-3000/2007-April/006614.html</a>)</aside> </aside> [2] Incomplete implementation prototype, by GvR (<a class="reference external" href="https://web.archive.org/web/20170223133820/http://svn.python.org/view/sandbox/trunk/abc/">https://web.archive.org/web/20170223133820/http://svn.python.org/view/sandbox/trunk/abc/</a>) [3] Possible Python 3K Class Tree?, wiki page created by Bill Janssen (<a class="reference external" href="https://wiki.python.org/moin/AbstractBaseClasses">https://wiki.python.org/moin/AbstractBaseClasses</a>) <aside class="footnote-list brackets"> <aside class="footnote brackets" id="id14" role="doc-footnote"> <dt class="label" id="id14">[<a href="#id11">4</a>]</dt> <dd>Generic Functions implementation, by GvR (<a class="reference external" href="https://web.archive.org/web/20170223135019/http://svn.python.org/view/sandbox/trunk/overload/">https://web.archive.org/web/20170223135019/http://svn.python.org/view/sandbox/trunk/overload/</a>)</aside> <aside class="footnote brackets" id="id15" role="doc-footnote"> <dt class="label" id="id15">[<a href="#id12">5</a>]</dt> <dd>Charming Python: Scaling a new PEAK, by David Mertz (<a class="reference external" href="https://web.archive.org/web/20070515125102/http://www-128.ibm.com/developerworks/library/l-cppeak2/">https://web.archive.org/web/20070515125102/http://www-128.ibm.com/developerworks/library/l-cppeak2/</a>)</aside> <aside class="footnote brackets" id="id16" role="doc-footnote"> <dt class="label" id="id16">[<a href="#id5">6</a>]</dt> <dd>Implementation of @abstractmethod (<a class="reference external" href="https://github.com/python/cpython/issues/44895">https://github.com/python/cpython/issues/44895</a>)</aside> <aside class="footnote brackets" id="id17" role="doc-footnote"> <dt class="label" id="id17">[<a href="#id6">7</a>]</dt> <dd>Unifying types and classes in Python 2.2, by GvR (<a class="reference external" href="https://www.python.org/download/releases/2.2.3/descrintro/">https://www.python.org/download/releases/2.2.3/descrintro/</a>)</aside> <aside class="footnote brackets" id="id18" role="doc-footnote"> <dt class="label" id="id18">[<a href="#id7">8</a>]</dt> <dd>Putting Metaclasses to Work: A New Dimension in Object-Oriented Programming, by Ira R. Forman and Scott H. Danforth (<a class="reference external" href="https://archive.org/details/PuttingMetaclassesToWork">https://archive.org/details/PuttingMetaclassesToWork</a>)</aside> </aside> [9] Partial order, in Wikipedia (<a class="reference external" href="https://en.wikipedia.org/wiki/Partial_order">https://en.wikipedia.org/wiki/Partial_order</a>) [10] Total order, in Wikipedia (<a class="reference external" href="https://en.wikipedia.org/wiki/Total_order">https://en.wikipedia.org/wiki/Total_order</a>) <aside class="footnote-list brackets"> <aside class="footnote brackets" id="id19" role="doc-footnote"> <dt class="label" id="id19">[<a href="#id9">11</a>]</dt> <dd>Finite set, in Wikipedia (<a class="reference external" href="https://en.wikipedia.org/wiki/Finite_set">https://en.wikipedia.org/wiki/Finite_set</a>)</aside> <aside class="footnote brackets" id="id20" role="doc-footnote"> <dt class="label" id="id20">[<a href="#id3">12</a>]</dt> <dd>Make isinstance/issubclass overloadable (<a class="reference external" href="https://bugs.python.org/issue1708353">https://bugs.python.org/issue1708353</a>)</aside> <aside class="footnote brackets" id="id21" role="doc-footnote"> <dt class="label" id="id21">[<a href="#id4">13</a>]</dt> <dd>ABCMeta sample implementation (<a class="reference external" href="https://web.archive.org/web/20170224195724/http://svn.python.org/view/sandbox/trunk/abc/xyz.py">https://web.archive.org/web/20170224195724/http://svn.python.org/view/sandbox/trunk/abc/xyz.py</a>)</aside> <aside class="footnote brackets" id="id22" role="doc-footnote"> <dt class="label" id="id22">[<a href="#id8">14</a>]</dt> <dd>python-dev email (“Comparing heterogeneous types”) <a class="reference external" href="https://mail.python.org/pipermail/python-dev/2004-June/045111.html">https://mail.python.org/pipermail/python-dev/2004-June/045111.html</a></aside> <aside class="footnote brackets" id="id23" role="doc-footnote"> <dt class="label" id="id23">[<a href="#id10">15</a>]</dt> <dd>Function <code class="docutils literal notranslate">frozenset_hash()</code> in Object/setobject.c (<a class="reference external" href="https://web.archive.org/web/20170224204758/http://svn.python.org/view/python/trunk/Objects/setobject.c">https://web.archive.org/web/20170224204758/http://svn.python.org/view/python/trunk/Objects/setobject.c</a>)</aside> <aside class="footnote brackets" id="id24" role="doc-footnote"> <dt class="label" id="id24">[<a href="#id2">16</a>]</dt> <dd>Multiple interpreters in mod_python (<a class="reference external" href="https://web.archive.org/web/20070515132123/http://www.modpython.org/live/current/doc-html/pyapi-interps.html">https://web.archive.org/web/20070515132123/http://www.modpython.org/live/current/doc-html/pyapi-interps.html</a>)</aside> </aside> </section> <section id="copyright"> <h2><a class="toc-backref" href="#copyright" role="doc-backlink">Copyright</a></h2> This document has been placed in the public domain. </section> </section> <hr class="docutils" /> Source: <a class="reference external" href="https://github.com/python/peps/blob/main/peps/pep-3119.rst">https://github.com/python/peps/blob/main/peps/pep-3119.rst</a> Last modified: <a class="reference external" href="https://github.com/python/peps/commits/main/peps/pep-3119.rst">2025-02-01 08:55:40 GMT</a> </article> <nav id="pep-sidebar"> <h2>Contents</h2> <ul> <li><a class="reference internal" href="#abstract">Abstract</a><ul> <li><a class="reference internal" href="#acknowledgements">Acknowledgements</a></li> </ul> </li> <li><a class="reference internal" href="#rationale">Rationale</a></li> <li><a class="reference internal" href="#specification">Specification</a><ul> <li><a class="reference internal" href="#overloading-isinstance-and-issubclass">Overloading <code class="docutils literal notranslate">isinstance()</code> and <code class="docutils literal notranslate">issubclass()</code></a></li> <li><a class="reference internal" href="#the-abc-module-an-abc-support-framework">The <code class="docutils literal notranslate">abc</code> Module: an ABC Support Framework</a></li> <li><a class="reference internal" href="#abcs-for-containers-and-iterators">ABCs for Containers and Iterators</a><ul> <li><a class="reference internal" href="#one-trick-ponies">One Trick Ponies</a></li> <li><a class="reference internal" href="#sets">Sets</a></li> <li><a class="reference internal" href="#mappings">Mappings</a></li> <li><a class="reference internal" href="#sequences">Sequences</a></li> </ul> </li> <li><a class="reference internal" href="#strings">Strings</a></li> </ul> </li> <li><a class="reference internal" href="#abcs-vs-alternatives">ABCs vs. Alternatives</a><ul> <li><a class="reference internal" href="#abcs-vs-duck-typing">ABCs vs. Duck Typing</a></li> <li><a class="reference internal" href="#abcs-vs-generic-functions">ABCs vs. Generic Functions</a></li> <li><a class="reference internal" href="#abcs-vs-interfaces">ABCs vs. Interfaces</a></li> </ul> </li> <li><a class="reference internal" href="#references">References</a></li> <li><a class="reference internal" href="#copyright">Copyright</a></li> </ul> <a id="source" href="https://github.com/python/peps/blob/main/peps/pep-3119.rst">Page Source (GitHub)</a> </nav> </section> <script src="../_static/colour_scheme.js"></script> <script src="../_static/wrap_tables.js"></script> <script src="../_static/sticky_banner.js"></script> </body> </html>