zsh 5.3
=======
- [x] Have you followed the [guidelines for contributing](https://github.com/Homebrew/homebrew-core/blob/master/CONTRIBUTING.md)?
- [x] Have you checked that there aren't other open [pull requests](https://github.com/Homebrew/homebrew-core/pulls) for the same formula update/change?
- [x] Have you built your formula locally with `brew install --build-from-source <formula>`, where `<formula>` is the name of the formula you're submitting?
- [x] Does your build pass `brew audit --strict <formula>` (after doing `brew install <formula>`)?
-----
Makefile: install shell wrapper with PYTHONIOENCODING=utf-8
===========================================================
`PYTHONIOENCODING` has been a headache for us since the very beginning. Here we solve it once and for all (for Makefile-based installations, including package managers) by installing the actual googler script to libexec, and instead putting a shell wrapper in bin setting
`PYTHONIOENCODING` to `utf-8`.
From now on users can run
```sh
LC_ALL=en_US.US-ASCII PYTHONIOENCODING=ascii googler
```
and expect googler to work as usual.
Single file installations are still vulnerable, but at least 36526b5 makes googler fail noisily with a clear message.
Make sure stdout encoding is UTF-8
==================================
Python 3 is much better at defaulting to UTF-8, the one true encoding, but unfortunately you can still have non-UTF-8 stdout:[1]
> The character encoding is platform-dependent. Under Windows, if the stream is interactive (that is, if its isatty() method returns True), the console codepage is used, otherwise the ANSI code page. Under other platforms, the locale encoding is used (see locale.getpreferredencoding()).
>
> Under all platforms though, you can override this value by setting the PYTHONIOENCODING environment variable before starting Python.
`PYTHONIOENCODING` would solve it once and for all, but again unfortunately, a shebang like
```sh
#!/usr/bin/env PYTHONIOENCODING=utf-8 python3
```
isn't cross platform; and googler, proud of being a single-script program, can't afford a wrapper script. (In fact, we can totally explore that option for a Makefile based install.) Alternatively we could
1. Force the encoding post Python init;
2. Print encoded 8-bit data directly to the underlying binary buffers.
The former (when implemented through `codecs.StreamWriter`) has shown to interact poorly with readline; the latter is plain ugly.
That leaves us with one option (other than the wrapper script, which I'll explore in a separate PR): ask users to do the right thing.
In this PR, we check to make sure stdout encoding is `utf-8` (post argparse, so the check isn't performed if we're only printing help message), and abort if not. The message should be fairly helpful, complete with what users are expected to do (but I won't try to teach users how to set environment variables):
```
$ unset LC_ALL PYTHONIOENCODING
$ LC_CTYPE=en_US.US-ASCII googler hello
stdout encoding 'ascii' detected. googler requires utf-8 to work properly. The wrong encoding may be due to a non-UTF-8 locale or an improper PYTHONIOENCODING. (For the record, your locale language is en_US and locale encoding is ISO8859-1; your PYTHONIOENCODING is not set.)
Please set a UTF-8 locale (e.g., en_US.UTF-8) or set PYTHONIOENCODING to utf-8.
$ LC_CTYPE=en_US.ISO8859-1 googler hello
stdout encoding 'iso8859-1' detected. googler requires utf-8 to work properly. The wrong encoding may be due to a non-UTF-8 locale or an improper PYTHONIOENCODING. (For the record, your locale language is en_US and locale encoding is ISO8859-1; your PYTHONIOENCODING is not set.)
Please set a UTF-8 locale (e.g., en_US.UTF-8) or set PYTHONIOENCODING to utf-8.
$ LC_CTYPE=zh_CN.GBK googler hello
stdout encoding 'gbk' detected. googler requires utf-8 to work properly. The wrong encoding may be due to a non-UTF-8 locale or an improper PYTHONIOENCODING. (For the record, your locale language is zh_CN and locale encoding is gbk; your PYTHONIOENCODING is not set.)
Please set a UTF-8 locale (e.g., en_US.UTF-8) or set PYTHONIOENCODING to utf-8.
$ LC_CTYPE=zh_TW.Big5 googler hello
stdout encoding 'big5' detected. googler requires utf-8 to work properly. The wrong encoding may be due to a non-UTF-8 locale or an improper PYTHONIOENCODING. (For the record, your locale language is zh_TW and locale encoding is big5; your PYTHONIOENCODING is not set.)
Please set a UTF-8 locale (e.g., en_US.UTF-8) or set PYTHONIOENCODING to utf-8.
$ PYTHONIOENCODING=utf-16 googler hello
stdout encoding 'utf-16' detected. googler requires utf-8 to work properly. The wrong encoding may be due to a non-UTF-8 locale or an improper PYTHONIOENCODING. (For the record, your locale language is en_US and locale encoding is UTF-8; your PYTHONIOENCODING is utf-16.)
Please set a UTF-8 locale (e.g., en_US.UTF-8) or set PYTHONIOENCODING to utf-8.
```
This is a rather heavy-handed approach, but frankly I think it's much better than failing with a cryptic `UnicodeEncodeError`, which users then need to search about. (By the way, I tried a bunch of simple English words in US Google, and the results always contain non-ASCII characters, so the failure rate when stdout encoding isn't utf-8 is basically 100%.)
I'm not checking on win32 because
1. No one uses googler on win32;
2. I'm too lazy to check whether to expect `utf-8` or `cp65001`.
There's also a drive-by commit to eliminate the need of the `platform` module (in favor of consistent use of `sys.platform`).
[1] https://docs.python.org/3/library/sys.html#sys.stdout