Mailman 3 February 2020 - docs

[issue21547] '!s' formatting documentation bug
by Joshua Landau May 31, 2020

May 31, 2020

New submission from Joshua Landau: In the docs for 2.x about the formatting syntax: https://docs.python.org/2/library/string.html#format-string-syntax it says "Two conversion flags are currently supported: '!s' which calls str() on the value, and '!r' which calls repr()." but for unicode formatters, '!s' calls unicode() instead. See http://stackoverflow.com/questions/23773816/why-python-str-format-doesnt-ca… for the question that found this. ---------- assignee: docs@python components: Documentation messages: 218863 nosy: Joshua.Landau, docs@python priority: normal severity: normal status: open title: '!s' formatting documentation bug versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue21547> _______________________________________

5 4

[issue9196] Improve docs for string interpolation "%s" re Unicode strings
by Craig McQueen May 31, 2020

May 31, 2020

New submission from Craig McQueen <python(a)craig.mcqueen.id.au>: I have just been trying to figure out how string interpolation works for "%s", when Unicode strings are involved. It seems it's a bit complicated, but the Python documentation doesn't really describe it. It just says %s "converts any Python object using str()". Here is what I have found (I think), and it could be worth improving the documentation of this somehow. Example 1: "%s" % test_object >From what I can tell, in this case: 1. test_object.__str__() is called. 2. If test_object.__str__() returns a string object, then that is substituted. 3. If test_object.__str__() returns a Unicode object (for some reason), then test_object.__unicode__() is called, then _that_ is substituted instead. The output string is turned into Unicode. This behaviour is surprising. [Note that the call to test_object.__str__() is not the same as str(test_object), because the former can return a Unicode object without causing an error, while the latter, if it gets a Unicode object, will then try to encode('ascii') to a string, possibly generating a UnicodeEncodeError exception.] Example 2: u"%s" % test_object In this case: 1. test_object.__unicode__() is called, if it exists, and the result is substituted. The output string is Unicode. 2. If test_object.__unicode__() doesn't exist, then test_object.__str__() is called instead, converted to Unicode, and substituted. The output string is Unicode. Example 3: "%s %s" % (u'unicode', test_object) In this case: 1. The first substitution causes the output string to be Unicode. 2. It seems that (1) causes the second substitution to follow the same rules as Example 2. This is a little surprising. ---------- assignee: docs@python components: Documentation messages: 109516 nosy: cmcqueen1975, docs@python priority: normal severity: normal status: open title: Improve docs for string interpolation "%s" re Unicode strings versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9196> _______________________________________

5 10

[issue20686] Confusing statement
by Daniel U. Thibault May 31, 2020

May 31, 2020

New submission from Daniel U. Thibault: Near the end of 3.1.3 http://docs.python.org/2/tutorial/introduction.html#unicode-strings you can read: "When a Unicode string is printed, written to a file, or converted with str(), conversion takes place using this default encoding." This can be interpreted as stating that stating that printing a Unicode string (using the print function or the shell's default print behaviour) results in ASCII printout. It can likewise be interpreted as stating that any write of a Unicode string to a file converts the string to ASCII. Experimentation shows this is not true. Perhaps you meant something like this: "When a Unicode string is converted with str() in order to be printed or written to a file, conversion takes place using this default encoding." Grammatical comments: In the statement "When a Unicode string is printed, written to a file, or converted with str(), conversion takes place using this default encoding.", the ", or" puts the three elements of the enumeration on the same level (respectively "printed", "written to a file", and "converted with str()"). The confusion seems to arise because "with str()" was meant to apply to the list as a whole, not just its last element. ---------- assignee: docs@python components: Documentation messages: 211627 nosy: Daniel.U..Thibault, docs@python priority: normal severity: normal status: open title: Confusing statement type: enhancement _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue20686> _______________________________________

4 9

[issue17387] Error in C API documentation of PySequenceMethods
by Alex Orange May 31, 2020

May 31, 2020

New submission from Alex Orange: The documentation at http://docs.python.org/2/c-api/typeobj.html#PySequenceMethods is missing sq_slice between sq_item and sq_ass_item. This will mess up anyone trying to use anything after sq_item (that isn't using designated initializers). ---------- assignee: docs@python components: Documentation messages: 183779 nosy: Alex.Orange, docs@python priority: normal severity: normal status: open title: Error in C API documentation of PySequenceMethods versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue17387> _______________________________________

5 10

[issue15952] format(value) and value.__format__() behave differently with unicode format
by Chris Jerdonek May 31, 2020

May 31, 2020

