[docs] base64 "legacy" functions violate RFC 3548 (issue 1753718)

[vadmium+py at gmail.com]

http://bugs.python.org/review/1753718/diff/16149/Doc/library/base64.rst
File Doc/library/base64.rst (right):

http://bugs.python.org/review/1753718/diff/16149/Doc/library/base64.rst#newcode52
Doc/library/base64.rst:52: Optional *altchars* must be a
:term:`bytes-like object` of at least
On 2015/12/16 03:08:46, r.david.murray wrote:
> On 2015/12/14 03:39:33, vadmium wrote:
> > Safer to say it must be a bytes object. The code does an assert
using len().
> 
> Why is that an issue?  It accepts bytearray and memoryview, so saying
bytes
> object would be incorrect.

I think it is better to document a subset of what is accepted than a
superset. According the the glossary and the buffer protocol, a
bytes-like object does not have to implement len(). For memoryviews, I
think len() returns the number of array elements, not necessarily equal
to nbytes. I usually use ctypes to test for bytes-like support:

>>> class Alts(ctypes.Structure):
...     _fields_ = (("a", ctypes.c_char), ("b", ctypes.c_char))
... 
>>> byteslike = Alts(*b"{}")
>>> bytes(byteslike)
b'{}'
>>> b64encode(b"\xFF\xFF\xFF", altchars=byteslike)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/home/proj/python/cpython/Lib/base64.py", line 63, in b64encode
    assert len(altchars) == 2, repr(altchars)
TypeError: object of type 'Alts' has no len()

http://bugs.python.org/review/1753718/diff/16149/Doc/library/base64.rst#newcode53
Doc/library/base64.rst:53: length 2 (additional characters are ignored)
which specifies an alternative
Just noticed it has to be exactly two bytes long; same for b64decode()

http://bugs.python.org/review/1753718/diff/16149/Doc/library/base64.rst#newcode185
Doc/library/base64.rst:185: *ignorechars* should be a :term:`bytes-like
object` containing characters to ignore
On 2015/12/16 03:08:46, r.david.murray wrote:
> On 2015/12/14 03:39:33, vadmium wrote:
> > Safer to just say bytes; the code tests “x in ignorechars”
> 
> Again, why is this a problem?

>>> a85decode(" ", ignorechars=ctypes.create_string_buffer(b"
\t\n\r\v"))
/home/proj/python/cpython/Lib/base64.py:412: BytesWarning: Comparison
between bytes and int
  elif x in ignorechars:
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/home/proj/python/cpython/Lib/base64.py", line 416, in a85decode
    raise ValueError('Non-Ascii85 digit found: %c' % x)
ValueError: Non-Ascii85 digit found:

http://bugs.python.org/review/1753718/diff/16149/Doc/library/base64.rst#newcode233
Doc/library/base64.rst:233: Decode the :term:`bytes-like object` *s*,
which must contain one or more lines of base64
On 2015/12/16 03:08:46, r.david.murray wrote:
> On 2015/12/14 03:39:33, vadmium wrote:
> > The object must also be a one-dimensional array of bytes (c, b or B
format)
> 
> There was a lot of discussion around this when the terms were added to
and then
> modified in the glossary.  The actual requirement is a C contiguous
buffer
> (which the glossary defines), and if base64 actually requires it to be
one
> dimensional then that's a bug, either in the code or in the glossary.

Yes, I see now that this contradicts the “versionchanged:: 3.4”
statement at the top.

http://bugs.python.org/review/1753718/diff/16167/Doc/library/base64.rst
File Doc/library/base64.rst (right):

http://bugs.python.org/review/1753718/diff/16167/Doc/library/base64.rst#newcode48
Doc/library/base64.rst:48: .. function:: b64encode(s, aultchars=None)
Stray U got added here

http://bugs.python.org/review/1753718/