Skip to content
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

Jump to bottom

gh-105145: Remove old functions to config Python init #105154

Merged
merged 2 commits into from
Jun 1, 2023
Merged

gh-105145: Remove old functions to config Python init #105154

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1453a74
gh-105145: Remove old functions to config Python init
vstinner May 31, 2023
833ddf7
Run make regen-limited-abi
vstinner May 31, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
234 changes: 10 additions & 224 deletions Doc/c-api/init.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,16 +25,10 @@

* :c:func:`PyImport_AppendInittab`
* :c:func:`PyImport_ExtendInittab`
* :c:func:`PyInitFrozenExtensions`

Check warning on line 28 in Doc/c-api/init.rst

View workflow job for this annotation

GitHub Actions / Docs / Docs 

c:func reference target not found: PyInitFrozenExtensions
* :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:
Expand Down Expand Up @@ -157,7 +151,7 @@
:c:member:`PyConfig.use_environment` should be used instead, see
:ref:`Python Initialization Configuration <init-config>`.

Ignore all :envvar:`PYTHON*` environment variables, e.g.

Check warning on line 154 in Doc/c-api/init.rst

View workflow job for this annotation

GitHub Actions / Docs / Docs 

'envvar' reference target not found: PYTHON*
:envvar:`PYTHONPATH` and :envvar:`PYTHONHOME`, that might be set.

Set by the :option:`-E` and :option:`-I` options.
Expand Down Expand Up @@ -229,7 +223,7 @@
: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

Check warning on line 226 in Doc/c-api/init.rst

View workflow job for this annotation

GitHub Actions / Docs / Docs 

py:class reference target not found: WindowsConsoleIO
:class:`WindowsConsoleIO` for :mod:`sys` standard streams.

Set to ``1`` if the :envvar:`PYTHONLEGACYWINDOWSSTDIO` environment
Expand Down Expand Up @@ -332,16 +326,13 @@
.. c:function:: void Py_Initialize()

.. index::
single: Py_SetProgramName()
single: PyEval_InitThreads()
single: modules (in module sys)
single: path (in module sys)
pair: module; builtins
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,
Expand All @@ -352,7 +343,9 @@
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.

Expand Down Expand Up @@ -400,7 +393,7 @@
developer might want to free all memory allocated by Python before exiting from
the application.

**Bugs and caveats:** The destruction of modules and objects in modules is done

Check warning on line 396 in Doc/c-api/init.rst

View workflow job for this annotation

GitHub Actions / Docs / Docs 

py:meth reference target not found: __del__
in random order; this may cause destructors (:meth:`__del__` methods) to fail
when they depend on other objects (even functions) or modules. Dynamically
loaded extension modules loaded by Python are not unloaded. Small amounts of
Expand All @@ -425,76 +418,9 @@
=======================


.. 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()

Check warning on line 421 in Doc/c-api/init.rst

View workflow job for this annotation

GitHub Actions / Docs / Docs 

c:identifier reference target not found: wchar

.. 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.

Expand All @@ -505,11 +431,11 @@
It now returns ``NULL`` if called before :c:func:`Py_Initialize`.


.. c:function:: wchar_t* Py_GetPrefix()

Check warning on line 434 in Doc/c-api/init.rst

View workflow job for this annotation

GitHub Actions / Docs / Docs 

c:identifier reference target not found: wchar_t

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
Expand All @@ -524,11 +450,11 @@
It now returns ``NULL`` if called before :c:func:`Py_Initialize`.


.. c:function:: wchar_t* Py_GetExecPrefix()

Check warning on line 453 in Doc/c-api/init.rst

View workflow job for this annotation

GitHub Actions / Docs / Docs 

c:identifier reference target not found: wchar_t

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`
Expand Down Expand Up @@ -565,15 +491,14 @@
It now returns ``NULL`` if called before :c:func:`Py_Initialize`.


.. c:function:: wchar_t* Py_GetProgramFullPath()

Check warning on line 494 in Doc/c-api/init.rst

View workflow job for this annotation

GitHub Actions / Docs / Docs 

c:identifier reference target not found: wchar_t

.. 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``.

Expand All @@ -584,15 +509,14 @@
It now returns ``NULL`` if called before :c:func:`Py_Initialize`.


.. c:function:: wchar_t* Py_GetPath()

Check warning on line 512 in Doc/c-api/init.rst

View workflow job for this annotation

GitHub Actions / Docs / Docs 

c:identifier reference target not found: wchar_t

.. 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
Expand All @@ -610,44 +534,6 @@
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
Expand Down Expand Up @@ -718,110 +604,10 @@
``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()

Check warning on line 607 in Doc/c-api/init.rst

View workflow job for this annotation

GitHub Actions / Docs / Docs 

c:identifier reference target not found: wchar_t

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
Expand Down