bpo-33601 Py_UTF8Mode is not documented

[Vidhyavinu]

Added UTF8Mode documentation to https://docs.python.org/dev/c-api/init.html#global-configuration-variables

https://bugs.python.org/issue33601

[AA-Turner]

I only see checks for if Py_UTF8Mode is greater than 0 in the source (https://cs.github.com/python/cpython?q=Py_UTF8Mode), but perhaps I'm missing something.

cc: @vstinner @methane

A

[vstinner]

I created #93103 to deprecate Global Configuration Variables like Py_IgnoreEnvironment.

[MaxwellDupre]

How about adding a link in C API Stability page to init.rst?
Also, adding
Py_UTF8Mode=1 enables UTF-8 mode. However the PYTHONUTF8 environment variable is ignored (even if use_environment=1).

[vstinner]

Please mention that the variable is now deprecated: #93943

[vstinner]

Suggested change

	If set to -1, look for the :option:`-x` option and the :envvar:`PYTHONUTF8` environment variable.
	If set to -1, look for the :option:`-x utf8 <-x>` command line option and the :envvar:`PYTHONUTF8` environment variable.

[vstinner]

I'm not sure that it works this way. preconfig_get_global_vars() ignores Py_UTF8Mode if Py_UTF8Mode <= 0.

Py_UTF8Mode should not be used: PyPreConfig.utf8_mode should be used instead. Today, it seems like the only purpose of Py_UTF8Mode is to explicitly enable the Python UTF-8 Mode with Py_UTF8Mode=1.

[vstinner]

You can add a link to https://docs.python.org/dev/library/os.html#python-utf-8-mode using utf8-mode reference. Please replace "UTF-8 Mode" with "Pyhon UTF-8 Mode".