comparing with https://hg.python.org/cpython
searching for changes
changeset:   95795:68a9a267d2cc
bookmark:    base64-docs-1753718
tag:         tip
user:        Isobel Hooper <isobel.hooper@gmail.com>
date:        Mon May 04 17:37:50 2015 +0100
summary:     Issue #1753718: base64 "legacy" functions violate RFC 3548

diff -r b871ace5c58f -r 68a9a267d2cc Doc/library/base64.rst
--- a/Doc/library/base64.rst	Sat Apr 25 00:21:52 2015 +0200
+++ b/Doc/library/base64.rst	Mon May 04 17:37:50 2015 +0100
@@ -21,13 +21,21 @@
 POST request.  The encoding algorithm is not the same as the
 :program:`uuencode` program.
 
-There are two :rfc:`3548` interfaces provided by this module.  The modern
+There are two interfaces provided by this module.  The modern
 interface supports encoding and decoding ASCII byte string objects using all
 three :rfc:`3548` defined alphabets (normal, URL-safe, and filesystem-safe).
 Additionally, the decoding functions of the modern interface also accept
-Unicode strings containing only ASCII characters. The legacy interface provides
-for encoding and decoding to and from file-like objects as well as byte
-strings, but only using the Base64 standard alphabet.
+Unicode strings containing only ASCII characters. The modern interface, as per
+:rfc:`3548`, does not break the output into multiple lines.
+
+The legacy interface provides for encoding and decoding to and from file-like 
+objects as well as byte strings, but only using the Base64 standard alphabet,
+and adds newlines every 76 characters as per :rfc:`2045`. Thus, the legacy 
+interface does not implement :rfc:`3548`.
+
+If you are encoding data for email attachments and wondering which to use,
+you can use the legacy functions, but you should probably be using the 
+:mod:`email` package instead.
 
 .. versionchanged:: 3.3
    ASCII-only Unicode strings are now accepted by the decoding functions of
@@ -236,6 +244,9 @@
    an empty bytes object. :func:`encode` returns the encoded data plus a trailing
    newline character (``b'\n'``).
 
+   Newlines will be inserted into the output every 76 characters, as per :rfc:`2045`
+   (MIME).
+
 
 .. function:: encodebytes(s)
               encodestring(s)
@@ -246,6 +257,9 @@
    base64-encoded data always including an extra trailing newline (``b'\n'``).
    ``encodestring`` is a deprecated alias.
 
+   Newlines will be inserted into the output every 76 characters, as per :rfc:`2045`
+   (MIME).
+
 
 An example usage of the module:
 
diff -r b871ace5c58f -r 68a9a267d2cc Doc/library/binascii.rst
--- a/Doc/library/binascii.rst	Sat Apr 25 00:21:52 2015 +0200
+++ b/Doc/library/binascii.rst	Mon May 04 17:37:50 2015 +0100
@@ -55,8 +55,8 @@
 .. function:: b2a_base64(data)
 
    Convert binary data to a line of ASCII characters in base64 coding. The return
-   value is the converted line, including a newline char. The length of *data*
-   should be at most 57 to adhere to the base64 standard.
+   value is the converted line, including a newline char. The output conforms to
+   the base64 standard in :rfc:`3548`.
 
 
 .. function:: a2b_qp(string, header=False)