diff --git a/pep-0461.txt b/pep-0461.txt index bf97983be..0ba446ff9 100644 --- a/pep-0461.txt +++ b/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