From 764e83db8536ece49550f8a44f0525cb031369a4 Mon Sep 17 00:00:00 2001 From: Victor Stinner Date: Mon, 23 May 2022 14:56:35 +0200 Subject: gh-93103: Deprecate global configuration variable (#93104) Deprecate global configuration variables, like Py_IgnoreEnvironmentFlag, in the documentation: the Py_InitializeFromConfig() API should be instead. --- Doc/c-api/init.rst | 109 +++++++++++++++++++++ Doc/c-api/init_config.rst | 17 ++-- .../2022-05-23-13-33-18.gh-issue-93103.ooD3Eb.rst | 4 + 3 files changed, 123 insertions(+), 7 deletions(-) create mode 100644 Misc/NEWS.d/next/C API/2022-05-23-13-33-18.gh-issue-93103.ooD3Eb.rst diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst index d495495..038498f 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 `. + 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 `. + 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 `. + 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 `. + 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 + `. + 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 `. + 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 `. + 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 `. + 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 `. + 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 `. + 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 `. + 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 `. + 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 `. + Don't add the :data:`user site-packages directory ` 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 `. + 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 `. + 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 `. + 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 `. + 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 `. + .. 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 `. + .. c:function:: int Py_IsInitialized() diff --git a/Doc/c-api/init_config.rst b/Doc/c-api/init_config.rst index d6a1237..b1e9800 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 ` 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 0000000..404f008 --- /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. -- cgit v0.12