gh-106240: Add stdlib_deprecations module

Doc/library/index.rst

@@ -74,4 +74,5 @@ the `Python Package Index <https://pypi.org>`_.
  windows.rst
  unix.rst
  superseded.rst
+ stdlib_deprecations.rst
  security_warnings.rst

Doc/library/stdlib_deprecations.rst

@@ -0,0 +1,47 @@
+:mod:`stdlib_deprecations` --- Standard library deprecations
+============================================================
+
+.. module:: stdlib_deprecations
+ :synopsis: Standard library deprecations.
+
+**Source code:** :source:`Lib/stdlib_deprecations.py`
+
+--------------
+
+Standard library deprecations.
+
+.. versionadded:: 3.13
+
+.. class:: Deprecated
+
+ Attributes:
+
+ .. attribute:: name
+
+ API name (string).
+
+ .. attribute:: version
+
+ Version when the API was deprecated (tuple of int).
+
+ .. attribute:: remove
+
+ Version when the API was or will be removed (tuple of int, or None).
+
+ .. attribute:: message
+
+ Message about the deprecation, usually explain how to replace the
+ deprecated API (str or None).
+
+
+.. function:: get_deprecated(name)
+
+ Return a :class:`Deprecated` object if the specified module or function is deprecated.
+ For a function name, return an :class:`Deprecated` object if its module is deprecated.
+ Return ``None`` if the API is not deprecated.
+
+
+.. function:: get_capi_deprecated(name)
+
+ Return a :class:`Deprecated` object if the specified C API symbol is deprecated.
+ Return ``None`` if the C API is not deprecated.

Doc/whatsnew/3.13.rst

@@ -81,7 +81,8 @@ Other Language Changes
 New Modules
 ===========
 
-* None yet.
+* Add :mod:`stdlib_deprecations` module.
+ (Contributed by Victor Stinner in :gh:`106240`.)
 
 
 Improved Modules

Lib/stdlib_deprecations.py

