diff --git a/pep-3119.txt b/pep-3119.txt index bf9b53429..678ccd50f 100644 --- a/pep-3119.txt +++ b/pep-3119.txt @@ -240,17 +240,19 @@ it has two prescribed methods. ``StopIteration``. The concrete ``__iter__`` method returns ``self``. (Note: this assumes PEP 3114 is implemented.) -``Finite`` +``Sized`` The base class for classes defining ``__len__``. The ``__len__`` method should return an ``Integer`` (see "Numbers" below) >= 0. The abstract ``__len__`` method returns 0. **Invariant:** If a - class ``C`` derives from ``Finite`` as well as from ``Iterable``, + class ``C`` derives from ``Sized`` as well as from ``Iterable``, the invariant ``sum(1 for x in o) == len(o)`` should hold for any - instance ``o`` of ``C``. **Open issue:** ``Finite`` may be a - confusing name. Other alternatives already rejected: ``Lengthy``, - ``Sizeable`` (both too cute), ``Countable`` (the set of natural - numbers is a countable set in math). We may just have to teach - people what we mean... + instance ``o`` of ``C``. **Open issue:** Is ``Sized`` the best + name? Proposed alternatives already tentatively rejected: + ``Finite`` (nobody understood it), ``Lengthy``, ``Sizeable`` (both + too cute), ``Countable`` (the set of natural numbers is a + countable set in math), ``Enumerable`` (sounds like a sysnonym for + ``Iterable``), ``Dimension``, ``Extent`` (sound like numbers to + me). ``Container`` The base class for classes defining ``__contains__``. The @@ -301,7 +303,7 @@ out of the scope of a pragmatic proposal like this. ``Set`` This is a finite, iterable container, i.e. a subclass of - ``Finite``, ``Iterable`` and ``Container``. Not every subset of + ``Sized``, ``Iterable`` and ``Container``. Not every subset 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 @@ -309,7 +311,7 @@ out of the scope of a pragmatic proposal like this. Sets with different implementations can be compared safely, efficiently and correctly. Because ``Set`` derives from - ``Finite``, ``__eq__`` takes a shortcut and returns ``False`` + ``Sized``, ``__eq__`` takes a shortcut and returns ``False`` immediately if two sets of unequal length are compared. Similarly, ``__le__`` returns ``False`` immediately if the first set has more members than the second set. Note that set inclusion @@ -380,18 +382,20 @@ out of the scope of a pragmatic proposal like this. Abstract method that empties the set. (Making this concrete would just add a slow, cumbersome default implementation.) - **Open issues:** Should we support more operations implemented by - the Python 2 ``set`` type? E.g. pop, update, __ior__, - intersection_update, __iand__, difference_update, __ixor__, - symmetric_difference_update, __isub__. Should we unify ``remove`` - and ``discard``, a la Java (which has a single method returning - a boolean indicating whether it was removed or not)? + ``.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. - Note that in Python 2, ``a.update(b)`` is not exactly the same as - ``a |= b``, since ``update()`` takes any iterable for an argument, - while ``|=`` requires another set; similar for the other - operators. What to do about this? Do we really want the method - explosion that comes from this distinction? + This also supports the in-place mutating operations ``|=``, + ``&=``, ``^=``, ``-=``. It does not support the named methods + that perform (almost) the same operations, like ``update``, even + though these don't have exactly the same rules (``update`` takes + any iterable, while ``|=`` requires a set). + + **Open issues:** Should we unify ``remove`` and ``discard``, a la + Java (which has a single method returning a boolean indicating + whether it was removed or not)? Mappings @@ -426,7 +430,7 @@ The built-in type ``dict`` derives from ``MutableMapping``. iteration never ends. ``Mapping`` - A subclass of ``IterableMapping`` and ``Finite``. It defines + A subclass of ``IterableMapping`` and ``Sized``. It defines concrete methods ``__eq__``, ``keys``, ``items``, ``values``. The lengh of such an object should equal to the number of elements returned by iterating over the object until the end of the @@ -445,18 +449,15 @@ The built-in type ``dict`` derives from ``MutableMapping``. ``MutableMapping`` A subclass of ``Mapping`` that also implements some standard - mutating methods. At least ``__setitem__``, ``__delitem__``, - ``clear``, ``update``. -**Open Issues:** - -* What about pop, popitem, setdefault? (``MutableSequence`` does have - ``pop``. Though it's not quite the same.) + mutating methods. Abstract methods include ``__setitem__``, + ``__delitem__``, ``clear``, ``update``. Concrete methods include + ``pop``, ``popitem``. Note: ``setdefault`` is *not* included. * Do we need BasicMapping and IterableMapping? We should probably just start with Mapping. -* We should say something about mapping view types, too. +* We should say more about mapping view types. Sequences @@ -469,7 +470,7 @@ The built-in ``list`` and ``bytes`` types derive from from ``HashableSequence``. ``Sequence`` - A subclass of ``Iterable``, ``Finite``, ``Container``. It + A subclass of ``Iterable``, ``Sized``, ``Container``. It defines a new abstract method ``__getitem__`` that has a complicated signature: when called with an integer, it returns an element of the sequence or raises ``IndexError``; when called with @@ -494,12 +495,10 @@ from ``HashableSequence``. Abstract mutating methods: ``__setitem__`` (for integer indices as well as slices), ``__delitem__`` (ditto), ``insert``, ``append``, ``reverse``. Concrete mutating methods: ``extend``, ``pop``, - ``remove``. Note: this does not define ``sort()`` -- that is only - required to exist on genuine ``list`` instances. - - **Open issues:** What about ``+=`` and ``*=``? (Including these - in the spec would clarify that they are *required* to be - implemented as in-place modifications.) + ``remove``. Concrete mutating operators: ``+=``, ``*=`` (these + mutate the object in place). Note: this does not define + ``sort()`` -- that is only required to exist on genuine ``list`` + instances. ABCs for Numbers