Skip to content

gh-158001: Remove global configuration variables from C API #158020

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
vstinner merged 10 commits into from
Sep 24, 2026
Merged

gh-158001: Remove global configuration variables from C API #158020

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
eb053c3
gh-158001: Remove global configuration variables from C API
vstinner Sep 23, 2026
dbe5cae
Update tests
vstinner Sep 23, 2026
42963a7
Update make check-limited-abi
vstinner Sep 23, 2026
316cb16
doc: Remove links to removed variables
vstinner Sep 23, 2026
27cbdd6
Try to fix build on Windows
vstinner Sep 23, 2026
8b1af46
Update Doc/tools/removed-ids.txt
vstinner Sep 23, 2026
301c87c
Fix make check-c-globals
vstinner Sep 23, 2026
ef87ce6
Merge branch 'main' into remove_global_config
vstinner Sep 24, 2026
46fa563
Update doc to point to PyInitConfig
vstinner Sep 24, 2026
dcfba00
Update comment
vstinner Sep 24, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
274 changes: 1 addition & 273 deletions Doc/c-api/interp-lifecycle.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,8 +15,7 @@ Before Python initialization

In an application embedding Python, the :c:func:`Py_Initialize` function must
be called before using any other Python/C API functions; with the exception of
a few functions and the :ref:`global configuration variables
<global-conf-vars>`.
a few functions.

The following functions can be safely called before Python is initialized:

Expand Down Expand Up @@ -75,277 +74,6 @@ The following functions can be safely called before Python is initialized:
been initialized: :c:func:`Py_EncodeLocale`, and :c:func:`Py_RunMain`.


.. _global-conf-vars:

Global configuration variables
------------------------------

Python has variables for the global configuration to control different features
and options. By default, these flags are controlled by :ref:`command line
options <using-on-interface-options>`.

When a flag is set by an option, the value of the flag is the number of times
that the option was set. For example, ``-b`` sets :c:data:`Py_BytesWarningFlag`
to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.


.. c:var:: int Py_BytesWarningFlag

This API is kept for backward compatibility: setting
:c:member:`PyConfig.bytes_warning` should be used instead, see :ref:`Python
Initialization Configuration <init-config>`.

Issue a warning when comparing :class:`bytes` or :class:`bytearray` with
:class:`str` or :class:`bytes` with :class:`int`. Issue an error if greater
or equal to ``2``.

Set by the :option:`-b` option.

.. deprecated-removed:: 3.12 3.16


.. c:var:: int Py_DebugFlag

This API is kept for backward compatibility: setting
:c:member:`PyConfig.parser_debug` should be used instead, see :ref:`Python
Initialization Configuration <init-config>`.

Turn on parser debugging output (for expert only, depending on compilation
options).

Set by the :option:`-d` option and the :envvar:`PYTHONDEBUG` environment
variable.

.. deprecated-removed:: 3.12 3.16


.. c:var:: int Py_DontWriteBytecodeFlag

This API is kept for backward compatibility: setting
:c:member:`PyConfig.write_bytecode` should be used instead, see :ref:`Python
Initialization Configuration <init-config>`.

If set to non-zero, Python won't try to write ``.pyc`` files on the
import of source modules.

Set by the :option:`-B` option and the :envvar:`PYTHONDONTWRITEBYTECODE`
environment variable.

.. deprecated-removed:: 3.12 3.16


.. c:var:: int Py_FrozenFlag

This API is kept for backward compatibility: setting
:c:member:`PyConfig.pathconfig_warnings` should be used instead, see
:ref:`Python Initialization Configuration <init-config>`.

Private flag used by ``_freeze_module`` and ``frozenmain`` programs.

.. deprecated-removed:: 3.12 3.16


.. c:var:: int Py_HashRandomizationFlag

This API is kept for backward compatibility: setting
:c:member:`PyConfig.hash_seed` and :c:member:`PyConfig.use_hash_seed` should
be used instead, see :ref:`Python Initialization Configuration
<init-config>`.

Set to ``1`` if the :envvar:`PYTHONHASHSEED` environment variable is set to
a non-empty string.

If the flag is non-zero, read the :envvar:`PYTHONHASHSEED` environment
variable to initialize the secret hash seed.

.. deprecated-removed:: 3.12 3.16


.. c:var:: int Py_IgnoreEnvironmentFlag

This API is kept for backward compatibility: setting
:c:member:`PyConfig.use_environment` should be used instead, see
:ref:`Python Initialization Configuration <init-config>`.

Ignore all :envvar:`!PYTHON*` environment variables, e.g.
:envvar:`PYTHONPATH` and :envvar:`PYTHONHOME`, that might be set.

Set by the :option:`-E` and :option:`-I` options.

.. deprecated-removed:: 3.12 3.16


.. c:var:: int Py_InspectFlag

This API is kept for backward compatibility: setting
:c:member:`PyConfig.inspect` should be used instead, see
:ref:`Python Initialization Configuration <init-config>`.

When a script is passed as first argument or the :option:`-c` option is used,
enter interactive mode after executing the script or the command, even when
:data:`sys.stdin` does not appear to be a terminal.

