@@ -29,6 +29,8 @@ The following functions can be safely called before Python is initialized:
2929 * :c:func: `PyMem_SetAllocator `
3030 * :c:func: `PyMem_SetupDebugHooks `
3131 * :c:func: `PyObject_SetArenaAllocator `
32+ * :c:func: `Py_SetProgramName `
33+ * :c:func: `Py_SetPythonHome `
3234 * :c:func: `PySys_ResetWarnOptions `
3335
3436* Informative functions:
@@ -59,7 +61,7 @@ The following functions can be safely called before Python is initialized:
5961 :c:func: `Py_Initialize `: :c:func: `Py_EncodeLocale `, :c:func: `Py_GetPath `,
6062 :c:func: `Py_GetPrefix `, :c:func: `Py_GetExecPrefix `,
6163 :c:func: `Py_GetProgramFullPath `, :c:func: `Py_GetPythonHome `,
62- and :c:func: `Py_GetProgramName `.
64+ :c:func: ` Py_GetProgramName ` and :c:func: `PyEval_InitThreads `.
6365
6466
6567.. _global-conf-vars :
@@ -326,6 +328,7 @@ Initializing and finalizing the interpreter
326328.. c :function :: void Py_Initialize ()
327329
328330 .. index::
331+ single: PyEval_InitThreads()
329332 single: modules (in module sys)
330333 single: path (in module sys)
331334 pair: module; builtins
@@ -425,6 +428,34 @@ Process-wide parameters
425428=======================
426429
427430
431+ .. c:function:: void Py_SetProgramName(const wchar_t *name)
432+
433+ .. index ::
434+ single: Py_Initialize()
435+ single: main()
436+ single: Py_GetPath()
437+
438+ This API is kept for backward compatibility: setting
439+ :c:member: `PyConfig.program_name ` should be used instead, see :ref: `Python
440+ Initialization Configuration <init-config>`.
441+
442+ This function should be called before :c:func: `Py_Initialize ` is called for
443+ the first time, if it is called at all. It tells the interpreter the value
444+ of the ``argv[0] `` argument to the :c:func: `main ` function of the program
445+ (converted to wide characters).
446+ This is used by :c:func:`Py_GetPath` and some other functions below to find
447+ the Python run-time libraries relative to the interpreter executable. The
448+ default value is ``'python'``. The argument should point to a
449+ zero-terminated wide character string in static storage whose contents will not
450+ change for the duration of the program's execution. No code in the Python
451+ interpreter will change the contents of this storage.
452+
453+ Use :c:func:`Py_DecodeLocale` to decode a bytes string to get a
454+ :c:expr:`wchar_*` string.
455+
456+ .. deprecated:: 3.11
457+
458+
428459.. c:function:: wchar_t* Py_GetProgramName()
429460
430461 Return the program name set with :c:member:`PyConfig.program_name`, or the default.
@@ -626,6 +657,106 @@ Process-wide parameters
626657 ``sys.version``.
627658
628659
660+ .. c:function:: void PySys_SetArgvEx(int argc, wchar_t **argv, int updatepath)
661+
662+ .. index::
663+ single: main()
664+ single: Py_FatalError()
665+ single: argv (in module sys)
666+
667+ This API is kept for backward compatibility: setting
668+ :c:member:`PyConfig.argv`, :c:member:`PyConfig.parse_argv` and
669+ :c:member:`PyConfig.safe_path` should be used instead, see :ref:`Python
670+ Initialization Configuration <init-config>`.
671+
672+ Set :data:`sys.argv` based on *argc* and *argv*. These parameters are
673+ similar to those passed to the program's :c:func:`main` function with the
674+ difference that the first entry should refer to the script file to be
675+ executed rather than the executable hosting the Python interpreter. If there
676+ isn't a script that will be run, the first entry in *argv* can be an empty
677+ string. If this function fails to initialize :data:`sys.argv`, a fatal
678+ condition is signalled using :c:func:`Py_FatalError`.
679+
680+ If *updatepath* is zero, this is all the function does. If *updatepath*
681+ is non-zero, the function also modifies :data:`sys.path` according to the
682+ following algorithm:
683+
684+ - If the name of an existing script is passed in ``argv[0]``, the absolute
685+ path of the directory where the script is located is prepended to
686+ :data:`sys.path`.
687+ - Otherwise (that is, if *argc* is ``0`` or ``argv[0]`` doesn't point
688+ to an existing file name), an empty string is prepended to
689+ :data:`sys.path`, which is the same as prepending the current working
690+ directory (``" ." ``).
691+
692+ Use :c:func:`Py_DecodeLocale` to decode a bytes string to get a
693+ :c:expr:`wchar_*` string.
694+
695+ See also :c:member:`PyConfig.orig_argv` and :c:member:`PyConfig.argv`
696+ members of the :ref:`Python Initialization Configuration <init-config>`.
697+
698+ .. note::
699+ It is recommended that applications embedding the Python interpreter
700+ for purposes other than executing a single script pass ``0`` as *updatepath*,
701+ and update :data:`sys.path` themselves if desired.
702+ See :cve:`2008-5983`.
703+
704+ On versions before 3.1.3, you can achieve the same effect by manually
705+ popping the first :data:`sys.path` element after having called
706+ :c:func:`PySys_SetArgv`, for example using::
707+
708+ PyRun_SimpleString(" import sys; sys.path.pop(0 )\n" );
709+
710+ .. versionadded:: 3.1.3
711+
712+ .. XXX impl. doesn't seem consistent in allowing ``0``/``NULL`` for the params;
713+ check w/ Guido.
714+
715+ .. deprecated:: 3.11
716+
717+
718+ .. c:function:: void PySys_SetArgv(int argc, wchar_t **argv)
719+
720+ This API is kept for backward compatibility: setting
721+ :c:member:`PyConfig.argv` and :c:member:`PyConfig.parse_argv` should be used
722+ instead, see :ref:`Python Initialization Configuration <init-config>`.
723+
724+ This function works like :c:func:`PySys_SetArgvEx` with *updatepath* set
725+ to ``1`` unless the :program:`python` interpreter was started with the
726+ :option:`-I`.
727+
728+ Use :c:func:`Py_DecodeLocale` to decode a bytes string to get a
729+ :c:expr:`wchar_*` string.
730+
731+ See also :c:member:`PyConfig.orig_argv` and :c:member:`PyConfig.argv`
732+ members of the :ref:`Python Initialization Configuration <init-config>`.
733+
734+ .. versionchanged:: 3.4 The *updatepath* value depends on :option:`-I`.
735+
736+ .. deprecated:: 3.11
737+
738+
739+ .. c:function:: void Py_SetPythonHome(const wchar_t *home)
740+
741+ This API is kept for backward compatibility: setting
742+ :c:member:`PyConfig.home` should be used instead, see :ref:`Python
743+ Initialization Configuration <init-config>`.
744+
745+ Set the default " home" directory, that is, the location of the standard
746+ Python libraries. See :envvar:`PYTHONHOME` for the meaning of the
747+ argument string.
748+
749+ The argument should point to a zero-terminated character string in static
750+ storage whose contents will not change for the duration of the program's
751+ execution. No code in the Python interpreter will change the contents of
752+ this storage.
753+
754+ Use :c:func:`Py_DecodeLocale` to decode a bytes string to get a
755+ :c:expr:`wchar_*` string.
756+
757+ .. deprecated:: 3.11
758+
759+
629760.. c:function:: wchar_t* Py_GetPythonHome()
630761
631762 Return the default " home" , that is, the value set by
@@ -841,6 +972,33 @@ code, or when embedding the Python interpreter:
841972 This thread's interpreter state.
842973
843974
975+ .. c:function:: void PyEval_InitThreads()
976+
977+ .. index::
978+ single: PyEval_AcquireThread()
979+ single: PyEval_ReleaseThread()
980+ single: PyEval_SaveThread()
981+ single: PyEval_RestoreThread()
982+
983+ Deprecated function which does nothing.
984+
985+ In Python 3.6 and older, this function created the GIL if it didn't exist.
986+
987+ .. versionchanged:: 3.9
988+ The function now does nothing.
989+
990+ .. versionchanged:: 3.7
991+ This function is now called by :c:func:`Py_Initialize()`, so you don't
992+ have to call it yourself anymore.
993+
994+ .. versionchanged:: 3.2
995+ This function cannot be called before :c:func:`Py_Initialize()` anymore.
996+
997+ .. deprecated:: 3.9
998+
999+ .. index:: pair: module; _thread
1000+
1001+
8441002.. c:function:: PyThreadState* PyEval_SaveThread()
8451003
8461004 Release the global interpreter lock (if it has been created) and reset the
0 commit comments