Mailman 3 March 2020 - docs

[issue34451] docs: tutorial/introduction doesn't mention toggle of prompts
by Jonathan Fine 06 Jan '21

06 Jan '21

New submission from Jonathan Fine <jfine2358(a)gmail.com>: Interactive code examples need the prompt to be stripped, before copy-and-paste. This is explained in https://docs.python.org/3/tutorial/introduction.html But this page does not tell us about the [>>>] prompt-toggle at top of each interactive code example. This caused a user error, reported in https://mail.python.org/pipermail/python-ideas/2018-August/052869.html. The [>>>] toggle isn't in the Python 2.7 docs, so nothing to fix there! ---------- assignee: docs@python components: Documentation messages: 323839 nosy: docs@python, jfine2358 priority: normal severity: normal status: open title: docs: tutorial/introduction doesn't mention toggle of prompts versions: Python 3.4, Python 3.5, Python 3.6, Python 3.7, Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue34451> _______________________________________

5 6

[issue8595] Unexpected default timeout in http-client-related libraries
by Julian 29 Dec '20

29 Dec '20

New submission from Julian <python_org(a)somethinkodd.com>: Since Python 2.6, httplib has offered a timeout parameter for fetches. As the documentation explains, if this parameter is not provided, it uses the global default. What the document doesn't explain is httplib builds on top of the socket library. The socket library has a default timeout of None (i.e. forever). This may be an appropriate default for general sockets, but it is a poor default for httplib; typical http clients would use a timeout in the 2-10 second range. This problem is propagated up to urllib2, which sits on httplib, and further obscures that the default might be unsuitable. >From an inspection of the manuals, Python 3.0.1 suffers from the same problem except, the names have changed. urllib.response sits on http.client. I, for one, made a brutal mistake of assuming that the "global default" would be some reasonable default for fetching web pages; I didn't have any specific timeout in mind, and was happy for the library to take care of it. Several million successful http downloads later, my server application thread froze waiting forever when talking to a recalcitrant web-server. I imagine others have fallen for the same trap. While an ideal solution would be for httplib and http.client to use a more generally acceptable default, I can see it might be far too late to make such a change without breaking existing applications. Failing that, I would recommend that the documentation for httplib, urllib, urllib2, http.client and urllib.request (+ any other similar libraries sitting on socket? FTP, SMTP?) be changed to highlight that the default global timeout, sans deliberate override, is to wait a surprisingly long time. ---------- assignee: docs@python components: Documentation, Library (Lib) messages: 104763 nosy: docs@python, oddthinking priority: normal severity: normal status: open title: Unexpected default timeout in http-client-related libraries type: behavior versions: Python 2.6, Python 2.7, Python 3.1 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue8595> _______________________________________

5 8

[issue8822] datetime naive and aware types should have a well-defined definition that can be cross-referenced
by anatoly techtonik 29 Dec '20

29 Dec '20

New submission from anatoly techtonik <techtonik(a)gmail.com>: 'naive' and 'aware' are key datetime types - they need a proper definition and anchor for crossrefences. If you take a look at http://docs.python.org/library/datetime.html - the definition of distinction between them is too vague and this seeds of uncertainty grow through the rest of the doc. It is not said how to make non-naive object, how to detect if object of naive or aware. All this stuff is very important for troubleshooting datetims issues in Python projects. It needs a proper documentation. ---------- assignee: docs@python components: Documentation messages: 106524 nosy: docs@python, techtonik priority: normal severity: normal status: open title: datetime naive and aware types should have a well-defined definition that can be cross-referenced _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue8822> _______________________________________

6 15

[issue38649] tkinter messagebox is sloppy
by David Lambert 25 Dec '20

25 Dec '20

