[Python-checkins] r59095 - peps/trunk/pep-3137.txt
guido.van.rossum
python-checkins at python.org
Wed Nov 21 20:45:46 CET 2007
Author: guido.van.rossum
Date: Wed Nov 21 20:45:46 2007
New Revision: 59095
Modified:
peps/trunk/pep-3137.txt
Log:
Update the PEP with the new name for PyByte (bytearray), and some minor edits.
Modified: peps/trunk/pep-3137.txt
==============================================================================
--- peps/trunk/pep-3137.txt (original)
+++ peps/trunk/pep-3137.txt Wed Nov 21 20:45:46 2007
@@ -60,15 +60,17 @@
- ``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
-so we can reuse its name for the mutable bytes type.
+just mentioned here to justify getting rid of the old ``buffer`` 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 @@
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 |
- +--------------+-------------+------------+--------------------+
- | PyUnicode | unicode u'' | str '' | str '' |
- | PyString | str '' | str8 s'' | bytes b'' |
- | PyBytes | N/A | bytes b'' | buffer buffer(b'') |
- | PyBuffer | buffer | buffer | N/A |
- | PyMemoryView | N/A | memoryview | memoryview |
- +--------------+-------------+------------+--------------------+
+ +--------------+-------------+------------+--------------------------+
+ | C name | 2.x repr | 3.0a1 repr | 3.0a2 repr |
+ +--------------+-------------+------------+--------------------------+
+ | PyUnicode | unicode u'' | str '' | str '' |
+ | PyString | str '' | str8 s'' | bytes b'' |
+ | PyBytes | N/A | bytes b'' | bytearray bytearray(b'') |
+ | PyBuffer | buffer | buffer | N/A |
+ | 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
-buffer object, use buffer(b'...') or buffer([...]). The latter may
-use a list of integers in range(256).
+bytes object, whatever variation is used. To create a mutable array
+of bytes, use bytearray(b'...') or bytearray([...]). The latter form
+takes a list of integers in range(256).
Functionality
=============
@@ -103,8 +105,8 @@
PEP 3118 Buffer API
-------------------
-Both bytes and buffer implement the PEP 3118 buffer API. The bytes
-type only implements read-only requests; the buffer type allows
+Both bytes and bytearray implement the PEP 3118 buffer API. The bytes
+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 @@
------------
There are four forms of constructors, applicable to both bytes and
-buffer:
+bytearray:
- - ``bytes(<bytes>)``, ``bytes(<buffer>)``, ``buffer(<bytes>)``,
- ``buffer(<buffer>)``: simple copying constructors, with the note
- that ``bytes(<bytes>)`` might return its (immutable) argument.
+ - ``bytes(<bytes>)``, ``bytes(<bytearray>)``, ``bytearray(<bytes>)``,
+ ``bytearray(<bytearray>)``: simple copying constructors, with the
+ 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.
- The <encoding> argument is mandatory; <errors> is optional.
+ ``str.encode()`` method returns an *immutable* bytes object. The
+ <encoding> argument is mandatory; <errors> is optional.
+ <encoding> and <errrors>, if given, must be ``str`` instances.
+
+ - ``bytes(<memory view>)``, ``bytearray(<memory view>)``: construct
+ a bytes or bytearray object from anything that implements the PEP
+ 3118 buffer API.
+
+ - ``bytes(<iterable of ints>)``, ``bytearray(<iterable of ints>)``:
+ construct a bytes or bytearray object from a stream of integers in
+ range(256).
- - ``bytes(<memory view>)``, ``buffer(<memory view>)``: construct a
- bytes or buffer object from anything implementing the PEP 3118
- buffer API.
-
- - ``bytes(<iterable of ints>)``, ``buffer(<iterable of ints>)``:
- construct an immutable bytes or mutable buffer object from a
- stream of integers in range(256).
-
- - ``buffer(<int>)``: construct a zero-initialized buffer of a given
- length.
+ - ``bytes(<int>)``, ``bytearray(<int>)``: construct a
+ zero-initialized bytes or bytearray object of a given length.
Comparisons
-----------
-The bytes and buffer types are comparable with each other and
-orderable, so that e.g. b'abc' == buffer(b'abc') < b'abd'.
+The bytes and bytearray types are comparable with each other and
+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 @@
Slicing
-------
-Slicing a bytes object returns a bytes object. Slicing a buffer
-object returns a buffer object.
+Slicing a bytes object returns a bytes object. Slicing a bytearray
+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 @@
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,
-except where mentioned:
+The following operators are implemented by the bytes and bytearray
+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 @@
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 @@
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 @@
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
-raise a TypeError exception. (However, comparing bytes/buffer and str
-objects for equality will simply return False; see the section on
+bytearray) objects and str objects without specifying an encoding will
+raise a TypeError exception. (However, comparing bytes/bytearray and
+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
More information about the Python-checkins
mailing list