bpo-33601: Document for Py_UTF8Mode

[y43ren]

Adding documentation for Py_UTF8Mode.

https://bugs.python.org/issue33601

[the-knights-who-say-ni]

Hello, and thanks for your contribution!

I'm a bot set up to make sure that the project can legally accept your contribution by verifying you have signed the PSF contributor agreement (CLA).

Unfortunately our records indicate you have not signed the CLA. For legal reasons we need you to sign this before we can look at your contribution. Please follow the steps outlined in the CPython devguide to rectify this issue.

When your account is ready, please add a comment in this pull request
and a Python core developer will remove the CLA not signed label
to make the bot check again.

Thanks again to your contribution and we look forward to looking at it!

[vstinner]

The documentation is incorrect. Extract of Python/bltinmodule.c:

/* UTF-8 mode (PEP 540): if equals to 1, use the UTF-8 encoding, and change
   stdin and stdout error handler to "surrogateescape". It is equal to
   -1 by default: unknown, will be set by Py_Main() */
int Py_UTF8Mode = -1;

I suggest:

• If set to 1, enable the UTF-8 Mode
• If set to 0, disable the UTF-8 Mode
• If set to -1, look for the :envvar:PYTHONUTF8 environment variable and the :option:-X utf8 command line option

I would suggest to not document here the effects of the UTF-8 Mode.

Currently, the effects of the UTF-8 Mode are not documented. But I would prefer to not document it at 3 different places: C API doc, PYTHONUTF8 doc, -X utf8 doc.

I don't know what is the best place to document the UTF-8 Mode, but I would prefer to document it in a Python documentation (not in the C API).

[vstinner]

I suggest to add "the": See the :pep:540 ...

[bedevere-bot]

A Python core developer has requested some changes be made to your pull request before we can consider merging it. If you could please address their requests along with any other requests in other reviews from core developers that would be appreciated.

Once you have made the requested changes, please leave a comment on this pull request containing the phrase I have made the requested changes; please review again. I will then notify any core developers who have left a review that you're ready for them to take another look at this pull request.

[vstinner]

@y43ren: Did you sign the Python CLA? See #7143 (comment)

[vstinner]

@y43ren: Do you still plan to work on this PR? I don't see any change since I reviewed your first PR version.

[brettcannon]

Thanks for the PR, but closing as the CLA has not been signed within the last month. If you do decide to sign the CLA we can re-open this PR.