Skip to content

Commit 764e83d

Browse files
authored
gh-93103: Deprecate global configuration variable (#93104)
Deprecate global configuration variables, like Py_IgnoreEnvironmentFlag, in the documentation: the Py_InitializeFromConfig() API should be instead.
1 parent 760ec89 commit 764e83d

File tree

3 files changed

+123
-7
lines changed

3 files changed

+123
-7
lines changed

Doc/c-api/init.rst

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -83,74 +83,133 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
8383

8484
.. c:var:: int Py_BytesWarningFlag
8585
86+
This API is kept for backward compatibility: setting
87+
:c:member:`PyConfig.bytes_warning` should be used instead, see :ref:`Python
88+
Initialization Configuration <init-config>`.
89+
8690
Issue a warning when comparing :class:`bytes` or :class:`bytearray` with
8791
:class:`str` or :class:`bytes` with :class:`int`. Issue an error if greater
8892
or equal to ``2``.
8993

9094
Set by the :option:`-b` option.
9195

96+
.. deprecated:: 3.12
97+
9298
.. c:var:: int Py_DebugFlag
9399
100+
This API is kept for backward compatibility: setting
101+
:c:member:`PyConfig.parser_debug` should be used instead, see :ref:`Python
102+
Initialization Configuration <init-config>`.
103+
94104
Turn on parser debugging output (for expert only, depending on compilation
95105
options).
96106

97107
Set by the :option:`-d` option and the :envvar:`PYTHONDEBUG` environment
98108
variable.
99109

110+
.. deprecated:: 3.12
111+
100112
.. c:var:: int Py_DontWriteBytecodeFlag
101113
114+
This API is kept for backward compatibility: setting
115+
:c:member:`PyConfig.write_bytecode` should be used instead, see :ref:`Python
116+
Initialization Configuration <init-config>`.
117+
102118
If set to non-zero, Python won't try to write ``.pyc`` files on the
103119
import of source modules.
104120

105121
Set by the :option:`-B` option and the :envvar:`PYTHONDONTWRITEBYTECODE`
106122
environment variable.
107123

124+
.. deprecated:: 3.12
125+
108126
.. c:var:: int Py_FrozenFlag
109127
128+
This API is kept for backward compatibility: setting
129+
:c:member:`PyConfig.pathconfig_warnings` should be used instead, see
130+
:ref:`Python Initialization Configuration <init-config>`.
131+
110132
Suppress error messages when calculating the module search path in
111133
:c:func:`Py_GetPath`.
112134

113135
Private flag used by ``_freeze_module`` and ``frozenmain`` programs.
114136

137+
.. deprecated:: 3.12
138+
115139
.. c:var:: int Py_HashRandomizationFlag
116140
141+
This API is kept for backward compatibility: setting
142+
:c:member:`PyConfig.hash_seed` and :c:member:`PyConfig.use_hash_seed` should
143+
be used instead, see :ref:`Python Initialization Configuration
144+
<init-config>`.
145+
117146
Set to ``1`` if the :envvar:`PYTHONHASHSEED` environment variable is set to
118147
a non-empty string.
119148

120149
If the flag is non-zero, read the :envvar:`PYTHONHASHSEED` environment
121150
variable to initialize the secret hash seed.
122151

152+
.. deprecated:: 3.12
153+
123154
.. c:var:: int Py_IgnoreEnvironmentFlag
124155
156+
This API is kept for backward compatibility: setting
157+
:c:member:`PyConfig.use_environment` should be used instead, see
158+
:ref:`Python Initialization Configuration <init-config>`.
159+
125160
Ignore all :envvar:`PYTHON*` environment variables, e.g.
126161
:envvar:`PYTHONPATH` and :envvar:`PYTHONHOME`, that might be set.
127162

128163
Set by the :option:`-E` and :option:`-I` options.
129164

165+
.. deprecated:: 3.12
166+
130167
.. c:var:: int Py_InspectFlag
131168
169+
This API is kept for backward compatibility: setting
170+
:c:member:`PyConfig.inspect` should be used instead, see
171+
:ref:`Python Initialization Configuration <init-config>`.
172+
132173
When a script is passed as first argument or the :option:`-c` option is used,
133174
enter interactive mode after executing the script or the command, even when
134175
:data:`sys.stdin` does not appear to be a terminal.
135176

136177
Set by the :option:`-i` option and the :envvar:`PYTHONINSPECT` environment
137178
variable.
138179

180+
.. deprecated:: 3.12
181+
139182
.. c:var:: int Py_InteractiveFlag
140183
184+
This API is kept for backward compatibility: setting
185+
:c:member:`PyConfig.interactive` should be used instead, see
186+
:ref:`Python Initialization Configuration <init-config>`.
187+
141188
Set by the :option:`-i` option.
142189

190+
.. deprecated:: 3.12
191+
143192
.. c:var:: int Py_IsolatedFlag
144193
194+
This API is kept for backward compatibility: setting
195+
:c:member:`PyConfig.isolated` should be used instead, see
196+
:ref:`Python Initialization Configuration <init-config>`.
197+
145198
Run Python in isolated mode. In isolated mode :data:`sys.path` contains
146199
neither the script's directory nor the user's site-packages directory.
147200

148201
Set by the :option:`-I` option.
149202

150203
.. versionadded:: 3.4
151204

205+
.. deprecated:: 3.12
206+
152207
.. c:var:: int Py_LegacyWindowsFSEncodingFlag
153208
209+
This API is kept for backward compatibility: setting
210+
:c:member:`PyPreConfig.legacy_windows_fs_encoding` should be used instead, see
211+
:ref:`Python Initialization Configuration <init-config>`.
212+
154213
If the flag is non-zero, use the ``mbcs`` encoding with ``replace`` error
155214
handler, instead of the UTF-8 encoding with ``surrogatepass`` error handler,
156215
for the :term:`filesystem encoding and error handler`.
@@ -162,8 +221,14 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
162221

163222
.. availability:: Windows.
164223

224+
.. deprecated:: 3.12
225+
165226
.. c:var:: int Py_LegacyWindowsStdioFlag
166227
228+
This API is kept for backward compatibility: setting
229+
:c:member:`PyConfig.legacy_windows_stdio` should be used instead, see
230+
:ref:`Python Initialization Configuration <init-config>`.
231+
167232
If the flag is non-zero, use :class:`io.FileIO` instead of
168233
:class:`WindowsConsoleIO` for :mod:`sys` standard streams.
169234

@@ -174,45 +239,81 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
174239

175240
.. availability:: Windows.
176241

242+
.. deprecated:: 3.12
243+
177244
.. c:var:: int Py_NoSiteFlag
178245
246+
This API is kept for backward compatibility: setting
247+
:c:member:`PyConfig.site_import` should be used instead, see
248+
:ref:`Python Initialization Configuration <init-config>`.
249+
179250
Disable the import of the module :mod:`site` and the site-dependent
180251
manipulations of :data:`sys.path` that it entails. Also disable these
181252
manipulations if :mod:`site` is explicitly imported later (call
182253
:func:`site.main` if you want them to be triggered).
183254

184255
Set by the :option:`-S` option.
185256

257+
.. deprecated:: 3.12
258+
186259
.. c:var:: int Py_NoUserSiteDirectory
187260
261+
This API is kept for backward compatibility: setting
262+
:c:member:`PyConfig.user_site_directory` should be used instead, see
263+
:ref:`Python Initialization Configuration <init-config>`.
264+
188265
Don't add the :data:`user site-packages directory <site.USER_SITE>` to
189266
:data:`sys.path`.
190267

191268
Set by the :option:`-s` and :option:`-I` options, and the
192269
:envvar:`PYTHONNOUSERSITE` environment variable.
193270

271+
.. deprecated:: 3.12
272+
194273
.. c:var:: int Py_OptimizeFlag
195274
275+
This API is kept for backward compatibility: setting
276+
:c:member:`PyConfig.optimization_level` should be used instead, see
277+
:ref:`Python Initialization Configuration <init-config>`.
278+
196279
Set by the :option:`-O` option and the :envvar:`PYTHONOPTIMIZE` environment
197280
variable.
198281

282+
.. deprecated:: 3.12
283+
199284
.. c:var:: int Py_QuietFlag
200285
286+
This API is kept for backward compatibility: setting
287+
:c:member:`PyConfig.quiet` should be used instead, see :ref:`Python
288+
Initialization Configuration <init-config>`.
289+
201290
Don't display the copyright and version messages even in interactive mode.
202291

203292
Set by the :option:`-q` option.
204293

205294
.. versionadded:: 3.2
206295

296+
.. deprecated:: 3.12
297+
207298
.. c:var:: int Py_UnbufferedStdioFlag
208299
300+
This API is kept for backward compatibility: setting
301+
:c:member:`PyConfig.buffered_stdio` should be used instead, see :ref:`Python
302+
Initialization Configuration <init-config>`.
303+
209304
Force the stdout and stderr streams to be unbuffered.
210305

211306
Set by the :option:`-u` option and the :envvar:`PYTHONUNBUFFERED`
212307
environment variable.
213308

309+
.. deprecated:: 3.12
310+
214311
.. c:var:: int Py_VerboseFlag
215312
313+
This API is kept for backward compatibility: setting
314+
:c:member:`PyConfig.verbose` should be used instead, see :ref:`Python
315+
Initialization Configuration <init-config>`.
316+
216317
Print a message each time a module is initialized, showing the place
217318
(filename or built-in module) from which it is loaded. If greater or equal
218319
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.
221322
Set by the :option:`-v` option and the :envvar:`PYTHONVERBOSE` environment
222323
variable.
223324

325+
.. deprecated:: 3.12
326+
224327

225328
Initializing and finalizing the interpreter
226329
===========================================
@@ -253,6 +356,9 @@ Initializing and finalizing the interpreter
253356
(without calling :c:func:`Py_FinalizeEx` first). There is no return value; it is a
254357
fatal error if the initialization fails.
255358

359+
Use the :c:func:`Py_InitializeFromConfig` function to customize the
360+
:ref:`Python Initialization Configuration <init-config>`.
361+
256362
.. note::
257363
On Windows, changes the console mode from ``O_TEXT`` to ``O_BINARY``, which will
258364
also affect non-Python uses of the console using the C Runtime.
@@ -264,6 +370,9 @@ Initializing and finalizing the interpreter
264370
*initsigs* is ``0``, it skips initialization registration of signal handlers, which
265371
might be useful when Python is embedded.
266372
373+
Use the :c:func:`Py_InitializeFromConfig` function to customize the
374+
:ref:`Python Initialization Configuration <init-config>`.
375+
267376
268377
.. c:function:: int Py_IsInitialized()
269378

Doc/c-api/init_config.rst

Lines changed: 10 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -835,8 +835,10 @@ PyConfig
835835
836836
* Set :c:member:`~PyConfig.safe_path` to ``1``:
837837
don't prepend a potentially unsafe path to :data:`sys.path` at Python
838-
startup.
839-
* Set :c:member:`~PyConfig.use_environment` to ``0``.
838+
startup, such as the current directory, the script's directory or an
839+
empty string.
840+
* Set :c:member:`~PyConfig.use_environment` to ``0``: ignore ``PYTHON``
841+
environment variables.
840842
* Set :c:member:`~PyConfig.user_site_directory` to ``0``: don't add the user
841843
site directory to :data:`sys.path`.
842844
* Python REPL doesn't import :mod:`readline` nor enable default readline
@@ -846,7 +848,8 @@ PyConfig
846848
847849
Default: ``0`` in Python mode, ``1`` in isolated mode.
848850
849-
See also :c:member:`PyPreConfig.isolated`.
851+
See also the :ref:`Isolated Configuration <init-isolated-conf>` and
852+
:c:member:`PyPreConfig.isolated`.
850853
851854
.. c:member:: int legacy_windows_stdio
852855
@@ -1177,13 +1180,13 @@ PyConfig
11771180
imported, showing the place (filename or built-in module) from which
11781181
it is loaded.
11791182
1180-
If greater or equal to ``2``, print a message for each file that is checked
1181-
for when searching for a module. Also provides information on module
1182-
cleanup at exit.
1183+
If greater than or equal to ``2``, print a message for each file that is
1184+
checked for when searching for a module. Also provides information on
1185+
module cleanup at exit.
11831186
11841187
Incremented by the :option:`-v` command line option.
11851188
1186-
Set to the :envvar:`PYTHONVERBOSE` environment variable value.
1189+
Set by the :envvar:`PYTHONVERBOSE` environment variable value.
11871190
11881191
Default: ``0``.
11891192
Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
Deprecate global configuration variables, like
2+
:c:var:`Py_IgnoreEnvironmentFlag`, in the documentation: the
3+
:c:func:`Py_InitializeFromConfig` API should be instead. Patch by Victor
4+
Stinner.

0 commit comments

Comments
 (0)