[Python-checkins] peps: added list of currently supported codes; modified description for %a; added

Wed Mar 26 15:46:40 CET 2014

http://hg.python.org/peps/rev/bede07793448
changeset: 5433:bede07793448
user: Ethan Furman <ethan at stoneleaf.us>
date: Wed Mar 26 07:46:34 2014 -0700
summary:
 added list of currently supported codes; modified description for %a; added reference to competing PEP 460
files:
 pep-0461.txt | 46 ++++++++++++++++++++++++++-------------
 1 files changed, 31 insertions(+), 15 deletions(-)

diff --git a/pep-0461.txt b/pep-0461.txt
--- a/pep-0461.txt
+++ b/pep-0461.txt
@@ -50,11 +50,17 @@
 %-interpolation
 ---------------
 
-All the numeric formatting codes (such as ``%x``, ``%o``, ``%e``, ``%f``,
-``%g``, etc.) will be supported, and will work as they do for str, including
-the padding, justification and other related modifiers. The only difference
-will be that the results from these codes will be ASCII-encoded text, not
-unicode. In other words, for any numeric formatting code `%x`::
+All the numeric formatting codes (``d``, ``i``, ``o``, ``u``, ``x``, ``X``,
+``e``, ``E'', ``f``, ``F``, ``g``, ``G``, and any that are subsequently added
+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``.
+
+For the numeric codes, the only difference between ``str`` and ``bytes`` (or
+``bytearray``) interpolation is that the results from these codes will be
+ASCII-encoded text, not unicode. In other words, for any numeric formatting
+code `%x`::
 
 b"%x" % val
 
@@ -116,18 +122,24 @@
 TypeError: b'%s' does not accept 'str', it must be encoded to `bytes`
 
 
-``%a`` will call ``ascii()`` on the interpolated value. This is intended
-as a debugging aid, rather than something that should be used in production.
-Non-ASCII values will be encoded to either ``\xnn`` or ``\unnnn``
-representation. Use cases include developing a new protocol and writing
-landmarks into the stream; debugging data going into an existing protocol
-to see if the problem is the protocol itself or bad data; a fall-back for a
-serialization format; or even a rudimentary serialization format when
-defining ``__bytes__`` would not be appropriate [8].
+``%a`` will give the equivalent of
+``repr(some_obj).encode('ascii', 'backslashreplace')`` on the interpolated
+value. Use cases include developing a new protocol and writing landmarks
+into the stream; debugging data going into an existing protocol to see if
+the problem is the protocol itself or bad data; a fall-back for a serialization
+format; or any situation where defining ``__bytes__`` would not be appropriate
+but a readable/informative representation is needed [8].
 
-.. note::
+Examples::
 
- If a ``str`` is passed into ``%a``, it will be surrounded by quotes.
+ >>> b'%a' % 3.14
+ b'3.14'
+
+ >>> b'%a' % b'abc'
+ b'abc'
+
+ >>> b'%a' % 'def'
+ b"'def'"
 
 
 Unsupported codes
@@ -166,6 +178,9 @@
 ``__format_bytes__``, etc.; such methods are not needed at this time, but can
 be visited again later if real-world use shows deficiencies with this solution.
 
+A competing PEP, ``PEP 460 Add binary interpolation and formatting`` [9], also
+exists.
+
 
 Objections
 ==========
@@ -204,6 +219,7 @@
 examples: ``memoryview``, ``array.array``, ``bytearray``, ``bytes``
 .. [7] http://docs.python.org/3/reference/datamodel.html#object.__bytes__
 .. [8] https://mail.python.org/pipermail/python-dev/2014-February/132750.html
+.. [9] http://python.org/dev/peps/pep-0460/
 
 
 Copyright
-- 
Repository URL: http://hg.python.org/peps