@@ -0,0 +1,185 @@
+import dataclasses
+import re
+
+
+@dataclasses.dataclass(slots=True, frozen=True)
+class Deprecated:
+ name: str
+ version: tuple[int]
+ remove: tuple[int] | None
+ message: str | None
+
+
+def _parse_version(version_str):
+ version = tuple(int(part) for part in version_str.split('.'))
+ if len(version) < 2:
+ raise ValueError(f"invalid Python version: {version_str!r}")
+ return version
+
+
+_DEPRECATIONS = {}
+_DEPRECATIONS_CAPI = {}
+_REGEX_NAME = r'[A-Za-z_][A-Za-z0-9_]*'
+_REGEX_QUALNAME = fr'^{_REGEX_NAME}(\.{_REGEX_NAME})*$'
+
+
+def _deprecate_api(api_dict, name, version, remove, replace):
+ if not re.match(_REGEX_QUALNAME, name):
+ raise ValueError(f"invalid name: {name!a}")
+ version = _parse_version(version)
+ if remove is not None:
+ remove = _parse_version(remove)
+ if replace is not None:
+ msg = f'use {replace}'
+ else:
+ msg = None
+ deprecated = Deprecated(name, version, remove, msg)
+ api_dict[deprecated.name] = deprecated
+
+
+def _deprecate(name, version, *, remove=None, replace=None):
+ global _DEPRECATIONS
+ _deprecate_api(_DEPRECATIONS, name, version, remove, replace)
+
+
+def _deprecate_capi(name, version, *, remove=None, replace=None):
+ global _DEPRECATIONS_CAPI
+ _deprecate_api(_DEPRECATIONS_CAPI, name, version, remove, replace)
+
+
+# Python 2.6
+_deprecate('gzip.GzipFile.filename', '2.6', remove='3.12',
+ replace='gzip.GzipFile.name'),
+
+# Python 3.6
+_deprecate('asyncore', '3.6', remove='3.12', replace='asyncio'),
+_deprecate('asynchat', '3.6', remove='3.12', replace='asyncio'),
+_deprecate('smtpd', '3.6', remove='3.12', replace='aiosmtp'),
+_deprecate('ssl.RAND_pseudo_bytes', '3.6', remove='3.12',
+ replace='os.urandom()'),
+
+# Python 3.7
+_deprecate('ssl.match_hostname', '3.7', remove='3.12'),
+_deprecate('ssl.wrap_socket', '3.7', remove='3.12',
+ replace='ssl.SSLContext.wrap_socket()'),
+_deprecate('locale.format', '3.7', remove='3.12',
+ replace='locale.format_string()'),
+
+# Python 3.10
+_deprecate('io.OpenWrapper', '3.10', remove='3.12', replace='open()'),
+_deprecate('_pyio.OpenWrapper', '3.10', remove='3.12', replace='open()'),
+_deprecate('xml.etree.ElementTree.copy', '3.10', remove='3.12',
+ replace='copy.copy()'),
+_deprecate('zipimport.zipimporter.find_loader', '3.10', remove='3.12',
+ replace='find_spec() method: PEP 451'),
+_deprecate('zipimport.zipimporter.find_module', '3.10', remove='3.12',
+ replace='find_spec() method: PEP 451'),
+
+# Python 3.11
+_deprecate('aifc', '3.11', remove='3.13'),
+_deprecate('audioop', '3.11', remove='3.13'),
+_deprecate('cgi', '3.11', remove='3.13'),
+_deprecate('cgitb', '3.11', remove='3.13'),
+_deprecate('chunk', '3.11', remove='3.13'),
+_deprecate('crypt', '3.11', remove='3.13'),
+_deprecate('imghdr', '3.11', remove='3.13'),
+_deprecate('mailcap', '3.11', remove='3.13'),
+_deprecate('msilib', '3.11', remove='3.13'),
+_deprecate('nis', '3.11', remove='3.13'),
+_deprecate('nntplib', '3.11', remove='3.13'),
+_deprecate('ossaudiodev', '3.11', remove='3.13'),
+_deprecate('pipes', '3.11', remove='3.13'),
+_deprecate('sndhdr', '3.11', remove='3.13'),
+_deprecate('spwd', '3.11', remove='3.13'),
+_deprecate('sunau', '3.11', remove='3.13'),
+_deprecate('telnetlib', '3.11', remove='3.13'),
+_deprecate('uu', '3.11', remove='3.13'),
+_deprecate('xdrlib', '3.11', remove='3.13'),
+
+# Python 3.12
+_deprecate('datetime.datetime.utcnow', '3.12',
+ replace='datetime.datetime.now(tz=datetime.UTC)'),
+_deprecate('datetime.datetime.utcfromtimestamp', '3.12',
+ replace='datetime.datetime.fromtimestamp(tz=datetime.UTC)'),
+_deprecate('calendar.January', '3.12'),
+_deprecate('calendar.February', '3.12'),
+_deprecate('sys.last_value', '3.12'),
+_deprecate('sys.last_traceback', '3.12'),
+_deprecate('sys.last_exc', '3.12'),
+_deprecate('xml.etree.ElementTree.__bool__', '3.12'),
+
+# Python 3.13
+_deprecate('ctypes.SetPointerType', '3.13', remove='3.15'),
+_deprecate('ctypes.ARRAY', '3.13', remove='3.15'),
+_deprecate('wave.Wave_read.getmark', '3.13', remove='3.15'),
+_deprecate('wave.Wave_read.getmarkers', '3.13', remove='3.15'),
+_deprecate('wave.Wave_read.setmark', '3.13', remove='3.15'),
+
+
+# C API: Python 3.10
+for name in (
+ 'PyUnicode_AS_DATA',
+ 'PyUnicode_AS_UNICODE',
+ 'PyUnicode_AsUnicodeAndSize',
+ 'PyUnicode_AsUnicode',
+ 'PyUnicode_FromUnicode',
+ 'PyUnicode_GET_DATA_SIZE',
+ 'PyUnicode_GET_SIZE',
+ 'PyUnicode_GetSize',
+ 'PyUnicode_IS_COMPACT',
+ 'PyUnicode_IS_READY',
+ 'PyUnicode_READY',
+ 'Py_UNICODE_WSTR_LENGTH',
+ '_PyUnicode_AsUnicode',
+ 'PyUnicode_WCHAR_KIND',
+ 'PyUnicodeObject',
+ 'PyUnicode_InternImmortal',
+):
+ _deprecate_capi(name, '3.10', remove='3.12')
+
+# C API: Python 3.12
+_deprecate_capi('PyDictObject.ma_version_tag', '3.12', remove='3.14'),
+for name, replace in (
+ ('Py_DebugFlag', 'PyConfig.parser_debug'),
+ ('Py_VerboseFlag', 'PyConfig.verbose'),
+ ('Py_QuietFlag', 'PyConfig.quiet'),
+ ('Py_InteractiveFlag', 'PyConfig.interactive'),
+ ('Py_InspectFlag', 'PyConfig.inspect'),
+ ('Py_OptimizeFlag', 'PyConfig.optimization_level'),
+ ('Py_NoSiteFlag', 'PyConfig.site_import'),
+ ('Py_BytesWarningFlag', 'PyConfig.bytes_warning'),
+ ('Py_FrozenFlag', 'PyConfig.pathconfig_warnings'),
+ ('Py_IgnoreEnvironmentFlag', 'PyConfig.use_environment'),
+ ('Py_DontWriteBytecodeFlag', 'PyConfig.write_bytecode'),
+ ('Py_NoUserSiteDirectory', 'PyConfig.user_site_directory'),
+ ('Py_UnbufferedStdioFlag', 'PyConfig.buffered_stdio'),
+ ('Py_HashRandomizationFlag', 'PyConfig.hash_seed'),
+ ('Py_IsolatedFlag', 'PyConfig.isolated'),
+ ('Py_LegacyWindowsFSEncodingFlag', 'PyPreConfig.legacy_windows_fs_encoding'),
+ ('Py_LegacyWindowsStdioFlag', 'PyConfig.legacy_windows_stdio'),
+ ('Py_FileSystemDefaultEncoding', 'PyConfig.filesystem_encoding'),
+ ('Py_FileSystemDefaultEncodeErrors', 'PyConfig.filesystem_errors'),
+ ('Py_UTF8Mode', 'PyPreConfig.utf8_mode'),
+):
+ _deprecate_capi(name, '3.12', replace=replace)
+
+_deprecate_capi('PyErr_Display', '3.12', replace='PyErr_DisplayException()'),
+_deprecate_capi('_PyErr_ChainExceptions', '3.12', replace='_PyErr_ChainExceptions1()'),
+
+
+def get_deprecated(name):
+ try:
+ return _DEPRECATIONS[name]
+ except KeyError:
+ pass
+
+ parts = name.split('.')
+ if len(parts) == 1:
+ return False
+
+ module_name = parts[0]
+ return _DEPRECATIONS.get(module_name)
+
+
+def get_capi_deprecated(name):
+ return _DEPRECATIONS_CAPI.get(name)

