[Python-3000] PEP 3119 - Introducing Abstract Base Classes (original) (raw)

Thu Apr 26 20:50:59 CEST 2007

class A:
    @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
Another constraint is that hashable objects, once created, should
never change their value (as compared by ``==``) or their hash
value.  If a class cannot guarantee this, it should not derive
from ``Hashable``; if it cannot guarantee this for certain
instances only, ``__hash__`` for those instances should raise a
``TypeError`` 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 ``__hash__`` method raises ``TypeError``.
**Note:** strictly speaking, there are three variants of this method's
semantics.  The first one is for sets and mappings, which is fast:
O(1) or O(log N).  The second one is for membership checking on
sequences, which is slow: O(N).  The third one is for subsequence
checking on (character or byte) strings, which is also slow: O(N).
Would it make sense to distinguish these?  The signature of the
third variant is different, since it takes a sequence (typically
of the same type as the method's target) intead of an element.
For now, I'm using the same type for all three.  This means that
is is possible for ``x in o`` to be True even though ``x`` is
never yielded by ``iter(o)``.  A suggested name for the third form
is ``Searchable``.
class EvenIntegers(Container):
    def __contains__(self, x):
        return x % 2 == 0
Sets with different implementations can be compared safely,
(usually) efficiently and correctly using the mathematical
definitions of the subclass/superclass operations for finite sets.
The ordering operations have concrete implementations; subclasses
may override these for speed but should maintain the semantics.
Because ``Set`` derives from ``Sized``, ``__eq__`` may take a
shortcut and returns ``False`` immediately if two sets of unequal
length are compared.  Similarly, ``__le__`` may return ``False``
immediately if the first set has more members than the second set.
Note that set inclusion implements only a partial ordering;
e.g. ``{1, 2}`` and ``{1, 3}`` are not ordered (all three of
``<``, ``==`` and ``>`` return ``False`` 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).

**Note:** the ``issubset`` and ``issuperset`` methods found on the
set type in Python 2 are not supported, as these are mostly just
aliases for ``__le__`` and ``__ge__``.

**Open issues:** should we define comparison of instances of
different concrete set types this way?
**Open issues:** Should ``__or__`` and friends be abstract or
concrete methods?  Making them abstract means that every
ComposableSet implementation must reimplement all of them.  But
making them concrete begs the question of the actual return type:
since the ABC doesn't (and IMO shouldn't) define the constructor
signature for subclasses, the concrete implementations in the ABC
don't have an API to construct a new instance given an iterable.
Perhaps the right choice is to have a static concrete factory
function ``fromiterable`` which takes an iterable and returns
a ``ComposableSet`` instance.  Subclasses can override this and
benefit from the default implementations of ``__or__`` etc.; or
they can override ``__or__`` if they want to.
**Open issues:** Spell out the hash algorithm.  Should there be
another ABC that derives from Set and Hashable, but not from
Composable?
``.add(x)``
    Abstract method returning a ``bool`` that adds the element
    ``x`` if it isn't already in the set.  It should return
    ``True`` if ``x`` was added, ``False`` if it was already
    there. The abstract implementation raises
    ``NotImplementedError``.

``.discard(x)``
    Abstract method returning a ``bool`` that removes the element
    ``x`` if present.  It should return ``True`` if the element
    was present and ``False`` if it wasn't.  The abstract
    implementation raises ``NotImplementedError``.

``.pop()``
    Concrete method that removes an arbitrary item.  If the set is
    empty, it raises ``KeyError``.  The default implementation
    removes the first item returned by the set's iterator.

``.toggle(x)``
    Concrete method returning a ``bool`` that adds x to the set if
    it wasn't there, but removes it if it was there.  It should
    return ``True`` if ``x`` was added, ``False`` if it was
    removed.

``.clear()``
    Concrete method that empties the set.  The default
    implementation repeatedly calls ``self.pop()`` until
    ``KeyError`` 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.)

This also supports the in-place mutating operations ``|=``,
``&=``, ``^=``, ``-=``.  These are concrete methods whose right
operand can be an arbitrary ``Iterable``, except for ``&=``, whose
right operand must be a ``Container``.  This ABC does not support
the named methods present on the built-in concrete ``set`` type
that perform (almost) the same operations.
``.__getitem__(key)``
    Abstract method that returns the value corresponding to
    ``key``, or raises ``KeyError``.  The implementation always
    raises ``KeyError``.

``.get(key, default=None)``
    Concrete method returning ``self[key]`` if this does not raise
    ``KeyError``, and the ``default`` value if it does.

``.__contains__()``
    Concrete method returning ``True`` if ``self[key]`` does not
    raise ``KeyError``, and ``False`` if it does.
``__len__``
    Abstract method returning the length of the key set.

``__iter__``
    Abstract method returning each key in the key set exactly once.

``__eq__``
    Concrete method for comparing mappings.  Two mappings, even
    with different implementations, can be compared for equality,
    and are considered equal if and only iff their item sets are
    equal.  **Open issues:** should we define comparison of
    instances of different concrete mapping types this way?

``keys``
    Concrete method returning the key set as a ``Set``.  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 ``Set``.

``items``
    Concrete method returning the items as a ``Set``.  The default
    concrete implementation returns a "view" on the item set;
    subclasses are not required to return a view but they should
    return a ``Set``.

``values``
    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.

The following invariant should hold for any mapping ``m``::

    set(m.items()) == set(zip(m.keys(), m.values()))

i.e. iterating over the keys and the values in parallel should
return *corresponding* keys and values.  **Open issues:** Should
this always be required?  How about the stronger invariant using
``list()`` instead of ``set()``?
**Open issues:** Other candidate methods, which can all have
default concrete implementations that only depend on ``__len__``
and ``__getitem__`` with an integer argument: __reversed__, index,
count, __add__, __mul__, __eq__, __lt__, __le__.
@prettyprint.register(Set)
def pp_set(s):
    return "{" + ... + "}"  # Details left as an exercise

[Python-3000] PEP 3119 - Introducing Abstract Base Classes (original) (raw)

Abstract

Acknowledgements

Rationale

Specification

ABC Support Framework

ABCs for Containers and Iterators

Strings

Numbers

Guidelines for Writing ABCs

ABCs vs. Alternatives

ABCs vs. Duck Typing

ABCs vs. Generic Functions

ABCs vs. Interfaces

References

Copyright