gh-104922: Doc: add note about PY_SSIZE_T_CLEAN (#106314)

Add note about PY_SSIZE_T_CLEAN in extending and embedding document.

diff --git a/Doc/extending/embedding.rst b/Doc/extending/embedding.rst
index 1470029b804779ae8725a7211e629b2a3d1fc8fe..bd1abe36cbb80e2862f24c8cc38fd1f4c4261fcd 100644 (file)
--- a/Doc/extending/embedding.rst
+++ b/Doc/extending/embedding.rst
@@ -87,6 +87,13 @@ perform some operation on a file. ::
         Py_ExitStatusException(status);
    }
 
+.. note::
+
+   ``#define PY_SSIZE_T_CLEAN`` was used to indicate that ``Py_ssize_t`` should be
+   used in some APIs instead of ``int``.
+   It is not necessary since Python 3.13, but we keep it here for backward compatibility.
+   See :ref:`arg-parsing-string-and-buffers` for a description of this macro.
+
 Setting :c:member:`PyConfig.program_name` should be called before
 :c:func:`Py_InitializeFromConfig` to inform the interpreter about paths to Python run-time
 libraries.  Next, the Python interpreter is initialized with

diff --git a/Doc/extending/extending.rst b/Doc/extending/extending.rst
index ef93848840861c3800e42d3f59fc509bc3f3c0a5..7d08bb9f6b8dd893d7d2774526f058f85804edcb 100644 (file)
--- a/Doc/extending/extending.rst
+++ b/Doc/extending/extending.rst
@@ -69,8 +69,10 @@ the module and a copyright notice if you like).
    headers on some systems, you *must* include :file:`Python.h` before any standard
    headers are included.
 
-   It is recommended to always define ``PY_SSIZE_T_CLEAN`` before including
-   ``Python.h``.  See :ref:`arg-parsing-string-and-buffers` for a description of this macro.
+   ``#define PY_SSIZE_T_CLEAN`` was used to indicate that ``Py_ssize_t`` should be
+   used in some APIs instead of ``int``.
+   It is not necessary since Python 3.13, but we keep it here for backward compatibility.
+   See :ref:`arg-parsing-string-and-buffers` for a description of this macro.
 
 All user-visible symbols defined by :file:`Python.h` have a prefix of ``Py`` or
 ``PY``, except those defined in standard header files. For convenience, and