Set by the :option:`-i` option and the :envvar:`PYTHONINSPECT` environment
variable.

.. deprecated-removed:: 3.12 3.16


.. c:var:: int Py_InteractiveFlag

This API is kept for backward compatibility: setting
:c:member:`PyConfig.interactive` should be used instead, see
:ref:`Python Initialization Configuration <init-config>`.

Set by the :option:`-i` option.

.. deprecated-removed:: 3.12 3.16


.. c:var:: int Py_IsolatedFlag

This API is kept for backward compatibility: setting
:c:member:`PyConfig.isolated` should be used instead, see
:ref:`Python Initialization Configuration <init-config>`.

Run Python in isolated mode. In isolated mode :data:`sys.path` contains
neither the script's directory nor the user's site-packages directory.

Set by the :option:`-I` option.

.. versionadded:: 3.4

.. deprecated-removed:: 3.12 3.16


.. c:var:: int Py_LegacyWindowsFSEncodingFlag

This API is kept for backward compatibility: setting
:c:member:`PyPreConfig.legacy_windows_fs_encoding` should be used instead, see
:ref:`Python Initialization Configuration <init-config>`.

If the flag is non-zero, use the ``mbcs`` encoding with ``replace`` error
handler, instead of the UTF-8 encoding with ``surrogatepass`` error handler,
for the :term:`filesystem encoding and error handler`.

Set to ``1`` if the :envvar:`PYTHONLEGACYWINDOWSFSENCODING` environment
variable is set to a non-empty string.

See :pep:`529` for more details.

.. availability:: Windows.

.. deprecated-removed:: 3.12 3.16


.. c:var:: int Py_LegacyWindowsStdioFlag

This API is kept for backward compatibility: setting
:c:member:`PyConfig.legacy_windows_stdio` should be used instead, see
:ref:`Python Initialization Configuration <init-config>`.

If the flag is non-zero, use :class:`io.FileIO` instead of
:class:`!io._WindowsConsoleIO` for :mod:`sys` standard streams.

Set to ``1`` if the :envvar:`PYTHONLEGACYWINDOWSSTDIO` environment
variable is set to a non-empty string.

See :pep:`528` for more details.

.. availability:: Windows.

.. deprecated-removed:: 3.12 3.16


.. c:var:: int Py_NoSiteFlag

This API is kept for backward compatibility: setting
:c:member:`PyConfig.site_import` should be used instead, see
:ref:`Python Initialization Configuration <init-config>`.

Disable the import of the module :mod:`site` and the site-dependent
manipulations of :data:`sys.path` that it entails. Also disable these
manipulations if :mod:`site` is explicitly imported later (call
:func:`site.main` if you want them to be triggered).

Set by the :option:`-S` option.

.. deprecated-removed:: 3.12 3.16


.. c:var:: int Py_NoUserSiteDirectory

This API is kept for backward compatibility: setting
:c:member:`PyConfig.user_site_directory` should be used instead, see
:ref:`Python Initialization Configuration <init-config>`.

Don't add the :data:`user site-packages directory <site.USER_SITE>` to
:data:`sys.path`.

Set by the :option:`-s` and :option:`-I` options, and the
:envvar:`PYTHONNOUSERSITE` environment variable.

.. deprecated-removed:: 3.12 3.16


.. c:var:: int Py_OptimizeFlag

This API is kept for backward compatibility: setting
:c:member:`PyConfig.optimization_level` should be used instead, see
:ref:`Python Initialization Configuration <init-config>`.

Set by the :option:`-O` option and the :envvar:`PYTHONOPTIMIZE` environment
variable.

.. deprecated-removed:: 3.12 3.16


.. c:var:: int Py_QuietFlag

This API is kept for backward compatibility: setting
:c:member:`PyConfig.quiet` should be used instead, see :ref:`Python
Initialization Configuration <init-config>`.

Don't display the copyright and version messages even in interactive mode.

Set by the :option:`-q` option.

.. versionadded:: 3.2

.. deprecated-removed:: 3.12 3.16


.. c:var:: int Py_UnbufferedStdioFlag

This API is kept for backward compatibility: setting
:c:member:`PyConfig.buffered_stdio` should be used instead, see :ref:`Python
Initialization Configuration <init-config>`.

Force the stdout and stderr streams to be unbuffered.

Set by the :option:`-u` option and the :envvar:`PYTHONUNBUFFERED`
environment variable.

.. deprecated-removed:: 3.12 3.16


.. c:var:: int Py_VerboseFlag

This API is kept for backward compatibility: setting
:c:member:`PyConfig.verbose` should be used instead, see :ref:`Python
Initialization Configuration <init-config>`.

Print a message each time a module is initialized, showing the place
(filename or built-in module) from which it is loaded. If greater or equal
to ``2``, print a message for each file that is checked for when
searching for a module. Also provides information on module cleanup at exit.

Set by the :option:`-v` option and the :envvar:`PYTHONVERBOSE` environment
variable.

.. deprecated-removed:: 3.12 3.16


