[Python-checkins] gh-93103: Deprecate global configuration variable (#93104)
vstinner
webhook-mailer at python.org
Mon May 23 08:57:00 EDT 2022
https://github.com/python/cpython/commit/764e83db8536ece49550f8a44f0525cb031369a4
commit: 764e83db8536ece49550f8a44f0525cb031369a4
branch: main
author: Victor Stinner <vstinner at python.org>
committer: vstinner <vstinner at python.org>
date: 2022-05-23T14:56:35+02:00
summary:
gh-93103: Deprecate global configuration variable (#93104)
Deprecate global configuration variables, like
Py_IgnoreEnvironmentFlag, in the documentation: the
Py_InitializeFromConfig() API should be instead.
files:
A Misc/NEWS.d/next/C API/2022-05-23-13-33-18.gh-issue-93103.ooD3Eb.rst
M Doc/c-api/init.rst
M Doc/c-api/init_config.rst
diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst
index d4954958f855f5..038498f325ceb3 100644
--- a/Doc/c-api/init.rst
+++ b/Doc/c-api/init.rst
@@ -83,52 +83,93 @@ 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:: 3.12
+
.. 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:: 3.12
+
.. 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:: 3.12
+
.. 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>`.
+
Suppress error messages when calculating the module search path in
:c:func:`Py_GetPath`.
Private flag used by ``_freeze_module`` and ``frozenmain`` programs.
+ .. deprecated:: 3.12
+
.. 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:: 3.12
+
.. 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:: 3.12
+
.. 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.
@@ -136,12 +177,24 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
Set by the :option:`-i` option and the :envvar:`PYTHONINSPECT` environment
variable.
+ .. deprecated:: 3.12
+
.. 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:: 3.12
+
.. 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.
@@ -149,8 +202,14 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
.. versionadded:: 3.4
+ .. deprecated:: 3.12
+
.. 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`.
@@ -162,8 +221,14 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
.. availability:: Windows.
+ .. deprecated:: 3.12
+
.. 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:`WindowsConsoleIO` for :mod:`sys` standard streams.
@@ -174,8 +239,14 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
.. availability:: Windows.
+ .. deprecated:: 3.12
+
.. 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
@@ -183,36 +254,66 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
Set by the :option:`-S` option.
+ .. deprecated:: 3.12
+
.. 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:: 3.12
+
.. 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:: 3.12
+
.. 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:: 3.12
+
.. 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:: 3.12
+
.. 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
@@ -221,6 +322,8 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
Set by the :option:`-v` option and the :envvar:`PYTHONVERBOSE` environment
variable.
+ .. deprecated:: 3.12
+
Initializing and finalizing the interpreter
===========================================
@@ -253,6 +356,9 @@ Initializing and finalizing the interpreter
(without calling :c:func:`Py_FinalizeEx` first). There is no return value; it is a
fatal error if the initialization fails.
+ Use the :c:func:`Py_InitializeFromConfig` function to customize the
+ :ref:`Python Initialization Configuration <init-config>`.
+
.. note::
On Windows, changes the console mode from ``O_TEXT`` to ``O_BINARY``, which will
also affect non-Python uses of the console using the C Runtime.
@@ -264,6 +370,9 @@ Initializing and finalizing the interpreter
*initsigs* is ``0``, it skips initialization registration of signal handlers, which
might be useful when Python is embedded.
+ Use the :c:func:`Py_InitializeFromConfig` function to customize the
+ :ref:`Python Initialization Configuration <init-config>`.
+
.. c:function:: int Py_IsInitialized()
diff --git a/Doc/c-api/init_config.rst b/Doc/c-api/init_config.rst
index d6a12375cd56f0..b1e9800352fee8 100644
--- a/Doc/c-api/init_config.rst
+++ b/Doc/c-api/init_config.rst
@@ -835,8 +835,10 @@ PyConfig
* Set :c:member:`~PyConfig.safe_path` to ``1``:
don't prepend a potentially unsafe path to :data:`sys.path` at Python
- startup.
- * Set :c:member:`~PyConfig.use_environment` to ``0``.
+ startup, such as the current directory, the script's directory or an
+ empty string.
+ * Set :c:member:`~PyConfig.use_environment` to ``0``: ignore ``PYTHON``
+ environment variables.
* Set :c:member:`~PyConfig.user_site_directory` to ``0``: don't add the user
site directory to :data:`sys.path`.
* Python REPL doesn't import :mod:`readline` nor enable default readline
@@ -846,7 +848,8 @@ PyConfig
Default: ``0`` in Python mode, ``1`` in isolated mode.
- See also :c:member:`PyPreConfig.isolated`.
+ See also the :ref:`Isolated Configuration <init-isolated-conf>` and
+ :c:member:`PyPreConfig.isolated`.
.. c:member:: int legacy_windows_stdio
@@ -1177,13 +1180,13 @@ PyConfig
imported, 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.
+ If greater than 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.
Incremented by the :option:`-v` command line option.
- Set to the :envvar:`PYTHONVERBOSE` environment variable value.
+ Set by the :envvar:`PYTHONVERBOSE` environment variable value.
Default: ``0``.
diff --git a/Misc/NEWS.d/next/C API/2022-05-23-13-33-18.gh-issue-93103.ooD3Eb.rst b/Misc/NEWS.d/next/C API/2022-05-23-13-33-18.gh-issue-93103.ooD3Eb.rst
new file mode 100644
index 00000000000000..404f0089cd0b79
--- /dev/null
+++ b/Misc/NEWS.d/next/C API/2022-05-23-13-33-18.gh-issue-93103.ooD3Eb.rst
@@ -0,0 +1,4 @@
+Deprecate global configuration variables, like
+:c:var:`Py_IgnoreEnvironmentFlag`, in the documentation: the
+:c:func:`Py_InitializeFromConfig` API should be instead. Patch by Victor
+Stinner.
More information about the Python-checkins
mailing list