New submission from Chris Jerdonek: format(value) and value.__format__() behave differently even though the documentation says otherwise: "Note: format(value, format_spec) merely calls value.__format__(format_spec)." (from http://docs.python.org/library/functions.html?#format ) The difference happens when the format string is unicode. For example: >>> format(10, u'n') u'10' >>> (10).__format__(u'n') # parentheses needed to prevent SyntaxError '10' So either the documentation should be changed, or the behavior should be changed to match. Related to this: neither the "Format Specification Mini-Language" documentation nor the string.Formatter docs seem to say anything about the effect that a unicode format string should have on the return value (in particular, should it cause the return value to be unicode or not): http://docs.python.org/library/string.html#formatspec http://docs.python.org/library/string.html#string-formatting See also issue 15276 (int formatting), issue 15951 (empty format string), and issue 7300 (unicode arguments). ---------- assignee: docs@python components: Documentation messages: 170575 nosy: cjerdonek, docs@python priority: normal severity: normal status: open title: format(value) and value.__format__() behave differently with unicode format type: behavior versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15952> _______________________________________

5 8

[issue26369] doc for unicode.decode and str.encode is unnecessarily confusing
by Ben Spiller May 30, 2020

May 30, 2020

New submission from Ben Spiller: It's well known that lots of people struggle writing correct programs using non-ascii strings in python 2.x, but I think one of the main reasons for this could be very easily fixed with a small addition to the documentation for str.encode and unicode.decode, which is currently quite vague. The decode/encode methods really make most sense when called on a unicode string i.e. unicode.encode() to produce a byte string, or on a byte string e.g. str.decode() to produce a unicode object from a byte string. However, the additional presence of the opposite methods str.encode() and unicode.decode() is quite confusing, and a frequent source of errors - e.g. calling str.encode('utf-8') first DECODES the str object (which might already be in utf8) to a unicode string **using the default encoding of "ascii"** (!) before ENCODING to a utf-8 byte str as requested, which of course will fail at the first stage with the classic error "UnicodeDecodeError: 'ascii' codec can't decode byte" if there are any non-ascii chars present. It's unfortunate that this initial decode/encode stage ignores both the "encoding" argument (used only for the subsequent encode/decode) and the "errors" argument (commonly used when the programmer is happy with a best-effort conversion e.g. for logging purposes). Anyway, given this behaviour, a lot of time would be saved by a simple sentence on the doc for str.encode()/unicode.decode() essentially warning people that those methods aren't that useful and they probably really intended to use str.decode()/unicode.encode() - the current doc gives absolutely no clue about this extra stage which ignores the input arguments and sues 'ascii' and 'strict'. It might also be worth stating in the documentation that the pattern (u.encode(encoding) if isinstance(u, unicode) else u) can be helpful for cases where you unavoidably have to deal with both kinds of input, string calling str.encode is such a bad idea. In an ideal world I'd love to see the implementation of str.encode/unicode.decode changed to be more useful (i.e. instead of using ascii, it would be more logical and useful to use the passed-in encoding to perform the initial decode/encode, and the apss-in 'errors' value). I wasn't sure if that change would be accepted so for now I'm proposing better documentation of the existing behaviour as a second-best. ---------- assignee: docs@python components: Documentation messages: 260359 nosy: benspiller, docs@python priority: normal severity: normal status: open title: doc for unicode.decode and str.encode is unnecessarily confusing type: behavior versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue26369> _______________________________________

7 16

[issue31869] commentary on ssl.PROTOCOL_TLS
by J Sloot May 30, 2020

May 30, 2020

New submission from J Sloot <jsloot(a)gmail.com>: on https://docs.python.org/2/library/ssl.html#ssl.PROTOCOL_TLS for ssl.PROTOCOL_TLS When the commentary from ssl.PRTOCOL_TLS moved from PROTOCOL_SSLv23 to PROTOCOL_TLS the note {Despite the name, this option can select "TLS" protocols as well as "SSL"} didn't change. Suggested new wording {Despite the name, this option can select "SSL" protocols as well as "TLS"} ---------- assignee: docs@python components: Documentation messages: 304996 nosy: J Sloot, docs@python priority: normal severity: normal status: open title: commentary on ssl.PROTOCOL_TLS versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue31869> _______________________________________

5 6

[issue29017] Docs: PySide is provided by 'The Qt Company' and not by 'Nokia'
by Ettore Atalan May 30, 2020

May 30, 2020

New submission from Ettore Atalan: Regarding URL: http://docs.python.org/3/library/othergui.html Section: PySide PySide is provided by 'The Qt Company' and no longer by 'Nokia' like mentioned in the documentation. ---------- assignee: docs@python components: Documentation messages: 283646 nosy: Ettore Atalan, docs@python priority: normal severity: normal status: open title: Docs: PySide is provided by 'The Qt Company' and not by 'Nokia' versions: Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue29017> _______________________________________

4 8

[issue37218] Default hmac.new() digestmod has not been removed from documentation
by Alex Willmer May 28, 2020

May 28, 2020

New submission from Alex Willmer <alex(a)moreati.org.uk>: Until Python 3.8 hmc.new() defaulted the digestmod argument to 'hmac-md5'. This was deperecated, to be removed in Python 3.8. In Python 3.8.0b1 it is gone, e.g. Python 3.8.0b1 (default, Jun 6 2019, 03:44:52) [GCC 7.4.0] on linux Type "help", "copyright", "credits" or "license" for more information. >>> import hmac >>> hmac.new(b'qwertyuiop').name Traceback (most recent call last): File "<stdin>", line 1, in <module> File "/usr/lib/python3.8/hmac.py", line 146, in new return HMAC(key, msg, digestmod) File "/usr/lib/python3.8/hmac.py", line 49, in __init__ raise ValueError('`digestmod` is required.') ValueError: `digestmod` is required. but the deprecation note, and the documented signature haven't been updated. PR incoming ---------- assignee: docs@python components: Documentation messages: 345144 nosy: Alex.Willmer, docs@python priority: normal severity: normal status: open title: Default hmac.new() digestmod has not been removed from documentation versions: Python 3.8, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue37218> _______________________________________

4 5

[issue37878] sub-ineterpreters : Document PyThreadState_DeleteCurrent() ?
by Joannah Nanjekye May 28, 2020

May 28, 2020

New submission from Joannah Nanjekye <nanjekyejoannah(a)gmail.com>: I just noticed that PyThreadState_DeleteCurrent()in Python/pystate.c is not documented. Relevant documentation should go in Doc/c-api/init.rst If no one objects to this. ---------- assignee: docs@python components: Documentation keywords: easy messages: 349881 nosy: docs@python, eric.snow, nanjekyejoannah, ncoghlan, vstinner priority: normal severity: normal stage: needs patch status: open title: sub-ineterpreters : Document PyThreadState_DeleteCurrent() ? versions: Python 3.8, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue37878> _______________________________________

5 24