[Python-checkins] peps: PEP 467: more concrete examples of current inconsistencies

[nick.coghlan]

http://hg.python.org/peps/rev/9b80a489c6e4
changeset:   5451:9b80a489c6e4
user:        Nick Coghlan <ncoghlan at gmail.com>
date:        Sun Mar 30 17:03:44 2014 +1000
summary:
  PEP 467: more concrete examples of current inconsistencies

files:
  pep-0467.txt |  48 +++++++++++++++++++++++++++++++++++++--
  1 files changed, 45 insertions(+), 3 deletions(-)


diff --git a/pep-0467.txt b/pep-0467.txt
--- a/pep-0467.txt
+++ b/pep-0467.txt
@@ -182,12 +182,49 @@
 Consistent support for different input types
 --------------------------------------------
 
+The ``bytes`` and ``bytearray`` methods inspired by the Python 2 ``str``
+type generally expect to operate on binary subsequences: other objects
+implementing the buffer API. By contrast, the mutating APIs added to
+the ``bytearray`` interface expect to operate on individual elements:
+integer in the range 0 to 255 (inclusive).
+
 In Python 3.3, the binary search operations (``in``, ``count()``,
 ``find()``, ``index()``, ``rfind()`` and ``rindex()``) were updated to
-accept integers in the range 0 to 255 (inclusive) as their first argument
-(in addition to the existing support for binary sequences).
+accept integers in the range 0 to 255 (inclusive) as their first argument,
+in addition to the existing support for binary subsequences.
 
-This PEP proposes extending that behaviour of accepting integers as being
+This results in behaviour like the following in Python 3.3+::
+
+    >>> data = bytes([1, 2, 3, 4])
+    >>> 3 in data
+    True
+    >>> b"\x03" in data
+    True
+    >>> data.count(3)
+    1
+    >>> data.count(b"\x03")
+    1
+
+    >>> data.replace(3, 4)
+    Traceback (most recent call last):
+      File "<stdin>", line 1, in <module>
+    TypeError: expected bytes, bytearray or buffer compatible object
+    >>> data.replace(b"\x03", b"\x04")
+    b'\x01\x02\x04\x04'
+
+    >>> mutable = bytearray(data)
+    >>> mutable
+    bytearray(b'\x01\x02\x03\x04')
+    >>> mutable.append(b"\x05")
+    Traceback (most recent call last):
+      File "<stdin>", line 1, in <module>
+    TypeError: an integer is required
+    >>> mutable.append(5)
+    >>> mutable
+    bytearray(b'\x01\x02\x03\x04\x05')
+
+
+This PEP proposes extending the behaviour of accepting integers as being
 equivalent to the corresponding length 1 binary sequence to several other
 ``bytes`` and ``bytearray`` methods that currently expect a ``bytes``
 object for certain parameters. In essence, if a value is an acceptable
@@ -227,6 +264,11 @@
 * ``+=``: updated to be consistent with ``bytes()`` changes (if any)
 * ``extend()``: updated to be consistent with ``bytes()`` changes (if any)
 
+The general principle behind these changes is to restore the flexible
+"element-or-subsequence" behaviour seen in the ``str`` API, even though
+Python 3 actually represents subsequences and individual elements as
+distinct types in the binary domain.
+
 
 Acknowledgement of surprising behaviour of some ``bytearray`` methods
 ---------------------------------------------------------------------

-- 
Repository URL: http://hg.python.org/peps