base64 newlines - documentation (again)

[796bb27b-4e01-460d-b54e-084608b9e1b4]

BPO	547037
Nosy	@freddrake, @warsaw, @rhettinger
Files	base64.diff: Patch to libbase64.tex base64-2.diff: Revised patch to libbase64.tex base64-3.diff: Patch with Barry's wording

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields: ```python assignee = 'https://github.com/rhettinger' closed_at = created_at = labels = ['docs'] title = 'base64 newlines - documentation (again)' updated_at = user = 'https://bugs.python.org/prouse' ``` bugs.python.org fields: ```python activity = actor = 'rhettinger' assignee = 'rhettinger' closed = True closed_date = None closer = None components = ['Documentation'] creation = creator = 'p_rouse' dependencies = [] files = ['439', '440', '441'] hgrepos = [] issue_num = 547037 keywords = [] message_count = 12.0 messages = ['10465', '10466', '10467', '10468', '10469', '10470', '10471', '10472', '10473', '10474', '10475', '10476'] nosy_count = 4.0 nosy_names = ['fdrake', 'barry', 'rhettinger', 'p_rouse'] pr_nums = [] priority = 'normal' resolution = 'accepted' stage = None status = 'closed' superseder = None type = None url = 'https://bugs.python.org/issue547037' versions = ['Python 2.2'] ```

[796bb27b-4e01-460d-b54e-084608b9e1b4]

The documentation fix for bug 463330, describing the newline added by base64.encode and base64.encodestring appears to be incorrect!

The "courtesy newline" is appended to the result, not the input (at line 466 of binsacii.c), so it is *not* true that

base64.encodestring('hello') == base64.encodestring('hello\n')

In fact:

base64.encodestring('hello') == 'aGVsbG8=\n' base64.encodestring('hello\n') == 'aGVsbG8K\n'

This applies to documentation for 2.2 and 2.2.1, and actual behaviour has been checked in 2.2

[rhettinger]

Logged In: YES user_id=80475

Barry, is this the intended behavior or should the comment in the docs be eliminated? The conversation in www.python.org/sf/463330 was not clear to me on this point.

Confirmed:
>>> import base64
>>> v = base64.encodestring('hello!')
>>> w = base64.encodestring('hello!\n')
>>> v == w, v , w
(False, 'aGVsbG8h\n', 'aGVsbG8hCg==\n')

[warsaw]

Logged In: YES user_id=12800

The intended behavior is irrelevant \<wink>. Since this is how the base64 module works, it needs to be correctly documented. It's way too late to be changing this behavior, as broken as some might think it is.:)

Note that the email package has an RFC 2045-2047 compliant base64 encoding module called email.base64MIME. It currently isn't documented (but will be before 2.3 is released).

Reassigning to Fred so he can correct the base64 documentation.

[rhettinger]

Logged In: YES user_id=80475

Fred, is the attached patch okay to commit to 2.3 and release 22-maint?

[freddrake]

Logged In: YES user_id=3066

Barry, you're the MIME guru, tell Raymond whether he should check in his patch. ;-)

[warsaw]

Logged In: YES user_id=12800

I'm not sure the patch is sufficient. You need to at least explain that a newline is always added to the output.

[rhettinger]

Logged In: YES user_id=80475

Please approve the new patch.

[warsaw]

Logged In: YES user_id=12800

Actually, I realized encodestring() is a bit more subtle than that. I think what it actually does is "return a string containing one or more lines of base64-encoded data" always including an extra trailing newline.

[rhettinger]

Logged In: YES user_id=80475

Inserted new wording into patch below. Do you also want this backported to release22-maint?

[freddrake]

Logged In: YES user_id=3066

I think the patch should apply to both release21-maint and release22-maint as well as the trunk. I don't think this describes a recently introduced behavior in the base64 module.

[warsaw]

Logged In: YES user_id=12800

Fred's right, the behavior is long standing. I'm good with the patch. Reassigning to Raymond for application of patch, who should close this report once that's done.

[rhettinger]

Logged In: YES user_id=80475

Committed as libbase64.tex 1.21 and 1.20.6.1. Closing bug.