Document Python 3.7 behaviour in "Python 3 Surrogate Handling" documentation

http://click.palletsprojects.com/en/7.x/python3/#python-3-surrogate-handling rightly warns about issues when using Python 3.

A RuntimeError is documented.

The good news is that this RuntimeError no longer is a problem in Python 3.7, as demonstrated below.

This took some experimentation to find out, and as a user I would have liked to see this in the documentation.

Thank you!

~/Desktop ~> echo $LANG

~/Desktop ~> echo $LC_ALL

~/Desktop ~> cat example.py
import click

@click.command()
def hello():
    pass

hello()
~/Desktop ~> vf activate python-3.5.6
~/Desktop (python-3.5.6) ~> python --version
Python 3.5.6
~/Desktop (python-3.5.6) ~> python example.py
Traceback (most recent call last):
  File "example.py", line 7, in <module>
    hello()
  File "/Users/adam/.virtualenvs/python-3.5.6/lib/python3.5/site-packages/click/core.py", line 764, in __call__
    return self.main(*args, **kwargs)
  File "/Users/adam/.virtualenvs/python-3.5.6/lib/python3.5/site-packages/click/core.py", line 696, in main
    _verify_python3_env()
  File "/Users/adam/.virtualenvs/python-3.5.6/lib/python3.5/site-packages/click/_unicodefun.py", line 124, in _verify_python3_env
    ' mitigation steps.' + extra
RuntimeError: Click will abort further execution because Python 3 was configured to use ASCII as encoding for the environment. Consult https://click.palletsprojects.com/en/7.x/python3/ for mitigation steps.

This system lists a couple of UTF-8 supporting locales that
you can pick from.  The following suitable locales were
discovered: af_ZA.UTF-8, am_ET.UTF-8, be_BY.UTF-8, bg_BG.UTF-8, ca_ES.UTF-8, cs_CZ.UTF-8, da_DK.UTF-8, de_AT.UTF-8, de_CH.UTF-8, de_DE.UTF-8, el_GR.UTF-8, en_AU.UTF-8, en_CA.UTF-8, en_GB.UTF-8, en_IE.UTF-8, en_NZ.UTF-8, en_US.UTF-8, es_ES.UTF-8, et_EE.UTF-8, eu_ES.UTF-8, fi_FI.UTF-8, fr_BE.UTF-8, fr_CA.UTF-8, fr_CH.UTF-8, fr_FR.UTF-8, he_IL.UTF-8, hr_HR.UTF-8, hu_HU.UTF-8, hy_AM.UTF-8, is_IS.UTF-8, it_CH.UTF-8, it_IT.UTF-8, ja_JP.UTF-8, kk_KZ.UTF-8, ko_KR.UTF-8, lt_LT.UTF-8, nl_BE.UTF-8, nl_NL.UTF-8, no_NO.UTF-8, pl_PL.UTF-8, pt_BR.UTF-8, pt_PT.UTF-8, ro_RO.UTF-8, ru_RU.UTF-8, sk_SK.UTF-8, sl_SI.UTF-8, sr_YU.UTF-8, sv_SE.UTF-8, tr_TR.UTF-8, uk_UA.UTF-8, zh_CN.UTF-8, zh_HK.UTF-8, zh_TW.UTF-8
~/Desktop (python-3.5.6) ~> vf activate py37 
~/Desktop (py37) ~> python --version
Python 3.7.2
~/Desktop (py37) ~> python example.py
~/Desktop (py37) ~> 

[davidism]

I’d be happy to review a pull request that adds a mention of Python 3.7 and the relevant PEPs that changed this behavior. Be sure to make it against the 7.x branch, not master.

[davidism]

Docs updated in #1334