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

Doc/library/sys.rst

@@ -24,6 +24,22 @@ 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>` on the *What's New in 3.14*
+ page for more details.
+
+ .. TODO: When we're in Python 3.16:
+ - Add a **CAUTION** section about the differences of :data:`sys.abiflags`
+ between prior-3.14, 3.14-3.15, and 3.16+ on Windows.
+ - Move porting recommendations from whatsnew/3.14.rst.
+
 
 .. function:: addaudithook(hook)
 

Doc/whatsnew/3.14.rst

@@ -1693,6 +1693,66 @@ sys
 * Raise :exc:`DeprecationWarning` for :func:`sys._clear_type_cache`. This
  function was deprecated in Python 3.13 but it didn't raise a runtime warning.
 
+* 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 incoming sys.abiflags change on Windows before 3.16
+ 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.
+Before this incoming change is made, :func:`sysconfig.get_config_vars` would be
+useful. See also :ref:`Changes of **sysconfig** <whatsnew314-sysconfig-abiflags>`.
+
+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
 --------------
@@ -1701,6 +1761,8 @@ sys.monitoring
  :monitoring-event:`BRANCH_RIGHT`. The ``BRANCH`` event is deprecated.
 
 
+.. _whatsnew314-sysconfig-abiflags:
+
 sysconfig
 ---------
 

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

@@ -314,6 +314,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'):
@@ -322,7 +323,14 @@ def get_makefile_filename():
  if _PYTHON_BUILD:
  return os.path.join(_PROJECT_BASE, "Makefile")
 
- if hasattr(sys, 'abiflags'):
+ # TODO: 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.filterwarnings('ignore', r'sys\.abiflags', category=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':
+ # TODO: Remove this special case handling in Python 3.16
+ with warnings.catch_warnings():
+ # ignore DeprecationWarning on sys.abiflags change on Windows
+ warnings.filterwarnings('ignore', r'sys\.abiflags', category=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

@@ -890,6 +890,15 @@ def check_bolt_optimized():
  return '--enable-bolt' in config_args
 
 
+# TODO: 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.filterwarnings('ignore', r'sys\.abiflags', category=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

@@ -723,9 +723,34 @@ def test_attributes(self):
  self.assertIsInstance(sys.float_repr_style, str)
  self.assertIn(sys.float_repr_style, ('short', 'legacy'))
  if not sys.platform.startswith('win'):
+ self.assertEqual(os.name, 'posix')
  self.assertIsInstance(sys.abiflags, str)
  else:
- self.assertFalse(hasattr(sys, 'abiflags'))
+ self.assertEqual(os.name, 'nt')
+ # TODO: Simpify the tests.
+ # sys.abiflags will be defined on Windows in Python 3.16.
+ 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
 
  def test_thread_info(self):
  info = sys.thread_info
@@ -1341,7 +1366,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/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.