[Python-checkins] r58267 - peps/trunk/pep-3137.txt

[guido.van.rossum]

Author: guido.van.rossum
Date: Thu Sep 27 01:06:19 2007
New Revision: 58267

Modified:
   peps/trunk/pep-3137.txt
Log:
Added language about operators and pickling.
Standardized on "implementing" the PEP 3118 buffer API rather than
"supporting" it.


Modified: peps/trunk/pep-3137.txt
==============================================================================
--- peps/trunk/pep-3137.txt	(original)
+++ peps/trunk/pep-3137.txt	Thu Sep 27 01:06:19 2007
@@ -87,9 +87,9 @@
 PEP 3118 Buffer API
 -------------------
 
-Both bytes and buffer support the PEP 3118 buffer API.  The bytes type
-only supports read-only requests; the buffer type allows writable and
-data-locked requests as well.  The element data type is always 'B'
+Both bytes and buffer implement the PEP 3118 buffer API.  The bytes
+type only supports read-only requests; the buffer type allows writable
+and data-locked requests as well.  The element data type is always 'B'
 (i.e. unsigned byte).
 
 Constructors
@@ -108,7 +108,7 @@
     The <encoding> argument is mandatory; <errors> is optional.
 
   - ``bytes(<memory view>)``, ``buffer(<memory view>)``: construct a
-    bytes or buffer object from anything that supports the PEP 3118
+    bytes or buffer object from anything implementing the PEP 3118
     buffer API.
 
   - ``bytes(<iterable of ints>)``, ``buffer(<iterable of ints>)``:
@@ -134,7 +134,7 @@
 object returns a buffer object.
 
 Slice assignment to a mutable buffer object accept anything that
-supports the PEP 3118 buffer API, or an iterable of integers in
+implements the PEP 3118 buffer API, or an iterable of integers in
 range(256).
 
 Indexing
@@ -159,6 +159,36 @@
 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'...')".
 
+Operators
+---------
+
+The following operators are supported by the bytes and buffer types,
+except where mentioned:
+
+  - ``b1 + b2``: concatenation.  With mixed bytes/buffer 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.
+
+  - ``b * n``, ``n * b``: repetition; n must be an integer.
+
+  - ``b *= n``: mutates b if it is a buffer object.
+
+  - ``b1 in b2``, ``b1 not in b2``: substring test; b1 can be any
+    object implementing the PEP 3118 buffer API.
+
+  - ``i in b``, ``i not in b``: single-byte membership test; i must
+    be an integer (if it is a length-1 bytes array, it is considered
+    to be a substring test, with the same outcome).
+
+  - ``len(b)``: the number of bytes.
+
+  - ``hash(b)``: the hash value; only implemented by the bytes type.
+
+Note that the % operator is *not* supported.  It does not appear worth
+the complexity.
+
 Methods
 -------
 
@@ -212,16 +242,21 @@
 promise that printing a bytes object interprets the individual bytes
 as characters (unlike in Python 2.x).
 
-The str type currently supports the PEP 3118 buffer API.  While this is
-perhaps occasionally convenient, it is also potentially confusing,
+The str type currently implements the PEP 3118 buffer API.  While this
+is perhaps occasionally convenient, it is also potentially confusing,
 because the bytes accessed via the buffer API represent a
 platform-depending encoding: depending on the platform byte order and
 a compile-time configuration option, the encoding could be UTF-16-BE,
 UTF-16-LE, UTF-32-BE, or UTF-32-LE.  Worse, a different implementation
 of the str type might completely change the bytes representation,
 e.g. to UTF-8, or even make it impossible to access the data as a
-contiguous array of bytes at all.  Therefore, support for the PEP 3118
-buffer API will be removed from the str type.
+contiguous array of bytes at all.  Therefore, the PEP 3118 buffer API
+will be removed from the str type.
+
+Pickling
+--------
+
+Left as an exercise for the reader.
 
 Copyright
 =========