Debian Codegraph @

Doc/c-api/init_config.rst

raw
1 .. highlight:: c
2
3 .. _init-config:
4
5 ***********************************
6 Python Initialization Configuration
7 ***********************************
8
9
10 .. _pyinitconfig_api:
11
12 PyInitConfig C API
13 ==================
14
15 .. versionadded:: 3.14
16
17 Python can be initialized with :c:func:`Py_InitializeFromInitConfig`.
18
19 The :c:func:`Py_RunMain` function can be used to write a customized Python
20 program.
21
22 See also :ref:`Initialization, Finalization, and Threads <initialization>`.
23
24 .. seealso::
25 :pep:`741` "Python Configuration C API".
26
27
28 Example
29 -------
30
31 Example of customized Python always running with the :ref:`Python Development
32 Mode <devmode>` enabled; return ``-1`` on error:
33
34 .. code-block:: c
35
36 int init_python(void)
37 {
38 PyInitConfig *config = PyInitConfig_Create();
39 if (config == NULL) {
40 printf("PYTHON INIT ERROR: memory allocation failed\n");
41 return -1;
42 }
43
44 // Enable the Python Development Mode
45 if (PyInitConfig_SetInt(config, "dev_mode", 1) < 0) {
46 goto error;
47 }
48
49 // Initialize Python with the configuration
50 if (Py_InitializeFromInitConfig(config) < 0) {
51 goto error;
52 }
53 PyInitConfig_Free(config);
54 return 0;
55
56 error:
57 {
58 // Display the error message.
59 //
60 // This uncommon braces style is used, because you cannot make
61 // goto targets point to variable declarations.
62 const char *err_msg;
63 (void)PyInitConfig_GetError(config, &err_msg);
64 printf("PYTHON INIT ERROR: %s\n", err_msg);
65 PyInitConfig_Free(config);
66 return -1;
67 }
68 }
69
70 Create Config
71 -------------
72
73 .. c:struct:: PyInitConfig
74
75 Opaque structure to configure the Python initialization.
76
77
78 .. c:function:: PyInitConfig* PyInitConfig_Create(void)
79
80 Create a new initialization configuration using :ref:`Isolated Configuration
81 <init-isolated-conf>` default values.
82
83 It must be freed by :c:func:`PyInitConfig_Free`.
84
85 Return ``NULL`` on memory allocation failure.
86
87
88 .. c:function:: void PyInitConfig_Free(PyInitConfig *config)
89
90 Free memory of the initialization configuration *config*.
91
92 If *config* is ``NULL``, no operation is performed.
93
94
95 Error Handling
96 --------------
97
98 .. c:function:: int PyInitConfig_GetError(PyInitConfig* config, const char **err_msg)
99
100 Get the *config* error message.
101
102 * Set *\*err_msg* and return ``1`` if an error is set.
103 * Set *\*err_msg* to ``NULL`` and return ``0`` otherwise.
104
105 An error message is a UTF-8 encoded string.
106
107 If *config* has an exit code, format the exit code as an error
108 message.
109
110 The error message remains valid until another ``PyInitConfig``
111 function is called with *config*. The caller doesn't have to free the
112 error message.
113
114
115 .. c:function:: int PyInitConfig_GetExitCode(PyInitConfig* config, int *exitcode)
116
117 Get the *config* exit code.
118
119 * Set *\*exitcode* and return ``1`` if *config* has an exit code set.
120 * Return ``0`` if *config* has no exit code set.
121
122 Only the ``Py_InitializeFromInitConfig()`` function can set an exit
123 code if the ``parse_argv`` option is non-zero.
124
125 An exit code can be set when parsing the command line failed (exit
126 code ``2``) or when a command line option asks to display the command
127 line help (exit code ``0``).
128
129
130 Get Options
131 -----------
132
133 The configuration option *name* parameter must be a non-NULL null-terminated
134 UTF-8 encoded string. See :ref:`Configuration Options <pyinitconfig-opts>`.
135
136 .. c:function:: int PyInitConfig_HasOption(PyInitConfig *config, const char *name)
137
138 Test if the configuration has an option called *name*.
139
140 Return ``1`` if the option exists, or return ``0`` otherwise.
141
142
143 .. c:function:: int PyInitConfig_GetInt(PyInitConfig *config, const char *name, int64_t *value)
144
145 Get an integer configuration option.
146
147 * Set *\*value*, and return ``0`` on success.
148 * Set an error in *config* and return ``-1`` on error.
149
150
151 .. c:function:: int PyInitConfig_GetStr(PyInitConfig *config, const char *name, char **value)
152
153 Get a string configuration option as a null-terminated UTF-8
154 encoded string.
155
156 * Set *\*value*, and return ``0`` on success.
157 * Set an error in *config* and return ``-1`` on error.
158
159 *\*value* can be set to ``NULL`` if the option is an optional string and the
160 option is unset.
161
162 On success, the string must be released with ``free(value)`` if it's not
163 ``NULL``.
164
165
166 .. c:function:: int PyInitConfig_GetStrList(PyInitConfig *config, const char *name, size_t *length, char ***items)
167
168 Get a string list configuration option as an array of
169 null-terminated UTF-8 encoded strings.
170
171 * Set *\*length* and *\*value*, and return ``0`` on success.
172 * Set an error in *config* and return ``-1`` on error.
173
174 On success, the string list must be released with
175 ``PyInitConfig_FreeStrList(length, items)``.
176
177
178 .. c:function:: void PyInitConfig_FreeStrList(size_t length, char **items)
179
180 Free memory of a string list created by
181 ``PyInitConfig_GetStrList()``.
182
183
184 Set Options
185 -----------
186
187 The configuration option *name* parameter must be a non-NULL null-terminated
188 UTF-8 encoded string. See :ref:`Configuration Options <pyinitconfig-opts>`.
189
190 Some configuration options have side effects on other options. This logic is
191 only implemented when ``Py_InitializeFromInitConfig()`` is called, not by the
192 "Set" functions below. For example, setting ``dev_mode`` to ``1`` does not set
193 ``faulthandler`` to ``1``.
194
195 .. c:function:: int PyInitConfig_SetInt(PyInitConfig *config, const char *name, int64_t value)
196
197 Set an integer configuration option.
198
199 * Return ``0`` on success.
200 * Set an error in *config* and return ``-1`` on error.
201
202
203 .. c:function:: int PyInitConfig_SetStr(PyInitConfig *config, const char *name, const char *value)
204
205 Set a string configuration option from a null-terminated UTF-8
206 encoded string. The string is copied.
207
208 * Return ``0`` on success.
209 * Set an error in *config* and return ``-1`` on error.
210
211
212 .. c:function:: int PyInitConfig_SetStrList(PyInitConfig *config, const char *name, size_t length, char * const *items)
213
214 Set a string list configuration option from an array of
215 null-terminated UTF-8 encoded strings. The string list is copied.
216
217 * Return ``0`` on success.
218 * Set an error in *config* and return ``-1`` on error.
219
220
221 Module
222 ------
223
224 .. c:function:: int PyInitConfig_AddModule(PyInitConfig *config, const char *name, PyObject* (*initfunc)(void))
225
226 Add a built-in extension module to the table of built-in modules.
227
228 The new module can be imported by the name *name*, and uses the function
229 *initfunc* as the initialization function called on the first attempted
230 import.
231
232 * Return ``0`` on success.
233 * Set an error in *config* and return ``-1`` on error.
234
235 If Python is initialized multiple times, ``PyInitConfig_AddModule()`` must
236 be called at each Python initialization.
237
238 Similar to the :c:func:`PyImport_AppendInittab` function.
239
240
241 Initialize Python
242 -----------------
243
244 .. c:function:: int Py_InitializeFromInitConfig(PyInitConfig *config)
245
246 Initialize Python from the initialization configuration.
247
248 * Return ``0`` on success.
249 * Set an error in *config* and return ``-1`` on error.
250 * Set an exit code in *config* and return ``-1`` if Python wants to
251 exit.
252
253 See ``PyInitConfig_GetExitcode()`` for the exit code case.
254
255
256 .. _pyinitconfig-opts:
257
258 Configuration Options
259 =====================
260
261 .. list-table::
262 :header-rows: 1
263
264 * - Option
265 - PyConfig/PyPreConfig member
266 - Type
267 - Visibility
268 * - ``"allocator"``
269 - :c:member:`allocator <PyPreConfig.allocator>`
270 - ``int``
271 - Read-only
272 * - ``"argv"``
273 - :c:member:`argv <PyConfig.argv>`
274 - ``list[str]``
275 - Public
276 * - ``"base_exec_prefix"``
277 - :c:member:`base_exec_prefix <PyConfig.base_exec_prefix>`
278 - ``str``
279 - Public
280 * - ``"base_executable"``
281 - :c:member:`base_executable <PyConfig.base_executable>`
282 - ``str``
283 - Public
284 * - ``"base_prefix"``
285 - :c:member:`base_prefix <PyConfig.base_prefix>`
286 - ``str``
287 - Public
288 * - ``"buffered_stdio"``
289 - :c:member:`buffered_stdio <PyConfig.buffered_stdio>`
290 - ``bool``
291 - Read-only
292 * - ``"bytes_warning"``
293 - :c:member:`bytes_warning <PyConfig.bytes_warning>`
294 - ``int``
295 - Public
296 * - ``"check_hash_pycs_mode"``
297 - :c:member:`check_hash_pycs_mode <PyConfig.check_hash_pycs_mode>`
298 - ``str``
299 - Read-only
300 * - ``"code_debug_ranges"``
301 - :c:member:`code_debug_ranges <PyConfig.code_debug_ranges>`
302 - ``bool``
303 - Read-only
304 * - ``"coerce_c_locale"``
305 - :c:member:`coerce_c_locale <PyPreConfig.coerce_c_locale>`
306 - ``bool``
307 - Read-only
308 * - ``"coerce_c_locale_warn"``
309 - :c:member:`coerce_c_locale_warn <PyPreConfig.coerce_c_locale_warn>`
310 - ``bool``
311 - Read-only
312 * - ``"configure_c_stdio"``
313 - :c:member:`configure_c_stdio <PyConfig.configure_c_stdio>`
314 - ``bool``
315 - Read-only
316 * - ``"configure_locale"``
317 - :c:member:`configure_locale <PyPreConfig.configure_locale>`
318 - ``bool``
319 - Read-only
320 * - ``"cpu_count"``
321 - :c:member:`cpu_count <PyConfig.cpu_count>`
322 - ``int``
323 - Public
324 * - ``"dev_mode"``
325 - :c:member:`dev_mode <PyConfig.dev_mode>`
326 - ``bool``
327 - Read-only
328 * - ``"dump_refs"``
329 - :c:member:`dump_refs <PyConfig.dump_refs>`
330 - ``bool``
331 - Read-only
332 * - ``"dump_refs_file"``
333 - :c:member:`dump_refs_file <PyConfig.dump_refs_file>`
334 - ``str``
335 - Read-only
336 * - ``"exec_prefix"``
337 - :c:member:`exec_prefix <PyConfig.exec_prefix>`
338 - ``str``
339 - Public
340 * - ``"executable"``
341 - :c:member:`executable <PyConfig.executable>`
342 - ``str``
343 - Public
344 * - ``"faulthandler"``
345 - :c:member:`faulthandler <PyConfig.faulthandler>`
346 - ``bool``
347 - Read-only
348 * - ``"filesystem_encoding"``
349 - :c:member:`filesystem_encoding <PyConfig.filesystem_encoding>`
350 - ``str``
351 - Read-only
352 * - ``"filesystem_errors"``
353 - :c:member:`filesystem_errors <PyConfig.filesystem_errors>`
354 - ``str``
355 - Read-only
356 * - ``"hash_seed"``
357 - :c:member:`hash_seed <PyConfig.hash_seed>`
358 - ``int``
359 - Read-only
360 * - ``"home"``
361 - :c:member:`home <PyConfig.home>`
362 - ``str``
363 - Read-only
364 * - ``"import_time"``
365 - :c:member:`import_time <PyConfig.import_time>`
366 - ``int``
367 - Read-only
368 * - ``"inspect"``
369 - :c:member:`inspect <PyConfig.inspect>`
370 - ``bool``
371 - Public
372 * - ``"install_signal_handlers"``
373 - :c:member:`install_signal_handlers <PyConfig.install_signal_handlers>`
374 - ``bool``
375 - Read-only
376 * - ``"int_max_str_digits"``
377 - :c:member:`int_max_str_digits <PyConfig.int_max_str_digits>`
378 - ``int``
379 - Public
380 * - ``"interactive"``
381 - :c:member:`interactive <PyConfig.interactive>`
382 - ``bool``
383 - Public
384 * - ``"isolated"``
385 - :c:member:`isolated <PyConfig.isolated>`
386 - ``bool``
387 - Read-only
388 * - ``"legacy_windows_fs_encoding"``
389 - :c:member:`legacy_windows_fs_encoding <PyPreConfig.legacy_windows_fs_encoding>`
390 - ``bool``
391 - Read-only
392 * - ``"legacy_windows_stdio"``
393 - :c:member:`legacy_windows_stdio <PyConfig.legacy_windows_stdio>`
394 - ``bool``
395 - Read-only
396 * - ``"malloc_stats"``
397 - :c:member:`malloc_stats <PyConfig.malloc_stats>`
398 - ``bool``
399 - Read-only
400 * - ``"module_search_paths"``
401 - :c:member:`module_search_paths <PyConfig.module_search_paths>`
402 - ``list[str]``
403 - Public
404 * - ``"optimization_level"``
405 - :c:member:`optimization_level <PyConfig.optimization_level>`
406 - ``int``
407 - Public
408 * - ``"orig_argv"``
409 - :c:member:`orig_argv <PyConfig.orig_argv>`
410 - ``list[str]``
411 - Read-only
412 * - ``"parse_argv"``
413 - :c:member:`parse_argv <PyConfig.parse_argv>`
414 - ``bool``
415 - Read-only
416 * - ``"parser_debug"``
417 - :c:member:`parser_debug <PyConfig.parser_debug>`
418 - ``bool``
419 - Public
420 * - ``"pathconfig_warnings"``
421 - :c:member:`pathconfig_warnings <PyConfig.pathconfig_warnings>`
422 - ``bool``
423 - Read-only
424 * - ``"perf_profiling"``
425 - :c:member:`perf_profiling <PyConfig.perf_profiling>`
426 - ``bool``
427 - Read-only
428 * - ``"platlibdir"``
429 - :c:member:`platlibdir <PyConfig.platlibdir>`
430 - ``str``
431 - Public
432 * - ``"prefix"``
433 - :c:member:`prefix <PyConfig.prefix>`
434 - ``str``
435 - Public
436 * - ``"program_name"``
437 - :c:member:`program_name <PyConfig.program_name>`
438 - ``str``
439 - Read-only
440 * - ``"pycache_prefix"``
441 - :c:member:`pycache_prefix <PyConfig.pycache_prefix>`
442 - ``str``
443 - Public
444 * - ``"quiet"``
445 - :c:member:`quiet <PyConfig.quiet>`
446 - ``bool``
447 - Public
448 * - ``"run_command"``
449 - :c:member:`run_command <PyConfig.run_command>`
450 - ``str``
451 - Read-only
452 * - ``"run_filename"``
453 - :c:member:`run_filename <PyConfig.run_filename>`
454 - ``str``
455 - Read-only
456 * - ``"run_module"``
457 - :c:member:`run_module <PyConfig.run_module>`
458 - ``str``
459 - Read-only
460 * - ``"run_presite"``
461 - :c:member:`run_presite <PyConfig.run_presite>`
462 - ``str``
463 - Read-only
464 * - ``"safe_path"``
465 - :c:member:`safe_path <PyConfig.safe_path>`
466 - ``bool``
467 - Read-only
468 * - ``"show_ref_count"``
469 - :c:member:`show_ref_count <PyConfig.show_ref_count>`
470 - ``bool``
471 - Read-only
472 * - ``"site_import"``
473 - :c:member:`site_import <PyConfig.site_import>`
474 - ``bool``
475 - Read-only
476 * - ``"skip_source_first_line"``
477 - :c:member:`skip_source_first_line <PyConfig.skip_source_first_line>`
478 - ``bool``
479 - Read-only
480 * - ``"stdio_encoding"``
481 - :c:member:`stdio_encoding <PyConfig.stdio_encoding>`
482 - ``str``
483 - Read-only
484 * - ``"stdio_errors"``
485 - :c:member:`stdio_errors <PyConfig.stdio_errors>`
486 - ``str``
487 - Read-only
488 * - ``"stdlib_dir"``
489 - :c:member:`stdlib_dir <PyConfig.stdlib_dir>`
490 - ``str``
491 - Public
492 * - ``"tracemalloc"``
493 - :c:member:`tracemalloc <PyConfig.tracemalloc>`
494 - ``int``
495 - Read-only
496 * - ``"use_environment"``
497 - :c:member:`use_environment <PyConfig.use_environment>`
498 - ``bool``
499 - Public
500 * - ``"use_frozen_modules"``
501 - :c:member:`use_frozen_modules <PyConfig.use_frozen_modules>`
502 - ``bool``
503 - Read-only
504 * - ``"use_hash_seed"``
505 - :c:member:`use_hash_seed <PyConfig.use_hash_seed>`
506 - ``bool``
507 - Read-only
508 * - ``"use_system_logger"``
509 - :c:member:`use_system_logger <PyConfig.use_system_logger>`
510 - ``bool``
511 - Read-only
512 * - ``"user_site_directory"``
513 - :c:member:`user_site_directory <PyConfig.user_site_directory>`
514 - ``bool``
515 - Read-only
516 * - ``"utf8_mode"``
517 - :c:member:`utf8_mode <PyPreConfig.utf8_mode>`
518 - ``bool``
519 - Read-only
520 * - ``"verbose"``
521 - :c:member:`verbose <PyConfig.verbose>`
522 - ``int``
523 - Public
524 * - ``"warn_default_encoding"``
525 - :c:member:`warn_default_encoding <PyConfig.warn_default_encoding>`
526 - ``bool``
527 - Read-only
528 * - ``"warnoptions"``
529 - :c:member:`warnoptions <PyConfig.warnoptions>`
530 - ``list[str]``
531 - Public
532 * - ``"write_bytecode"``
533 - :c:member:`write_bytecode <PyConfig.write_bytecode>`
534 - ``bool``
535 - Public
536 * - ``"xoptions"``
537 - :c:member:`xoptions <PyConfig.xoptions>`
538 - ``dict[str, str]``
539 - Public
540 * - ``"_pystats"``
541 - :c:member:`_pystats <PyConfig._pystats>`
542 - ``bool``
543 - Read-only
544
545 Visibility:
546
547 * Public: Can be retrieved by :c:func:`PyConfig_Get` and set by
548 :c:func:`PyConfig_Set`.
549 * Read-only: Can be retrieved by :c:func:`PyConfig_Get`, but cannot be set by
550 :c:func:`PyConfig_Set`.
551
552
553 Runtime Python configuration API
554 ================================
555
556 At runtime, it's possible to get and set configuration options using
557 :c:func:`PyConfig_Get` and :c:func:`PyConfig_Set` functions.
558
559 The configuration option *name* parameter must be a non-NULL null-terminated
560 UTF-8 encoded string. See :ref:`Configuration Options <pyinitconfig-opts>`.
561
562 Some options are read from the :mod:`sys` attributes. For example, the option
563 ``"argv"`` is read from :data:`sys.argv`.
564
565
566 .. c:function:: PyObject* PyConfig_Get(const char *name)
567
568 Get the current runtime value of a configuration option as a Python object.
569
570 * Return a new reference on success.
571 * Set an exception and return ``NULL`` on error.
572
573 The object type depends on the configuration option. It can be:
574
575 * ``bool``
576 * ``int``
577 * ``str``
578 * ``list[str]``
579 * ``dict[str, str]``
580
581 The caller must have an :term:`attached thread state`. The function cannot
582 be called before Python initialization nor after Python finalization.
583
584 .. versionadded:: 3.14
585
586
587 .. c:function:: int PyConfig_GetInt(const char *name, int *value)
588
589 Similar to :c:func:`PyConfig_Get`, but get the value as a C int.
590
591 * Return ``0`` on success.
592 * Set an exception and return ``-1`` on error.
593
594 .. versionadded:: 3.14
595
596
597 .. c:function:: PyObject* PyConfig_Names(void)
598
599 Get all configuration option names as a ``frozenset``.
600
601 * Return a new reference on success.
602 * Set an exception and return ``NULL`` on error.
603
604 The caller must have an :term:`attached thread state`. The function cannot
605 be called before Python initialization nor after Python finalization.
606
607 .. versionadded:: 3.14
608
609
610 .. c:function:: int PyConfig_Set(const char *name, PyObject *value)
611
612 Set the current runtime value of a configuration option.
613
614 * Raise a :exc:`ValueError` if there is no option *name*.
615 * Raise a :exc:`ValueError` if *value* is an invalid value.
616 * Raise a :exc:`ValueError` if the option is read-only (cannot be set).
617 * Raise a :exc:`TypeError` if *value* has not the proper type.
618
619 The caller must have an :term:`attached thread state`. The function cannot
620 be called before Python initialization nor after Python finalization.
621
622 .. audit-event:: cpython.PyConfig_Set name,value c.PyConfig_Set
623
624 .. versionadded:: 3.14
625
626
627 .. _pyconfig_api:
628
629 PyConfig C API
630 ==============
631
632 .. versionadded:: 3.8
633
634 Python can be initialized with :c:func:`Py_InitializeFromConfig` and the
635 :c:type:`PyConfig` structure. It can be preinitialized with
636 :c:func:`Py_PreInitialize` and the :c:type:`PyPreConfig` structure.
637
638 There are two kinds of configuration:
639
640 * The :ref:`Python Configuration <init-python-config>` can be used to build a
641 customized Python which behaves as the regular Python. For example,
642 environment variables and command line arguments are used to configure
643 Python.
644
645 * The :ref:`Isolated Configuration <init-isolated-conf>` can be used to embed
646 Python into an application. It isolates Python from the system. For example,
647 environment variables are ignored, the LC_CTYPE locale is left unchanged and
648 no signal handler is registered.
649
650 The :c:func:`Py_RunMain` function can be used to write a customized Python
651 program.
652
653 See also :ref:`Initialization, Finalization, and Threads <initialization>`.
654
655 .. seealso::
656 :pep:`587` "Python Initialization Configuration".
657
658
659 Example
660 -------
661
662 Example of customized Python always running in isolated mode::
663
664 int main(int argc, char **argv)
665 {
666 PyStatus status;
667
668 PyConfig config;
669 PyConfig_InitPythonConfig(&config);
670 config.isolated = 1;
671
672 /* Decode command line arguments.
673 Implicitly preinitialize Python (in isolated mode). */
674 status = PyConfig_SetBytesArgv(&config, argc, argv);
675 if (PyStatus_Exception(status)) {
676 goto exception;
677 }
678
679 status = Py_InitializeFromConfig(&config);
680 if (PyStatus_Exception(status)) {
681 goto exception;
682 }
683 PyConfig_Clear(&config);
684
685 return Py_RunMain();
686
687 exception:
688 PyConfig_Clear(&config);
689 if (PyStatus_IsExit(status)) {
690 return status.exitcode;
691 }
692 /* Display the error message and exit the process with
693 non-zero exit code */
694 Py_ExitStatusException(status);
695 }
696
697
698 PyWideStringList
699 ----------------
700
701 .. c:type:: PyWideStringList
702
703 List of ``wchar_t*`` strings.
704
705 If *length* is non-zero, *items* must be non-``NULL`` and all strings must be
706 non-``NULL``.
707
708 .. c:namespace:: NULL
709
710 Methods:
711
712 .. c:function:: PyStatus PyWideStringList_Append(PyWideStringList *list, const wchar_t *item)
713
714 Append *item* to *list*.
715
716 Python must be preinitialized to call this function.
717
718 .. c:function:: PyStatus PyWideStringList_Insert(PyWideStringList *list, Py_ssize_t index, const wchar_t *item)
719
720 Insert *item* into *list* at *index*.
721
722 If *index* is greater than or equal to *list* length, append *item* to
723 *list*.
724
725 *index* must be greater than or equal to ``0``.
726
727 Python must be preinitialized to call this function.
728
729 .. c:namespace:: PyWideStringList
730
731 Structure fields:
732
733 .. c:member:: Py_ssize_t length
734
735 List length.
736
737 .. c:member:: wchar_t** items
738
739 List items.
740
741 PyStatus
742 --------
743
744 .. c:type:: PyStatus
745
746 Structure to store an initialization function status: success, error
747 or exit.
748
749 For an error, it can store the C function name which created the error.
750
751 Structure fields:
752
753 .. c:member:: int exitcode
754
755 Exit code. Argument passed to ``exit()``.
756
757 .. c:member:: const char *err_msg
758
759 Error message.
760
761 .. c:member:: const char *func
762
763 Name of the function which created an error, can be ``NULL``.
764
765 .. c:namespace:: NULL
766
767 Functions to create a status:
768
769 .. c:function:: PyStatus PyStatus_Ok(void)
770
771 Success.
772
773 .. c:function:: PyStatus PyStatus_Error(const char *err_msg)
774
775 Initialization error with a message.
776
777 *err_msg* must not be ``NULL``.
778
779 .. c:function:: PyStatus PyStatus_NoMemory(void)
780
781 Memory allocation failure (out of memory).
782
783 .. c:function:: PyStatus PyStatus_Exit(int exitcode)
784
785 Exit Python with the specified exit code.
786
787 Functions to handle a status:
788
789 .. c:function:: int PyStatus_Exception(PyStatus status)
790
791 Is the status an error or an exit? If true, the exception must be
792 handled; by calling :c:func:`Py_ExitStatusException` for example.
793
794 .. c:function:: int PyStatus_IsError(PyStatus status)
795
796 Is the result an error?
797
798 .. c:function:: int PyStatus_IsExit(PyStatus status)
799
800 Is the result an exit?
801
802 .. c:function:: void Py_ExitStatusException(PyStatus status)
803
804 Call ``exit(exitcode)`` if *status* is an exit. Print the error
805 message and exit with a non-zero exit code if *status* is an error. Must
806 only be called if ``PyStatus_Exception(status)`` is non-zero.
807
808 .. note::
809 Internally, Python uses macros which set ``PyStatus.func``,
810 whereas functions to create a status set ``func`` to ``NULL``.
811
812 Example::
813
814 PyStatus alloc(void **ptr, size_t size)
815 {
816 *ptr = PyMem_RawMalloc(size);
817 if (*ptr == NULL) {
818 return PyStatus_NoMemory();
819 }
820 return PyStatus_Ok();
821 }
822
823 int main(int argc, char **argv)
824 {
825 void *ptr;
826 PyStatus status = alloc(&ptr, 16);
827 if (PyStatus_Exception(status)) {
828 Py_ExitStatusException(status);
829 }
830 PyMem_Free(ptr);
831 return 0;
832 }
833
834
835 PyPreConfig
836 -----------
837
838 .. c:type:: PyPreConfig
839
840 Structure used to preinitialize Python.
841
842 .. c:namespace:: NULL
843
844 Function to initialize a preconfiguration:
845
846 .. c:function:: void PyPreConfig_InitPythonConfig(PyPreConfig *preconfig)
847
848 Initialize the preconfiguration with :ref:`Python Configuration
849 <init-python-config>`.
850
851 .. c:function:: void PyPreConfig_InitIsolatedConfig(PyPreConfig *preconfig)
852
853 Initialize the preconfiguration with :ref:`Isolated Configuration
854 <init-isolated-conf>`.
855
856 .. c:namespace:: PyPreConfig
857
858 Structure fields:
859
860 .. c:member:: int allocator
861
862 Name of the Python memory allocators:
863
864 * ``PYMEM_ALLOCATOR_NOT_SET`` (``0``): don't change memory allocators
865 (use defaults).
866 * ``PYMEM_ALLOCATOR_DEFAULT`` (``1``): :ref:`default memory allocators
867 <default-memory-allocators>`.
868 * ``PYMEM_ALLOCATOR_DEBUG`` (``2``): :ref:`default memory allocators
869 <default-memory-allocators>` with :ref:`debug hooks
870 <pymem-debug-hooks>`.
871 * ``PYMEM_ALLOCATOR_MALLOC`` (``3``): use ``malloc()`` of the C library.
872 * ``PYMEM_ALLOCATOR_MALLOC_DEBUG`` (``4``): force usage of
873 ``malloc()`` with :ref:`debug hooks <pymem-debug-hooks>`.
874 * ``PYMEM_ALLOCATOR_PYMALLOC`` (``5``): :ref:`Python pymalloc memory
875 allocator <pymalloc>`.
876 * ``PYMEM_ALLOCATOR_PYMALLOC_DEBUG`` (``6``): :ref:`Python pymalloc
877 memory allocator <pymalloc>` with :ref:`debug hooks
878 <pymem-debug-hooks>`.
879 * ``PYMEM_ALLOCATOR_MIMALLOC`` (``6``): use ``mimalloc``, a fast
880 malloc replacement.
881 * ``PYMEM_ALLOCATOR_MIMALLOC_DEBUG`` (``7``): use ``mimalloc``, a fast
882 malloc replacement with :ref:`debug hooks <pymem-debug-hooks>`.
883
884
885 ``PYMEM_ALLOCATOR_PYMALLOC`` and ``PYMEM_ALLOCATOR_PYMALLOC_DEBUG`` are
886 not supported if Python is :option:`configured using --without-pymalloc
887 <--without-pymalloc>`.
888
889 ``PYMEM_ALLOCATOR_MIMALLOC`` and ``PYMEM_ALLOCATOR_MIMALLOC_DEBUG`` are
890 not supported if Python is :option:`configured using --without-mimalloc
891 <--without-mimalloc>` or if the underlying atomic support isn't
892 available.
893
894 See :ref:`Memory Management <memory>`.
895
896 Default: ``PYMEM_ALLOCATOR_NOT_SET``.
897
898 .. c:member:: int configure_locale
899
900 Set the LC_CTYPE locale to the user preferred locale.
901
902 If equals to ``0``, set :c:member:`~PyPreConfig.coerce_c_locale` and
903 :c:member:`~PyPreConfig.coerce_c_locale_warn` members to ``0``.
904
905 See the :term:`locale encoding`.
906
907 Default: ``1`` in Python config, ``0`` in isolated config.
908
909 .. c:member:: int coerce_c_locale
910
911 If equals to ``2``, coerce the C locale.
912
913 If equals to ``1``, read the LC_CTYPE locale to decide if it should be
914 coerced.
915
916 See the :term:`locale encoding`.
917
918 Default: ``-1`` in Python config, ``0`` in isolated config.
919
920 .. c:member:: int coerce_c_locale_warn
921
922 If non-zero, emit a warning if the C locale is coerced.
923
924 Default: ``-1`` in Python config, ``0`` in isolated config.
925
926 .. c:member:: int dev_mode
927
928 :ref:`Python Development Mode <devmode>`: see
929 :c:member:`PyConfig.dev_mode`.
930
931 Default: ``-1`` in Python mode, ``0`` in isolated mode.
932
933 .. c:member:: int isolated
934
935 Isolated mode: see :c:member:`PyConfig.isolated`.
936
937 Default: ``0`` in Python mode, ``1`` in isolated mode.
938
939 .. c:member:: int legacy_windows_fs_encoding
940
941 If non-zero:
942
943 * Set :c:member:`PyPreConfig.utf8_mode` to ``0``,
944 * Set :c:member:`PyConfig.filesystem_encoding` to ``"mbcs"``,
945 * Set :c:member:`PyConfig.filesystem_errors` to ``"replace"``.
946
947 Initialized from the :envvar:`PYTHONLEGACYWINDOWSFSENCODING` environment
948 variable value.
949
950 Only available on Windows. ``#ifdef MS_WINDOWS`` macro can be used for
951 Windows specific code.
952
953 Default: ``0``.
954
955 .. c:member:: int parse_argv
956
957 If non-zero, :c:func:`Py_PreInitializeFromArgs` and
958 :c:func:`Py_PreInitializeFromBytesArgs` parse their ``argv`` argument the
959 same way the regular Python parses command line arguments: see
960 :ref:`Command Line Arguments <using-on-cmdline>`.
961
962 Default: ``1`` in Python config, ``0`` in isolated config.
963
964 .. c:member:: int use_environment
965
966 Use :ref:`environment variables <using-on-envvars>`? See
967 :c:member:`PyConfig.use_environment`.
968
969 Default: ``1`` in Python config and ``0`` in isolated config.
970
971 .. c:member:: int utf8_mode
972
973 If non-zero, enable the :ref:`Python UTF-8 Mode <utf8-mode>`.
974
975 Set to ``0`` or ``1`` by the :option:`-X utf8 <-X>` command line option
976 and the :envvar:`PYTHONUTF8` environment variable.
977
978 Also set to ``1`` if the ``LC_CTYPE`` locale is ``C`` or ``POSIX``.
979
980 Default: ``-1`` in Python config and ``0`` in isolated config.
981
982
983 .. _c-preinit:
984
985 Preinitialize Python with PyPreConfig
986 -------------------------------------
987
988 The preinitialization of Python:
989
990 * Set the Python memory allocators (:c:member:`PyPreConfig.allocator`)
991 * Configure the LC_CTYPE locale (:term:`locale encoding`)
992 * Set the :ref:`Python UTF-8 Mode <utf8-mode>`
993 (:c:member:`PyPreConfig.utf8_mode`)
994
995 The current preconfiguration (``PyPreConfig`` type) is stored in
996 ``_PyRuntime.preconfig``.
997
998 Functions to preinitialize Python:
999
1000 .. c:function:: PyStatus Py_PreInitialize(const PyPreConfig *preconfig)
1001
1002 Preinitialize Python from *preconfig* preconfiguration.
1003
1004 *preconfig* must not be ``NULL``.
1005
1006 .. c:function:: PyStatus Py_PreInitializeFromBytesArgs(const PyPreConfig *preconfig, int argc, char * const *argv)
1007
1008 Preinitialize Python from *preconfig* preconfiguration.
1009
1010 Parse *argv* command line arguments (bytes strings) if
1011 :c:member:`~PyPreConfig.parse_argv` of *preconfig* is non-zero.
1012
1013 *preconfig* must not be ``NULL``.
1014
1015 .. c:function:: PyStatus Py_PreInitializeFromArgs(const PyPreConfig *preconfig, int argc, wchar_t * const * argv)
1016
1017 Preinitialize Python from *preconfig* preconfiguration.
1018
1019 Parse *argv* command line arguments (wide strings) if
1020 :c:member:`~PyPreConfig.parse_argv` of *preconfig* is non-zero.
1021
1022 *preconfig* must not be ``NULL``.
1023
1024 The caller is responsible to handle exceptions (error or exit) using
1025 :c:func:`PyStatus_Exception` and :c:func:`Py_ExitStatusException`.
1026
1027 For :ref:`Python Configuration <init-python-config>`
1028 (:c:func:`PyPreConfig_InitPythonConfig`), if Python is initialized with
1029 command line arguments, the command line arguments must also be passed to
1030 preinitialize Python, since they have an effect on the pre-configuration
1031 like encodings. For example, the :option:`-X utf8 <-X>` command line option
1032 enables the :ref:`Python UTF-8 Mode <utf8-mode>`.
1033
1034 ``PyMem_SetAllocator()`` can be called after :c:func:`Py_PreInitialize` and
1035 before :c:func:`Py_InitializeFromConfig` to install a custom memory allocator.
1036 It can be called before :c:func:`Py_PreInitialize` if
1037 :c:member:`PyPreConfig.allocator` is set to ``PYMEM_ALLOCATOR_NOT_SET``.
1038
1039 Python memory allocation functions like :c:func:`PyMem_RawMalloc` must not be
1040 used before the Python preinitialization, whereas calling directly ``malloc()``
1041 and ``free()`` is always safe. :c:func:`Py_DecodeLocale` must not be called
1042 before the Python preinitialization.
1043
1044 Example using the preinitialization to enable
1045 the :ref:`Python UTF-8 Mode <utf8-mode>`::
1046
1047 PyStatus status;
1048 PyPreConfig preconfig;
1049 PyPreConfig_InitPythonConfig(&preconfig);
1050
1051 preconfig.utf8_mode = 1;
1052
1053 status = Py_PreInitialize(&preconfig);
1054 if (PyStatus_Exception(status)) {
1055 Py_ExitStatusException(status);
1056 }
1057
1058 /* at this point, Python speaks UTF-8 */
1059
1060 Py_Initialize();
1061 /* ... use Python API here ... */
1062 Py_Finalize();
1063
1064
1065 PyConfig
1066 --------
1067
1068 .. c:type:: PyConfig
1069
1070 Structure containing most parameters to configure Python.
1071
1072 When done, the :c:func:`PyConfig_Clear` function must be used to release the
1073 configuration memory.
1074
1075 .. c:namespace:: NULL
1076
1077 Structure methods:
1078
1079 .. c:function:: void PyConfig_InitPythonConfig(PyConfig *config)
1080
1081 Initialize configuration with the :ref:`Python Configuration
1082 <init-python-config>`.
1083
1084 .. c:function:: void PyConfig_InitIsolatedConfig(PyConfig *config)
1085
1086 Initialize configuration with the :ref:`Isolated Configuration
1087 <init-isolated-conf>`.
1088
1089 .. c:function:: PyStatus PyConfig_SetString(PyConfig *config, wchar_t * const *config_str, const wchar_t *str)
1090
1091 Copy the wide character string *str* into ``*config_str``.
1092
1093 :ref:`Preinitialize Python <c-preinit>` if needed.
1094
1095 .. c:function:: PyStatus PyConfig_SetBytesString(PyConfig *config, wchar_t * const *config_str, const char *str)
1096
1097 Decode *str* using :c:func:`Py_DecodeLocale` and set the result into
1098 ``*config_str``.
1099
1100 :ref:`Preinitialize Python <c-preinit>` if needed.
1101
1102 .. c:function:: PyStatus PyConfig_SetArgv(PyConfig *config, int argc, wchar_t * const *argv)
1103
1104 Set command line arguments (:c:member:`~PyConfig.argv` member of
1105 *config*) from the *argv* list of wide character strings.
1106
1107 :ref:`Preinitialize Python <c-preinit>` if needed.
1108
1109 .. c:function:: PyStatus PyConfig_SetBytesArgv(PyConfig *config, int argc, char * const *argv)
1110
1111 Set command line arguments (:c:member:`~PyConfig.argv` member of
1112 *config*) from the *argv* list of bytes strings. Decode bytes using
1113 :c:func:`Py_DecodeLocale`.
1114
1115 :ref:`Preinitialize Python <c-preinit>` if needed.
1116
1117 .. c:function:: PyStatus PyConfig_SetWideStringList(PyConfig *config, PyWideStringList *list, Py_ssize_t length, wchar_t **items)
1118
1119 Set the list of wide strings *list* to *length* and *items*.
1120
1121 :ref:`Preinitialize Python <c-preinit>` if needed.
1122
1123 .. c:function:: PyStatus PyConfig_Read(PyConfig *config)
1124
1125 Read all Python configuration.
1126
1127 Fields which are already initialized are left unchanged.
1128
1129 Fields for :ref:`path configuration <init-path-config>` are no longer
1130 calculated or modified when calling this function, as of Python 3.11.
1131
1132 The :c:func:`PyConfig_Read` function only parses
1133 :c:member:`PyConfig.argv` arguments once: :c:member:`PyConfig.parse_argv`
1134 is set to ``2`` after arguments are parsed. Since Python arguments are
1135 stripped from :c:member:`PyConfig.argv`, parsing arguments twice would
1136 parse the application options as Python options.
1137
1138 :ref:`Preinitialize Python <c-preinit>` if needed.
1139
1140 .. versionchanged:: 3.10
1141 The :c:member:`PyConfig.argv` arguments are now only parsed once,
1142 :c:member:`PyConfig.parse_argv` is set to ``2`` after arguments are
1143 parsed, and arguments are only parsed if
1144 :c:member:`PyConfig.parse_argv` equals ``1``.
1145
1146 .. versionchanged:: 3.11
1147 :c:func:`PyConfig_Read` no longer calculates all paths, and so fields
1148 listed under :ref:`Python Path Configuration <init-path-config>` may
1149 no longer be updated until :c:func:`Py_InitializeFromConfig` is
1150 called.
1151
1152 .. c:function:: void PyConfig_Clear(PyConfig *config)
1153
1154 Release configuration memory.
1155
1156 Most ``PyConfig`` methods :ref:`preinitialize Python <c-preinit>` if needed.
1157 In that case, the Python preinitialization configuration
1158 (:c:type:`PyPreConfig`) is based on the :c:type:`PyConfig`. If configuration
1159 fields which are in common with :c:type:`PyPreConfig` are tuned, they must
1160 be set before calling a :c:type:`PyConfig` method:
1161
1162 * :c:member:`PyConfig.dev_mode`
1163 * :c:member:`PyConfig.isolated`
1164 * :c:member:`PyConfig.parse_argv`
1165 * :c:member:`PyConfig.use_environment`
1166
1167 Moreover, if :c:func:`PyConfig_SetArgv` or :c:func:`PyConfig_SetBytesArgv`
1168 is used, this method must be called before other methods, since the
1169 preinitialization configuration depends on command line arguments (if
1170 :c:member:`~PyConfig.parse_argv` is non-zero).
1171
1172 The caller of these methods is responsible to handle exceptions (error or
1173 exit) using ``PyStatus_Exception()`` and ``Py_ExitStatusException()``.
1174
1175 .. c:namespace:: PyConfig
1176
1177 Structure fields:
1178
1179 .. c:member:: PyWideStringList argv
1180
1181 .. index::
1182 single: main()
1183 single: argv (in module sys)
1184
1185 Set :data:`sys.argv` command line arguments based on
1186 :c:member:`~PyConfig.argv`. These parameters are similar to those passed
1187 to the program's :c:func:`main` function with the difference that the
1188 first entry should refer to the script file to be executed rather than
1189 the executable hosting the Python interpreter. If there isn't a script
1190 that will be run, the first entry in :c:member:`~PyConfig.argv` can be an
1191 empty string.
1192
1193 Set :c:member:`~PyConfig.parse_argv` to ``1`` to parse
1194 :c:member:`~PyConfig.argv` the same way the regular Python parses Python
1195 command line arguments and then to strip Python arguments from
1196 :c:member:`~PyConfig.argv`.
1197
1198 If :c:member:`~PyConfig.argv` is empty, an empty string is added to
1199 ensure that :data:`sys.argv` always exists and is never empty.
1200
1201 Default: ``NULL``.
1202
1203 See also the :c:member:`~PyConfig.orig_argv` member.
1204
1205 .. c:member:: int safe_path
1206
1207 If equals to zero, ``Py_RunMain()`` prepends a potentially unsafe path to
1208 :data:`sys.path` at startup:
1209
1210 * If :c:member:`argv[0] <PyConfig.argv>` is equal to ``L"-m"``
1211 (``python -m module``), prepend the current working directory.
1212 * If running a script (``python script.py``), prepend the script's
1213 directory. If it's a symbolic link, resolve symbolic links.
1214 * Otherwise (``python -c code`` and ``python``), prepend an empty string,
1215 which means the current working directory.
1216
1217 Set to ``1`` by the :option:`-P` command line option and the
1218 :envvar:`PYTHONSAFEPATH` environment variable.
1219
1220 Default: ``0`` in Python config, ``1`` in isolated config.
1221
1222 .. versionadded:: 3.11
1223
1224 .. c:member:: wchar_t* base_exec_prefix
1225
1226 :data:`sys.base_exec_prefix`.
1227
1228 Default: ``NULL``.
1229
1230 Part of the :ref:`Python Path Configuration <init-path-config>` output.
1231
1232 See also :c:member:`PyConfig.exec_prefix`.
1233
1234 .. c:member:: wchar_t* base_executable
1235
1236 Python base executable: :data:`sys._base_executable`.
1237
1238 Set by the :envvar:`__PYVENV_LAUNCHER__` environment variable.
1239
1240 Set from :c:member:`PyConfig.executable` if ``NULL``.
1241
1242 Default: ``NULL``.
1243
1244 Part of the :ref:`Python Path Configuration <init-path-config>` output.
1245
1246 See also :c:member:`PyConfig.executable`.
1247
1248 .. c:member:: wchar_t* base_prefix
1249
1250 :data:`sys.base_prefix`.
1251
1252 Default: ``NULL``.
1253
1254 Part of the :ref:`Python Path Configuration <init-path-config>` output.
1255
1256 See also :c:member:`PyConfig.prefix`.
1257
1258 .. c:member:: int buffered_stdio
1259
1260 If equals to ``0`` and :c:member:`~PyConfig.configure_c_stdio` is non-zero,
1261 disable buffering on the C streams stdout and stderr.
1262
1263 Set to ``0`` by the :option:`-u` command line option and the
1264 :envvar:`PYTHONUNBUFFERED` environment variable.
1265
1266 stdin is always opened in buffered mode.
1267
1268 Default: ``1``.
1269
1270 .. c:member:: int bytes_warning
1271
1272 If equals to ``1``, issue a warning when comparing :class:`bytes` or
1273 :class:`bytearray` with :class:`str`, or comparing :class:`bytes` with
1274 :class:`int`.
1275
1276 If equal or greater to ``2``, raise a :exc:`BytesWarning` exception in these
1277 cases.
1278
1279 Incremented by the :option:`-b` command line option.
1280
1281 Default: ``0``.
1282
1283 .. c:member:: int warn_default_encoding
1284
1285 If non-zero, emit a :exc:`EncodingWarning` warning when :class:`io.TextIOWrapper`
1286 uses its default encoding. See :ref:`io-encoding-warning` for details.
1287
1288 Default: ``0``.
1289
1290 .. versionadded:: 3.10
1291
1292 .. c:member:: int code_debug_ranges
1293
1294 If equals to ``0``, disables the inclusion of the end line and column
1295 mappings in code objects. Also disables traceback printing carets to
1296 specific error locations.
1297
1298 Set to ``0`` by the :envvar:`PYTHONNODEBUGRANGES` environment variable
1299 and by the :option:`-X no_debug_ranges <-X>` command line option.
1300
1301 Default: ``1``.
1302
1303 .. versionadded:: 3.11
1304
1305 .. c:member:: wchar_t* check_hash_pycs_mode
1306
1307 Control the validation behavior of hash-based ``.pyc`` files:
1308 value of the :option:`--check-hash-based-pycs` command line option.
1309
1310 Valid values:
1311
1312 - ``L"always"``: Hash the source file for invalidation regardless of
1313 value of the 'check_source' flag.
1314 - ``L"never"``: Assume that hash-based pycs always are valid.
1315 - ``L"default"``: The 'check_source' flag in hash-based pycs
1316 determines invalidation.
1317
1318 Default: ``L"default"``.
1319
1320 See also :pep:`552` "Deterministic pycs".
1321
1322 .. c:member:: int configure_c_stdio
1323
1324 If non-zero, configure C standard streams:
1325
1326 * On Windows, set the binary mode (``O_BINARY``) on stdin, stdout and
1327 stderr.
1328 * If :c:member:`~PyConfig.buffered_stdio` equals zero, disable buffering
1329 of stdin, stdout and stderr streams.
1330 * If :c:member:`~PyConfig.interactive` is non-zero, enable stream
1331 buffering on stdin and stdout (only stdout on Windows).
1332
1333 Default: ``1`` in Python config, ``0`` in isolated config.
1334
1335 .. c:member:: int dev_mode
1336
1337 If non-zero, enable the :ref:`Python Development Mode <devmode>`.
1338
1339 Set to ``1`` by the :option:`-X dev <-X>` option and the
1340 :envvar:`PYTHONDEVMODE` environment variable.
1341
1342 Default: ``-1`` in Python mode, ``0`` in isolated mode.
1343
1344 .. c:member:: int dump_refs
1345
1346 Dump Python references?
1347
1348 If non-zero, dump all objects which are still alive at exit.
1349
1350 Set to ``1`` by the :envvar:`PYTHONDUMPREFS` environment variable.
1351
1352 Needs a special build of Python with the ``Py_TRACE_REFS`` macro defined:
1353 see the :option:`configure --with-trace-refs option <--with-trace-refs>`.
1354
1355 Default: ``0``.
1356
1357 .. c:member:: wchar_t* dump_refs_file
1358
1359 Filename where to dump Python references.
1360
1361 Set by the :envvar:`PYTHONDUMPREFSFILE` environment variable.
1362
1363 Default: ``NULL``.
1364
1365 .. versionadded:: 3.11
1366
1367 .. c:member:: wchar_t* exec_prefix
1368
1369 The site-specific directory prefix where the platform-dependent Python
1370 files are installed: :data:`sys.exec_prefix`.
1371
1372 Default: ``NULL``.
1373
1374 Part of the :ref:`Python Path Configuration <init-path-config>` output.
1375
1376 See also :c:member:`PyConfig.base_exec_prefix`.
1377
1378 .. c:member:: wchar_t* executable
1379
1380 The absolute path of the executable binary for the Python interpreter:
1381 :data:`sys.executable`.
1382
1383 Default: ``NULL``.
1384
1385 Part of the :ref:`Python Path Configuration <init-path-config>` output.
1386
1387 See also :c:member:`PyConfig.base_executable`.
1388
1389 .. c:member:: int faulthandler
1390
1391 Enable faulthandler?
1392
1393 If non-zero, call :func:`faulthandler.enable` at startup.
1394
1395 Set to ``1`` by :option:`-X faulthandler <-X>` and the
1396 :envvar:`PYTHONFAULTHANDLER` environment variable.
1397
1398 Default: ``-1`` in Python mode, ``0`` in isolated mode.
1399
1400 .. c:member:: wchar_t* filesystem_encoding
1401
1402 :term:`Filesystem encoding <filesystem encoding and error handler>`:
1403 :func:`sys.getfilesystemencoding`.
1404
1405 On macOS, Android and VxWorks: use ``"utf-8"`` by default.
1406
1407 On Windows: use ``"utf-8"`` by default, or ``"mbcs"`` if
1408 :c:member:`~PyPreConfig.legacy_windows_fs_encoding` of
1409 :c:type:`PyPreConfig` is non-zero.
1410
1411 Default encoding on other platforms:
1412
1413 * ``"utf-8"`` if :c:member:`PyPreConfig.utf8_mode` is non-zero.
1414 * ``"ascii"`` if Python detects that ``nl_langinfo(CODESET)`` announces
1415 the ASCII encoding, whereas the ``mbstowcs()`` function
1416 decodes from a different encoding (usually Latin1).
1417 * ``"utf-8"`` if ``nl_langinfo(CODESET)`` returns an empty string.
1418 * Otherwise, use the :term:`locale encoding`:
1419 ``nl_langinfo(CODESET)`` result.
1420
1421 At Python startup, the encoding name is normalized to the Python codec
1422 name. For example, ``"ANSI_X3.4-1968"`` is replaced with ``"ascii"``.
1423
1424 See also the :c:member:`~PyConfig.filesystem_errors` member.
1425
1426 .. c:member:: wchar_t* filesystem_errors
1427
1428 :term:`Filesystem error handler <filesystem encoding and error handler>`:
1429 :func:`sys.getfilesystemencodeerrors`.
1430
1431 On Windows: use ``"surrogatepass"`` by default, or ``"replace"`` if
1432 :c:member:`~PyPreConfig.legacy_windows_fs_encoding` of
1433 :c:type:`PyPreConfig` is non-zero.
1434
1435 On other platforms: use ``"surrogateescape"`` by default.
1436
1437 Supported error handlers:
1438
1439 * ``"strict"``
1440 * ``"surrogateescape"``
1441 * ``"surrogatepass"`` (only supported with the UTF-8 encoding)
1442
1443 See also the :c:member:`~PyConfig.filesystem_encoding` member.
1444
1445 .. c:member:: int use_frozen_modules
1446
1447 If non-zero, use frozen modules.
1448
1449 Set by the :envvar:`PYTHON_FROZEN_MODULES` environment variable.
1450
1451 Default: ``1`` in a release build, or ``0`` in a :ref:`debug build
1452 <debug-build>`.
1453
1454 .. c:member:: unsigned long hash_seed
1455 .. c:member:: int use_hash_seed
1456
1457 Randomized hash function seed.
1458
1459 If :c:member:`~PyConfig.use_hash_seed` is zero, a seed is chosen randomly
1460 at Python startup, and :c:member:`~PyConfig.hash_seed` is ignored.
1461
1462 Set by the :envvar:`PYTHONHASHSEED` environment variable.
1463
1464 Default *use_hash_seed* value: ``-1`` in Python mode, ``0`` in isolated
1465 mode.
1466
1467 .. c:member:: wchar_t* home
1468
1469 Set the default Python "home" directory, that is, the location of the
1470 standard Python libraries (see :envvar:`PYTHONHOME`).
1471
1472 Set by the :envvar:`PYTHONHOME` environment variable.
1473
1474 Default: ``NULL``.
1475
1476 Part of the :ref:`Python Path Configuration <init-path-config>` input.
1477
1478 .. c:member:: int import_time
1479
1480 If ``1``, profile import time.
1481 If ``2``, include additional output that indicates
1482 when an imported module has already been loaded.
1483
1484 Set by the :option:`-X importtime <-X>` option and the
1485 :envvar:`PYTHONPROFILEIMPORTTIME` environment variable.
1486
1487 Default: ``0``.
1488
1489 .. versionchanged:: 3.14
1490
1491 Added support for ``import_time = 2``
1492
1493 .. c:member:: int inspect
1494
1495 Enter interactive mode after executing a script or a command.
1496
1497 If greater than ``0``, enable inspect: when a script is passed as first
1498 argument or the -c option is used, enter interactive mode after executing
1499 the script or the command, even when :data:`sys.stdin` does not appear to
1500 be a terminal.
1501
1502 Incremented by the :option:`-i` command line option. Set to ``1`` if the
1503 :envvar:`PYTHONINSPECT` environment variable is non-empty.
1504
1505 Default: ``0``.
1506
1507 .. c:member:: int install_signal_handlers
1508
1509 Install Python signal handlers?
1510
1511 Default: ``1`` in Python mode, ``0`` in isolated mode.
1512
1513 .. c:member:: int interactive
1514
1515 If greater than ``0``, enable the interactive mode (REPL).
1516
1517 Incremented by the :option:`-i` command line option.
1518
1519 Default: ``0``.
1520
1521 .. c:member:: int int_max_str_digits
1522
1523 Configures the :ref:`integer string conversion length limitation
1524 <int_max_str_digits>`. An initial value of ``-1`` means the value will
1525 be taken from the command line or environment or otherwise default to
1526 4300 (:data:`sys.int_info.default_max_str_digits`). A value of ``0``
1527 disables the limitation. Values greater than zero but less than 640
1528 (:data:`sys.int_info.str_digits_check_threshold`) are unsupported and
1529 will produce an error.
1530
1531 Configured by the :option:`-X int_max_str_digits <-X>` command line
1532 flag or the :envvar:`PYTHONINTMAXSTRDIGITS` environment variable.
1533
1534 Default: ``-1`` in Python mode. 4300
1535 (:data:`sys.int_info.default_max_str_digits`) in isolated mode.
1536
1537 .. versionadded:: 3.12
1538
1539 .. c:member:: int cpu_count
1540
1541 If the value of :c:member:`~PyConfig.cpu_count` is not ``-1`` then it will
1542 override the return values of :func:`os.cpu_count`,
1543 :func:`os.process_cpu_count`, and :func:`multiprocessing.cpu_count`.
1544
1545 Configured by the :samp:`-X cpu_count={n|default}` command line
1546 flag or the :envvar:`PYTHON_CPU_COUNT` environment variable.
1547
1548 Default: ``-1``.
1549
1550 .. versionadded:: 3.13
1551
1552 .. c:member:: int isolated
1553
1554 If greater than ``0``, enable isolated mode:
1555
1556 * Set :c:member:`~PyConfig.safe_path` to ``1``:
1557 don't prepend a potentially unsafe path to :data:`sys.path` at Python
1558 startup, such as the current directory, the script's directory or an
1559 empty string.
1560 * Set :c:member:`~PyConfig.use_environment` to ``0``: ignore ``PYTHON``
1561 environment variables.
1562 * Set :c:member:`~PyConfig.user_site_directory` to ``0``: don't add the user
1563 site directory to :data:`sys.path`.
1564 * Python REPL doesn't import :mod:`readline` nor enable default readline
1565 configuration on interactive prompts.
1566
1567 Set to ``1`` by the :option:`-I` command line option.
1568
1569 Default: ``0`` in Python mode, ``1`` in isolated mode.
1570
1571 See also the :ref:`Isolated Configuration <init-isolated-conf>` and
1572 :c:member:`PyPreConfig.isolated`.
1573
1574 .. c:member:: int legacy_windows_stdio
1575
1576 If non-zero, use :class:`io.FileIO` instead of
1577 :class:`!io._WindowsConsoleIO` for :data:`sys.stdin`, :data:`sys.stdout`
1578 and :data:`sys.stderr`.
1579
1580 Set to ``1`` if the :envvar:`PYTHONLEGACYWINDOWSSTDIO` environment
1581 variable is set to a non-empty string.
1582
1583 Only available on Windows. ``#ifdef MS_WINDOWS`` macro can be used for
1584 Windows specific code.
1585
1586 Default: ``0``.
1587
1588 See also the :pep:`528` (Change Windows console encoding to UTF-8).
1589
1590 .. c:member:: int malloc_stats
1591
1592 If non-zero, dump statistics on :ref:`Python pymalloc memory allocator
1593 <pymalloc>` at exit.
1594
1595 Set to ``1`` by the :envvar:`PYTHONMALLOCSTATS` environment variable.
1596
1597 The option is ignored if Python is :option:`configured using
1598 the --without-pymalloc option <--without-pymalloc>`.
1599
1600 Default: ``0``.
1601
1602 .. c:member:: wchar_t* platlibdir
1603
1604 Platform library directory name: :data:`sys.platlibdir`.
1605
1606 Set by the :envvar:`PYTHONPLATLIBDIR` environment variable.
1607
1608 Default: value of the ``PLATLIBDIR`` macro which is set by the
1609 :option:`configure --with-platlibdir option <--with-platlibdir>`
1610 (default: ``"lib"``, or ``"DLLs"`` on Windows).
1611
1612 Part of the :ref:`Python Path Configuration <init-path-config>` input.
1613
1614 .. versionadded:: 3.9
1615
1616 .. versionchanged:: 3.11
1617 This macro is now used on Windows to locate the standard
1618 library extension modules, typically under ``DLLs``. However,
1619 for compatibility, note that this value is ignored for any
1620 non-standard layouts, including in-tree builds and virtual
1621 environments.
1622
1623 .. c:member:: wchar_t* pythonpath_env
1624
1625 Module search paths (:data:`sys.path`) as a string separated by ``DELIM``
1626 (:data:`os.pathsep`).
1627
1628 Set by the :envvar:`PYTHONPATH` environment variable.
1629
1630 Default: ``NULL``.
1631
1632 Part of the :ref:`Python Path Configuration <init-path-config>` input.
1633
1634 .. c:member:: PyWideStringList module_search_paths
1635 .. c:member:: int module_search_paths_set
1636
1637 Module search paths: :data:`sys.path`.
1638
1639 If :c:member:`~PyConfig.module_search_paths_set` is equal to ``0``,
1640 :c:func:`Py_InitializeFromConfig` will replace
1641 :c:member:`~PyConfig.module_search_paths` and sets
1642 :c:member:`~PyConfig.module_search_paths_set` to ``1``.
1643
1644 Default: empty list (``module_search_paths``) and ``0``
1645 (``module_search_paths_set``).
1646
1647 Part of the :ref:`Python Path Configuration <init-path-config>` output.
1648
1649 .. c:member:: int optimization_level
1650
1651 Compilation optimization level:
1652
1653 * ``0``: Peephole optimizer, set ``__debug__`` to ``True``.
1654 * ``1``: Level 0, remove assertions, set ``__debug__`` to ``False``.
1655 * ``2``: Level 1, strip docstrings.
1656
1657 Incremented by the :option:`-O` command line option. Set to the
1658 :envvar:`PYTHONOPTIMIZE` environment variable value.
1659
1660 Default: ``0``.
1661
1662 .. c:member:: PyWideStringList orig_argv
1663
1664 The list of the original command line arguments passed to the Python
1665 executable: :data:`sys.orig_argv`.
1666
1667 If :c:member:`~PyConfig.orig_argv` list is empty and
1668 :c:member:`~PyConfig.argv` is not a list only containing an empty
1669 string, :c:func:`PyConfig_Read` copies :c:member:`~PyConfig.argv` into
1670 :c:member:`~PyConfig.orig_argv` before modifying
1671 :c:member:`~PyConfig.argv` (if :c:member:`~PyConfig.parse_argv` is
1672 non-zero).
1673
1674 See also the :c:member:`~PyConfig.argv` member and the
1675 :c:func:`Py_GetArgcArgv` function.
1676
1677 Default: empty list.
1678
1679 .. versionadded:: 3.10
1680
1681 .. c:member:: int parse_argv
1682
1683 Parse command line arguments?
1684
1685 If equals to ``1``, parse :c:member:`~PyConfig.argv` the same way the regular
1686 Python parses :ref:`command line arguments <using-on-cmdline>`, and strip
1687 Python arguments from :c:member:`~PyConfig.argv`.
1688
1689 The :c:func:`PyConfig_Read` function only parses
1690 :c:member:`PyConfig.argv` arguments once: :c:member:`PyConfig.parse_argv`
1691 is set to ``2`` after arguments are parsed. Since Python arguments are
1692 stripped from :c:member:`PyConfig.argv`, parsing arguments twice would
1693 parse the application options as Python options.
1694
1695 Default: ``1`` in Python mode, ``0`` in isolated mode.
1696
1697 .. versionchanged:: 3.10
1698 The :c:member:`PyConfig.argv` arguments are now only parsed if
1699 :c:member:`PyConfig.parse_argv` equals to ``1``.
1700
1701 .. c:member:: int parser_debug
1702
1703 Parser debug mode. If greater than ``0``, turn on parser debugging output (for expert only, depending
1704 on compilation options).
1705
1706 Incremented by the :option:`-d` command line option. Set to the
1707 :envvar:`PYTHONDEBUG` environment variable value.
1708
1709 Needs a :ref:`debug build of Python <debug-build>` (the ``Py_DEBUG`` macro
1710 must be defined).
1711
1712 Default: ``0``.
1713
1714 .. c:member:: int pathconfig_warnings
1715
1716 If non-zero, calculation of path configuration is allowed to log
1717 warnings into ``stderr``. If equals to ``0``, suppress these warnings.
1718
1719 Default: ``1`` in Python mode, ``0`` in isolated mode.
1720
1721 Part of the :ref:`Python Path Configuration <init-path-config>` input.
1722
1723 .. versionchanged:: 3.11
1724 Now also applies on Windows.
1725
1726 .. c:member:: wchar_t* prefix
1727
1728 The site-specific directory prefix where the platform independent Python
1729 files are installed: :data:`sys.prefix`.
1730
1731 Default: ``NULL``.
1732
1733 Part of the :ref:`Python Path Configuration <init-path-config>` output.
1734
1735 See also :c:member:`PyConfig.base_prefix`.
1736
1737 .. c:member:: wchar_t* program_name
1738
1739 Program name used to initialize :c:member:`~PyConfig.executable` and in
1740 early error messages during Python initialization.
1741
1742 * On macOS, use :envvar:`PYTHONEXECUTABLE` environment variable if set.
1743 * If the ``WITH_NEXT_FRAMEWORK`` macro is defined, use
1744 :envvar:`__PYVENV_LAUNCHER__` environment variable if set.
1745 * Use ``argv[0]`` of :c:member:`~PyConfig.argv` if available and
1746 non-empty.
1747 * Otherwise, use ``L"python"`` on Windows, or ``L"python3"`` on other
1748 platforms.
1749
1750 Default: ``NULL``.
1751
1752 Part of the :ref:`Python Path Configuration <init-path-config>` input.
1753
1754 .. c:member:: wchar_t* pycache_prefix
1755
1756 Directory where cached ``.pyc`` files are written:
1757 :data:`sys.pycache_prefix`.
1758
1759 Set by the :option:`-X pycache_prefix=PATH <-X>` command line option and
1760 the :envvar:`PYTHONPYCACHEPREFIX` environment variable.
1761 The command-line option takes precedence.
1762
1763 If ``NULL``, :data:`sys.pycache_prefix` is set to ``None``.
1764
1765 Default: ``NULL``.
1766
1767 .. c:member:: int quiet
1768
1769 Quiet mode. If greater than ``0``, don't display the copyright and version at
1770 Python startup in interactive mode.
1771
1772 Incremented by the :option:`-q` command line option.
1773
1774 Default: ``0``.
1775
1776 .. c:member:: wchar_t* run_command
1777
1778 Value of the :option:`-c` command line option.
1779
1780 Used by :c:func:`Py_RunMain`.
1781
1782 Default: ``NULL``.
1783
1784 .. c:member:: wchar_t* run_filename
1785
1786 Filename passed on the command line: trailing command line argument
1787 without :option:`-c` or :option:`-m`. It is used by the
1788 :c:func:`Py_RunMain` function.
1789
1790 For example, it is set to ``script.py`` by the ``python3 script.py arg``
1791 command line.
1792
1793 See also the :c:member:`PyConfig.skip_source_first_line` option.
1794
1795 Default: ``NULL``.
1796
1797 .. c:member:: wchar_t* run_module
1798
1799 Value of the :option:`-m` command line option.
1800
1801 Used by :c:func:`Py_RunMain`.
1802
1803 Default: ``NULL``.
1804
1805 .. c:member:: wchar_t* run_presite
1806
1807 ``package.module`` path to module that should be imported before
1808 ``site.py`` is run.
1809
1810 Set by the :option:`-X presite=package.module <-X>` command-line
1811 option and the :envvar:`PYTHON_PRESITE` environment variable.
1812 The command-line option takes precedence.
1813
1814 Needs a :ref:`debug build of Python <debug-build>` (the ``Py_DEBUG`` macro
1815 must be defined).
1816
1817 Default: ``NULL``.
1818
1819 .. c:member:: int show_ref_count
1820
1821 Show total reference count at exit (excluding :term:`immortal` objects)?
1822
1823 Set to ``1`` by :option:`-X showrefcount <-X>` command line option.
1824
1825 Needs a :ref:`debug build of Python <debug-build>` (the ``Py_REF_DEBUG``
1826 macro must be defined).
1827
1828 Default: ``0``.
1829
1830 .. c:member:: int site_import
1831
1832 Import the :mod:`site` module at startup?
1833
1834 If equal to zero, disable the import of the module site and the
1835 site-dependent manipulations of :data:`sys.path` that it entails.
1836
1837 Also disable these manipulations if the :mod:`site` module is explicitly
1838 imported later (call :func:`site.main` if you want them to be triggered).
1839
1840 Set to ``0`` by the :option:`-S` command line option.
1841
1842 :data:`sys.flags.no_site <sys.flags>` is set to the inverted value of
1843 :c:member:`~PyConfig.site_import`.
1844
1845 Default: ``1``.
1846
1847 .. c:member:: int skip_source_first_line
1848
1849 If non-zero, skip the first line of the :c:member:`PyConfig.run_filename`
1850 source.
1851
1852 It allows the usage of non-Unix forms of ``#!cmd``. This is intended for
1853 a DOS specific hack only.
1854
1855 Set to ``1`` by the :option:`-x` command line option.
1856
1857 Default: ``0``.
1858
1859 .. c:member:: wchar_t* stdio_encoding
1860 .. c:member:: wchar_t* stdio_errors
1861
1862 Encoding and encoding errors of :data:`sys.stdin`, :data:`sys.stdout` and
1863 :data:`sys.stderr` (but :data:`sys.stderr` always uses
1864 ``"backslashreplace"`` error handler).
1865
1866 Use the :envvar:`PYTHONIOENCODING` environment variable if it is
1867 non-empty.
1868
1869 Default encoding:
1870
1871 * ``"UTF-8"`` if :c:member:`PyPreConfig.utf8_mode` is non-zero.
1872 * Otherwise, use the :term:`locale encoding`.
1873
1874 Default error handler:
1875
1876 * On Windows: use ``"surrogateescape"``.
1877 * ``"surrogateescape"`` if :c:member:`PyPreConfig.utf8_mode` is non-zero,
1878 or if the LC_CTYPE locale is "C" or "POSIX".
1879 * ``"strict"`` otherwise.
1880
1881 See also :c:member:`PyConfig.legacy_windows_stdio`.
1882
1883 .. c:member:: int tracemalloc
1884
1885 Enable tracemalloc?
1886
1887 If non-zero, call :func:`tracemalloc.start` at startup.
1888
1889 Set by :option:`-X tracemalloc=N <-X>` command line option and by the
1890 :envvar:`PYTHONTRACEMALLOC` environment variable.
1891
1892 Default: ``-1`` in Python mode, ``0`` in isolated mode.
1893
1894 .. c:member:: int perf_profiling
1895
1896 Enable the Linux ``perf`` profiler support?
1897
1898 If equals to ``1``, enable support for the Linux ``perf`` profiler.
1899
1900 If equals to ``2``, enable support for the Linux ``perf`` profiler with
1901 DWARF JIT support.
1902
1903 Set to ``1`` by :option:`-X perf <-X>` command-line option and the
1904 :envvar:`PYTHONPERFSUPPORT` environment variable.
1905
1906 Set to ``2`` by the :option:`-X perf_jit <-X>` command-line option and
1907 the :envvar:`PYTHON_PERF_JIT_SUPPORT` environment variable.
1908
1909 Default: ``-1``.
1910
1911 .. seealso::
1912 See :ref:`perf_profiling` for more information.
1913
1914 .. versionadded:: 3.12
1915
1916 .. c:member:: wchar_t* stdlib_dir
1917
1918 Directory of the Python standard library.
1919
1920 Default: ``NULL``.
1921
1922 .. versionadded:: 3.11
1923
1924 .. c:member:: int use_environment
1925
1926 Use :ref:`environment variables <using-on-envvars>`?
1927
1928 If equals to zero, ignore the :ref:`environment variables
1929 <using-on-envvars>`.
1930
1931 Set to ``0`` by the :option:`-E` environment variable.
1932
1933 Default: ``1`` in Python config and ``0`` in isolated config.
1934
1935 .. c:member:: int use_system_logger
1936
1937 If non-zero, ``stdout`` and ``stderr`` will be redirected to the system
1938 log.
1939
1940 Only available on macOS 10.12 and later, and on iOS.
1941
1942 Default: ``0`` (don't use the system log) on macOS; ``1`` on iOS (use the
1943 system log).
1944
1945 .. versionadded:: 3.14
1946
1947 .. c:member:: int user_site_directory
1948
1949 If non-zero, add the user site directory to :data:`sys.path`.
1950
1951 Set to ``0`` by the :option:`-s` and :option:`-I` command line options.
1952
1953 Set to ``0`` by the :envvar:`PYTHONNOUSERSITE` environment variable.
1954
1955 Default: ``1`` in Python mode, ``0`` in isolated mode.
1956
1957 .. c:member:: int verbose
1958
1959 Verbose mode. If greater than ``0``, print a message each time a module is
1960 imported, showing the place (filename or built-in module) from which
1961 it is loaded.
1962
1963 If greater than or equal to ``2``, print a message for each file that is
1964 checked for when searching for a module. Also provides information on
1965 module cleanup at exit.
1966
1967 Incremented by the :option:`-v` command line option.
1968
1969 Set by the :envvar:`PYTHONVERBOSE` environment variable value.
1970
1971 Default: ``0``.
1972
1973 .. c:member:: PyWideStringList warnoptions
1974
1975 Options of the :mod:`warnings` module to build warnings filters, lowest
1976 to highest priority: :data:`sys.warnoptions`.
1977
1978 The :mod:`warnings` module adds :data:`sys.warnoptions` in the reverse
1979 order: the last :c:member:`PyConfig.warnoptions` item becomes the first
1980 item of :data:`warnings.filters` which is checked first (highest
1981 priority).
1982
1983 The :option:`-W` command line options adds its value to
1984 :c:member:`~PyConfig.warnoptions`, it can be used multiple times.
1985
1986 The :envvar:`PYTHONWARNINGS` environment variable can also be used to add
1987 warning options. Multiple options can be specified, separated by commas
1988 (``,``).
1989
1990 Default: empty list.
1991
1992 .. c:member:: int write_bytecode
1993
1994 If equal to ``0``, Python won't try to write ``.pyc`` files on the import of
1995 source modules.
1996
1997 Set to ``0`` by the :option:`-B` command line option and the
1998 :envvar:`PYTHONDONTWRITEBYTECODE` environment variable.
1999
2000 :data:`sys.dont_write_bytecode` is initialized to the inverted value of
2001 :c:member:`~PyConfig.write_bytecode`.
2002
2003 Default: ``1``.
2004
2005 .. c:member:: PyWideStringList xoptions
2006
2007 Values of the :option:`-X` command line options: :data:`sys._xoptions`.
2008
2009 Default: empty list.
2010
2011 .. c:member:: int _pystats
2012
2013 If non-zero, write performance statistics at Python exit.
2014
2015 Need a special build with the ``Py_STATS`` macro:
2016 see :option:`--enable-pystats`.
2017
2018 Default: ``0``.
2019
2020 If :c:member:`~PyConfig.parse_argv` is non-zero, :c:member:`~PyConfig.argv`
2021 arguments are parsed the same way the regular Python parses :ref:`command line
2022 arguments <using-on-cmdline>`, and Python arguments are stripped from
2023 :c:member:`~PyConfig.argv`.
2024
2025 The :c:member:`~PyConfig.xoptions` options are parsed to set other options: see
2026 the :option:`-X` command line option.
2027
2028 .. versionchanged:: 3.9
2029
2030 The ``show_alloc_count`` field has been removed.
2031
2032
2033 .. _init-from-config:
2034
2035 Initialization with PyConfig
2036 ----------------------------
2037
2038 Initializing the interpreter from a populated configuration struct is handled
2039 by calling :c:func:`Py_InitializeFromConfig`.
2040
2041 The caller is responsible to handle exceptions (error or exit) using
2042 :c:func:`PyStatus_Exception` and :c:func:`Py_ExitStatusException`.
2043
2044 If :c:func:`PyImport_FrozenModules`, :c:func:`PyImport_AppendInittab` or
2045 :c:func:`PyImport_ExtendInittab` are used, they must be set or called after
2046 Python preinitialization and before the Python initialization. If Python is
2047 initialized multiple times, :c:func:`PyImport_AppendInittab` or
2048 :c:func:`PyImport_ExtendInittab` must be called before each Python
2049 initialization.
2050
2051 The current configuration (``PyConfig`` type) is stored in
2052 ``PyInterpreterState.config``.
2053
2054 Example setting the program name::
2055
2056 void init_python(void)
2057 {
2058 PyStatus status;
2059
2060 PyConfig config;
2061 PyConfig_InitPythonConfig(&config);
2062
2063 /* Set the program name. Implicitly preinitialize Python. */
2064 status = PyConfig_SetString(&config, &config.program_name,
2065 L"/path/to/my_program");
2066 if (PyStatus_Exception(status)) {
2067 goto exception;
2068 }
2069
2070 status = Py_InitializeFromConfig(&config);
2071 if (PyStatus_Exception(status)) {
2072 goto exception;
2073 }
2074 PyConfig_Clear(&config);
2075 return;
2076
2077 exception:
2078 PyConfig_Clear(&config);
2079 Py_ExitStatusException(status);
2080 }
2081
2082 More complete example modifying the default configuration, read the
2083 configuration, and then override some parameters. Note that since
2084 3.11, many parameters are not calculated until initialization, and
2085 so values cannot be read from the configuration structure. Any values
2086 set before initialize is called will be left unchanged by
2087 initialization::
2088
2089 PyStatus init_python(const char *program_name)
2090 {
2091 PyStatus status;
2092
2093 PyConfig config;
2094 PyConfig_InitPythonConfig(&config);
2095
2096 /* Set the program name before reading the configuration
2097 (decode byte string from the locale encoding).
2098
2099 Implicitly preinitialize Python. */
2100 status = PyConfig_SetBytesString(&config, &config.program_name,
2101 program_name);
2102 if (PyStatus_Exception(status)) {
2103 goto done;
2104 }
2105
2106 /* Read all configuration at once */
2107 status = PyConfig_Read(&config);
2108 if (PyStatus_Exception(status)) {
2109 goto done;
2110 }
2111
2112 /* Specify sys.path explicitly */
2113 /* If you want to modify the default set of paths, finish
2114 initialization first and then use PySys_GetObject("path") */
2115 config.module_search_paths_set = 1;
2116 status = PyWideStringList_Append(&config.module_search_paths,
2117 L"/path/to/stdlib");
2118 if (PyStatus_Exception(status)) {
2119 goto done;
2120 }
2121 status = PyWideStringList_Append(&config.module_search_paths,
2122 L"/path/to/more/modules");
2123 if (PyStatus_Exception(status)) {
2124 goto done;
2125 }
2126
2127 /* Override executable computed by PyConfig_Read() */
2128 status = PyConfig_SetString(&config, &config.executable,
2129 L"/path/to/my_executable");
2130 if (PyStatus_Exception(status)) {
2131 goto done;
2132 }
2133
2134 status = Py_InitializeFromConfig(&config);
2135
2136 done:
2137 PyConfig_Clear(&config);
2138 return status;
2139 }
2140
2141
2142 .. _init-isolated-conf:
2143
2144 Isolated Configuration
2145 ----------------------
2146
2147 :c:func:`PyPreConfig_InitIsolatedConfig` and
2148 :c:func:`PyConfig_InitIsolatedConfig` functions create a configuration to
2149 isolate Python from the system. For example, to embed Python into an
2150 application.
2151
2152 This configuration ignores global configuration variables, environment
2153 variables, command line arguments (:c:member:`PyConfig.argv` is not parsed)
2154 and user site directory. The C standard streams (ex: ``stdout``) and the
2155 LC_CTYPE locale are left unchanged. Signal handlers are not installed.
2156
2157 Configuration files are still used with this configuration to determine
2158 paths that are unspecified. Ensure :c:member:`PyConfig.home` is specified
2159 to avoid computing the default path configuration.
2160
2161
2162 .. _init-python-config:
2163
2164 Python Configuration
2165 --------------------
2166
2167 :c:func:`PyPreConfig_InitPythonConfig` and :c:func:`PyConfig_InitPythonConfig`
2168 functions create a configuration to build a customized Python which behaves as
2169 the regular Python.
2170
2171 Environments variables and command line arguments are used to configure
2172 Python, whereas global configuration variables are ignored.
2173
2174 This function enables C locale coercion (:pep:`538`)
2175 and :ref:`Python UTF-8 Mode <utf8-mode>`
2176 (:pep:`540`) depending on the LC_CTYPE locale, :envvar:`PYTHONUTF8` and
2177 :envvar:`PYTHONCOERCECLOCALE` environment variables.
2178
2179
2180 .. _init-path-config:
2181
2182 Python Path Configuration
2183 -------------------------
2184
2185 :c:type:`PyConfig` contains multiple fields for the path configuration:
2186
2187 * Path configuration inputs:
2188
2189 * :c:member:`PyConfig.home`
2190 * :c:member:`PyConfig.platlibdir`
2191 * :c:member:`PyConfig.pathconfig_warnings`
2192 * :c:member:`PyConfig.program_name`
2193 * :c:member:`PyConfig.pythonpath_env`
2194 * current working directory: to get absolute paths
2195 * ``PATH`` environment variable to get the program full path
2196 (from :c:member:`PyConfig.program_name`)
2197 * ``__PYVENV_LAUNCHER__`` environment variable
2198 * (Windows only) Application paths in the registry under
2199 "Software\Python\PythonCore\X.Y\PythonPath" of HKEY_CURRENT_USER and
2200 HKEY_LOCAL_MACHINE (where X.Y is the Python version).
2201
2202 * Path configuration output fields:
2203
2204 * :c:member:`PyConfig.base_exec_prefix`
2205 * :c:member:`PyConfig.base_executable`
2206 * :c:member:`PyConfig.base_prefix`
2207 * :c:member:`PyConfig.exec_prefix`
2208 * :c:member:`PyConfig.executable`
2209 * :c:member:`PyConfig.module_search_paths_set`,
2210 :c:member:`PyConfig.module_search_paths`
2211 * :c:member:`PyConfig.prefix`
2212
2213 If at least one "output field" is not set, Python calculates the path
2214 configuration to fill unset fields. If
2215 :c:member:`~PyConfig.module_search_paths_set` is equal to ``0``,
2216 :c:member:`~PyConfig.module_search_paths` is overridden and
2217 :c:member:`~PyConfig.module_search_paths_set` is set to ``1``.
2218
2219 It is possible to completely ignore the function calculating the default
2220 path configuration by setting explicitly all path configuration output
2221 fields listed above. A string is considered as set even if it is non-empty.
2222 ``module_search_paths`` is considered as set if
2223 ``module_search_paths_set`` is set to ``1``. In this case,
2224 ``module_search_paths`` will be used without modification.
2225
2226 Set :c:member:`~PyConfig.pathconfig_warnings` to ``0`` to suppress warnings when
2227 calculating the path configuration (Unix only, Windows does not log any warning).
2228
2229 If :c:member:`~PyConfig.base_prefix` or :c:member:`~PyConfig.base_exec_prefix`
2230 fields are not set, they inherit their value from :c:member:`~PyConfig.prefix`
2231 and :c:member:`~PyConfig.exec_prefix` respectively.
2232
2233 :c:func:`Py_RunMain` and :c:func:`Py_Main` modify :data:`sys.path`:
2234
2235 * If :c:member:`~PyConfig.run_filename` is set and is a directory which contains a
2236 ``__main__.py`` script, prepend :c:member:`~PyConfig.run_filename` to
2237 :data:`sys.path`.
2238 * If :c:member:`~PyConfig.isolated` is zero:
2239
2240 * If :c:member:`~PyConfig.run_module` is set, prepend the current directory
2241 to :data:`sys.path`. Do nothing if the current directory cannot be read.
2242 * If :c:member:`~PyConfig.run_filename` is set, prepend the directory of the
2243 filename to :data:`sys.path`.
2244 * Otherwise, prepend an empty string to :data:`sys.path`.
2245
2246 If :c:member:`~PyConfig.site_import` is non-zero, :data:`sys.path` can be
2247 modified by the :mod:`site` module. If
2248 :c:member:`~PyConfig.user_site_directory` is non-zero and the user's
2249 site-package directory exists, the :mod:`site` module appends the user's
2250 site-package directory to :data:`sys.path`.
2251
2252 The following configuration files are used by the path configuration:
2253
2254 * ``pyvenv.cfg``
2255 * ``._pth`` file (ex: ``python._pth``)
2256 * ``pybuilddir.txt`` (Unix only)
2257
2258 If a ``._pth`` file is present:
2259
2260 * Set :c:member:`~PyConfig.isolated` to ``1``.
2261 * Set :c:member:`~PyConfig.use_environment` to ``0``.
2262 * Set :c:member:`~PyConfig.site_import` to ``0``.
2263 * Set :c:member:`~PyConfig.safe_path` to ``1``.
2264
2265 If :c:member:`~PyConfig.home` is not set and a ``pyvenv.cfg`` file is present in
2266 the same directory as :c:member:`~PyConfig.executable`, or its parent,
2267 :c:member:`~PyConfig.prefix` and :c:member:`~PyConfig.exec_prefix` are set that
2268 location. When this happens, :c:member:`~PyConfig.base_prefix` and
2269 :c:member:`~PyConfig.base_exec_prefix` still keep their value, pointing to the
2270 base installation. See :ref:`sys-path-init-virtual-environments` for more
2271 information.
2272
2273 The ``__PYVENV_LAUNCHER__`` environment variable is used to set
2274 :c:member:`PyConfig.base_executable`.
2275
2276 .. versionchanged:: 3.14
2277
2278 :c:member:`~PyConfig.prefix`, and :c:member:`~PyConfig.exec_prefix`, are now
2279 set to the ``pyvenv.cfg`` directory. This was previously done by :mod:`site`,
2280 therefore affected by :option:`-S`.
2281
2282
2283 Py_GetArgcArgv()
2284 ================
2285
2286 .. c:function:: void Py_GetArgcArgv(int *argc, wchar_t ***argv)
2287
2288 Get the original command line arguments, before Python modified them.
2289
2290 See also :c:member:`PyConfig.orig_argv` member.
2291
2292 Delaying main module execution
2293 ==============================
2294
2295 In some embedding use cases, it may be desirable to separate interpreter initialization
2296 from the execution of the main module.
2297
2298 This separation can be achieved by setting ``PyConfig.run_command`` to the empty
2299 string during initialization (to prevent the interpreter from dropping into the
2300 interactive prompt), and then subsequently executing the desired main module
2301 code using ``__main__.__dict__`` as the global namespace.