remembered to save changes before committing :/

pep-0461.txt

@@ -55,7 +55,8 @@ All the numeric formatting codes (``d``, ``i``, ``o``, ``u``, ``x``, ``X``,
 to Python 3) will be supported, and will work as they do for str, including
 the padding, justification and other related modifiers (currently ``#``, ``0``,
 ``-``, `` `` (space), and ``+`` (plus any added to Python 3)).  The only
-non-numeric codes allowed are ``c``, ``s``, and ``a``.
+non-numeric codes allowed are ``c``, ``b``, ``a``, and ``s`` (which is a
+synonym for b).
 
 For the numeric codes, the only difference between ``str`` and ``bytes`` (or
 ``bytearray``) interpolation is that the results from these codes will be
@@ -90,9 +91,8 @@ Examples::
     >>> b'%c' % b'a'
     b'a'
 
-``%s`` is included for two reasons:  1) `b` is already a format code for
-``format`` numerics (binary), and 2) it will make 2/3 code easier as Python 2.x
-code uses ``%s``; however, it is restricted in what it will accept:
+``%b`` will insert a series of bytes.  These bytes are collected in one of two
+ways: 
 
   - input type supports ``Py_buffer`` [4]_?
     use it to collect the necessary bytes
@@ -100,7 +100,7 @@ code uses ``%s``; however, it is restricted in what it will accept:
   - input type is something else?
     use its ``__bytes__`` method [5]_ ; if there isn't one, raise a ``TypeError``
 
-In particular, ``%s`` will not accept numbers nor ``str``.  ``str`` is rejected
+In particular, ``%b`` will not accept numbers nor ``str``.  ``str`` is rejected
 as the string to bytes conversion requires an encoding, and we are refusing to
 guess; numbers are rejected because:
 
@@ -111,23 +111,26 @@ guess; numbers are rejected because:
 
   - given the nature of wire formats, explicit is definitely better than implicit
 
+``%s`` is included as a synonym for ``%b`` for the sole purpose of making 2/3 code
+bases easier to maintain.  Python 3 only code should use ``%b``.
+
 Examples::
 
-    >>> b'%s' % b'abc'
+    >>> b'%b' % b'abc'
     b'abc'
 
-    >>> b'%s' % 'some string'.encode('utf8')
+    >>> b'%b' % 'some string'.encode('utf8')
     b'some string'
 
-    >>> b'%s' % 3.14
+    >>> b'%b' % 3.14
     Traceback (most recent call last):
     ...
-    TypeError: b'%s' does not accept numbers, use a numeric code instead
+    TypeError: b'%b' does not accept 'float'
 
-    >>> b'%s' % 'hello world!'
+    >>> b'%b' % 'hello world!'
     Traceback (most recent call last):
     ...
-    TypeError: b'%s' does not accept 'str', it must be encoded to `bytes`
+    TypeError: b'%b' does not accept 'str'
 
 
 ``%a`` will give the equivalent of
@@ -159,20 +162,14 @@ Unsupported codes
 Proposed variations
 ===================
 
-It was suggested to let ``%s`` accept numbers, but since numbers have their own
-format codes this idea was discarded.
-
-It has been suggested to use ``%b`` for bytes as well as ``%s``.  This was
-rejected as not adding any value either in clarity or simplicity.
-
 It has been proposed to automatically use ``.encode('ascii','strict')`` for
-``str`` arguments to ``%s``.
+``str`` arguments to ``%b``.
 
   - Rejected as this would lead to intermittent failures.  Better to have the
     operation always fail so the trouble-spot can be correctly fixed.
 
-It has been proposed to have ``%s`` return the ascii-encoded repr when the
-value is a ``str`` (b'%s' % 'abc'  --> b"'abc'").
+It has been proposed to have ``%b`` return the ascii-encoded repr when the
+value is a ``str`` (b'%b' % 'abc'  --> b"'abc'").
 
   - Rejected as this would lead to hard to debug failures far from the problem
     site.  Better to have the operation always fail so the trouble-spot can be