From 02824ae90e9637c28749f094d7f3003bc9c59653 Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+aa-turner@users.noreply.github.com> Date: Fri, 22 Sep 2023 18:24:13 +0100 Subject: [PATCH 1/9] Move C-API deprecations to the C-API section --- Doc/whatsnew/3.12.rst | 31 +++++++++++++++++-------------- 1 file changed, 17 insertions(+), 14 deletions(-) diff --git a/Doc/whatsnew/3.12.rst b/Doc/whatsnew/3.12.rst index 1223f859265ed9..ebc3634d3feb15 100644 --- a/Doc/whatsnew/3.12.rst +++ b/Doc/whatsnew/3.12.rst @@ -1108,11 +1108,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 @@ -1243,9 +1238,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`). @@ -1255,9 +1247,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 ` with mutable - bases using the C API (:gh:`95388`) - Pending Removal in Future Versions ---------------------------------- @@ -2039,6 +2028,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` @@ -2068,9 +2062,6 @@ 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. - * The ``structmember.h`` header is deprecated, though it continues to be available and there are no plans to remove it. @@ -2102,6 +2093,9 @@ Deprecated (Contributed in :gh:`47146` by Petr Viktorin, based on earlier work by Alexander Belopolsky and Matthias Braun.) +* Creating immutable types (:c:macro:`Py_TPFLAGS_IMMUTABLETYPE`) with mutable + bases is deprecated and will be disabled in Python 3.14. (:gh:`95388`) + * :c:func:`PyErr_Fetch` and :c:func:`PyErr_Restore` are deprecated. Use :c:func:`PyErr_GetRaisedException` and :c:func:`PyErr_SetRaisedException` instead. @@ -2118,6 +2112,15 @@ 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`). + +* Creating immutable types (:c:macro:`Py_TPFLAGS_IMMUTABLETYPE`) with mutable + bases (:gh:`95388`). + Removed ------- From f9a6a95c35a107315996a84cb44161c845dbc476 Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+aa-turner@users.noreply.github.com> Date: Fri, 22 Sep 2023 18:33:22 +0100 Subject: [PATCH 2/9] Copy the 3.13 "Pending Removal in Future Versions" list --- Doc/whatsnew/3.12.rst | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/Doc/whatsnew/3.12.rst b/Doc/whatsnew/3.12.rst index ebc3634d3feb15..6647735ec6c930 100644 --- a/Doc/whatsnew/3.12.rst +++ b/Doc/whatsnew/3.12.rst @@ -2121,6 +2121,37 @@ Pending Removal in Python 3.14 * Creating immutable types (:c:macro:`Py_TPFLAGS_IMMUTABLETYPE`) with mutable bases (:gh:`95388`). +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` +* :c:func:`!PyUnicode_AsDecodedObject` +* :c:func:`!PyUnicode_AsDecodedUnicode` +* :c:func:`!PyUnicode_AsEncodedObject` +* :c:func:`!PyUnicode_AsEncodedUnicode` +* :c:func:`PyUnicode_READY`: unneeded 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 +* 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 ------- From 5d875539f619551d8a9c6f061f3b380528305cae Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+aa-turner@users.noreply.github.com> Date: Fri, 22 Sep 2023 18:33:46 +0100 Subject: [PATCH 3/9] Note that the global config variables will be removed in 3.14 --- Doc/whatsnew/3.12.rst | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/Doc/whatsnew/3.12.rst b/Doc/whatsnew/3.12.rst index 6647735ec6c930..f305b36edf0aac 100644 --- a/Doc/whatsnew/3.12.rst +++ b/Doc/whatsnew/3.12.rst @@ -2118,6 +2118,34 @@ 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 immutable types (:c:macro:`Py_TPFLAGS_IMMUTABLETYPE`) with mutable bases (:gh:`95388`). From 1653e42d57c784adea95504e09663ea5326bdae1 Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+aa-turner@users.noreply.github.com> Date: Fri, 22 Sep 2023 18:34:59 +0100 Subject: [PATCH 4/9] Copy the 3.13 "Pending Removal in Python 3.15" list --- Doc/whatsnew/3.12.rst | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/Doc/whatsnew/3.12.rst b/Doc/whatsnew/3.12.rst index f305b36edf0aac..b27987bf1ffc0e 100644 --- a/Doc/whatsnew/3.12.rst +++ b/Doc/whatsnew/3.12.rst @@ -2149,6 +2149,26 @@ Pending Removal in Python 3.14 * Creating immutable types (:c:macro:`Py_TPFLAGS_IMMUTABLETYPE`) with mutable bases (:gh:`95388`). +Pending Removal in Python 3.15 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +* :c:func:`PyImport_ImportModuleNoBlock`: use :c:func:`PyImport_ImportModule` +* :c:func:`PyWeakref_GET_OBJECT`: use :c:func:`PyWeakref_GetRef` +* :c:func:`PyWeakref_GetObject`: use :c:func:`PyWeakref_GetRef` +* :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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ From ac8849c7e06c0721daffe5bf624459c7a4c3f537 Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+aa-turner@users.noreply.github.com> Date: Fri, 22 Sep 2023 18:38:03 +0100 Subject: [PATCH 5/9] Note pending removal of PyErr_Display --- Doc/whatsnew/3.12.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/Doc/whatsnew/3.12.rst b/Doc/whatsnew/3.12.rst index b27987bf1ffc0e..b08a1566c45b7c 100644 --- a/Doc/whatsnew/3.12.rst +++ b/Doc/whatsnew/3.12.rst @@ -2187,6 +2187,7 @@ although there is currently no date scheduled for their removal. * :c:func:`!PyUnicode_AsEncodedObject` * :c:func:`!PyUnicode_AsEncodedUnicode` * :c:func:`PyUnicode_READY`: unneeded since Python 3.12 +* :c:func:`!PyErr_Display`: use :c:func:`PyErr_DisplayException` * :c:func:`!_PyErr_ChainExceptions` * :c:member:`!PyBytesObject.ob_shash` member: call :c:func:`PyObject_Hash` instead From 4502df21d019f1913b223cb61209eafef9339f46 Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+aa-turner@users.noreply.github.com> Date: Fri, 22 Sep 2023 18:39:01 +0100 Subject: [PATCH 6/9] Suggest alternative for ``_PyErr_ChainExceptions`` --- Doc/whatsnew/3.12.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/whatsnew/3.12.rst b/Doc/whatsnew/3.12.rst index b08a1566c45b7c..dbce628e1a7529 100644 --- a/Doc/whatsnew/3.12.rst +++ b/Doc/whatsnew/3.12.rst @@ -2188,7 +2188,7 @@ although there is currently no date scheduled for their removal. * :c:func:`!PyUnicode_AsEncodedUnicode` * :c:func:`PyUnicode_READY`: unneeded since Python 3.12 * :c:func:`!PyErr_Display`: use :c:func:`PyErr_DisplayException` -* :c:func:`!_PyErr_ChainExceptions` +* :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 From a9241e2e1644d4378d4ef2fd24ff0ba4f69f6ca1 Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+aa-turner@users.noreply.github.com> Date: Fri, 22 Sep 2023 18:49:22 +0100 Subject: [PATCH 7/9] Fix rebase error (restore position; use nicer markup) --- Doc/whatsnew/3.12.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Doc/whatsnew/3.12.rst b/Doc/whatsnew/3.12.rst index dbce628e1a7529..c21e545ea95c6c 100644 --- a/Doc/whatsnew/3.12.rst +++ b/Doc/whatsnew/3.12.rst @@ -2062,6 +2062,9 @@ Deprecated :c:type:`PyConfig` instead. (Contributed by Victor Stinner in :gh:`77782`.) +* Creating :c:data:`immutable types ` with mutable + bases is deprecated and will be disabled in Python 3.14. (:gh:`95388`) + * The ``structmember.h`` header is deprecated, though it continues to be available and there are no plans to remove it. @@ -2093,9 +2096,6 @@ Deprecated (Contributed in :gh:`47146` by Petr Viktorin, based on earlier work by Alexander Belopolsky and Matthias Braun.) -* Creating immutable types (:c:macro:`Py_TPFLAGS_IMMUTABLETYPE`) with mutable - bases is deprecated and will be disabled in Python 3.14. (:gh:`95388`) - * :c:func:`PyErr_Fetch` and :c:func:`PyErr_Restore` are deprecated. Use :c:func:`PyErr_GetRaisedException` and :c:func:`PyErr_SetRaisedException` instead. @@ -2146,7 +2146,7 @@ Pending Removal in Python 3.14 The :c:func:`Py_InitializeFromConfig` API should be used with :c:type:`PyConfig` instead. -* Creating immutable types (:c:macro:`Py_TPFLAGS_IMMUTABLETYPE`) with mutable +* Creating :c:data:`immutable types ` with mutable bases (:gh:`95388`). Pending Removal in Python 3.15 From 7312d08ebeb2b0d9af3d45925680dfe26f08f2e9 Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+AA-Turner@users.noreply.github.com> Date: Mon, 25 Sep 2023 07:28:17 +0100 Subject: [PATCH 8/9] Suggest more replacement functions Co-authored-by: Serhiy Storchaka --- Doc/whatsnew/3.12.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/Doc/whatsnew/3.12.rst b/Doc/whatsnew/3.12.rst index c21e545ea95c6c..7a25fde244f97b 100644 --- a/Doc/whatsnew/3.12.rst +++ b/Doc/whatsnew/3.12.rst @@ -2180,12 +2180,12 @@ although there is currently no date scheduled for their removal. * :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:`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`` From 242093774a916ee27d8c733d6e309ef25e04777b Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+aa-turner@users.noreply.github.com> Date: Mon, 25 Sep 2023 13:25:57 +0100 Subject: [PATCH 9/9] syntax --- Doc/whatsnew/3.12.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Doc/whatsnew/3.12.rst b/Doc/whatsnew/3.12.rst index 7a25fde244f97b..136517c1467aa2 100644 --- a/Doc/whatsnew/3.12.rst +++ b/Doc/whatsnew/3.12.rst @@ -2182,10 +2182,10 @@ although there is currently no date scheduled for their removal. * :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_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``