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

Doc/library/sys.rst

@@ -24,6 +24,54 @@ always available. Unless explicitly noted otherwise, all variables are read-only
 
    .. availability:: Unix.
 
+   .. versionchanged:: next
+      A deprecation warning 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')``                              |
+      +---------------------------------------+---------------------------------------------------------------------+
+
 
 .. function:: addaudithook(hook)
 

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,12 @@ def get_makefile_filename():
     if _PYTHON_BUILD:
         return os.path.join(_PROJECT_BASE, "Makefile")
 
-    if hasattr(sys, 'abiflags'):
+    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 +502,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 +512,10 @@ def _init_config_vars():
     base_prefix = _BASE_PREFIX
     base_exec_prefix = _BASE_EXEC_PREFIX
 
-    try:
-        abiflags = sys.abiflags
-    except AttributeError:
-        abiflags = ''
+    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,13 @@ 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':
+            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,13 @@ def check_bolt_optimized():
     return '--enable-bolt' in config_args
 
 
+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.

Python/sysmodule.c

@@ -1,4 +1,3 @@
-
 /* System module */
 
 /*
@@ -36,7 +35,7 @@ Data members:
 #include "pycore_pystats.h"       // _Py_PrintSpecializationStats()
 #include "pycore_structseq.h"     // _PyStructSequence_InitBuiltinWithFlags()
 #include "pycore_sysmodule.h"     // export _PySys_GetSizeOf()
-#include "pycore_unicodeobject.h" // _PyUnicode_InternImmortal()
+#include "pycore_unicodeobject.h" // _PyUnicode_InternImmortal(), _PyUnicode_EqualToASCIIString()
 
 #include "pydtrace.h"             // PyDTrace_AUDIT()
 #include "osdefs.h"               // DELIM
@@ -75,6 +74,25 @@ module sys
 #include "clinic/sysmodule.c.h"
 
 
+#ifndef ABIFLAGS
+
+// XXX: remove this and related code after set sys.abiflags on Windows in 3.16.
+static int
+_warn_incoming_sys_abiflags_change()
+{
+    return PyErr_WarnEx(
+        PyExc_DeprecationWarning,
+        "sys.abiflags will be set to a meaningful value on all platforms "
+        "in Python 3.16 instead of absent.\n\n"
+        "Please consider using `warnings.simplefilter()` with the "
+        "`warnings.catch_warnings()` context manager.\n"
+        "Or update the code with `if sys.platform.startswith('win')` "
+        "condition.",
+        /*stack_level=*/1);
+}
+
+#endif
+
 PyObject *
 _PySys_GetRequiredAttr(PyObject *name)
 {
@@ -92,6 +110,14 @@ _PySys_GetRequiredAttr(PyObject *name)
     }
     PyObject *value;
     if (PyDict_GetItemRef(sysdict, name, &value) == 0) {
+#ifndef ABIFLAGS
+        if (_PyUnicode_EqualToASCIIString(name, "abiflags")) {
+            if (_warn_incoming_sys_abiflags_change() < 0) {
+                Py_XDECREF(value);
+                return NULL;
+            }
+        }
+#endif
         PyErr_Format(PyExc_RuntimeError, "lost sys.%U", name);
     }
     return value;
@@ -108,6 +134,14 @@ _PySys_GetRequiredAttrString(const char *name)
     }
     PyObject *value;
     if (PyDict_GetItemStringRef(sysdict, name, &value) == 0) {
+#ifndef ABIFLAGS
+        if (strcmp(name, "abiflags") == 0) {
+            if (_warn_incoming_sys_abiflags_change() < 0) {
+                Py_XDECREF(value);
+                return NULL;
+            }
+        }
+#endif
         PyErr_Format(PyExc_RuntimeError, "lost sys.%s", name);
     }
     return value;
@@ -129,7 +163,17 @@ _PySys_GetOptionalAttr(PyObject *name, PyObject **value)
         *value = NULL;
         return 0;
     }
-    return PyDict_GetItemRef(sysdict, name, value);
+    int ret = PyDict_GetItemRef(sysdict, name, value);
+#ifndef ABIFLAGS
+    if (ret == 0 && _PyUnicode_EqualToASCIIString(name, "abiflags")) {
+        if (_warn_incoming_sys_abiflags_change() < 0) {
+            Py_XDECREF(*value);
+            *value = NULL;
+            return -1;
+        }
+    }
+#endif
+    return ret;
 }
 
 int
@@ -141,7 +185,17 @@ _PySys_GetOptionalAttrString(const char *name, PyObject **value)
         *value = NULL;
         return 0;
     }
-    return PyDict_GetItemStringRef(sysdict, name, value);
+    int ret = PyDict_GetItemStringRef(sysdict, name, value);
+#ifndef ABIFLAGS
+    if (ret == 0 && strcmp(name, "abiflags") == 0) {
+        if (_warn_incoming_sys_abiflags_change() < 0) {
+            Py_XDECREF(*value);
+            *value = NULL;
+            return -1;
+        }
+    }
+#endif
+    return ret;
 }
 
 PyObject *
@@ -154,14 +208,23 @@ PySys_GetObject(const char *name)
     }
     PyObject *exc = _PyErr_GetRaisedException(tstate);
     PyObject *value;
-    (void) PyDict_GetItemStringRef(sysdict, name, &value);
+    int ret = PyDict_GetItemStringRef(sysdict, name, &value);
     /* XXX Suppress a new exception if it was raised and restore
      * the old one. */
     if (_PyErr_Occurred(tstate)) {
         PyErr_FormatUnraisable("Exception ignored in PySys_GetObject()");
     }
     _PyErr_SetRaisedException(tstate, exc);
     Py_XDECREF(value);  // return a borrowed reference
+#ifndef ABIFLAGS
+    if (ret == 0 && strcmp(name, "abiflags") == 0) {
+        if (_warn_incoming_sys_abiflags_change() < 0) {
+            return NULL;
+        }
+    }
+#else
+    (void) ret;  // ignore unused variable warning
+#endif
     return value;
 }
 
@@ -921,6 +984,33 @@ sys_exit_impl(PyObject *module, PyObject *status)
 }
 
 
+// This function is used to warn about the future change of sys.abiflags
+// from absent to a meaningful value on all platforms.
+// It can be removed when the change is made.
+static PyObject *
+sys___getattr__(PyObject *module, PyObject *name)
+{
+    PyObject *value = NULL;
+    if (_PySys_GetOptionalAttr(name, &value) < 0) {
+        Py_XDECREF(value);
+        return NULL;
+    }
+    if (value == NULL) {
+        PyErr_Clear();
+        PyErr_Format(PyExc_AttributeError,
+                     "module 'sys' has no attribute '%U'", name);
+    }
+    return value;
+}
+
+PyDoc_STRVAR(sysmodule__getattr___doc,
+"__getattr__($module, name, /)\n"
+"--\n"
+"\n"
+"Get a sys attribute by name.\n"
+);
+
+
 static PyObject *
 get_utf8_unicode(void)
 {
@@ -2651,6 +2741,8 @@ static PyMethodDef sys_methods[] = {
     SYS_EXC_INFO_METHODDEF
     SYS_EXCEPTHOOK_METHODDEF
     SYS_EXIT_METHODDEF
+    {"__getattr__", _PyCFunction_CAST(sys___getattr__),
+     METH_O, sysmodule__getattr___doc},
     SYS_GETDEFAULTENCODING_METHODDEF
     SYS_GETDLOPENFLAGS_METHODDEF
     SYS_GETALLOCATEDBLOCKS_METHODDEF