Initializing and finalizing the interpreter
-------------------------------------------

Expand Down
4 changes: 0 additions & 4 deletions Doc/data/stable_abi.dat
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

34 changes: 17 additions & 17 deletions Doc/deprecations/c-api-pending-removal-in-3.16.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,56 +17,56 @@ Pending removal in Python 3.16

* Global configuration variables:

* :c:var:`Py_DebugFlag`:
* :c:var:`!Py_DebugFlag`:
Use :c:member:`PyConfig.parser_debug` or
:c:func:`PyConfig_Get("parser_debug") <PyConfig_Get>` instead.
* :c:var:`Py_VerboseFlag`:
* :c:var:`!Py_VerboseFlag`:
Use :c:member:`PyConfig.verbose` or
:c:func:`PyConfig_Get("verbose") <PyConfig_Get>` instead.
* :c:var:`Py_QuietFlag`:
* :c:var:`!Py_QuietFlag`:
Use :c:member:`PyConfig.quiet` or
:c:func:`PyConfig_Get("quiet") <PyConfig_Get>` instead.
* :c:var:`Py_InteractiveFlag`:
* :c:var:`!Py_InteractiveFlag`:
Use :c:member:`PyConfig.interactive` or
:c:func:`PyConfig_Get("interactive") <PyConfig_Get>` instead.
* :c:var:`Py_InspectFlag`:
* :c:var:`!Py_InspectFlag`:
Use :c:member:`PyConfig.inspect` or
:c:func:`PyConfig_Get("inspect") <PyConfig_Get>` instead.
* :c:var:`Py_OptimizeFlag`:
* :c:var:`!Py_OptimizeFlag`:
Use :c:member:`PyConfig.optimization_level` or
:c:func:`PyConfig_Get("optimization_level") <PyConfig_Get>` instead.
* :c:var:`Py_NoSiteFlag`:
* :c:var:`!Py_NoSiteFlag`:
Use :c:member:`PyConfig.site_import` or
:c:func:`PyConfig_Get("site_import") <PyConfig_Get>` instead.
* :c:var:`Py_BytesWarningFlag`:
* :c:var:`!Py_BytesWarningFlag`:
Use :c:member:`PyConfig.bytes_warning` or
:c:func:`PyConfig_Get("bytes_warning") <PyConfig_Get>` instead.
* :c:var:`Py_FrozenFlag`:
* :c:var:`!Py_FrozenFlag`:
Use :c:member:`PyConfig.pathconfig_warnings` or
:c:func:`PyConfig_Get("pathconfig_warnings") <PyConfig_Get>` instead.
* :c:var:`Py_IgnoreEnvironmentFlag`:
* :c:var:`!Py_IgnoreEnvironmentFlag`:
Use :c:member:`PyConfig.use_environment` or
:c:func:`PyConfig_Get("use_environment") <PyConfig_Get>` instead.
* :c:var:`Py_DontWriteBytecodeFlag`:
* :c:var:`!Py_DontWriteBytecodeFlag`:
Use :c:member:`PyConfig.write_bytecode` or
:c:func:`PyConfig_Get("write_bytecode") <PyConfig_Get>` instead.
* :c:var:`Py_NoUserSiteDirectory`:
* :c:var:`!Py_NoUserSiteDirectory`:
Use :c:member:`PyConfig.user_site_directory` or
:c:func:`PyConfig_Get("user_site_directory") <PyConfig_Get>` instead.
* :c:var:`Py_UnbufferedStdioFlag`:
* :c:var:`!Py_UnbufferedStdioFlag`:
Use :c:member:`PyConfig.buffered_stdio` or
:c:func:`PyConfig_Get("buffered_stdio") <PyConfig_Get>` instead.
* :c:var:`Py_HashRandomizationFlag`:
* :c:var:`!Py_HashRandomizationFlag`:
Use :c:member:`PyConfig.use_hash_seed`
and :c:member:`PyConfig.hash_seed` or
:c:func:`PyConfig_Get("hash_seed") <PyConfig_Get>` instead.
* :c:var:`Py_IsolatedFlag`:
* :c:var:`!Py_IsolatedFlag`:
Use :c:member:`PyConfig.isolated` or
:c:func:`PyConfig_Get("isolated") <PyConfig_Get>` instead.
* :c:var:`Py_LegacyWindowsFSEncodingFlag`:
* :c:var:`!Py_LegacyWindowsFSEncodingFlag`:
Use :c:member:`PyPreConfig.legacy_windows_fs_encoding` or
:c:func:`PyConfig_Get("legacy_windows_fs_encoding") <PyConfig_Get>` instead.
* :c:var:`Py_LegacyWindowsStdioFlag`:
* :c:var:`!Py_LegacyWindowsStdioFlag`:
Use :c:member:`PyConfig.legacy_windows_stdio` or
:c:func:`PyConfig_Get("legacy_windows_stdio") <PyConfig_Get>` instead.
* :c:var:`!Py_FileSystemDefaultEncoding`, :c:var:`!Py_HasFileSystemDefaultEncoding`:
Expand Down
Loading
Loading