mirror of
https://github.com/python/cpython.git
synced 2025-09-26 10:19:53 +00:00
gh-105145: Remove old functions to config Python init (#105154)
Remove the following old functions to configure the Python initialization, deprecated in Python 3.11: * PySys_AddWarnOptionUnicode() * PySys_AddWarnOption() * PySys_AddXOption() * PySys_HasWarnOptions() * PySys_SetArgvEx() * PySys_SetArgv() * PySys_SetPath() * Py_SetPath() * Py_SetProgramName() * Py_SetPythonHome() * Py_SetStandardStreamEncoding() * _Py_SetProgramFullPath() Most of these functions are kept in the stable ABI, except: * Py_SetStandardStreamEncoding() * _Py_SetProgramFullPath() Update Doc/extending/embedding.rst and Doc/extending/extending.rst to use the new PyConfig API. _testembed.c: * check_stdio_details() now sets stdio_encoding and stdio_errors of PyConfig. * Add definitions of functions removed from the API but kept in the stable ABI. * test_init_from_config() and test_init_read_set() now use PyConfig_SetString() instead of PyConfig_SetBytesString(). Remove _Py_ClearStandardStreamEncoding() internal function.
This commit is contained in:
Victor Stinner
GitHub
parent
8ed705c083
commit
424049cc11
22 changed files with 182 additions and 522 deletions
|
|
@ -29,12 +29,6 @@ The following functions can be safely called before Python is initialized:
|
|||
* :c:func:`PyMem_SetAllocator`
|
||||
* :c:func:`PyMem_SetupDebugHooks`
|
||||
* :c:func:`PyObject_SetArenaAllocator`
|
||||
* :c:func:`Py_SetPath`
|
||||
* :c:func:`Py_SetProgramName`
|
||||
* :c:func:`Py_SetPythonHome`
|
||||
* :c:func:`Py_SetStandardStreamEncoding`
|
||||
* :c:func:`PySys_AddWarnOption`
|
||||
* :c:func:`PySys_AddXOption`
|
||||
* :c:func:`PySys_ResetWarnOptions`
|
||||
|
||||
* Informative functions:
|
||||
|
|
@ -332,7 +326,6 @@ Initializing and finalizing the interpreter
|
|||
.. c:function:: void Py_Initialize()
|
||||
|
||||
.. index::
|
||||
single: Py_SetProgramName()
|
||||
single: PyEval_InitThreads()
|
||||
single: modules (in module sys)
|
||||
single: path (in module sys)
|
||||
|
|
@ -340,8 +333,6 @@ Initializing and finalizing the interpreter
|
|||
pair: module; __main__
|
||||
pair: module; sys
|
||||
triple: module; search; path
|
||||
single: PySys_SetArgv()
|
||||
single: PySys_SetArgvEx()
|
||||
single: Py_FinalizeEx()
|
||||
|
||||
Initialize the Python interpreter. In an application embedding Python,
|
||||
|
|
@ -352,7 +343,9 @@ Initializing and finalizing the interpreter
|
|||
the table of loaded modules (``sys.modules``), and creates the fundamental
|
||||
modules :mod:`builtins`, :mod:`__main__` and :mod:`sys`. It also initializes
|
||||
the module search path (``sys.path``). It does not set ``sys.argv``; use
|
||||
:c:func:`PySys_SetArgvEx` for that. This is a no-op when called for a second time
|
||||
the new :c:type:`PyConfig` API of the :ref:`Python Initialization
|
||||
Configuration <init-config>` for that. This is a no-op when called for a
|
||||
second time
|
||||
(without calling :c:func:`Py_FinalizeEx` first). There is no return value; it is a
|
||||
fatal error if the initialization fails.
|
||||
|
||||
|
|
@ -425,76 +418,9 @@ Process-wide parameters
|
|||
=======================
|
||||
|
||||
|
||||
.. c:function:: int Py_SetStandardStreamEncoding(const char *encoding, const char *errors)
|
||||
|
||||
.. index::
|
||||
single: Py_Initialize()
|
||||
single: main()
|
||||
triple: stdin; stdout; sdterr
|
||||
|
||||
This API is kept for backward compatibility: setting
|
||||
:c:member:`PyConfig.stdio_encoding` and :c:member:`PyConfig.stdio_errors`
|
||||
should be used instead, see :ref:`Python Initialization Configuration
|
||||
<init-config>`.
|
||||
|
||||
This function should be called before :c:func:`Py_Initialize`, if it is
|
||||
called at all. It specifies which encoding and error handling to use
|
||||
with standard IO, with the same meanings as in :func:`str.encode`.
|
||||
|
||||
It overrides :envvar:`PYTHONIOENCODING` values, and allows embedding code
|
||||
to control IO encoding when the environment variable does not work.
|
||||
|
||||
*encoding* and/or *errors* may be ``NULL`` to use
|
||||
:envvar:`PYTHONIOENCODING` and/or default values (depending on other
|
||||
settings).
|
||||
|
||||
Note that :data:`sys.stderr` always uses the "backslashreplace" error
|
||||
handler, regardless of this (or any other) setting.
|
||||
|
||||
If :c:func:`Py_FinalizeEx` is called, this function will need to be called
|
||||
again in order to affect subsequent calls to :c:func:`Py_Initialize`.
|
||||
|
||||
Returns ``0`` if successful, a nonzero value on error (e.g. calling after the
|
||||
interpreter has already been initialized).
|
||||
|
||||
.. versionadded:: 3.4
|
||||
|
||||
.. deprecated:: 3.11
|
||||
|
||||
|
||||
.. c:function:: void Py_SetProgramName(const wchar_t *name)
|
||||
|
||||
.. index::
|
||||
single: Py_Initialize()
|
||||
single: main()
|
||||
single: Py_GetPath()
|
||||
|
||||
This API is kept for backward compatibility: setting
|
||||
:c:member:`PyConfig.program_name` should be used instead, see :ref:`Python
|
||||
Initialization Configuration <init-config>`.
|
||||
|
||||
This function should be called before :c:func:`Py_Initialize` is called for
|
||||
the first time, if it is called at all. It tells the interpreter the value
|
||||
of the ``argv[0]`` argument to the :c:func:`main` function of the program
|
||||
(converted to wide characters).
|
||||
This is used by :c:func:`Py_GetPath` and some other functions below to find
|
||||
the Python run-time libraries relative to the interpreter executable. The
|
||||
default value is ``'python'``. The argument should point to a
|
||||
zero-terminated wide character string in static storage whose contents will not
|
||||
change for the duration of the program's execution. No code in the Python
|
||||
interpreter will change the contents of this storage.
|
||||
|
||||
Use :c:func:`Py_DecodeLocale` to decode a bytes string to get a
|
||||
:c:expr:`wchar_*` string.
|
||||
|
||||
.. deprecated:: 3.11
|
||||
|
||||
|
||||
.. c:function:: wchar* Py_GetProgramName()
|
||||
|
||||
.. index:: single: Py_SetProgramName()
|
||||
|
||||
Return the program name set with :c:func:`Py_SetProgramName`, or the default.
|
||||
Return the program name set with :c:member:`PyConfig.program_name`, or the default.
|
||||
The returned string points into static storage; the caller should not modify its
|
||||
value.
|
||||
|
||||
|
|
@ -509,7 +435,7 @@ Process-wide parameters
|
|||
|
||||
Return the *prefix* for installed platform-independent files. This is derived
|
||||
through a number of complicated rules from the program name set with
|
||||
:c:func:`Py_SetProgramName` and some environment variables; for example, if the
|
||||
:c:member:`PyConfig.program_name` and some environment variables; for example, if the
|
||||
program name is ``'/usr/local/bin/python'``, the prefix is ``'/usr/local'``. The
|
||||
returned string points into static storage; the caller should not modify its
|
||||
value. This corresponds to the :makevar:`prefix` variable in the top-level
|
||||
|
|
@ -528,7 +454,7 @@ Process-wide parameters
|
|||
|
||||
Return the *exec-prefix* for installed platform-*dependent* files. This is
|
||||
derived through a number of complicated rules from the program name set with
|
||||
:c:func:`Py_SetProgramName` and some environment variables; for example, if the
|
||||
:c:member:`PyConfig.program_name` and some environment variables; for example, if the
|
||||
program name is ``'/usr/local/bin/python'``, the exec-prefix is
|
||||
``'/usr/local'``. The returned string points into static storage; the caller
|
||||
should not modify its value. This corresponds to the :makevar:`exec_prefix`
|
||||
|
|
@ -568,12 +494,11 @@ Process-wide parameters
|
|||
.. c:function:: wchar_t* Py_GetProgramFullPath()
|
||||
|
||||
.. index::
|
||||
single: Py_SetProgramName()
|
||||
single: executable (in module sys)
|
||||
|
||||
Return the full program name of the Python executable; this is computed as a
|
||||
side-effect of deriving the default module search path from the program name
|
||||
(set by :c:func:`Py_SetProgramName` above). The returned string points into
|
||||
(set by :c:member:`PyConfig.program_name`). The returned string points into
|
||||
static storage; the caller should not modify its value. The value is available
|
||||
to Python code as ``sys.executable``.
|
||||
|
||||
|
|
@ -589,10 +514,9 @@ Process-wide parameters
|
|||
.. index::
|
||||
triple: module; search; path
|
||||
single: path (in module sys)
|
||||
single: Py_SetPath()
|
||||
|
||||
Return the default module search path; this is computed from the program name
|
||||
(set by :c:func:`Py_SetProgramName` above) and some environment variables.
|
||||
(set by :c:member:`PyConfig.program_name`) and some environment variables.
|
||||
The returned string consists of a series of directory names separated by a
|
||||
platform dependent delimiter character. The delimiter character is ``':'``
|
||||
on Unix and macOS, ``';'`` on Windows. The returned string points into
|
||||
|
|
@ -610,44 +534,6 @@ Process-wide parameters
|
|||
It now returns ``NULL`` if called before :c:func:`Py_Initialize`.
|
||||
|
||||
|
||||
.. c:function:: void Py_SetPath(const wchar_t *)
|
||||
|
||||
.. index::
|
||||
triple: module; search; path
|
||||
single: path (in module sys)
|
||||
single: Py_GetPath()
|
||||
|
||||
This API is kept for backward compatibility: setting
|
||||
:c:member:`PyConfig.module_search_paths` and
|
||||
:c:member:`PyConfig.module_search_paths_set` should be used instead, see
|
||||
:ref:`Python Initialization Configuration <init-config>`.
|
||||
|
||||
Set the default module search path. If this function is called before
|
||||
:c:func:`Py_Initialize`, then :c:func:`Py_GetPath` won't attempt to compute a
|
||||
default search path but uses the one provided instead. This is useful if
|
||||
Python is embedded by an application that has full knowledge of the location
|
||||
of all modules. The path components should be separated by the platform
|
||||
dependent delimiter character, which is ``':'`` on Unix and macOS, ``';'``
|
||||
on Windows.
|
||||
|
||||
This also causes :data:`sys.executable` to be set to the program
|
||||
full path (see :c:func:`Py_GetProgramFullPath`) and for :data:`sys.prefix` and
|
||||
:data:`sys.exec_prefix` to be empty. It is up to the caller to modify these
|
||||
if required after calling :c:func:`Py_Initialize`.
|
||||
|
||||
Use :c:func:`Py_DecodeLocale` to decode a bytes string to get a
|
||||
:c:expr:`wchar_*` string.
|
||||
|
||||
The path argument is copied internally, so the caller may free it after the
|
||||
call completes.
|
||||
|
||||
.. versionchanged:: 3.8
|
||||
The program full path is now used for :data:`sys.executable`, instead
|
||||
of the program name.
|
||||
|
||||
.. deprecated:: 3.11
|
||||
|
||||
|
||||
.. c:function:: const char* Py_GetVersion()
|
||||
|
||||
Return the version of this Python interpreter. This is a string that looks
|
||||
|
|
@ -718,110 +604,10 @@ Process-wide parameters
|
|||
``sys.version``.
|
||||
|
||||
|
||||
.. c:function:: void PySys_SetArgvEx(int argc, wchar_t **argv, int updatepath)
|
||||
|
||||
.. index::
|
||||
single: main()
|
||||
single: Py_FatalError()
|
||||
single: argv (in module sys)
|
||||
|
||||
This API is kept for backward compatibility: setting
|
||||
:c:member:`PyConfig.argv`, :c:member:`PyConfig.parse_argv` and
|
||||
:c:member:`PyConfig.safe_path` should be used instead, see :ref:`Python
|
||||
Initialization Configuration <init-config>`.
|
||||
|
||||
Set :data:`sys.argv` based on *argc* and *argv*. These parameters are
|
||||
similar to those passed to the program's :c:func:`main` function with the
|
||||
difference that the first entry should refer to the script file to be
|
||||
executed rather than the executable hosting the Python interpreter. If there
|
||||
isn't a script that will be run, the first entry in *argv* can be an empty
|
||||
string. If this function fails to initialize :data:`sys.argv`, a fatal
|
||||
condition is signalled using :c:func:`Py_FatalError`.
|
||||
|
||||
If *updatepath* is zero, this is all the function does. If *updatepath*
|
||||
is non-zero, the function also modifies :data:`sys.path` according to the
|
||||
following algorithm:
|
||||
|
||||
- If the name of an existing script is passed in ``argv[0]``, the absolute
|
||||
path of the directory where the script is located is prepended to
|
||||
:data:`sys.path`.
|
||||
- Otherwise (that is, if *argc* is ``0`` or ``argv[0]`` doesn't point
|
||||
to an existing file name), an empty string is prepended to
|
||||
:data:`sys.path`, which is the same as prepending the current working
|
||||
directory (``"."``).
|
||||
|
||||
Use :c:func:`Py_DecodeLocale` to decode a bytes string to get a
|
||||
:c:expr:`wchar_*` string.
|
||||
|
||||
See also :c:member:`PyConfig.orig_argv` and :c:member:`PyConfig.argv`
|
||||
members of the :ref:`Python Initialization Configuration <init-config>`.
|
||||
|
||||
.. note::
|
||||
It is recommended that applications embedding the Python interpreter
|
||||
for purposes other than executing a single script pass ``0`` as *updatepath*,
|
||||
and update :data:`sys.path` themselves if desired.
|
||||
See `CVE-2008-5983 <https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2008-5983>`_.
|
||||
|
||||
On versions before 3.1.3, you can achieve the same effect by manually
|
||||
popping the first :data:`sys.path` element after having called
|
||||
:c:func:`PySys_SetArgv`, for example using::
|
||||
|
||||
PyRun_SimpleString("import sys; sys.path.pop(0)\n");
|
||||
|
||||
.. versionadded:: 3.1.3
|
||||
|
||||
.. XXX impl. doesn't seem consistent in allowing ``0``/``NULL`` for the params;
|
||||
check w/ Guido.
|
||||
|
||||
.. deprecated:: 3.11
|
||||
|
||||
|
||||
.. c:function:: void PySys_SetArgv(int argc, wchar_t **argv)
|
||||
|
||||
This API is kept for backward compatibility: setting
|
||||
:c:member:`PyConfig.argv` and :c:member:`PyConfig.parse_argv` should be used
|
||||
instead, see :ref:`Python Initialization Configuration <init-config>`.
|
||||
|
||||
This function works like :c:func:`PySys_SetArgvEx` with *updatepath* set
|
||||
to ``1`` unless the :program:`python` interpreter was started with the
|
||||
:option:`-I`.
|
||||
|
||||
Use :c:func:`Py_DecodeLocale` to decode a bytes string to get a
|
||||
:c:expr:`wchar_*` string.
|
||||
|
||||
See also :c:member:`PyConfig.orig_argv` and :c:member:`PyConfig.argv`
|
||||
members of the :ref:`Python Initialization Configuration <init-config>`.
|
||||
|
||||
.. versionchanged:: 3.4 The *updatepath* value depends on :option:`-I`.
|
||||
|
||||
.. deprecated:: 3.11
|
||||
|
||||
|
||||
.. c:function:: void Py_SetPythonHome(const wchar_t *home)
|
||||
|
||||
This API is kept for backward compatibility: setting
|
||||
:c:member:`PyConfig.home` should be used instead, see :ref:`Python
|
||||
Initialization Configuration <init-config>`.
|
||||
|
||||
Set the default "home" directory, that is, the location of the standard
|
||||
Python libraries. See :envvar:`PYTHONHOME` for the meaning of the
|
||||
argument string.
|
||||
|
||||
The argument should point to a zero-terminated character string in static
|
||||
storage whose contents will not change for the duration of the program's
|
||||
execution. No code in the Python interpreter will change the contents of
|
||||
this storage.
|
||||
|
||||
Use :c:func:`Py_DecodeLocale` to decode a bytes string to get a
|
||||
:c:expr:`wchar_*` string.
|
||||
|
||||
.. deprecated:: 3.11
|
||||
|
||||
|
||||
.. c:function:: wchar_t* Py_GetPythonHome()
|
||||
|
||||
Return the default "home", that is, the value set by a previous call to
|
||||
:c:func:`Py_SetPythonHome`, or the value of the :envvar:`PYTHONHOME`
|
||||
Return the default "home", that is, the value set by
|
||||
:c:member:`PyConfig.home`, or the value of the :envvar:`PYTHONHOME`
|
||||
environment variable if it is set.
|
||||
|
||||
This function should not be called before :c:func:`Py_Initialize`, otherwise
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue