gh-127405: Emit a deprecation warning about a future change of sys.abiflags availability on Windows

Doc/library/sys.rst

@@ -24,6 +24,16 @@ always available. Unless explicitly noted otherwise, all variables are read-only
 
    .. availability:: Unix.
 
+   .. versionchanged:: next
+      A :exc:`DeprecationWarning` will be emitted if the :data:`sys.abiflags`
+      member is accessed on Windows before Python 3.16. The :data:`sys.abiflags`
+      member will be set to a meaningful value on Windows in Python 3.16. This
+      means the :data:`sys.abiflags` member will always be available on all
+      platforms starting from Python 3.16.
+
+      See the notes for :ref:`incoming change to sys.abiflags <whatsnew314-sys-abiflags-change>`
+      in the *What's New* for more details.
+
 
 .. function:: addaudithook(hook)
 

Doc/whatsnew/3.14.rst

@@ -929,6 +929,62 @@ sys
 * On FreeBSD, :data:`sys.platform` doesn't contain the major version anymore.
   It is always ``'freebsd'``, instead of ``'freebsd13'`` or ``'freebsd14'``.
 
+* Schedule a change for availability of :data:`sys.abiflags` on Windows. A
+  :exc:`DeprecationWarning` will be emitted if the :data:`sys.abiflags` member
+  is accessed on Windows before Python 3.16.
+  (Contributed by Xuehai Pan in :gh:`131717`.)
+
+.. _whatsnew314-sys-abiflags-change:
+
+sys.abiflags
+------------
+
+A :exc:`DeprecationWarning` will be emitted if the :data:`sys.abiflags` member
+is accessed on Windows before Python 3.16.
+For example:
+
+.. code-block:: python
+
+   >>> import sys
+   >>> getattr(sys, 'abiflags', None)  # on Windows
+   <python-input-1>:1: DeprecationWarning: sys.abiflags will be set to a meaningful value on all platforms ...
+   >>> hasattr(sys, 'abiflags')  # on Windows
+   <python-input-2>:1: DeprecationWarning: sys.abiflags will be set to a meaningful value on all platforms ...
+   False
+
+To suppress this warning, use the :mod:`warnings` module:
+
+.. code-block:: python
+
+   import warnings
+
+   with warnings.catch_warnings():
+       # ignore DeprecationWarning on sys.abiflags change on Windows
+       warnings.simplefilter('ignore', DeprecationWarning)
+       abiflags = getattr(sys, 'abiflags', '')
+
+Due to historical reasons, :data:`sys.abiflags` is not covered by
+:pep:`3149` on Windows. Now we have multiple builds, such as the
+:term:`free-threaded <free threading>` build, that provide different ABIs.
+:data:`sys.abiflags` is now required under many circumstances to determine
+the ABI of the Python interpreter.
+
+The :data:`sys.abiflags` member will be set to a meaningful value on
+Windows in Python 3.16. This means the :data:`sys.abiflags` member will
+always be available on all platforms starting from Python 3.16.
+
+The following table shows how to migrate from the old code to the new code
+without changing the behavior:
+
++---------------------------------------+---------------------------------------------------------------------+
+| Code prior to Python 3.14             | Code prior to Python 3.16 with the same behavior                    |
++=======================================+=====================================================================+
+| ``sys.abiflags``                      | ``sys.abiflags``                                                    |
++---------------------------------------+---------------------------------------------------------------------+
+| ``getattr(sys, 'abiflags', default)`` | ``sys.abiflags if not sys.platform.startswith('win') else default`` |
++---------------------------------------+---------------------------------------------------------------------+
+| ``hasattr(sys, 'abiflags')``          | ``not sys.platform.startswith('win')``                              |
++---------------------------------------+---------------------------------------------------------------------+
 
 sys.monitoring
 --------------

Lib/site.py

@@ -318,11 +318,6 @@ def joinuser(*args):
 # Same to sysconfig.get_path('purelib', os.name+'_user')
 def _get_path(userbase):
     version = sys.version_info
-    if hasattr(sys, 'abiflags') and 't' in sys.abiflags:
-        abi_thread = 't'
-    else:
-        abi_thread = ''
-
     implementation = _get_implementation()
     implementation_lower = implementation.lower()
     if os.name == 'nt':
@@ -332,6 +327,7 @@ def _get_path(userbase):
     if sys.platform == 'darwin' and sys._framework:
         return f'{userbase}/lib/{implementation_lower}/site-packages'
 
+    abi_thread = 't' if 't' in sys.abiflags else ''
     return f'{userbase}/lib/python{version[0]}.{version[1]}{abi_thread}/site-packages'
 
 
@@ -400,11 +396,8 @@ def getsitepackages(prefixes=None):
 
         implementation = _get_implementation().lower()
         ver = sys.version_info
-        if hasattr(sys, 'abiflags') and 't' in sys.abiflags:
-            abi_thread = 't'
-        else:
-            abi_thread = ''
-        if os.sep == '/':
+        if os.name != 'nt':
+            abi_thread = 't' if 't' in sys.abiflags else ''
             libdirs = [sys.platlibdir]
             if sys.platlibdir != "lib":
                 libdirs.append("lib")

Lib/sysconfig/__init__.py

@@ -325,6 +325,7 @@ def get_default_scheme():
 
 def get_makefile_filename():
     """Return the path of the Makefile."""
+    import warnings
 
     # GH-127429: When cross-compiling, use the Makefile from the target, instead of the host Python.
     if cross_base := os.environ.get('_PYTHON_PROJECT_BASE'):
