GH-122085: Use include files for C API deprecations (#109843)

AA-Turner · web-flow · commit 76bdfa4cd025 · 2024-07-29T22:20:40.000+01:00
diff --git a/Doc/deprecations/c-api-pending-removal-in-3.14.rst b/Doc/deprecations/c-api-pending-removal-in-3.14.rst
@@ -0,0 +1,46 @@
+Pending Removal in Python 3.14
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* The ``ma_version_tag`` field in :c:type:`PyDictObject` for extension modules
+  (:pep:`699`; :gh:`101193`).
+
+* Creating :c:data:`immutable types <Py_TPFLAGS_IMMUTABLETYPE>` with mutable
+  bases (:gh:`95388`).
+
+* Functions to configure Python's initialization, deprecated in Python 3.11:
+
+  * ``PySys_SetArgvEx()``: set :c:member:`PyConfig.argv` instead.
+  * ``PySys_SetArgv()``: set :c:member:`PyConfig.argv` instead.
+  * ``Py_SetProgramName()``: set :c:member:`PyConfig.program_name` instead.
+  * ``Py_SetPythonHome()``: set :c:member:`PyConfig.home` instead.
+
+  The :c:func:`Py_InitializeFromConfig` API should be used with
+  :c:type:`PyConfig` instead.
+
+* Global configuration variables:
+
+  * :c:var:`Py_DebugFlag`: use :c:member:`PyConfig.parser_debug` instead.
+  * :c:var:`Py_VerboseFlag`: use :c:member:`PyConfig.verbose` instead.
+  * :c:var:`Py_QuietFlag`: use :c:member:`PyConfig.quiet` instead.
+  * :c:var:`Py_InteractiveFlag`: use :c:member:`PyConfig.interactive` instead.
+  * :c:var:`Py_InspectFlag`: use :c:member:`PyConfig.inspect` instead.
+  * :c:var:`Py_OptimizeFlag`: use :c:member:`PyConfig.optimization_level` instead.
+  * :c:var:`Py_NoSiteFlag`: use :c:member:`PyConfig.site_import` instead.
+  * :c:var:`Py_BytesWarningFlag`: use :c:member:`PyConfig.bytes_warning` instead.
+  * :c:var:`Py_FrozenFlag`: use :c:member:`PyConfig.pathconfig_warnings` instead.
+  * :c:var:`Py_IgnoreEnvironmentFlag`: use :c:member:`PyConfig.use_environment` instead.
+  * :c:var:`Py_DontWriteBytecodeFlag`: use :c:member:`PyConfig.write_bytecode` instead.
+  * :c:var:`Py_NoUserSiteDirectory`: use :c:member:`PyConfig.user_site_directory` instead.
+  * :c:var:`Py_UnbufferedStdioFlag`: use :c:member:`PyConfig.buffered_stdio` instead.
+  * :c:var:`Py_HashRandomizationFlag`: use :c:member:`PyConfig.use_hash_seed`
+    and :c:member:`PyConfig.hash_seed` instead.
+  * :c:var:`Py_IsolatedFlag`: use :c:member:`PyConfig.isolated` instead.
+  * :c:var:`Py_LegacyWindowsFSEncodingFlag`: use :c:member:`PyPreConfig.legacy_windows_fs_encoding` instead.
+  * :c:var:`Py_LegacyWindowsStdioFlag`: use :c:member:`PyConfig.legacy_windows_stdio` instead.
+  * :c:var:`!Py_FileSystemDefaultEncoding`: use :c:member:`PyConfig.filesystem_encoding` instead.
+  * :c:var:`!Py_HasFileSystemDefaultEncoding`: use :c:member:`PyConfig.filesystem_encoding` instead.
+  * :c:var:`!Py_FileSystemDefaultEncodeErrors`: use :c:member:`PyConfig.filesystem_errors` instead.
+  * :c:var:`!Py_UTF8Mode`: use :c:member:`PyPreConfig.utf8_mode` instead. (see :c:func:`Py_PreInitialize`)
+
+  The :c:func:`Py_InitializeFromConfig` API should be used with
+  :c:type:`PyConfig` instead.
diff --git a/Doc/deprecations/c-api-pending-removal-in-3.15.rst b/Doc/deprecations/c-api-pending-removal-in-3.15.rst
@@ -0,0 +1,20 @@
+Pending Removal in Python 3.15
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* The bundled copy of ``libmpdecimal``.
+* :c:func:`PyImport_ImportModuleNoBlock`: use :c:func:`PyImport_ImportModule` instead.
+* :c:func:`PyWeakref_GET_OBJECT`: use :c:func:`PyWeakref_GetRef` instead.
+* :c:func:`PyWeakref_GetObject`: use :c:func:`PyWeakref_GetRef` instead.
+* :c:type:`!Py_UNICODE_WIDE` type: use :c:type:`wchar_t` instead.
+* :c:type:`Py_UNICODE` type: use :c:type:`wchar_t` instead.
+* Python initialization functions:
+
+  * :c:func:`PySys_ResetWarnOptions`: clear :data:`sys.warnoptions` and
+    :data:`!warnings.filters` instead.
+  * :c:func:`Py_GetExecPrefix`: get :data:`sys.exec_prefix` instead.
+  * :c:func:`Py_GetPath`: get :data:`sys.path` instead.
+  * :c:func:`Py_GetPrefix`: get :data:`sys.prefix` instead.
+  * :c:func:`Py_GetProgramFullPath`: get :data:`sys.executable` instead.
+  * :c:func:`Py_GetProgramName`: get :data:`sys.executable` instead.
+  * :c:func:`Py_GetPythonHome`: get :c:member:`PyConfig.home` or
+    the :envvar:`PYTHONHOME` environment variable instead.
diff --git a/Doc/deprecations/c-api-pending-removal-in-future.rst b/Doc/deprecations/c-api-pending-removal-in-future.rst
@@ -0,0 +1,31 @@
+Pending Removal in Future Versions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following APIs are deprecated and will be removed,
+although there is currently no date scheduled for their removal.
+
+* :c:macro:`Py_TPFLAGS_HAVE_FINALIZE`: unneeded since Python 3.8.
+* :c:func:`PyErr_Fetch`: use :c:func:`PyErr_GetRaisedException` instead.
+* :c:func:`PyErr_NormalizeException`: use :c:func:`PyErr_GetRaisedException` instead.
+* :c:func:`PyErr_Restore`: use :c:func:`PyErr_SetRaisedException` instead.
+* :c:func:`PyModule_GetFilename`: use :c:func:`PyModule_GetFilenameObject` instead.
+* :c:func:`PyOS_AfterFork`: use :c:func:`PyOS_AfterFork_Child` instead.
+* :c:func:`PySlice_GetIndicesEx`: use :c:func:`PySlice_Unpack` and :c:func:`PySlice_AdjustIndices` instead.
+* :c:func:`!PyUnicode_AsDecodedObject`: use :c:func:`PyCodec_Decode` instead.
+* :c:func:`!PyUnicode_AsDecodedUnicode`: use :c:func:`PyCodec_Decode` instead.
+* :c:func:`!PyUnicode_AsEncodedObject`: use :c:func:`PyCodec_Encode` instead.
+* :c:func:`!PyUnicode_AsEncodedUnicode`: use :c:func:`PyCodec_Encode` instead.
+* :c:func:`PyUnicode_READY`: unneeded since Python 3.12
+* :c:func:`!PyErr_Display`: use :c:func:`PyErr_DisplayException` instead.
+* :c:func:`!_PyErr_ChainExceptions`: use ``_PyErr_ChainExceptions1`` instead.
+* :c:member:`!PyBytesObject.ob_shash` member:
+  call :c:func:`PyObject_Hash` instead.
+* :c:member:`!PyDictObject.ma_version_tag` member.
+* Thread Local Storage (TLS) API:
+
+  * :c:func:`PyThread_create_key`: use :c:func:`PyThread_tss_alloc` instead.
+  * :c:func:`PyThread_delete_key`: use :c:func:`PyThread_tss_free` instead.
+  * :c:func:`PyThread_set_key_value`: use :c:func:`PyThread_tss_set` instead.
+  * :c:func:`PyThread_get_key_value`: use :c:func:`PyThread_tss_get` instead.
+  * :c:func:`PyThread_delete_key_value`: use :c:func:`PyThread_tss_delete` instead.
+  * :c:func:`PyThread_ReInitTLS`: unneeded since Python 3.7.
diff --git a/Doc/deprecations/index.rst b/Doc/deprecations/index.rst
@@ -1,10 +1,15 @@
 Deprecations
 ============
 
-.. include:: pending-removal-in-3.14.rst
-
 .. include:: pending-removal-in-3.15.rst
 
 .. include:: pending-removal-in-3.16.rst
 
 .. include:: pending-removal-in-future.rst
+
+C API Deprecations
+------------------
+
+.. include:: c-api-pending-removal-in-3.15.rst
+
+.. include:: c-api-pending-removal-in-future.rst
diff --git a/Doc/whatsnew/3.12.rst b/Doc/whatsnew/3.12.rst
@@ -2210,92 +2210,13 @@ Deprecated
   overrides :c:member:`~PyTypeObject.tp_new` is deprecated.
   Call the metaclass instead.
 
-Pending Removal in Python 3.14
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. Add deprecations above alphabetically, not here at the end.
 
-* The ``ma_version_tag`` field in :c:type:`PyDictObject` for extension modules
-  (:pep:`699`; :gh:`101193`).
+.. include:: ../deprecations/c-api-pending-removal-in-3.14.rst
 
-* Global configuration variables:
+.. include:: ../deprecations/c-api-pending-removal-in-3.15.rst
 
-  * :c:var:`Py_DebugFlag`: use :c:member:`PyConfig.parser_debug`
-  * :c:var:`Py_VerboseFlag`: use :c:member:`PyConfig.verbose`
-  * :c:var:`Py_QuietFlag`: use :c:member:`PyConfig.quiet`
-  * :c:var:`Py_InteractiveFlag`: use :c:member:`PyConfig.interactive`
-  * :c:var:`Py_InspectFlag`: use :c:member:`PyConfig.inspect`
-  * :c:var:`Py_OptimizeFlag`: use :c:member:`PyConfig.optimization_level`
-  * :c:var:`Py_NoSiteFlag`: use :c:member:`PyConfig.site_import`
-  * :c:var:`Py_BytesWarningFlag`: use :c:member:`PyConfig.bytes_warning`
-  * :c:var:`Py_FrozenFlag`: use :c:member:`PyConfig.pathconfig_warnings`
-  * :c:var:`Py_IgnoreEnvironmentFlag`: use :c:member:`PyConfig.use_environment`
-  * :c:var:`Py_DontWriteBytecodeFlag`: use :c:member:`PyConfig.write_bytecode`
-  * :c:var:`Py_NoUserSiteDirectory`: use :c:member:`PyConfig.user_site_directory`
-  * :c:var:`Py_UnbufferedStdioFlag`: use :c:member:`PyConfig.buffered_stdio`
-  * :c:var:`Py_HashRandomizationFlag`: use :c:member:`PyConfig.use_hash_seed`
-    and :c:member:`PyConfig.hash_seed`
-  * :c:var:`Py_IsolatedFlag`: use :c:member:`PyConfig.isolated`
-  * :c:var:`Py_LegacyWindowsFSEncodingFlag`: use :c:member:`PyPreConfig.legacy_windows_fs_encoding`
-  * :c:var:`Py_LegacyWindowsStdioFlag`: use :c:member:`PyConfig.legacy_windows_stdio`
-  * :c:var:`!Py_FileSystemDefaultEncoding`: use :c:member:`PyConfig.filesystem_encoding`
-  * :c:var:`!Py_HasFileSystemDefaultEncoding`: use :c:member:`PyConfig.filesystem_encoding`
-  * :c:var:`!Py_FileSystemDefaultEncodeErrors`: use :c:member:`PyConfig.filesystem_errors`
-  * :c:var:`!Py_UTF8Mode`: use :c:member:`PyPreConfig.utf8_mode` (see :c:func:`Py_PreInitialize`)
-
-  The :c:func:`Py_InitializeFromConfig` API should be used with
-  :c:type:`PyConfig` instead.
-
-* Creating :c:data:`immutable types <Py_TPFLAGS_IMMUTABLETYPE>` with mutable
-  bases (:gh:`95388`).
-
-Pending Removal in Python 3.15
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-* :c:func:`PyImport_ImportModuleNoBlock`: use :c:func:`PyImport_ImportModule`
-* :c:type:`!Py_UNICODE_WIDE` type: use :c:type:`wchar_t`
-* :c:type:`Py_UNICODE` type: use :c:type:`wchar_t`
-* Python initialization functions:
-
-  * :c:func:`PySys_ResetWarnOptions`: clear :data:`sys.warnoptions` and
-    :data:`!warnings.filters`
-  * :c:func:`Py_GetExecPrefix`: get :data:`sys.exec_prefix`
-  * :c:func:`Py_GetPath`: get :data:`sys.path`
-  * :c:func:`Py_GetPrefix`: get :data:`sys.prefix`
-  * :c:func:`Py_GetProgramFullPath`: get :data:`sys.executable`
-  * :c:func:`Py_GetProgramName`: get :data:`sys.executable`
-  * :c:func:`Py_GetPythonHome`: get :c:member:`PyConfig.home` or
-    the :envvar:`PYTHONHOME` environment variable
-
-Pending Removal in Future Versions
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The following APIs are deprecated and will be removed,
-although there is currently no date scheduled for their removal.
-
-* :c:macro:`Py_TPFLAGS_HAVE_FINALIZE`: unneeded since Python 3.8
-* :c:func:`PyErr_Fetch`: use :c:func:`PyErr_GetRaisedException`
-* :c:func:`PyErr_NormalizeException`: use :c:func:`PyErr_GetRaisedException`
-* :c:func:`PyErr_Restore`: use :c:func:`PyErr_SetRaisedException`
-* :c:func:`PyModule_GetFilename`: use :c:func:`PyModule_GetFilenameObject`
-* :c:func:`PyOS_AfterFork`: use :c:func:`PyOS_AfterFork_Child`
-* :c:func:`PySlice_GetIndicesEx`: use :c:func:`PySlice_Unpack` and :c:func:`PySlice_AdjustIndices`
-* :c:func:`!PyUnicode_AsDecodedObject`: use :c:func:`PyCodec_Decode`
-* :c:func:`!PyUnicode_AsDecodedUnicode`: use :c:func:`PyCodec_Decode`
-* :c:func:`!PyUnicode_AsEncodedObject`: use :c:func:`PyCodec_Encode`
-* :c:func:`!PyUnicode_AsEncodedUnicode`: use :c:func:`PyCodec_Encode`
-* :c:func:`PyUnicode_READY`: unneeded since Python 3.12
-* :c:func:`!PyErr_Display`: use :c:func:`PyErr_DisplayException`
-* :c:func:`!_PyErr_ChainExceptions`: use ``_PyErr_ChainExceptions1``
-* :c:member:`!PyBytesObject.ob_shash` member:
-  call :c:func:`PyObject_Hash` instead
-* :c:member:`!PyDictObject.ma_version_tag` member
-* Thread Local Storage (TLS) API:
-
-  * :c:func:`PyThread_create_key`: use :c:func:`PyThread_tss_alloc`
-  * :c:func:`PyThread_delete_key`: use :c:func:`PyThread_tss_free`
-  * :c:func:`PyThread_set_key_value`: use :c:func:`PyThread_tss_set`
-  * :c:func:`PyThread_get_key_value`: use :c:func:`PyThread_tss_get`
-  * :c:func:`PyThread_delete_key_value`: use :c:func:`PyThread_tss_delete`
-  * :c:func:`PyThread_ReInitTLS`: unneeded since Python 3.7
+.. include:: ../deprecations/c-api-pending-removal-in-future.rst
 
 Removed
 -------
diff --git a/Doc/whatsnew/3.13.rst b/Doc/whatsnew/3.13.rst
@@ -2208,6 +2208,9 @@ Removed C APIs
   be used instead.
   (Contributed by Serhiy Storchaka in :gh:`86493`.)
 
+* Remove undocumented ``PY_TIMEOUT_MAX`` constant from the limited C API.
+  (Contributed by Victor Stinner in :gh:`110014`.)
+
 Deprecated C APIs
 -----------------
 
@@ -2249,105 +2252,13 @@ Deprecated C APIs
   Refer to the deprecation notices on each function for their recommended replacements.
   (Soft deprecated as part of :pep:`667`.)
 
-Pending Removal in Python 3.14
-------------------------------
-
-* Creating immutable types (:c:macro:`Py_TPFLAGS_IMMUTABLETYPE`) with mutable
-  bases using the C API.
-
-* Functions to configure the Python initialization, deprecated in Python 3.11:
-
-  * ``PySys_SetArgvEx()``: set :c:member:`PyConfig.argv` instead.
-  * ``PySys_SetArgv()``: set :c:member:`PyConfig.argv` instead.
-  * ``Py_SetProgramName()``: set :c:member:`PyConfig.program_name` instead.
-  * ``Py_SetPythonHome()``: set :c:member:`PyConfig.home` instead.
-
-  The :c:func:`Py_InitializeFromConfig` API should be used with
-  :c:type:`PyConfig` instead.
-
-* Global configuration variables:
-
-  * :c:var:`Py_DebugFlag`: use :c:member:`PyConfig.parser_debug`
-  * :c:var:`Py_VerboseFlag`: use :c:member:`PyConfig.verbose`
-  * :c:var:`Py_QuietFlag`: use :c:member:`PyConfig.quiet`
-  * :c:var:`Py_InteractiveFlag`: use :c:member:`PyConfig.interactive`
-  * :c:var:`Py_InspectFlag`: use :c:member:`PyConfig.inspect`
-  * :c:var:`Py_OptimizeFlag`: use :c:member:`PyConfig.optimization_level`
-  * :c:var:`Py_NoSiteFlag`: use :c:member:`PyConfig.site_import`
-  * :c:var:`Py_BytesWarningFlag`: use :c:member:`PyConfig.bytes_warning`
-  * :c:var:`Py_FrozenFlag`: use :c:member:`PyConfig.pathconfig_warnings`
-  * :c:var:`Py_IgnoreEnvironmentFlag`: use :c:member:`PyConfig.use_environment`
-  * :c:var:`Py_DontWriteBytecodeFlag`: use :c:member:`PyConfig.write_bytecode`
-  * :c:var:`Py_NoUserSiteDirectory`: use :c:member:`PyConfig.user_site_directory`
-  * :c:var:`Py_UnbufferedStdioFlag`: use :c:member:`PyConfig.buffered_stdio`
-  * :c:var:`Py_HashRandomizationFlag`: use :c:member:`PyConfig.use_hash_seed`
-    and :c:member:`PyConfig.hash_seed`
-  * :c:var:`Py_IsolatedFlag`: use :c:member:`PyConfig.isolated`
-  * :c:var:`Py_LegacyWindowsFSEncodingFlag`: use :c:member:`PyPreConfig.legacy_windows_fs_encoding`
-  * :c:var:`Py_LegacyWindowsStdioFlag`: use :c:member:`PyConfig.legacy_windows_stdio`
-  * :c:var:`!Py_FileSystemDefaultEncoding`: use :c:member:`PyConfig.filesystem_encoding`
-  * :c:var:`!Py_HasFileSystemDefaultEncoding`: use :c:member:`PyConfig.filesystem_encoding`
-  * :c:var:`!Py_FileSystemDefaultEncodeErrors`: use :c:member:`PyConfig.filesystem_errors`
-  * :c:var:`!Py_UTF8Mode`: use :c:member:`PyPreConfig.utf8_mode` (see :c:func:`Py_PreInitialize`)
-
-  The :c:func:`Py_InitializeFromConfig` API should be used with
-  :c:type:`PyConfig` instead.
-
-Pending Removal in Python 3.15
-------------------------------
-
-* The bundled copy of ``libmpdecimal``.
-* :c:func:`PyImport_ImportModuleNoBlock`: use :c:func:`PyImport_ImportModule`.
-* :c:func:`PyWeakref_GET_OBJECT`: use :c:func:`PyWeakref_GetRef` instead.
-* :c:func:`PyWeakref_GetObject`: use :c:func:`PyWeakref_GetRef` instead.
-* :c:type:`!Py_UNICODE_WIDE` type: use :c:type:`wchar_t` instead.
-* :c:type:`Py_UNICODE` type: use :c:type:`wchar_t` instead.
-* Python initialization functions:
-
-  * :c:func:`PySys_ResetWarnOptions`: clear :data:`sys.warnoptions` and
-    :data:`!warnings.filters` instead.
-  * :c:func:`Py_GetExecPrefix`: get :data:`sys.exec_prefix` instead.
-  * :c:func:`Py_GetPath`: get :data:`sys.path` instead.
-  * :c:func:`Py_GetPrefix`: get :data:`sys.prefix` instead.
-  * :c:func:`Py_GetProgramFullPath`: get :data:`sys.executable` instead.
-  * :c:func:`Py_GetProgramName`: get :data:`sys.executable` instead.
-  * :c:func:`Py_GetPythonHome`: get :c:member:`PyConfig.home` or
-    :envvar:`PYTHONHOME` environment variable instead.
+.. Add deprecations above alphabetically, not here at the end.
 
-Pending Removal in Future Versions
-----------------------------------
-
-The following APIs were deprecated in earlier Python versions and will be
-removed, although there is currently no date scheduled for their removal.
-
-* :c:macro:`Py_TPFLAGS_HAVE_FINALIZE`: no needed since Python 3.8.
-* :c:func:`PyErr_Fetch`: use :c:func:`PyErr_GetRaisedException`.
-* :c:func:`PyErr_NormalizeException`: use :c:func:`PyErr_GetRaisedException`.
-* :c:func:`PyErr_Restore`: use :c:func:`PyErr_SetRaisedException`.
-* :c:func:`PyModule_GetFilename`: use :c:func:`PyModule_GetFilenameObject`.
-* :c:func:`PyOS_AfterFork`: use :c:func:`PyOS_AfterFork_Child()`.
-* :c:func:`PySlice_GetIndicesEx`.
-* :c:func:`!PyUnicode_AsDecodedObject`.
-* :c:func:`!PyUnicode_AsDecodedUnicode`.
-* :c:func:`!PyUnicode_AsEncodedObject`.
-* :c:func:`!PyUnicode_AsEncodedUnicode`.
-* :c:func:`PyUnicode_READY`: not needed since Python 3.12.
-* :c:func:`!_PyErr_ChainExceptions`.
-* :c:member:`!PyBytesObject.ob_shash` member:
-  call :c:func:`PyObject_Hash` instead.
-* :c:member:`!PyDictObject.ma_version_tag` member.
-* TLS API:
-
-  * :c:func:`PyThread_create_key`: use :c:func:`PyThread_tss_alloc`.
-  * :c:func:`PyThread_delete_key`: use :c:func:`PyThread_tss_free`.
-  * :c:func:`PyThread_set_key_value`: use :c:func:`PyThread_tss_set`.
-  * :c:func:`PyThread_get_key_value`: use :c:func:`PyThread_tss_get`.
-  * :c:func:`PyThread_delete_key_value`: use :c:func:`PyThread_tss_delete`.
-  * :c:func:`PyThread_ReInitTLS`: no longer needed.
+.. include:: ../deprecations/c-api-pending-removal-in-3.14.rst
 
-* Remove undocumented ``PY_TIMEOUT_MAX`` constant from the limited C API.
-  (Contributed by Victor Stinner in :gh:`110014`.)
+.. include:: ../deprecations/c-api-pending-removal-in-3.15.rst
 
+.. include:: ../deprecations/c-api-pending-removal-in-future.rst
 
 Regression Test Changes
 =======================
diff --git a/Doc/whatsnew/3.14.rst b/Doc/whatsnew/3.14.rst
@@ -422,6 +422,12 @@ Deprecated
   :c:macro:`!isfinite` available from :file:`math.h`
   since C99.  (Contributed by Sergey B Kirpichev in :gh:`119613`.)
 
+.. Add deprecations above alphabetically, not here at the end.
+
+.. include:: ../deprecations/c-api-pending-removal-in-3.15.rst
+
+.. include:: ../deprecations/c-api-pending-removal-in-future.rst
+
 Removed
 -------
 
