mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-08-11 12:29:34 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 9

[3.12] GH-122085: Use include files for C API deprecations (GH-109843) (#122423)

Browse source 
(cherry picked from commit 76bdfa4cd0)
This commit is contained in:
Adam Turner 2024-07-30 04:40:18 +01:00 • committed by GitHub
parent 220e31adea
commit dd86217b60
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
5 changed files with 110 additions and 83 deletions
Download patch file Download diff file Expand all files Collapse all files

46
Doc/deprecations/c-api-pending-removal-in-3.14.rst Normal file
View file

@ -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.

20
Doc/deprecations/c-api-pending-removal-in-3.15.rst Normal file
View file

@ -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.

31
Doc/deprecations/c-api-pending-removal-in-future.rst Normal file
View file

@ -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.

9
Doc/deprecations/index.rst
View file

@ -10,3 +10,12 @@ Deprecations
.. include:: pending-removal-in-3.16.rst
.. include:: pending-removal-in-future.rst
C API Deprecations
------------------
.. include:: c-api-pending-removal-in-3.14.rst
.. include:: c-api-pending-removal-in-3.15.rst
.. include:: c-api-pending-removal-in-future.rst

87
Doc/whatsnew/3.12.rst
View file

@ -2221,92 +2221,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
-------