[3.12] pythonGH-109190: Copyedit 3.12 What's New: Improve the C-API deprecations section (pythonGH-109751) (python#109830)

* pythonGH-109190: Copyedit 3.12 What's New: Improve the C-API deprecations section (pythonGH-109751)
(cherry picked from commit bccc1b7)

Co-authored-by: Adam Turner <[email protected]>
Co-authored-by: Serhiy Storchaka <[email protected]>

* Remove the weakref get object functions

---------

Co-authored-by: Adam Turner <[email protected]>
Co-authored-by: Serhiy Storchaka <[email protected]>

Author: 3 people

Doc/whatsnew/3.12.rst

@@ -1126,11 +1126,6 @@ Deprecated
   :exc:`ImportWarning`).
   (Contributed by Brett Cannon in :gh:`65961`.)
 
-* In accordance with :pep:`699`, the ``ma_version_tag`` field in :c:type:`PyDictObject`
-  is deprecated for extension modules. Accessing this field will generate a compiler
-  warning at compile time. This field will be removed in Python 3.14.
-  (Contributed by Ramvikrams and Kumar Aditya in :gh:`101193`. PEP by Ken Jin.)
-
 * The bitwise inversion operator (``~``) on bool is deprecated. It will throw an
   error in Python 3.14. Use ``not`` for logical negation of bools instead.
   In the rare case that you really need the bitwise inversion of the underlying
@@ -1260,9 +1255,6 @@ Pending Removal in Python 3.14
 * :mod:`xml.etree.ElementTree`: Testing the truth value of an :class:`xml.etree.ElementTree.Element`
   is deprecated and will raise an exception in Python 3.14.
 
-* Creating immutable types (:c:macro:`Py_TPFLAGS_IMMUTABLETYPE`) with mutable
-  bases using the C API (:gh:`95388`).
-
 * ``__package__`` and ``__cached__`` will cease to be set or taken
   into consideration by the import system (:gh:`97879`).
 
@@ -1272,9 +1264,6 @@ Pending Removal in Python 3.14
   May be removed in 3.14.
   (Contributed by Nikita Sobolev in :gh:`101866`.)
 
-* Creating :c:data:`immutable types <Py_TPFLAGS_IMMUTABLETYPE>` with mutable
-  bases using the C API (:gh:`95388`)
-
 Pending Removal in Future Versions
 ----------------------------------
 
@@ -2059,6 +2048,11 @@ Porting to Python 3.12
 Deprecated
 ----------
 
+* In accordance with :pep:`699`, the ``ma_version_tag`` field in :c:type:`PyDictObject`
+  is deprecated for extension modules. Accessing this field will generate a compiler
+  warning at compile time. This field will be removed in Python 3.14.
+  (Contributed by Ramvikrams and Kumar Aditya in :gh:`101193`. PEP by Ken Jin.)
+
 * Deprecate global configuration variable:
 
   * :c:var:`Py_DebugFlag`: use :c:member:`PyConfig.parser_debug`
@@ -2088,8 +2082,8 @@ Deprecated
   :c:type:`PyConfig` instead.
   (Contributed by Victor Stinner in :gh:`77782`.)
 
-* Creating immutable types (:c:macro:`Py_TPFLAGS_IMMUTABLETYPE`) with mutable
-  bases is deprecated and will be disabled in Python 3.14.
+* Creating :c:data:`immutable types <Py_TPFLAGS_IMMUTABLETYPE>` with mutable
+  bases is deprecated and will be disabled in Python 3.14. (:gh:`95388`)
 
 * The :file:`structmember.h` header is deprecated, though it continues to be
   available and there are no plans to remove it.
@@ -2138,6 +2132,93 @@ Deprecated
   overrides :c:member:`~PyTypeObject.tp_new` is deprecated.
   Call the metaclass instead.
 
+Pending Removal in Python 3.14
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* The ``ma_version_tag`` field in :c:type:`PyDictObject` for extension modules
+  (:pep:`699`; :gh:`101193`).
+
+* 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.
+
+* 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
+
 Removed
 -------