Skip to content

Commit

Permalink
Enhance PyConfig documentation (python#92394)
Browse files Browse the repository at this point in the history
  • Loading branch information
@vstinner
vstinner authored May 9, 2022
1 parent 269e726 commit 7b9803f
Showing 1 changed file with 46 additions and 37 deletions.
83 changes: 46 additions & 37 deletions Doc/c-api/init_config.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -97,7 +97,7 @@ PyWideStringList
If *index* is greater than or equal to *list* length, append *item* to
*list*.
*index* must be greater than or equal to 0.
*index* must be greater than or equal to ``0``.
Python must be preinitialized to call this function.
Expand Down Expand Up @@ -256,18 +256,18 @@ PyPreConfig
Set the LC_CTYPE locale to the user preferred locale?
If equals to 0, set :c:member:`~PyPreConfig.coerce_c_locale` and
:c:member:`~PyPreConfig.coerce_c_locale_warn` members to 0.
If equals to ``0``, set :c:member:`~PyPreConfig.coerce_c_locale` and
:c:member:`~PyPreConfig.coerce_c_locale_warn` members to ``0``.
See the :term:`locale encoding`.
Default: ``1`` in Python config, ``0`` in isolated config.
.. c:member:: int coerce_c_locale
If equals to 2, coerce the C locale.
If equals to ``2``, coerce the C locale.
If equals to 1, read the LC_CTYPE locale to decide if it should be
If equals to ``1``, read the LC_CTYPE locale to decide if it should be
coerced.
See the :term:`locale encoding`.
Expand All @@ -282,8 +282,8 @@ PyPreConfig
.. c:member:: int dev_mode
If non-zero, enables the :ref:`Python Development Mode <devmode>`:
see :c:member:`PyConfig.dev_mode`.
:ref:`Python Development Mode <devmode>`: see
:c:member:`PyConfig.dev_mode`.
Default: ``-1`` in Python mode, ``0`` in isolated mode.
Expand Down Expand Up @@ -329,8 +329,10 @@ PyPreConfig
If non-zero, enable the :ref:`Python UTF-8 Mode <utf8-mode>`.
Set by the :option:`-X utf8 <-X>` command line option and the
:envvar:`PYTHONUTF8` environment variable.
Set to ``0`` or ``1`` by the :option:`-X utf8 <-X>` command line option
and the :envvar:`PYTHONUTF8` environment variable.
Also set to ``1`` if the ``LC_CTYPE`` locale is ``C`` or ``POSIX``.
Default: ``-1`` in Python config and ``0`` in isolated config.
Expand Down Expand Up @@ -555,7 +557,7 @@ PyConfig
* Otherwise (``python -c code`` and ``python``), prepend an empty string,
which means the current working directory.
Set to 1 by the :option:`-P` command line option and the
Set to ``1`` by the :option:`-P` command line option and the
:envvar:`PYTHONSAFEPATH` environment variable.
Default: ``0`` in Python config, ``1`` in isolated config.
Expand Down Expand Up @@ -592,10 +594,10 @@ PyConfig
.. c:member:: int buffered_stdio
If equals to 0 and :c:member:`~PyConfig.configure_c_stdio` is non-zero,
If equals to ``0`` and :c:member:`~PyConfig.configure_c_stdio` is non-zero,
disable buffering on the C streams stdout and stderr.
Set to 0 by the :option:`-u` command line option and the
Set to ``0`` by the :option:`-u` command line option and the
:envvar:`PYTHONUNBUFFERED` environment variable.
stdin is always opened in buffered mode.
Expand All @@ -604,11 +606,11 @@ PyConfig
.. c:member:: int bytes_warning
If equals to 1, issue a warning when comparing :class:`bytes` or
If equals to ``1``, issue a warning when comparing :class:`bytes` or
:class:`bytearray` with :class:`str`, or comparing :class:`bytes` with
:class:`int`.
If equal or greater to 2, raise a :exc:`BytesWarning` exception in these
If equal or greater to ``2``, raise a :exc:`BytesWarning` exception in these
cases.
Incremented by the :option:`-b` command line option.
Expand Down Expand Up @@ -671,6 +673,9 @@ PyConfig
If non-zero, enable the :ref:`Python Development Mode <devmode>`.
Set to ``1`` by the :option:`-X dev <-X>` option and the
:envvar:`PYTHONDEVMODE` environment variable.
Default: ``-1`` in Python mode, ``0`` in isolated mode.
.. c:member:: int dump_refs
Expand Down Expand Up @@ -800,7 +805,7 @@ PyConfig
Enter interactive mode after executing a script or a command.
If greater than 0, enable inspect: when a script is passed as first
If greater than ``0``, enable inspect: when a script is passed as first
argument or the -c option is used, enter interactive mode after executing
the script or the command, even when :data:`sys.stdin` does not appear to
be a terminal.
Expand All @@ -818,25 +823,27 @@ PyConfig
.. c:member:: int interactive
If greater than 0, enable the interactive mode (REPL).
If greater than ``0``, enable the interactive mode (REPL).
Incremented by the :option:`-i` command line option.
Default: ``0``.
.. c:member:: int isolated
If greater than 0, enable isolated mode:
If greater than ``0``, enable isolated mode:
* Set :c:member:`~PyConfig.safe_path` to 1:
* Set :c:member:`~PyConfig.safe_path` to ``1``:
don't prepend a potentially unsafe path to :data:`sys.path` at Python
startup.
* Set :c:member:`~PyConfig.use_environment` to 0.
* Set :c:member:`~PyConfig.user_site_directory` to 0: don't add the user
* Set :c:member:`~PyConfig.use_environment` to ``0``.
* Set :c:member:`~PyConfig.user_site_directory` to ``0``: don't add the user
site directory to :data:`sys.path`.
* Python REPL doesn't import :mod:`readline` nor enable default readline
configuration on interactive prompts.
Set to ``1`` by the :option:`-I` command line option.
Default: ``0`` in Python mode, ``1`` in isolated mode.
See also :c:member:`PyPreConfig.isolated`.
Expand Down Expand Up @@ -906,7 +913,7 @@ PyConfig
Module search paths: :data:`sys.path`.
If :c:member:`~PyConfig.module_search_paths_set` is equal to 0,
If :c:member:`~PyConfig.module_search_paths_set` is equal to ``0``,
:c:func:`Py_InitializeFromConfig` will replace
:c:member:`~PyConfig.module_search_paths` and sets
:c:member:`~PyConfig.module_search_paths_set` to ``1``.
Expand Down Expand Up @@ -970,7 +977,7 @@ PyConfig
.. c:member:: int parser_debug
Parser debug mode. If greater than 0, turn on parser debugging output (for expert only, depending
Parser debug mode. If greater than ``0``, turn on parser debugging output (for expert only, depending
on compilation options).
Incremented by the :option:`-d` command line option. Set to the
Expand All @@ -981,7 +988,7 @@ PyConfig
.. c:member:: int pathconfig_warnings
If non-zero, calculation of path configuration is allowed to log
warnings into ``stderr``. If equals to 0, suppress these warnings.
warnings into ``stderr``. If equals to ``0``, suppress these warnings.
Default: ``1`` in Python mode, ``0`` in isolated mode.
Expand Down Expand Up @@ -1031,7 +1038,7 @@ PyConfig
.. c:member:: int quiet
Quiet mode. If greater than 0, don't display the copyright and version at
Quiet mode. If greater than ``0``, don't display the copyright and version at
Python startup in interactive mode.
Incremented by the :option:`-q` command line option.
Expand Down Expand Up @@ -1071,7 +1078,7 @@ PyConfig
Show total reference count at exit?
Set to 1 by :option:`-X showrefcount <-X>` command line option.
Set to ``1`` by :option:`-X showrefcount <-X>` command line option.
Need a :ref:`debug build of Python <debug-build>` (the ``Py_REF_DEBUG``
macro must be defined).
Expand Down Expand Up @@ -1150,6 +1157,8 @@ PyConfig
If equals to zero, ignore the :ref:`environment variables
<using-on-envvars>`.
Set to ``0`` by the :option:`-E` environment variable.
Default: ``1`` in Python config and ``0`` in isolated config.
.. c:member:: int user_site_directory
Expand All @@ -1164,11 +1173,11 @@ PyConfig
.. c:member:: int verbose
Verbose mode. If greater than 0, print a message each time a module is
Verbose mode. If greater than ``0``, print a message each time a module is
imported, showing the place (filename or built-in module) from which
it is loaded.
If greater or equal to 2, print a message for each file that is checked
If greater or equal to ``2``, print a message for each file that is checked
for when searching for a module. Also provides information on module
cleanup at exit.
Expand Down Expand Up @@ -1199,7 +1208,7 @@ PyConfig
.. c:member:: int write_bytecode
If equal to 0, Python won't try to write ``.pyc`` files on the import of
If equal to ``0``, Python won't try to write ``.pyc`` files on the import of
source modules.
Set to ``0`` by the :option:`-B` command line option and the
Expand Down Expand Up @@ -1400,18 +1409,18 @@ Python Path Configuration
If at least one "output field" is not set, Python calculates the path
configuration to fill unset fields. If
:c:member:`~PyConfig.module_search_paths_set` is equal to 0,
:c:member:`~PyConfig.module_search_paths_set` is equal to ``0``,
:c:member:`~PyConfig.module_search_paths` is overridden and
:c:member:`~PyConfig.module_search_paths_set` is set to 1.
:c:member:`~PyConfig.module_search_paths_set` is set to ``1``.
It is possible to completely ignore the function calculating the default
path configuration by setting explicitly all path configuration output
fields listed above. A string is considered as set even if it is non-empty.
``module_search_paths`` is considered as set if
``module_search_paths_set`` is set to 1. In this case, path
``module_search_paths_set`` is set to ``1``. In this case, path
configuration input fields are ignored as well.
Set :c:member:`~PyConfig.pathconfig_warnings` to 0 to suppress warnings when
Set :c:member:`~PyConfig.pathconfig_warnings` to ``0`` to suppress warnings when
calculating the path configuration (Unix only, Windows does not log any warning).
If :c:member:`~PyConfig.base_prefix` or :c:member:`~PyConfig.base_exec_prefix`
Expand Down Expand Up @@ -1445,10 +1454,10 @@ The following configuration files are used by the path configuration:
If a ``._pth`` file is present:
* Set :c:member:`~PyConfig.isolated` to 1.
* Set :c:member:`~PyConfig.use_environment` to 0.
* Set :c:member:`~PyConfig.site_import` to 0.
* Set :c:member:`~PyConfig.safe_path` to 1.
* Set :c:member:`~PyConfig.isolated` to ``1``.
* Set :c:member:`~PyConfig.use_environment` to ``0``.
* Set :c:member:`~PyConfig.site_import` to ``0``.
* Set :c:member:`~PyConfig.safe_path` to ``1``.
The ``__PYVENV_LAUNCHER__`` environment variable is used to set
:c:member:`PyConfig.base_executable`
Expand Down Expand Up @@ -1511,7 +1520,7 @@ initialization, the core feature of :pep:`432`:
Private provisional API:
* :c:member:`PyConfig._init_main`: if set to 0,
* :c:member:`PyConfig._init_main`: if set to ``0``,
:c:func:`Py_InitializeFromConfig` stops at the "Core" initialization phase.
* :c:member:`PyConfig._isolated_interpreter`: if non-zero,
disallow threads, subprocesses and fork.
Expand Down

0 comments on commit 7b9803f

Please sign in to comment.