Update the PEP with the new name for PyByte (bytearray), and some minor edits.

pep-3137.txt

@@ -60,15 +60,17 @@ I propose the following type names at the Python level:
 
   - ``bytes`` is an immutable array of bytes (PyString)
 
-  - ``buffer`` is a mutable array of bytes (PyBytes)
+  - ``bytearray`` is a mutable array of bytes (PyBytes)
 
   - ``memoryview`` is a bytes view on another object (PyMemory)
 
-The old type named ``buffer`` is so similar to the new type
+The old type named ``bytearray`` is so similar to the new type
 ``memoryview``, introduce by PEP 3118, that it is redundant.  The rest
 of this PEP doesn't discuss the functionality of ``memoryview``; it is
-just mentioned here to justify getting rid of the old ``buffer`` type
+just mentioned here to justify getting rid of the old ``buffer`` type.
-so we can reuse its name for the mutable bytes type.
+(An earlier version of this PEP proposed ``buffer`` as the new name
+for PyBytes; in the end this name was deemed to confusing given the
+many other uses of the word buffer.)
 
 While eventually it makes sense to change the C API names, this PEP
 maintains the old C API names, which should be familiar to all.
@@ -79,23 +81,23 @@ Summary
 Here's a simple ASCII-art table summarizing the type names in various
 Python versions::
 
-    +--------------+-------------+------------+--------------------+
+    +--------------+-------------+------------+--------------------------+
-    | C name       | 2.x    repr | 3.0a1 repr | 3.0a2         repr |
+    | C name       | 2.x    repr | 3.0a1 repr | 3.0a2               repr |
-    +--------------+-------------+------------+--------------------+
+    +--------------+-------------+------------+--------------------------+
-    | PyUnicode    | unicode u'' | str     '' | str             '' |
+    | PyUnicode    | unicode u'' | str     '' | str                   '' |
-    | PyString     | str      '' | str8   s'' | bytes          b'' |
+    | PyString     | str      '' | str8   s'' | bytes                b'' |
-    | PyBytes      | N/A         | bytes  b'' | buffer buffer(b'') |
+    | PyBytes      | N/A         | bytes  b'' | bytearray bytearray(b'') |
-    | PyBuffer     | buffer      | buffer     | N/A                |
+    | PyBuffer     | buffer      | buffer     | N/A                      |
-    | PyMemoryView | N/A         | memoryview | memoryview         |
+    | PyMemoryView | N/A         | memoryview | memoryview         <...> |
-    +--------------+-------------+------------+--------------------+
+    +--------------+-------------+------------+--------------------------+
 
 Literal Notations
 =================
 
 The b'...' notation introduced in Python 3.0a1 returns an immutable
-bytes object, whatever variation is used.  To create a mutable bytes
+bytes object, whatever variation is used.  To create a mutable array
-buffer object, use buffer(b'...') or buffer([...]).  The latter may
+of bytes, use bytearray(b'...') or bytearray([...]).  The latter form
-use a list of integers in range(256).
+takes a list of integers in range(256).
 
 Functionality
 =============
@@ -103,8 +105,8 @@ Functionality
 PEP 3118 Buffer API
 -------------------
 
-Both bytes and buffer implement the PEP 3118 buffer API.  The bytes
+Both bytes and bytearray implement the PEP 3118 buffer API.  The bytes
-type only implements read-only requests; the buffer type allows
+type only implements read-only requests; the bytearray type allows
 writable and data-locked requests as well.  The element data type is
 always 'B' (i.e. unsigned byte).
 
@@ -112,33 +114,35 @@ Constructors
 ------------
 
 There are four forms of constructors, applicable to both bytes and
-buffer:
+bytearray:
 
-  - ``bytes(<bytes>)``, ``bytes(<buffer>)``, ``buffer(<bytes>)``,
+  - ``bytes(<bytes>)``, ``bytes(<bytearray>)``, ``bytearray(<bytes>)``,
-    ``buffer(<buffer>)``: simple copying constructors, with the note
+    ``bytearray(<bytearray>)``: simple copying constructors, with the
-    that ``bytes(<bytes>)`` might return its (immutable) argument.
+    note that ``bytes(<bytes>)`` might return its (immutable)
+    argument, but ``bytearray(<bytearray>)`` always makes a copy.
 
