#2630: Implement PEP 3138.
The repr() of a string now contains printable Unicode characters unescaped.
The new ascii() builtin can be used to get a repr() with only ASCII characters in it.
PEP and patch were written by Atsuo Ishimoto.
diff --git a/Doc/c-api/object.rst b/Doc/c-api/object.rst
index c9c4a42..f377c75 100644
--- a/Doc/c-api/object.rst
+++ b/Doc/c-api/object.rst
@@ -116,8 +116,18 @@
Compute a string representation of object *o*. Returns the string
representation on success, *NULL* on failure. This is the equivalent of the
- Python expression ``repr(o)``. Called by the :func:`repr` built-in function and
- by reverse quotes.
+ Python expression ``repr(o)``. Called by the :func:`repr` built-in function.
+
+
+.. cfunction:: PyObject* PyObject_ASCII(PyObject *o)
+
+ .. index:: builtin: ascii
+
+ As :cfunc:`PyObject_Repr`, compute a string representation of object *o*, but
+ escape the non-ASCII characters in the string returned by
+ :cfunc:`PyObject_Repr` with ``\x``, ``\u`` or ``\U`` escapes. This generates
+ a string similar to that returned by :cfunc:`PyObject_Repr` in Python 2.
+ Called by the :func:`ascii` built-in function.
.. cfunction:: PyObject* PyObject_Str(PyObject *o)
diff --git a/Doc/c-api/unicode.rst b/Doc/c-api/unicode.rst
index 17c25d5..653ee6e 100644
--- a/Doc/c-api/unicode.rst
+++ b/Doc/c-api/unicode.rst
@@ -144,6 +144,18 @@
Return 1 or 0 depending on whether *ch* is an alphanumeric character.
+
+.. cfunction:: int Py_UNICODE_ISPRINTABLE(Py_UNICODE ch)
+
+ Return 1 or 0 depending on whether *ch* is a printable character.
+ Nonprintable characters are those characters defined in the Unicode character
+ database as "Other" or "Separator", excepting the ASCII space (0x20) which is
+ considered printable. (Note that printable characters in this context are
+ those which should not be escaped when :func:`repr` is invoked on a string.
+ It has no bearing on the handling of strings written to :data:`sys.stdout` or
+ :data:`sys.stderr`.)
+
+
These APIs can be used for fast direct character conversions:
@@ -266,6 +278,9 @@
| | | of what the platform's |
| | | ``printf`` yields. |
+-------------------+---------------------+--------------------------------+
+ | :attr:`%A` | PyObject\* | The result of calling |
+ | | | :func:`ascii`. |
+ +-------------------+---------------------+--------------------------------+
| :attr:`%U` | PyObject\* | A unicode object. |
+-------------------+---------------------+--------------------------------+
| :attr:`%V` | PyObject\*, char \* | A unicode object (which may be |
diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
index 875eea0..a420974 100644
--- a/Doc/library/functions.rst
+++ b/Doc/library/functions.rst
@@ -91,6 +91,14 @@
return False
+.. function:: ascii(object)
+
+ As :func:`repr`, return a string containing a printable representation of an
+ object, but escape the non-ASCII characters in the string returned by
+ :func:`repr` using ``\x``, ``\u`` or ``\U`` escapes. This generates a string
+ similar to that returned by :func:`repr` in Python 2.
+
+
.. function:: bin(x)
Convert an integer number to a binary string. The result is a valid Python
diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst
index 27c3fb4..0dd520e 100644
--- a/Doc/library/stdtypes.rst
+++ b/Doc/library/stdtypes.rst
@@ -774,6 +774,17 @@
least one cased character, false otherwise.
+.. method:: str.isprintable()
+
+ Return true if all characters in the string are printable or the string is
+ empty, false otherwise. Nonprintable characters are those characters defined
+ in the Unicode character database as "Other" or "Separator", excepting the
+ ASCII space (0x20) which is considered printable. (Note that printable
+ characters in this context are those which should not be escaped when
+ :func:`repr` is invoked on a string. It has no bearing on the handling of
+ strings written to :data:`sys.stdout` or :data:`sys.stderr`.)
+
+
.. method:: str.isspace()
Return true if there are only whitespace characters in the string and there is
diff --git a/Doc/library/string.rst b/Doc/library/string.rst
index a5c3a81..668a530 100644
--- a/Doc/library/string.rst
+++ b/Doc/library/string.rst
@@ -229,8 +229,9 @@
value to a string before calling :meth:`__format__`, the normal formatting logic
is bypassed.
-Two conversion flags are currently supported: ``'!s'`` which calls :func:`str`
-on the value, and ``'!r'`` which calls :func:`repr`.
+Three conversion flags are currently supported: ``'!s'`` which calls :func:`str`
+on the value, ``'!r'`` which calls :func:`repr` and ``'!a'`` which calls
+:func:`ascii`.
Some examples::
diff --git a/Doc/using/cmdline.rst b/Doc/using/cmdline.rst
index 0a45aa5..39f0e08 100644
--- a/Doc/using/cmdline.rst
+++ b/Doc/using/cmdline.rst
@@ -425,6 +425,9 @@
``encodingname:errorhandler``. The ``:errorhandler`` part is optional and
has the same meaning as in :func:`str.encode`.
+ For stderr, the ``:errorhandler`` part is ignored; the handler will always be
+ ``'backslashreplace'``.
+
.. envvar:: PYTHONNOUSERSITE