Update description of sets to match the 2.3 sets.py

pep-0218.txt

@@ -9,16 +9,6 @@ Created: 31-Jul-2000
 Post-History: 
 
 
-Cautionary note
-
-    Much of this PEP has been implemented in the new "sets" module,
-    added to Python 2.3.  The sets module differs in a number of
-    aspects from this PEP; in particular its approach to mutability is
-    different.  It is my hope that this PEP's author will update his
-    PEP to match the sets module more closely.  [note added by Guido
-    van Rossum]
-
-
 Introduction
 
     This PEP proposes adding a Set module to the standard Python
@@ -103,10 +93,12 @@ Long-Term Proposal
         S.discard(x)    Remove "x" from the set if it is present, or
                         do nothing if it is not.
 
-        S.popitem()     Remove and return an arbitrary element,
+        S.pop()         Remove and return an arbitrary element,
                         raising a LookupError if the element is not
                         present.
 
+        S.clear()       Remove all elements from this set.
+
     and one new built-in conversion function:
 
         set(x)          Create a set containing the elements of the
@@ -128,6 +120,7 @@ Long-Term Proposal
     3. Sets raise "LookupError" exceptions, rather than "KeyError" or
        "ValueError", because set elements are neither keys nor values.
 
+
 Short-Term Proposal
 
     In order to determine whether there is enough demand for sets to
@@ -140,17 +133,17 @@ Short-Term Proposal
     so on.
 
     This class will use a dictionary internally to contain set values.
-    In order to avoid having to duplicate values (e.g. for iteration
-    through the set), the class will rely on the iterators which are
-    scheduled to appear in Python 2.2.
+    To avoid having to duplicate values (e.g. for iteration through
+    the set), the class will rely on the iterators added in Python
+    2.2.
 
     Tim Peters believes that the class's constructor should take a
     single sequence as an argument, and populate the set with that
     sequence's elements.  His argument is that in most cases,
-    programmers will be created sets from pre-existing sequences, so
-    that common case should be usual.  However, this would require
-    users to remember an extra set of parentheses when initializing a
-    set with known values:
+    programmers will be creating sets from pre-existing sequences, so
+    that this case should be the common one.  However, this would
+    require users to remember an extra set of parentheses when
+    initializing a set with known values:
 
     >>> Set((1, 2, 3, 4))       # case 1
 
@@ -164,7 +157,7 @@ Short-Term Proposal
     On the other, other hand, if Python does adopt a dictionary-like
     notation for sets in the future, then case 2 will become
     redundant.  We have therefore adopted the first strategy, in which
-    the initializer takes a single sequence argument.
+    the initializer takes a single iterable argument.
 
 
 Mutability
@@ -176,13 +169,13 @@ Mutability
     to be immutable, this would preclude sets of sets (which are
     widely used in graph algorithms and other applications).
 
-    At Tim Peters' suggestion, we will implement the following
-    compromise.  A set may only contain immutable elements, but is
-    itself mutable *until* its hash code is calculated.  As soon as
-    that happens, the set is "frozen", i.e. becomes immutable.  Thus,
-    a set may be used as a dictionary key, or as a set element, but
-    cannot be updated after this is done.  Peters reports that this
-    behavior rarely causes problems in practice.
+    There are two classes implemented in the "sets" module.  Instances
+    of the Set class can be modified by the addition or removal of
+    elements, and the ImmutableSet class is "frozen", with an
+    unchangeable collection of elements.  Therefore, an ImmutableSet
+    may be used as a dictionary key or as a set element, but cannot be
+    updated.  Both types of set require that their elements are
+    immutable, hashable objects.
 
 
 Alternatives