8000 bpo-32124: Document C functions safe before init (#4540) · python/cpython@84c4b19 · GitHub
[go: up one dir, main page]
Skip to content

Commit 84c4b19

Browse files
vstinnervstinner
authored
bpo-32124: Document C functions safe before init (#4540)
Explicitly document C functions and C variables that can be set before Py_Initialize().
1 parent da9c8c3 commit 84c4b19

File tree

3 files changed

+214
-5
lines changed

3 files changed

+214
-5
lines changed

‎Doc/c-api/init.rst

Lines changed: 212 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,213 @@
77
Initialization, Finalization, and Threads
88
*****************************************
99

10+
.. _pre-init-safe:
11+
12+
Before Python Initialization
13+
============================
14+
15+
In an application embedding Python, the :c:func:`Py_Initialize` function must
16+
be called before using any other Python/C API functions; with the exception of
17+
a few functions and the :ref:`global configuration variables
18+
<global-conf-vars>`.
19+
20+
The following functions can be safely called before Python is initialized:
21+
22+
* Configuration functions:
23+
24+
* :c:func:`PyImport_AppendInittab`
25+
* :c:func:`PyImport_ExtendInittab`
26+
* :c:func:`PyInitFrozenExtensions`
27+
* :c:func:`PyMem_SetAllocator`
28+
* :c:func:`PyMem_SetupDebugHooks`
29+
* :c:func:`PyObject_SetArenaAllocator`
30+
* :c:func:`Py_SetPath`
31+
* :c:func:`Py_SetProgramName`
32+
* :c:func:`Py_SetPythonHome`
33+
* :c:func:`Py_SetStandardStreamEncoding`
34+
35+
* Informative functions:
36+
37+
* :c:func:`PyMem_GetAllocator`
38+
* :c:func:`PyObject_GetArenaAllocator`
39+
* :c:func:`Py_GetBuildInfo`
40+
* :c:func:`Py_GetCompiler`
41+
* :c:func:`Py_GetCopyright`
42+
* :c:func:`Py_GetPlatform`
43+
* :c:func:`Py_GetProgramName`
44+
* :c:func:`Py_GetVersion`
45+
46+
* Utilities:
47+
48+
* :c:func:`Py_DecodeLocale`
49+
50+
* Memory allocators:
51+
52+
* :c:func:`PyMem_RawMalloc`
53+
* :c:func:`PyMem_RawRealloc`
54+
* :c:func:`PyMem_RawCalloc`
55+
* :c:func:`PyMem_RawFree`
56+
57+
.. note::
58+
59+
The following functions **should not be called** before
60+
:c:func:`Py_Initialize`: :c:func:`Py_EncodeLocale`, :c:func:`Py_GetPath`,
61+
:c:func:`Py_GetPrefix`, :c:func:`Py_GetExecPrefix` and
62+
:c:func:`Py_GetProgramFullPath` and :c:func:`Py_GetPythonHome`.
63+
64+
65+
.. _global-conf-vars:
66+
67+
Global configuration variables
68+
==============================
69+
70+
Python has variables for the global configuration to control different features
71+
and options. By default, these flags are controlled by :ref:`command line
72+
options <using-on-interface-options>`.
73+
74+
When a flag is set by an option, the value of the flag is the number of times
75+
that the option was set. For example, ``-b`` sets :c:data:`Py_BytesWarningFlag`
76+
to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
77+
78+
.. c:var:: Py_BytesWarningFlag
79+
80+
Issue a warning when comparing :class:`bytes` or :class:`bytearray` with
81+
:class:`str` or :class:`bytes` with :class:`int`. Issue an error if greater
82+
or equal to ``2``.
83+
84+
Set by the :option:`-b` option.
85+
86+
.. c:var:: Py_DebugFlag
87+
88+
Turn on parser debugging output (for expert only, depending on compilation
89+
options).
90+
91+
Set by the :option:`-d` option and the :envvar:`PYTHONDEBUG` environment
92+
variable.
93+
94+
.. c:var:: Py_DontWriteBytecodeFlag
95+
96+
If set to non-zero, Python won't try to write ``.pyc`` files on the
97+
import of source modules.
98+
99+
Set by the :option:`-B` option and the :envvar:`PYTHONDONTWRITEBYTECODE`
100+
environment variable.
101+
102+
.. c:var:: Py_FrozenFlag
103+
104+
Suppress error messages when calculating the module search path in
105+
:c:func:`Py_GetPath`.
106+
107+
Private flag used by ``_freeze_importlib`` and ``frozenmain`` programs.
108+
109+
.. c:var:: Py_HashRandomizationFlag
110+
111+
Set to ``1`` if the :envvar:`PYTHONHASHSEED` environment variable is set to
112+
a non-empty string.
113+
114+
If the flag is non-zero, read the :envvar:`PYTHONHASHSEED` environment
115+
variable to initialize the secret hash seed.
116+
117+
.. c:var:: Py_IgnoreEnvironmentFlag
118+
119+
Ignore all :envvar:`PYTHON*` environment variables, e.g.
120+
:envvar:`PYTHONPATH` and :envvar:`PYTHONHOME`, that might be set.
121+
122+
Set by the :option:`-E` and :option:`-I` options.
123+
124+
.. c:var:: Py_InspectFlag
125+
126+
When a script is passed as first argument or the :option:`-c` option is used,
127+
enter interactive mode after executing the script or the command, even when
128+
:data:`sys.stdin` does not appear to be a terminal.
129+
130+
Set by the :option:`-i` option and the :envvar:`PYTHONINSPECT` environment
131+
variable.
132+
133+
.. c:var:: Py_InteractiveFlag
134+
135+
Set by the :option:`-i` option.
136+
137+
.. c:var:: Py_IsolatedFlag
138+
139+
Run Python in isolated mode. In isolated mode :data:`sys.path` contains
140+
neither the script's directory nor the user's site-packages directory.
141+
142+
Set by the :option:`-I` option.
143+
144+
.. versionadded:: 3.4
145+
146+
.. c:var:: Py_LegacyWindowsFSEncodingFlag
147+
148+
If the flag is non-zero, use the ``mbcs`` encoding instead of the UTF-8
149+
encoding for the filesystem encoding.
150+
151+
Set to ``1`` if the :envvar:`PYTHONLEGACYWINDOWSFSENCODING` environment
152+
variable is set to a non-empty string.
153+
154+
See :pep:`529` for more details.
155+
156+
Availability: Windows.
157+
158+
.. c:var:: Py_LegacyWindowsStdioFlag
159+
160+
If the flag is non-zero, use :class:`io.FileIO` instead of
161+
:class:`WindowsConsoleIO` for :mod:`sys` standard streams.
162+
163+
Set to ``1`` if the :envvar:`PYTHONLEGACYWINDOWSSTDIO` environment
164+
variable is set to a non-empty string.
165+
166+
See :pep:`528` for more details.
167+
168+
Availability: Windows.
169+
170+
.. c:var:: Py_NoSiteFlag
171+
172+
Disable the import of the module :mod:`site` and the site-dependent
173+
manipulations of :data:`sys.path` that it entails. Also disable these
174+
manipulations if :mod:`site` is explicitly imported later (call
175+
:func:`site.main` if you want them to be triggered).
176+
177+
Set by the :option:`-S` option.
178+
179+
.. c:var:: Py_NoUserSiteDirectory
180+
181+
Don't add the :data:`user site-packages directory <site.USER_SITE>` to
182+
:data:`sys.path`.
183+
184+
Set by the :option:`-s` and :option:`-I` options, and the
185+
:envvar:`PYTHONNOUSERSITE` environment variable.
186+
187+
.. c:var:: Py_OptimizeFlag
188+
189+
Set by the :option:`-O` option and the :envvar:`PYTHONOPTIMIZE` environment
190+
variable.
191+
192+
.. c:var:: Py_QuietFlag
193+
194+
Don't display the copyright and version messages even in interactive mode.
195+
196+
Set by the :option:`-q` option.
197+
198+
.. versionadded:: 3.2
199+
200+
.. c:var:: Py_UnbufferedStdioFlag
201+
202+
Force the stdout and stderr streams to be unbuffered.
203+
204+
Set by the :option:`-u` option and the :envvar:`PYTHONUNBUFFERED`
205+
environment variable.
206+
207+
.. c:var:: Py_VerboseFlag
208+
209+
Print a message each time a module is initialized, showing the place
210+
(filename or built-in module) from which it is loaded. If greater or equal
211+
to ``2``, print a message for each file that is checked for when
212+
searching for a module. Also provides information on module cleanup at exit.
213+
214+
Set by the :option:`-v` option and the :envvar:`PYTHONVERBOSE` environment
215+
variable.
216+
10217

11218
Initializing and finalizing the interpreter
12219
===========================================
@@ -27,9 +234,11 @@ Initializing and finalizing the interpreter
27234
single: PySys_SetArgvEx()
28235
single: Py_FinalizeEx()
29236
30-
Initialize the Python interpreter. In an application embedding Python, this
31-
should be called before using any other Python/C API functions; with the
32-
exception of :c:func:`Py_SetProgramName`, :c:func:`Py_SetPythonHome` and :c:func:`Py_SetPath`. This initializes
237+
Initialize the Python interpreter. In an application embedding Python,
238+
this should be called before using any other Python/C API functions; see
239+
:ref:`Before Python Initialization <pre-init-safe>` for the few exceptions.
240+
241+
This initializes
33242
the table of loaded modules (``sys.modules``), and creates the fundamental
34243
modules :mod:`builtins`, :mod:`__main__` and :mod:`sys`. It also initializes
35244
the module search path (``sys.path``). It does not set ``sys.argv``; use

‎Doc/using/cmdline.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -212,7 +212,7 @@ Miscellaneous options
212212

213213
.. cmdoption:: -d
214214

215-
Turn on parser debugging output (for wizards only, depending on compilation
215+
Turn on parser debugging output (for expert only, depending on compilation
216216
options). See also :envvar:`PYTHONDEBUG`.
217217

218218

‎Misc/python.man

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -124,7 +124,7 @@ This terminates the option list (following options are passed as
124124
arguments to the command).
125125
.TP
126126
.B \-d
127-
Turn on parser debugging output (for wizards only, depending on
127+
Turn on parser debugging output (for expert only, depending on
128128
compilation options).
129129
.TP
130130
.B \-E

0 commit comments

Comments
 (0)
0