New submission from David Lambert <b49p23tivg(a)gmail.com>: Does aksokcancel return "true" or True ? The docstring should say True This is pervasive throughout the module. tkinter has such a mishmash of numbers supplied as strings, strings supplied as constants making this carelessness egregious. On the topic of constants, the messagebox module redefines OK. You might argue that the definition didn't change. I suspect this issue applies to all versions of tkinter or Tkinter having the messagebox. # types ABORTRETRYIGNORE = "abortretryignore" OK = "ok" ... # replies ... OK = "ok" def askokcancel(title=None, message=None, **options): "Ask if operation should proceed; return true if the answer is ok" s = _show(title, message, QUESTION, OKCANCEL, **options) return s == OK ---------- assignee: docs@python components: Documentation messages: 355729 nosy: David Lambert, docs@python priority: normal severity: normal status: open title: tkinter messagebox is sloppy type: enhancement versions: Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue38649> _______________________________________

3 4

[issue32501] Documentation for dir([object])
by Vladislavs Burakovs 24 Dec '20

24 Dec '20

New submission from Vladislavs Burakovs <solomonchild(a)gmail.com>: Documentation page [1] says "If the object has a method named __dir__(), this method will be called and must return the list of attributes.". It seems that on Python 3.6 it only works if the *class* has a method named __dir__. Should the documentation be changed? Microsoft Windows [Version 10.0.16299.192] (c) 2017 Microsoft Corporation. All rights reserved. D:\Users\wlad>python Python 3.6.4 (v3.6.4:d48eceb, Dec 19 2017, 06:04:45) [MSC v.1900 32 bit (Intel)] on win32 Type "help", "copyright", "credits" or "license" for more information. >>> class C: pass ... >>> x = C() >>> import types >>> x.__dir__ = types.MethodType(lambda _:[], x) >>> dir(x) ['__class__', '__delattr__', '__dict__', '__dir__', '__doc__', '__eq__', '__format__', '__ge__', '__getattribute__', '__gt__', '__hash__', '__init__', '__init_subclass__', '__le__', '__lt__', '__module__', '__ne__', '__new__', '__reduce__', '__reduce_ex__', '__repr__', '__setattr__', '__sizeof__', '__str__', '__subclasshook__', '__weakref__'] >>> C.__dir__ = types.MethodType(lambda _:[], x) >>> dir(x) [] [1] https://docs.python.org/3/library/functions.html ---------- assignee: docs@python components: Documentation messages: 309544 nosy: Vladislavs Burakovs, docs@python priority: normal severity: normal status: open title: Documentation for dir([object]) type: enhancement versions: Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue32501> _______________________________________

5 6

[issue35783] incorrect example of fetching messages in imaplib documentation
by Макс Вернер 22 Dec '20

22 Dec '20

New submission from Макс Вернер <mvarnar(a)gmail.com>: An example of fetching messages from the mailbox given in "IMAP4 Example" section is incorrect: typ, data = M.fetch(num, '(RFC822)') print('Message %s\n%s\n' % (num, data[0][1])) "fetch" may return server data that was not requested (see "7.4.2. FETCH Response" section of RFC 3501). In that case "data[0][1]" won't return what user expects. This is a bad example, that many people repeat and advise to other developers: https://stackoverflow.com/questions/13210737/get-only-new-emails-imaplib-an… https://gist.github.com/robulouski/7441883 https://stackoverflow.com/questions/51098962/check-if-email-inbox-is-empty-… https://stackoverflow.com/questions/21116498/imaplib-not-getting-all-emails… https://stackoverflow.com/questions/2230037/how-to-fetch-an-email-body-usin… I guess, this peculiarity should be clarified in the documentation. I offer to mark this fetching method is not safe and requests careful fetch result parsing. ---------- assignee: docs@python components: Documentation, email messages: 334048 nosy: barry, docs@python, r.david.murray, Макс Вернер priority: normal severity: normal status: open title: incorrect example of fetching messages in imaplib documentation type: enhancement versions: Python 2.7, Python 3.5, Python 3.6, Python 3.7, Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue35783> _______________________________________

2 1

[issue35790] Correct a statement about sys.exc_info() values restoration
by Géry 21 Dec '20

21 Dec '20

