Support multiline output in binascii.b2a_base64() and base64.b64encode()

[serhiy-storchaka]

Feature or enhancement

According to RFC 4648, section 3.1:

Implementations MUST NOT add line feeds to base-encoded data unless
the specification referring to this document explicitly directs base
encoders to add line feeds after a specific number of characters.

But many specifications use Base 64 separated on lines of fixed length. The stdlib code contains multiple functions that take the Base 64 data and split it on multiple lines. It is worth to add a special support of this in the base functions that encode to Base 64 -- to improve maintenability (there is a known bug in email.base64mime.body_encode()), convenience and performance.

I choose name wrapcol for the parameter because it is already used in base64.a85encode(). Other (mostly private) functions that implement the Base 64 wrapping use different names: maxlinelen, maxlen, max_line_length. PR #102753 propose name width for binascii.b2a_ascii85() (it is also used in textwrap). So there is no consistency or single dominant option, but I am open for suggestions.

Linked PRs

• gh-143214: Add the wrapcol parameter in binascii.b2a_base64() and base64.b64encode() #143216

[picnixz]

Usually I like parameters with short names because I don't need to wrap lines if I exceed the max line length. Ideally, I would have an explanatory name like "max_line_length", but I think wrapcol or maxcols is good. Note that the Unix base64 util uses --wrap=COLS for wrapping the output while xxd uses -c cols for wrapping. So including the notion of a "colunn" instead of of line/width seems better to me. Thus, I'm inclined to "colwrap=..." (instead of wrapcol), then "maxcols", and "width" for parity with textwrap (which may also be a strong argument for).

[cmaloney]

This is similar to gh-141966; wrapcol works as a name for me. Happy for this issue to implement/ship. Ideally this should be usable for the cases in base64, email.contentmanager, imaplib, and plistlib.

[serhiy-storchaka]

Oh, I searched for base64 issues, but missed your issue at the top of the list due to my sight condition.

Yes, #143216 utilizes the new argument in all these modules.

[serhiy-storchaka]

Oh, it is binascii.b2a_hex() that have a bytes_per_sep parameter with weird semantic. Anyway, it is not usable for Base 64 and other encodings which encode a byte in non-integer number of characters. Is is also not usable for Ascii 85 with variable characters-per-byte ratio. Control the number of characters per line in the output is more practical.