[Python-checkins] r54870 - peps/trunk/pep-3119.txt

[guido.van.rossum]

Author: guido.van.rossum
Date: Wed Apr 18 20:39:32 2007
New Revision: 54870

Modified:
   peps/trunk/pep-3119.txt
Log:
Add spec for abc module.  Add more sections but with temporary contents.


Modified: peps/trunk/pep-3119.txt
==============================================================================
--- peps/trunk/pep-3119.txt	(original)
+++ peps/trunk/pep-3119.txt	Wed Apr 18 20:39:32 2007
@@ -94,6 +94,86 @@
 to enforce that these promises are kept.
 
 
+Specification
+=============
+
+The specification follows the four categories listed in the abstract:
+
+* An "ABC support framework" which defines a metaclass, a base class,
+  a decorator, and some helpers that make it easy to define ABCs.
+  This will be added as a new library module named "abc".
+
+* Specific ABCs for containers and iterators, to be added to the
+  collections module.
+
+* Specific ABCs for numbers, to be added to a new module, yet to be
+  named.
+
+* Guidelines for writing additional ABCs.
+
+
+ABC Support Framework
+---------------------
+
+The abc module will define some utilities that help defining ABCs.
+These are:
+
+``@abstractmethod``
+    A decorator to be used to declare abstract methods.  This should
+    only be used with classes whose metaclass is (or is derived from)
+    ``AbstractClass`` below.  A class containing at least one method
+    declared with this decorator that hasn't been overridden yet
+    cannot be instantiated.  Such a methods may be called from the
+    overriding method in the subclass (using ``super`` or direct
+    invocation).
+    
+``Abstract``
+    A class implementing the constraint that it or its subclasses
+    cannot be instantiated unless each abstract method has been
+    overridden.  Its metaclass is ``AbstractClass``.  Note: being
+    derived from ``Abstract`` does not make a class abstract; the
+    abstract-ness is decided on a per-class basis, depending on
+    whether all methods defined with ``@abstractmethod`` have been
+    overridden.
+
+``AbstractClass``
+    The metaclass of Abstract (and all classes derived from it).  Its
+    purpose is to collect the information during the class
+    construction stage.  It derives from ``type``.
+
+``AbstractInstantiationError``
+    The exception raised when attempting to instantiate an abstract
+    class.  It derives from ``TypeError``.
+
+
+ABCs for Containers and Iterators
+---------------------------------
+
+XXX define: Iterable, Iterator, Sizeable (or Lengthy?), various Sets,
+Mappings, Sequences.  Also Hashable so we can define Immutable (which
+adds to "read-only", does not subtract from "mutable", nor does
+"mutable" add to "hashable" -- it adds to "read-only").  Also defines
+how set, frozenset, list, tuple, dict, bytes and str derive from
+these.
+
+
+ABCs for Numbers
+----------------
+
+XXX define: Number, Complex, Real, Rational, Integer.  Do we have a
+use case for Cardinal (Integer >= 0)?  Do we need Indexable (converts
+to Integer using __index__).
+
+
+Guidelines for Writing ABCs
+---------------------------
+
+XXX E.g. use @abstractmethod and Abstract base class; define abstract
+methods that could be useful as an end point when called via a super
+chain; keep abstract classes small, one per use case instead of one
+per concept.
+
+
 References
 ==========