bpo-36346: Doc: Update removal schedule of legacy Unicode (GH-21479)

See PEP 623 for detail.
(cherry picked from commit 270b4ad4df795783d417ba15080da8f95e598689)

Co-authored-by: Inada Naoki <songofacandy@gmail.com>

1 files changed, 30 insertions, 9 deletions

diff --git a/Doc/c-api/unicode.rst b/Doc/c-api/unicode.rst
index 0515183..4750f24 100644
--- a/Doc/c-api/unicode.rst
+++ b/Doc/c-api/unicode.rst
@@ -34,6 +34,11 @@ can internally be in two states depending on how they were created:
   :c:type:`Py_UNICODE*` representation; you will have to call
   :c:func:`PyUnicode_READY` on them before calling any other API.
 
+.. note::
+   The "legacy" Unicode object will be removed in Python 3.12 with deprecated
+   APIs. All Unicode objects will be "canonical" since then. See :pep:`623`
+   for more information.
+
 
 Unicode Type
 """"""""""""
@@ -107,6 +112,9 @@ access internal read-only data of Unicode objects:
 
    .. versionadded:: 3.3
 
+   .. deprecated-removed:: 3.10 3.12
+      This API will be removed with :c:func:`PyUnicode_FromUnicode`.
+
 
 .. c:function:: Py_ssize_t PyUnicode_GET_LENGTH(PyObject *o)
 
@@ -138,6 +146,9 @@ access internal read-only data of Unicode objects:
 
    .. versionadded:: 3.3
 
+   .. deprecated-removed:: 3.10 3.12
+      ``PyUnicode_WCHAR_KIND`` is deprecated.
+
 
 .. c:function:: int PyUnicode_KIND(PyObject *o)
 
@@ -203,7 +214,7 @@ access internal read-only data of Unicode objects:
    code units (this includes surrogate pairs as 2 units).  *o* has to be a
    Unicode object (not checked).
 
-   .. deprecated-removed:: 3.3 4.0
+   .. deprecated-removed:: 3.3 3.12
       Part of the old-style Unicode API, please migrate to using
       :c:func:`PyUnicode_GET_LENGTH`.
 
@@ -213,7 +224,7 @@ access internal read-only data of Unicode objects:
    Return the size of the deprecated :c:type:`Py_UNICODE` representation in
    bytes.  *o* has to be a Unicode object (not checked).
 
-   .. deprecated-removed:: 3.3 4.0
+   .. deprecated-removed:: 3.3 3.12
       Part of the old-style Unicode API, please migrate to using
       :c:func:`PyUnicode_GET_LENGTH`.
 
@@ -235,7 +246,7 @@ access internal read-only data of Unicode objects:
       code to use the new :c:func:`PyUnicode_nBYTE_DATA` macros or use
       :c:func:`PyUnicode_WRITE` or :c:func:`PyUnicode_READ`.
 
-   .. deprecated-removed:: 3.3 4.0
+   .. deprecated-removed:: 3.3 3.12
       Part of the old-style Unicode API, please migrate to using the
       :c:func:`PyUnicode_nBYTE_DATA` family of macros.
 
@@ -687,8 +698,10 @@ Extension modules can continue using them, as they will not be removed in Python
    string content has been filled before using any of the access macros such as
    :c:func:`PyUnicode_KIND`.
 
-   Please migrate to using :c:func:`PyUnicode_FromKindAndData`,
-   :c:func:`PyUnicode_FromWideChar` or :c:func:`PyUnicode_New`.
+   .. deprecated-removed:: 3.3 3.12
+      Part of the old-style Unicode API, please migrate to using
+      :c:func:`PyUnicode_FromKindAndData`, :c:func:`PyUnicode_FromWideChar`, or
+      :c:func:`PyUnicode_New`.
 
 
 .. c:function:: Py_UNICODE* PyUnicode_AsUnicode(PyObject *unicode)
@@ -701,9 +714,10 @@ Extension modules can continue using them, as they will not be removed in Python
    embedded null code points, which would cause the string to be truncated when
    used in most C functions.
 
-   Please migrate to using :c:func:`PyUnicode_AsUCS4`,
-   :c:func:`PyUnicode_AsWideChar`, :c:func:`PyUnicode_ReadChar` or similar new
-   APIs.
+   .. deprecated-removed:: 3.3 3.12
+      Part of the old-style Unicode API, please migrate to using
+      :c:func:`PyUnicode_AsUCS4`, :c:func:`PyUnicode_AsWideChar`,
+      :c:func:`PyUnicode_ReadChar` or similar new APIs.
 
    .. deprecated-removed:: 3.3 3.10
 
@@ -725,6 +739,11 @@ Extension modules can continue using them, as they will not be removed in Python
 
    .. versionadded:: 3.3
 
+   .. deprecated-removed:: 3.3 3.12
+      Part of the old-style Unicode API, please migrate to using
+      :c:func:`PyUnicode_AsUCS4`, :c:func:`PyUnicode_AsWideChar`,
+      :c:func:`PyUnicode_ReadChar` or similar new APIs.
+
 
 .. c:function:: Py_UNICODE* PyUnicode_AsUnicodeCopy(PyObject *unicode)
 
@@ -745,7 +764,9 @@ Extension modules can continue using them, as they will not be removed in Python
    Return the size of the deprecated :c:type:`Py_UNICODE` representation, in
    code units (this includes surrogate pairs as 2 units).
 
-   Please migrate to using :c:func:`PyUnicode_GetLength`.
+   .. deprecated-removed:: 3.3 3.12
+      Part of the old-style Unicode API, please migrate to using
+      :c:func:`PyUnicode_GET_LENGTH`.
 
 
 .. c:function:: PyObject* PyUnicode_FromObject(PyObject *obj)