Lib/test/test_stdlib_deprecations.py

@@ -0,0 +1,33 @@
+import unittest
+import stdlib_deprecations
+
+
+class Tests(unittest.TestCase):
+ def test_python_api(self):
+ obj = stdlib_deprecations.get_deprecated('asyncore')
+ self.assertEqual(obj.name, 'asyncore')
+ self.assertEqual(obj.version, (3, 6))
+ self.assertEqual(obj.remove, (3, 12))
+ self.assertEqual(obj.message, 'use asyncio')
+
+ self.assertIs(stdlib_deprecations.get_deprecated('asyncore.loop'),
+ stdlib_deprecations.get_deprecated('asyncore'))
+
+ self.assertIsNone(stdlib_deprecations.get_deprecated('builtins.open'))
+
+ def test_c_api(self):
+ obj = stdlib_deprecations.get_capi_deprecated('Py_VerboseFlag')
+ self.assertEqual(obj.name, 'Py_VerboseFlag')
+ self.assertEqual(obj.version, (3, 12))
+ self.assertIsNone(obj.remove)
+ self.assertEqual(obj.message, 'use PyConfig.verbose')
+
+ self.assertIsNotNone(stdlib_deprecations.get_capi_deprecated('Py_VerboseFlag'))
+ self.assertIsNotNone(stdlib_deprecations.get_capi_deprecated('PyUnicode_InternImmortal'))
+
+ self.assertIsNone(stdlib_deprecations.get_capi_deprecated('Py_Initialize'))
+
+
+
+if __name__ == '__main__':
+ unittest.main()

Misc/NEWS.d/next/Library/2023-06-29-14-35-35.gh-issue-106240.vELLlP.rst

@@ -0,0 +1 @@
+Add :mod:`stdlib_deprecations` module. Patch by Victor Stinner.