Mailman 3 December 2015 - docs

[issue25865] 7.2 Assignment statements documentation is vague and slightly misleading
by Andrew Barnert Dec. 15, 2015

Dec. 15, 2015

New submission from Andrew Barnert: >From https://docs.python.org/3/reference/simple_stmts.html#assignment-statements > If the target list contains one target prefixed with an asterisk, called a “starred” target: The object must be a sequence with at least as many items as there are targets in the target list, minus one. The first items of the sequence are assigned, from left to right, to the targets before the starred target. The final items of the sequence are assigned to the targets after the starred target. A list of the remaining items in the sequence is then assigned to the starred target (the list can be empty). > Else: The object must be a sequence with the same number of items as there are targets in the target list, and the items are assigned, from left to right, to the corresponding targets. The word "sequence" is used here multiple times. But the object being assigned to the target list can be any iterable (including an iterator, a set, some weird custom iterable you invent, ...). > If the target is a target list enclosed in parentheses or in square brackets: The object must be an iterable with the same number of items as there are targets in the target list, and its items are assigned, from left to right, to the corresponding targets. This doesn't mention that you can have a starred target inside the parenthesized or bracketed target list. More importantly, it covers the exact same case already covered above. There's semantics for "assignment of an object to a target list, optionally enclosed in parentheses or square brackets", and then semantics for "Assignment of an object to a single target... If the target is a target list enclosed in parentheses or in square brackets". According to the grammar, a single target (no commas, parens, or brackets) is a target list, but according to the previous paragraphs it seems like it isn't. Finally, there's nothing that explains what distinguishes between target list assignment and single target assignment. As far as I can tell, it's treated as a target list iff there's a comma, or there's square brackets around it (similar to the fact that tuples are defined by commas, but lists by square brackets--but without the exception for `()`); that should probably be documented. There's also some needless repetition there. I think better wording might be something like this: > Assignment is recursively defined as follows. > * If the target list is a comma-separated list of two or more targets, optionally enclosed in parentheses, or a comma-separated list of zero or more targets enclosed in square brackets: (It might be worth having a note here pointing out that these are almost the same rules for non-comprehension tuple and list displays, except that () is a tuple but not a target list. Or would that just be confusing?) (It might also be worth mentioning that this is the same feature referred to as "iterable unpacking", "sequence unpacking", and/or "tuple unpacking" in PEP 3132, the official tutorial, and lots of non-official materials?) > ** If the target list contains one target prefixed with an asterisk, called a “starred” target: The object must be an iterable with at least as many items as there are targets in the target list, minus one. The first items of the iterable are assigned, from left to right, to the targets before the starred target. The final items of the iterable are assigned to the targets after the starred target. A list of the remaining items in the iterable is then assigned to the starred target (the list can be empty). > ** Else: The object must be an iterable with the same number of items as there are targets in the target list, and the items are assigned, from left to right, to the corresponding targets. > * Otherwise, the target list is treated as a single target. > ** If the target is an identifier (name): ... (No section on bracketed target list here; that's already covered above.) > ** If the target is an attribute reference: ... > ** ... ---------- assignee: docs@python components: Documentation messages: 256443 nosy: abarnert, docs@python priority: normal severity: normal status: open title: 7.2 Assignment statements documentation is vague and slightly misleading _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue25865> _______________________________________

2 2

[issue1753718] base64 "legacy" functions violate RFC 3548
by R. David Murray Dec. 14, 2015

Dec. 14, 2015

R. David Murray added the comment: I missed the other comments somehow. Will take a look soon. ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue1753718> _______________________________________

1 0

[issue1753718] base64 "legacy" functions violate RFC 3548
by Martin Panter Dec. 14, 2015

Dec. 14, 2015

Martin Panter added the comment: The change to readline() works well. Any thoughts regarding my other comments? In particular, altchars and ignorechars cannot be arbitrary bytes-like objects. ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue1753718> _______________________________________

1 0

[issue1753718] base64 "legacy" functions violate RFC 3548
by R. David Murray Dec. 14, 2015

Dec. 14, 2015

R. David Murray added the comment: Updated patch. ---------- Added file: http://bugs.python.org/file41306/issue-01753718.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue1753718> _______________________________________

1 0

[issue1753718] base64 "legacy" functions violate RFC 3548
by R. David Murray Dec. 14, 2015

Dec. 14, 2015

R. David Murray added the comment: How about we just make the docs more correct and say that input is read until readline() returns an empty bytes object? That should make it clear that a line-oriented file is expected. ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue1753718> _______________________________________

1 0

Re: [docs] base64 "legacy" functions violate RFC 3548 (issue 1753718)
by vadmium+py＠gmail.com Dec. 14, 2015

Dec. 14, 2015

https://bugs.python.org/review/1753718/diff/16149/Doc/library/base64.rst File Doc/library/base64.rst (right): https://bugs.python.org/review/1753718/diff/16149/Doc/library/base64.rst#ne… Doc/library/base64.rst:197: If *pad* is true, the input is padded with "\\0" so its length is a padded with b"\\0" https://bugs.python.org/review/1753718/diff/16149/Doc/library/base64.rst#ne… Doc/library/base64.rst:198: multiple of 4 characters before encoding. four bytes https://bugs.python.org/review/1753718/

1 0