@@ -333,7 +334,14 @@ def get_makefile_filename():
     if _PYTHON_BUILD:
         return os.path.join(_PROJECT_BASE, "Makefile")
 
-    if hasattr(sys, 'abiflags'):
+    # XXX: Remove this in Python 3.16
+    # This flag will always be True since Python 3.16
+    with warnings.catch_warnings():
+        # ignore DeprecationWarning on sys.abiflags change on Windows
+        warnings.simplefilter('ignore', DeprecationWarning)
+        has_abiflags = hasattr(sys, 'abiflags')
+
+    if has_abiflags:
         config_dir_name = f'config-{_PY_VERSION_SHORT}{sys.abiflags}'
     else:
         config_dir_name = 'config'
@@ -496,6 +504,8 @@ def get_path(name, scheme=get_default_scheme(), vars=None, expand=True):
 
 
 def _init_config_vars():
+    import warnings
+
     global _CONFIG_VARS
     _CONFIG_VARS = {}
 
@@ -504,10 +514,12 @@ def _init_config_vars():
     base_prefix = _BASE_PREFIX
     base_exec_prefix = _BASE_EXEC_PREFIX
 
-    try:
-        abiflags = sys.abiflags
-    except AttributeError:
-        abiflags = ''
+    # XXX: Remove this context manager in Python 3.16
+    # sys.abiflags will always be available on all platforms since Python 3.16
+    with warnings.catch_warnings():
+        # ignore DeprecationWarning on sys.abiflags change on Windows
+        warnings.simplefilter('ignore', DeprecationWarning)
+        abiflags = getattr(sys, 'abiflags', '')
 
     if os.name == 'posix':
         _init_posix(_CONFIG_VARS)

Lib/test/pythoninfo.py

@@ -47,7 +47,14 @@ def get_infos(self):
 
 def copy_attributes(info_add, obj, name_fmt, attributes, *, formatter=None):
     for attr in attributes:
-        value = getattr(obj, attr, None)
+        if attr == 'abiflags':
+            # XXX: Remove this special case handling in Python 3.16
+            with warnings.catch_warnings():
+                # ignore DeprecationWarning on sys.abiflags change on Windows
+                warnings.simplefilter("ignore", DeprecationWarning)
+                value = getattr(obj, attr, None)
+        else:
+            value = getattr(obj, attr, None)
         if value is None:
             continue
         name = name_fmt % attr

Lib/test/support/__init__.py

@@ -877,6 +877,15 @@ def check_bolt_optimized():
     return '--enable-bolt' in config_args
 
 
+# XXX: Remove this in Python 3.16
+# This flag will always be True since Python 3.16
+with warnings.catch_warnings():
+    # ignore DeprecationWarning on sys.abiflags change on Windows
+    warnings.simplefilter('ignore', DeprecationWarning)
+    # Equal to `not sys.platform.startswith('win')` prior to 3.16
+    HAS_SYS_ABIFLAGS = hasattr(sys, 'abiflags')
+
+
 Py_GIL_DISABLED = bool(sysconfig.get_config_var('Py_GIL_DISABLED'))
 
 def requires_gil_enabled(msg="needs the GIL enabled"):

Lib/test/test_sys.py

@@ -720,6 +720,35 @@ def test_attributes(self):
         if not sys.platform.startswith('win'):
             self.assertIsInstance(sys.abiflags, str)
 
+            # test hasattr(sys, 'abiflags') == (os.name != 'nt)
+            self.assertEqual(os.name, 'posix')
+        else:
+            absent = object()
+            with self.assertWarnsRegex(
+                DeprecationWarning,
+                r'sys\.abiflags will be set\b.*\bon all platforms',
+            ):
+                self.assertIs(getattr(sys, 'abiflags', absent), absent)
+            with self.assertWarnsRegex(
+                DeprecationWarning,
+                r'sys\.abiflags will be set\b.*\bon all platforms',
+            ):
+                self.assertFalse(hasattr(sys, 'abiflags'))
+
+            # Emit a deprecated warning and also raise an AttributeError
+            with self.assertRaisesRegex(
+                AttributeError,
+                r"module 'sys' has no attribute 'abiflags'",
+            ):
+                with self.assertWarnsRegex(
+                    DeprecationWarning,
+                    r'sys\.abiflags will be set\b.*\bon all platforms',
+                ):
+                    _ = sys.abiflags
+
+            # test hasattr(sys, 'abiflags') == (os.name != 'nt)
+            self.assertEqual(os.name, 'nt')
+
     def test_thread_info(self):
         info = sys.thread_info
         self.assertEqual(len(info), 3)
@@ -1332,7 +1361,7 @@ def test_pystats(self):
         sys._stats_dump()
 
     @test.support.cpython_only
-    @unittest.skipUnless(hasattr(sys, 'abiflags'), 'need sys.abiflags')
+    @unittest.skipUnless(support.HAS_SYS_ABIFLAGS, 'need sys.abiflags')
     def test_disable_gil_abi(self):
         self.assertEqual('t' in sys.abiflags, support.Py_GIL_DISABLED)
 

Misc/ACKS

@@ -1402,6 +1402,7 @@ Todd R. Palmer
 Juan David Ibáñez Palomar
 Nicola Palumbo
 Jan Palus
+Xuehai Pan
 Yongzhi Pan
 Martin Panter
 Mathias Panzenböck

Misc/NEWS.d/next/Core_and_Builtins/2025-03-25-13-32-18.gh-issue-127405.o10vve.rst

@@ -0,0 +1 @@
+Emit a :exc:`DeprecationWarning` about a future change of :data:`sys.abiflags` availability on Windows. Patch by Xuehai Pan.