-  - ``bytes(<str>, <encoding>[, <errors>])``, ``buffer(<str>,
+  - ``bytes(<str>, <encoding>[, <errors>])``, ``bytearray(<str>,
     <encoding>[, <errors>])``: encode a text string.  Note that the
-    ``str.encode()`` method returns an *immutable* bytes object.
+    ``str.encode()`` method returns an *immutable* bytes object.  The
-    The <encoding> argument is mandatory; <errors> is optional.
+    <encoding> argument is mandatory; <errors> is optional.
+    <encoding> and <errrors>, if given, must be ``str`` instances.
 
-  - ``bytes(<memory view>)``, ``buffer(<memory view>)``: construct a
+  - ``bytes(<memory view>)``, ``bytearray(<memory view>)``: construct
-    bytes or buffer object from anything implementing the PEP 3118
+    a bytes or bytearray object from anything that implements the PEP
-    buffer API.
+    3118 buffer API.
 
-  - ``bytes(<iterable of ints>)``, ``buffer(<iterable of ints>)``:
+  - ``bytes(<iterable of ints>)``, ``bytearray(<iterable of ints>)``:
-    construct an immutable bytes or mutable buffer object from a
+    construct a bytes or bytearray object from a stream of integers in
-    stream of integers in range(256).
+    range(256).
 
-  - ``buffer(<int>)``: construct a zero-initialized buffer of a given
+  - ``bytes(<int>)``, ``bytearray(<int>)``: construct a
-    length.
+    zero-initialized bytes or bytearray object of a given length.
 
 Comparisons
 -----------
 
-The bytes and buffer types are comparable with each other and
+The bytes and bytearray types are comparable with each other and
-orderable, so that e.g. b'abc' == buffer(b'abc') < b'abd'.
+orderable, so that e.g. b'abc' == bytearray(b'abc') < b'abd'.
 
 Comparing either type to a str object for equality returns False
 regardless of the contents of either operand.  Ordering comparisons
@@ -156,20 +160,20 @@ back in 3.0a2 regardless of the fate of the rest of this PEP.)
 Slicing
 -------
 
-Slicing a bytes object returns a bytes object.  Slicing a buffer
+Slicing a bytes object returns a bytes object.  Slicing a bytearray
-object returns a buffer object.
+object returns a bytearray object.
 
-Slice assignment to a mutable buffer object accepts anything that
+Slice assignment to a bytearray object accepts anything that
 implements the PEP 3118 buffer API, or an iterable of integers in
 range(256).
 
 Indexing
 --------
 
-Indexing bytes and buffer returns small ints (like the bytes type in
+Indexing bytes and bytearray returns small ints (like the bytes type in
 3.0a1, and like lists or array.array('B')).
 
-Assignment to an item of a mutable buffer object accepts an int in
+Assignment to an item of a bytearray object accepts an int in
 range(256).  (To assign from a bytes sequence, use a slice
 assignment.)
 
@@ -178,23 +182,23 @@ Str() and Repr()
 
 The str() and repr() functions return the same thing for these
 objects.  The repr() of a bytes object returns a b'...' style literal.
-The repr() of a buffer returns a string of the form "buffer(b'...')".
+The repr() of a bytearray returns a string of the form "bytearray(b'...')".
 
 Operators
 ---------
 
-The following operators are implemented by the bytes and buffer types,
+The following operators are implemented by the bytes and bytearray
-except where mentioned:
+types, except where mentioned:
 
-  - ``b1 + b2``: concatenation.  With mixed bytes/buffer operands,
+  - ``b1 + b2``: concatenation.  With mixed bytes/bytearray operands,
     the return type is that of the first argument (this seems arbitrary
     until you consider how ``+=`` works).
 
-  - ``b1 += b2``: mutates b1 if it is a buffer object.
+  - ``b1 += b2``: mutates b1 if it is a bytearray object.
 
   - ``b * n``, ``n * b``: repetition; n must be an integer.
 
-  - ``b *= n``: mutates b if it is a buffer object.
+  - ``b *= n``: mutates b if it is a bytearray object.
 
   - ``b1 in b2``, ``b1 not in b2``: substring test; b1 can be any
     object implementing the PEP 3118 buffer API.
@@ -213,7 +217,7 @@ worth the complexity.
 Methods
 -------
 
-The following methods are implemented by bytes as well as buffer, with
+The following methods are implemented by bytes as well as bytearray, with
 similar semantics.  They accept anything that implements the PEP 3118
 buffer API for bytes arguments, and return the same type as the object
 whose method is called ("self")::
@@ -241,7 +245,7 @@ In addition, both types implement the class method ``.fromhex()``,
 which constructs an object from a string containing hexadecimal values
 (with or without spaces between the bytes).
 
-The buffer type implements these additional methods from the
+The bytearray type implements these additional methods from the
 MutableSequence ABC (see PEP 3119):
 
   .extend(), .insert(), .append(), .reverse(), .pop(), .remove().
@@ -251,19 +255,19 @@ Bytes and the Str Type
 
 Like the bytes type in Python 3.0a1, and unlike the relationship
 between str and unicode in Python 2.x, attempts to mix bytes (or
-buffer) objects and str objects without specifying an encoding will
+bytearray) objects and str objects without specifying an encoding will
-raise a TypeError exception.  (However, comparing bytes/buffer and str
+raise a TypeError exception.  (However, comparing bytes/bytearray and
-objects for equality will simply return False; see the section on
+str objects for equality will simply return False; see the section on
 Comparisons above.)
 
-Conversions between bytes or buffer objects and str objects must
+Conversions between bytes or bytearray objects and str objects must
 always be explicit, using an encoding.  There are two equivalent APIs:
 ``str(b, <encoding>[, <errors>])`` is equivalent to
 ``b.decode(<encoding>[, <errors>])``, and
 ``bytes(s, <encoding>[, <errors>])`` is equivalent to
 ``s.encode(<encoding>[, <errors>])``.
   
-There is one exception: we can convert from bytes (or buffer) to str
+There is one exception: we can convert from bytes (or bytearray) to str
 without specifying an encoding by writing ``str(b)``.  This produces
 the same result as ``repr(b)``.  This exception is necessary because
 of the general promise that *any* object can be printed, and printing