New submission from Géry <gery.ogam(a)gmail.com>: In the documentation of the try statement (https://docs.python.org/3/reference/compound_stmts.html#the-try-statement), I think that the sentence: "sys.exc_info() values are restored to their previous values (before the call) when returning from a function that handled an exception." should be replaced by this sentence: "sys.exc_info() values are restored to their previous values (before the call) when leaving an exception handler." as proven by this code which does not use any "function that handled an exception" and yet restores sys.exc_info() values: >>> try: ... raise ValueError ... except: ... try: ... raise TypeError ... except: ... print(sys.exc_info()) ... print(sys.exc_info()) ... (<class 'TypeError'>, TypeError(), <traceback object at 0x10ca19bc8>) (<class 'ValueError'>, ValueError(), <traceback object at 0x10ca19c08>) ---------- assignee: docs@python components: Documentation messages: 334092 nosy: docs@python, eric.araujo, ezio.melotti, maggyero, mdk, willingc priority: normal severity: normal status: open title: Correct a statement about sys.exc_info() values restoration versions: Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue35790> _______________________________________

2 6

[issue37717] argparse subcommand docs has non-existent parameter "action"
by retnikt 19 Dec '20

19 Dec '20

New submission from retnikt <retnikt(a)gmail.com>: In the library documentation for argparse, the section for ArgumentParser.add_subparsers ( https://docs.python.org/3/library/argparse.html#sub-commands ) states that there is a parameter for 'action' with the description 'the basic type of action to be taken when this argument is encountered at the command line'. However, no such parameter actually exists, and passing it to the function causes very strange behaviour: Traceback (most recent call last): File "<stdin>", line 1, in <module> File "/usr/lib/python3.6/argparse.py", line 1716, in add_subparsers action = parsers_class(option_strings=[], **kwargs) TypeError: __init__() got an unexpected keyword argument 'parser_class' This line should be removed from the documentation. It is present in versions 3.4+ and 2.7 ---------- assignee: docs@python components: Documentation messages: 348718 nosy: docs@python, retnikt priority: normal severity: normal status: open title: argparse subcommand docs has non-existent parameter "action" type: behavior versions: Python 2.7, Python 3.5, Python 3.6, Python 3.7, Python 3.8, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue37717> _______________________________________

3 4

[issue23522] Misleading note in Statistics module documentation
by Jake 19 Dec '20

19 Dec '20

New submission from Jake: In the statistics module documentation, there is a note that states that "The mean is strongly affected by outliers and is not a robust estimator for central location: the mean is not necessarily a typical example of the data points. For more robust, although less efficient, measures of central location, see median() and mode()" https://docs.python.org/3/library/statistics.html While I appreciate the intention, this is quite misleading. The implication is that the mean, median and mode are different ways to estimate one "central location", however, in reality they are very different things (albeit which refer to a similar notion). The sample mean is an unbiased estimator of the true mean but it need not be unbiased as an estimator of the true median or modes and vice versa for the median and mode. To make this clearer I would rephrase to "The mean is strongly affected by outliers and is not necessarily representative of the central tendency of the data. For cases with large outliers or very low sample size, see median() and mode()" Apologies if this is seen as frivolous, but statistics can be hard enough to remain very clear about even when the words are used precisely. ---------- assignee: docs@python components: Documentation messages: 236612 nosy: Journeyman08, docs@python priority: normal severity: normal status: open title: Misleading note in Statistics module documentation type: enhancement versions: Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue23522> _______________________________________

5 11

[issue39560] PyUnicode_FromKindAndData kind transformation is not documented
by Santiago M. Mola 18 Dec '20

18 Dec '20

New submission from Santiago M. Mola <santi(a)mola.io>: PyUnicode_FromKindAndData copies input data and transforms it to the most compact representation. This behavior is not documented. Proposed wording: > The input buffer is copied and transformed into the canonical representation, if necessary. For example, if the buffer is a UCS4 string (PyUnicode_4BYTE_KIND) and it consists only of codepoints in the UCS1 range, it will be transformed into UCS1 (PyUnicode_1BYTE_KIND). ---------- assignee: docs@python components: Documentation messages: 361426 nosy: docs@python, smola priority: normal severity: normal status: open title: PyUnicode_FromKindAndData kind transformation is not documented versions: Python 3.5, Python 3.6, Python 3.7, Python 3.8, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue39560> _______________________________________

3 2