[Python-checkins] peps: Update PEP 467 following docs updates

[nick.coghlan]

http://hg.python.org/peps/rev/7cc8313fadf7
changeset:   5517:7cc8313fadf7
user:        Nick Coghlan <ncoghlan at gmail.com>
date:        Fri Aug 15 15:34:40 2014 +1000
summary:
  Update PEP 467 following docs updates

files:
  pep-0467.txt |  65 +++++++++++----------------------------
  1 files changed, 18 insertions(+), 47 deletions(-)


diff --git a/pep-0467.txt b/pep-0467.txt
--- a/pep-0467.txt
+++ b/pep-0467.txt
@@ -1,5 +1,5 @@
 PEP: 467
-Title: Improved API consistency for bytes and bytearray
+Title: Minor API improvements for bytes and bytearray
 Version: $Revision$
 Last-Modified: $Date$
 Author: Nick Coghlan <ncoghlan at gmail.com>
@@ -8,7 +8,7 @@
 Content-Type: text/x-rst
 Created: 2014-03-30
 Python-Version: 3.5
-Post-History: 2014-03-30
+Post-History: 2014-03-30 2014-08-15
 
 
 Abstract
@@ -21,11 +21,8 @@
 3 series.
 
 This PEP proposes a number of small adjustments to the APIs of the ``bytes``
-and ``bytearray`` types to make their behaviour more internally consistent
-and to make it easier to operate entirely in the binary domain, as well as
-changes to their documentation to make it easier to grasp their dual roles
-as containers of "arbitrary binary data" and "binary data with ASCII
-compatible segments".
+and ``bytearray`` types to make it easier to operate entirely in the binary
+domain.
 
 
 Background
@@ -39,14 +36,18 @@
 simplifying shortcut.
 
 However, it turns out that this approach to the documentation of these types
-has a problem: it doesn't adequately introduce users to their hybrid nature,
+had a problem: it doesn't adequately introduce users to their hybrid nature,
 where they can be manipulated *either* as a "sequence of integers" type,
 *or* as ``str``-like types that assume ASCII compatible data.
 
-In addition to the documentation issues, there are some lingering design
-quirks from an earlier pre-release design where there was *no* separate
-``bytearray`` type, and instead the core ``bytes`` type was mutable (with
-no immutable counterpart).
+That oversight has now been corrected, with the binary sequence types now
+being documented entirely independently of the ``str`` documentation in
+`Python 3.4+ <https://docs.python.org/3/library/stdtypes.html#binary-sequence-types-bytes-bytearray-memoryview>`__
+
+The confusion isn't just a documentation issue, however, as there are also
+some lingering design quirks from an earlier pre-release design where there
+was *no* separate ``bytearray`` type, and instead the core ``bytes`` type
+was mutable (with no immutable counterpart).
 
 Finally, additional experience with using the existing Python 3 binary
 sequence types in real world applications has suggested it would be
@@ -56,19 +57,13 @@
 Proposals
 =========
 
-As a "consistency improvement" proposal, this PEP is actually about a number
-of smaller micro-proposals, each aimed at improving the self-consistency of
-the binary data model in Python 3. Proposals are motivated by one of three
-factors:
+As a "consistency improvement" proposal, this PEP is actually about a few
+smaller micro-proposals, each aimed at improving the usability of the binary
+data model in Python 3. Proposals are motivated by one of two main factors:
 
 * removing remnants of the original design of ``bytes`` as a mutable type
 * allowing users to easily convert integer values to a length 1 ``bytes``
   object
-* consistently applying the following analogies to the type API designs
-  and documentation:
-
-  * ``bytes``: tuple of integers, with additional str-like methods
-  * ``bytearray``: list of integers, with additional str-like methods
 
 
 Alternate Constructors
@@ -78,7 +73,7 @@
 argument, but interpret it to mean a zero-filled object of the given length.
 This is a legacy of the original design of ``bytes`` as a mutable type,
 rather than a particularly intuitive behaviour for users. It has become
-especially confusing now that other ``bytes`` interfaces treat integers
+especially confusing now that some other ``bytes`` interfaces treat integers
 and the corresponding length 1 bytes instances as equivalent input.
 Compare::
 
@@ -176,36 +171,12 @@
         # 0 to 255 inclusive
 
 
-Documentation clarifications
-----------------------------
-
-In an attempt to clarify the `documentation
-<https://docs.python.org/dev/library/stdtypes.html#binary-sequence-types-bytes-bytearray-memoryview>`__
-of the ``bytes`` and ``bytearray`` types, the following changes are
-proposed:
-
-* the documentation of the *sequence* behaviour of each type is moved to
-  section for that individual type. These sections will be updated to
-  explicitly make the ``tuple of integers`` and ``list of integers``
-  analogies, as well as to make it clear that these parts of the API work
-  with arbitrary binary data
-* the current "Bytes and bytearray operations" section will be updated to
-  "Handling binary data with ASCII compatible segments", and will explicitly
-  list *all* of the methods that are included.
-* clarify that due to their origins in the API of the immutable ``str``
-  type, even the ``bytearray`` versions of these methods do *not* operate
-  in place, but instead create a new object.
-
-A patch for at least this part of the proposal will be prepared before
-submitting the PEP for approval, as writing out these docs completely may
-suggest additional opportunities for API consistency improvements.
-
-
 References
 ==========
 
 .. [ideas-thread1] https://mail.python.org/pipermail/python-ideas/2014-March/027295.html
 .. [empty-buffer-issue] http://bugs.python.org/issue20895
+.. [GvR-initial-feedback] https://mail.python.org/pipermail/python-ideas/2014-March/027376.html
 
 
 Copyright

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