Document the peculiarity of using rb as the default open mode

[mpenkov]

By default, smart_open specifies the open mode to be rb. This is in contrast to the default r in both Py2 and Py3.

smart_open needs to quack like the built-in open. While the above discrepancy is not fatal, it complicates our implementation. For example, in Py3 the following raises an Exception:

>>> q = open("/dev/null", 'rb', encoding='utf-8')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: binary mode doesn't take an encoding argument

We cannot do the same, because we cannot tell the difference between:

1. User specified rb mode explicitly (as above)
2. User didn't specify a mode, and the default rb was set by smart_open

We should document the above somewhere central (like a project wiki) to make it obvious to future developers.

[piskvorky]

Yeah, I agree smart_open should "quack like open".

IIRC the rationale behind the rb default was that it's saner than r (we repeatedly saw novice Python users struggle with r, not understanding the difference). But since open uses r, we should use it too. We're stuck with it.

I'm +1 on changing the smart_open default (or any other defaults) to match the built-in. Backward compatibility shouldn't be an issue, because this was undocumented and people expected r anyway.