From 42ec190761a2e8503aaa06f0bfaaabe98749179b Mon Sep 17 00:00:00 2001
From: INADA Naoki <methane@users.noreply.github.com>
Date: Wed, 4 Apr 2018 13:59:08 +0900
Subject: [PATCH] bpo-33195: Doc: Deprecate Py_UNICODE in c-api/arg (GH-6329)

Py_UNICODE is deprecated since Python 3.3.
But the deprecation is missed in the c-api/arg document.
---
 Doc/c-api/arg.rst                             | 27 +++++++++++++++----
 .../2018-04-01-14-30-36.bpo-33195.dRS-XX.rst  |  3 +++
 2 files changed, 25 insertions(+), 5 deletions(-)
 create mode 100644 Misc/NEWS.d/next/Documentation/2018-04-01-14-30-36.bpo-33195.dRS-XX.rst

diff --git a/Doc/c-api/arg.rst b/Doc/c-api/arg.rst
index e4b48e66bc2..b41130ede41 100644
--- a/Doc/c-api/arg.rst
+++ b/Doc/c-api/arg.rst
@@ -151,19 +151,35 @@ which disallows mutable objects such as :class:`bytearray`.
       Previously, :exc:`TypeError` was raised when embedded null code points
       were encountered in the Python string.
 
+   .. deprecated-removed:: 3.3 4.0
+      Part of the old-style :c:type:`Py_UNICODE` API; please migrate to using
+      :c:func:`PyUnicode_AsWideCharString`.
+
 ``u#`` (:class:`str`) [const Py_UNICODE \*, int]
    This variant on ``u`` stores into two C variables, the first one a pointer to a
    Unicode data buffer, the second one its length.  This variant allows
    null code points.
 
+   .. deprecated-removed:: 3.3 4.0
+      Part of the old-style :c:type:`Py_UNICODE` API; please migrate to using
+      :c:func:`PyUnicode_AsWideCharString`.
+
 ``Z`` (:class:`str` or ``None``) [const Py_UNICODE \*]
    Like ``u``, but the Python object may also be ``None``, in which case the
    :c:type:`Py_UNICODE` pointer is set to *NULL*.
 
+   .. deprecated-removed:: 3.3 4.0
+      Part of the old-style :c:type:`Py_UNICODE` API; please migrate to using
+      :c:func:`PyUnicode_AsWideCharString`.
+
 ``Z#`` (:class:`str` or ``None``) [const Py_UNICODE \*, int]
    Like ``u#``, but the Python object may also be ``None``, in which case the
    :c:type:`Py_UNICODE` pointer is set to *NULL*.
 
+   .. deprecated-removed:: 3.3 4.0
+      Part of the old-style :c:type:`Py_UNICODE` API; please migrate to using
+      :c:func:`PyUnicode_AsWideCharString`.
+
 ``U`` (:class:`str`) [PyObject \*]
    Requires that the Python object is a Unicode object, without attempting
    any conversion.  Raises :exc:`TypeError` if the object is not a Unicode
@@ -552,12 +568,13 @@ Building values
    ``z#`` (:class:`str` or ``None``) [const char \*, int]
       Same as ``s#``.
 
-   ``u`` (:class:`str`) [const Py_UNICODE \*]
-      Convert a null-terminated buffer of Unicode (UCS-2 or UCS-4) data to a Python
-      Unicode object.  If the Unicode buffer pointer is *NULL*, ``None`` is returned.
+   ``u`` (:class:`str`) [const wchar_t \*]
+      Convert a null-terminated :c:type:`wchar_t` buffer of Unicode (UTF-16 or UCS-4)
+      data to a Python Unicode object.  If the Unicode buffer pointer is *NULL*,
+      ``None`` is returned.
 
-   ``u#`` (:class:`str`) [const Py_UNICODE \*, int]
-      Convert a Unicode (UCS-2 or UCS-4) data buffer and its length to a Python
+   ``u#`` (:class:`str`) [const wchar_t \*, int]
+      Convert a Unicode (UTF-16 or UCS-4) data buffer and its length to a Python
       Unicode object.   If the Unicode buffer pointer is *NULL*, the length is ignored
       and ``None`` is returned.
 
diff --git a/Misc/NEWS.d/next/Documentation/2018-04-01-14-30-36.bpo-33195.dRS-XX.rst b/Misc/NEWS.d/next/Documentation/2018-04-01-14-30-36.bpo-33195.dRS-XX.rst
new file mode 100644
index 00000000000..6884640325b
--- /dev/null
+++ b/Misc/NEWS.d/next/Documentation/2018-04-01-14-30-36.bpo-33195.dRS-XX.rst
@@ -0,0 +1,3 @@
+Deprecate ``Py_UNICODE`` usage in ``c-api/arg`` document. ``Py_UNICODE``
+related APIs are deprecated since Python 3.3, but it is missed in the
+document.