Update the PEP with the new name for PyByte (bytearray), and some minor edits.
This commit is contained in:
Guido van Rossum
parent
72044f05a8
commit
a6fafa5485
110
pep-3137.txt
110
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
|
||||
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 @@ 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 |
|
||||
+--------------+-------------+------------+--------------------+
|
||||
| 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 @@ Functionality
|
|||
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 @@ Constructors
|
|||
------------
|
||||
|
||||
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>)``, ``buffer(<memory view>)``: construct a
|
||||
bytes or buffer object from anything implementing the PEP 3118
|
||||
buffer API.
|
||||
- ``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>)``, ``buffer(<iterable of ints>)``:
|
||||
construct an immutable bytes or mutable buffer object from a
|
||||
stream of integers in range(256).
|
||||
- ``bytes(<iterable of ints>)``, ``bytearray(<iterable of ints>)``:
|
||||
construct a bytes or bytearray 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 @@ 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
|
||||
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 @@ 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,
|
||||
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 @@ 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
|
||||
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
|
||||
|
|
|
|||
Loading…
Reference in New Issue