#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.

2 files changed, 27 insertions, 2 deletions

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 @@ Object Protocol
 
    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 @@ the Python configuration.
 
    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 @@ APIs:
    |                   |                     | 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 |