Mailman 3 December 2020 - docs

[issue42681] mistake in curses documentation
by Robert T McQuaid 06 Jan '21

06 Jan '21

New submission from Robert T McQuaid <rtmq(a)fixcas.com>: The description of color_pair starts with curses.color_pair(color_number) It should be curses.color_pair(pair_number) ---------- assignee: docs@python components: Documentation messages: 383344 nosy: arbor, docs@python priority: normal severity: normal status: open title: mistake in curses documentation versions: Python 3.10 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue42681> _______________________________________

6 21

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

05 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

[issue42781] functools.cached_property docs should explain that it is non-overriding
by Luciano Ramalho 31 Dec '20

31 Dec '20

New submission from Luciano Ramalho <luciano(a)ramalho.org>: functools.cached_property is a great addition to the standard library, thanks! However, the docs do not say that @cached_property produces a non-overriding descriptor, in contrast with @property. If a user replaces a @property with a @cached_property, her code may or may not break depending on the existence of an instance attribute with the same name as the decorated method. This is surprising and may affect correctness, so it deserves even more attention than the possible performance loss already mentioned in the docs, related to the shared-dict optimization. In the future, perhaps we can add an argument to @cached_property to optionally make it produce overriding descriptors. ---------- assignee: docs@python components: Documentation messages: 384019 nosy: docs@python, ramalho priority: normal severity: normal status: open title: functools.cached_property docs should explain that it is non-overriding versions: Python 3.10, Python 3.8, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue42781> _______________________________________

3 8

[issue41224] Document is_annotated() in the symtable module
by Joannah Nanjekye 31 Dec '20

31 Dec '20

New submission from Joannah Nanjekye <nanjekyejoannah(a)gmail.com>: The function is_annotated() in symtable is not documented. Am using this opportunity to also add docstrings to the methods that didnot have them already. ---------- assignee: docs@python components: Documentation messages: 373200 nosy: docs@python, nanjekyejoannah priority: normal severity: normal status: open title: Document is_annotated() in the symtable module type: enhancement versions: Python 3.10 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue41224> _______________________________________

3 12

[issue42560] Improve Tkinter Documentation
by Mason Ginter 29 Dec '20

29 Dec '20

New submission from Mason Ginter <mason(a)dagint.com>: Online python Tkinter documentation (https://docs.python.org/3/library/tkinter.html) lacks many features. The main part I find lacking is documentation on methods, as many of them either aren't listed in the documentation and/or take *args as the only parameter, rather than defined parameters. Not sure how in-depth docs from effbot were, but those are not currently available. Existing documentation in the source code (https://github.com/python/cpython/blob/3.9/Lib/tkinter/__init__.py) seems to be a good start to adding to the online documentation. ---------- assignee: docs@python components: Documentation messages: 382437 nosy: docs@python, mason2 priority: normal severity: normal status: open title: Improve Tkinter Documentation type: enhancement _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue42560> _______________________________________

4 7

[issue42700] xml.parsers.expat.errors description of codes/messages is flipped
by Michael Wayne Goodman 29 Dec '20

29 Dec '20

New submission from Michael Wayne Goodman <goodman.m.w(a)gmail.com>: The documentation for xml.parsers.expat.errors.codes says: A dictionary mapping numeric error codes to their string descriptions. But this is backwards. It should say it maps the string descriptions to the error codes. Likewise, the docs for xml.parsers.expat.errors.messages is backwards. The other references to these dictionaries appear correct. For instance, under ExpatError.code: The :mod:`~xml.parsers.expat.errors` module also provides error message constants and a dictionary :data:`~xml.parsers.expat.errors.codes` mapping these messages back to the error codes, see below. This issue appears to be present in the docs for all available versions. ---------- assignee: docs@python components: Documentation messages: 383481 nosy: docs@python, goodmami priority: normal severity: normal status: open title: xml.parsers.expat.errors description of codes/messages is flipped versions: Python 3.10, Python 3.6, Python 3.7, Python 3.8, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue42700> _______________________________________

3 7

[issue42776] The string find method shows the problem
by andy ye 29 Dec '20

29 Dec '20

New submission from andy ye <andy.ye.jx(a)gmail.com>: data = 'abcddd' # True data.find('a', 0) # False data.find('a', start=0) # document class str(obj): def find(self, sub, start=None, end=None): # real signature unknown; restored from __doc__ """ S.find(sub[, start[, end]]) -> int Return the lowest index in S where substring sub is found, such that sub is contained within S[start:end]. Optional arguments start and end are interpreted as in slice notation. Return -1 on failure. """ return 0 ---------- assignee: docs@python components: Documentation files: 截屏2020-12-29 上午10.57.53.png messages: 383949 nosy: andyye, docs@python priority: normal severity: normal status: open title: The string find method shows the problem versions: Python 3.6 Added file: https://bugs.python.org/file49704/截屏2020-12-29 上午10.57.53.png _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue42776> _______________________________________

4 3

[issue7057] tkinter doc: more 3.x updates
by FredInChina 28 Dec '20

28 Dec '20

FredInChina <trustgold(a)gmail.com> added the comment: Are there good reasons not to close this issue? It is marked as "easy", but it seems that the problems in reference have either been fixed, or died of old age. ---------- nosy: +ReblochonMasque _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue7057> _______________________________________

1 0

[issue42770] Typo in email.headerregistry docs
by bazwal 28 Dec '20

28 Dec '20

New submission from bazwal <bazwal(a)gmail.com>: The section for class email.headerregistry.ContentDispositionHeader has a typo in an attribute name: "content-disposition" should be corrected to "content_disposition". ---------- assignee: docs@python components: Documentation messages: 383910 nosy: bazwal, docs@python priority: normal severity: normal status: open title: Typo in email.headerregistry docs type: enhancement versions: Python 3.10, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue42770> _______________________________________

5 9

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

28 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