[issue20837] Ambiguity words in base64 documentation
by INADA Naoki Dec. 14, 2015

Dec. 14, 2015

New submission from INADA Naoki: http://docs.python.org/3/library/base64.html > The modern interface supports encoding and decoding ASCII byte string objects using all three alphabets. What "all three alphabets" means? I think it is about *altchars*. But the sentence is too ambiguous to translate it in Japanese. ---------- assignee: docs@python components: Documentation messages: 212604 nosy: docs@python, naoki priority: normal severity: normal status: open title: Ambiguity words in base64 documentation versions: Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue20837> _______________________________________

6 8

[issue1753718] base64 "legacy" functions violate RFC 3548
by Martin Panter Dec. 14, 2015

Dec. 14, 2015

Martin Panter added the comment: Left some review comments. I left a comment about the original patch as well, because I didn’t notice the new patch in time :) Also, maybe we should say the input to the “legacy” MIME decode() function should be multiple lines, since it calls readline() with no line limit. ---------- nosy: +martin.panter _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue1753718> _______________________________________

1 0

Re: [docs] base64 "legacy" functions violate RFC 3548 (issue 1753718)
by vadmium+py＠gmail.com Dec. 14, 2015

Dec. 14, 2015

Mainly comments about data types accepted. Previous comment was made before I noticed the new patch. 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#new… Doc/library/base64.rst:30: In addition to the above, the legacy interface also provides for encoding and This is a bit misleading, e.g. the “legacy” interface doesn’t accept str objects. http://bugs.python.org/review/1753718/diff/16149/Doc/library/base64.rst#new… Doc/library/base64.rst:52: Optional *altchars* must be a :term:`bytes-like object` of at least Safer to say it must be a bytes object. The code does an assert using len(). http://bugs.python.org/review/1753718/diff/16149/Doc/library/base64.rst#new… Doc/library/base64.rst:61: Decode the Base64 encoded :term:`bytes-like object` *s* and return or ASCII str http://bugs.python.org/review/1753718/diff/16149/Doc/library/base64.rst#new… Doc/library/base64.rst:64: Optional *altchars* must be a :term:`bytes-like object` of The code goes out of its way to also support ASCII character strings http://bugs.python.org/review/1753718/diff/16149/Doc/library/base64.rst#new… Doc/library/base64.rst:85: Decode :term:`bytes-like object` *s* using the standard Base64 alphabet or ASCII str http://bugs.python.org/review/1753718/diff/16149/Doc/library/base64.rst#new… Doc/library/base64.rst:99: Decode :term:`bytes-like object` *s* using a URL-safe alphabet, which or ASCII str http://bugs.python.org/review/1753718/diff/16149/Doc/library/base64.rst#new… Doc/library/base64.rst:112: Decode the Base32 encoded :term:`bytes-like object` *s* and return or ASCII str http://bugs.python.org/review/1753718/diff/16149/Doc/library/base64.rst#new… Doc/library/base64.rst:139: Decode the Base16 encoded :term:`bytes-like object` *s* and return the or ASCII str http://bugs.python.org/review/1753718/diff/16149/Doc/library/base64.rst#new… Doc/library/base64.rst:175: Decode the Ascii85 encoded :term:`bytes-like object` *s* and return or ASCII str http://bugs.python.org/review/1753718/diff/16149/Doc/library/base64.rst#new… Doc/library/base64.rst:185: *ignorechars* should be a :term:`bytes-like object` containing characters to ignore Safer to just say bytes; the code tests “x in ignorechars” http://bugs.python.org/review/1753718/diff/16149/Doc/library/base64.rst#new… Doc/library/base64.rst:205: Decode the base85-encoded :term:`bytes-like object` *b* and return or ASCII str http://bugs.python.org/review/1753718/diff/16149/Doc/library/base64.rst#new… Doc/library/base64.rst:233: Decode the :term:`bytes-like object` *s*, which must contain one or more lines of base64 The object must also be a one-dimensional array of bytes (c, b or B format) http://bugs.python.org/review/1753718/diff/16149/Doc/library/base64.rst#new… Doc/library/base64.rst:234: encoded data, and return the decoded :class:`bytes` ``decodestring`` is a deprecated alias. Dropped a full stop. Which is why I like starting sentences with capital letters :) http://bugs.python.org/review/1753718/diff/16149/Doc/library/base64.rst#new… Doc/library/base64.rst:252: Encode the :term:`bytes-like object` *s*, which can contain arbitrary binary Same 1-D byte array restriction applies http://bugs.python.org/review/1753718/

1 0

base64 "legacy" functions violate RFC 3548 (issue 1753718)
by vadmium+py＠gmail.com Dec. 14, 2015

Dec. 14, 2015

http://bugs.python.org/review/1753718/diff/16115/Doc/library/base64.rst File Doc/library/base64.rst (right): http://bugs.python.org/review/1753718/diff/16115/Doc/library/base64.rst#new… Doc/library/base64.rst:34: interface does not implement :rfc:`3548`. In my mind, MIME’s transfer encoding is an application of RFC 3548; it does implement base 64 under the covers. The real point is it just adds line breaking on top. What about: “. . . and adds newlines every 76 characters. The legacy interface implements MIME’s *base64* transfer encoding, as per :rfc:`2045`.” http://bugs.python.org/review/1753718/

1 0