Mailman 3 October 2018 - docs

[issue13433] String format documentation contains error regarding %g
by Christian Iversen 18 Feb '21

18 Feb '21

New submission from Christian Iversen <ci(a)sikkerhed.org>: The documentation for string format options state that both %f, %g and %e default to 6 digits after the decimal point. In fact, %g always seems to use 5 digits by default: >>> "%g" % 2.1234567 '2.12346' >>> "%f" % 2.1234567 '2.123457' >>> "%e" % 2.1234567 '2.123457e+00' But something much more insidious is wrong, because even when explicitly told how many digits to have, %g is one off: >>> "%.6g" % 2.1234567 '2.12346' >>> "%.6f" % 2.1234567 '2.123457' >>> "%.6e" % 2.1234567 '2.123457e+00' This can't be right? ---------- assignee: docs@python components: Documentation messages: 147940 nosy: Christian.Iversen, docs@python priority: normal severity: normal status: open title: String format documentation contains error regarding %g type: behavior versions: Python 2.6, Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13433> _______________________________________

6 11

[issue29086] Document C API that is not part of the limited API
by Serhiy Storchaka 18 Feb '21

18 Feb '21

New submission from Serhiy Storchaka: >From the documentation: https://docs.python.org/3/c-api/stable.html In the C API documentation, API elements that are not part of the limited API are marked as "Not part of the limited API." But they don't. Following sample patch adds the notes to Unicode Objects and Codecs C API. I'm going to add them to all C API. What are your though about formatting the note? Should it be before the description, after the description, but before the "deprecated" directive (as in the patch), or after the first paragraph of the description? Should it be on the separate line or be appended at the end of the previous paragraph, or starts the first paragraph (if before the description)? May be introduce a special directive for it? ---------- assignee: docs@python components: Documentation files: unicode-not-part-of-the-limited-api.patch keywords: patch messages: 284125 nosy: docs@python, georg.brandl, serhiy.storchaka priority: normal severity: normal status: open title: Document C API that is not part of the limited API type: enhancement versions: Python 3.5, Python 3.6, Python 3.7 Added file: http://bugs.python.org/file46057/unicode-not-part-of-the-limited-api.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue29086> _______________________________________

5 6

[issue20464] Update distutils sample config file in Doc/install/index.rst
by Zachary Ware 03 Feb '21

03 Feb '21

New submission from Zachary Ware: >From docs@: On Thu, Jan 16, 2014 at 2:56 AM, Peter Bröcker <peter.broecker(a)uni-koeln.de> wrote: > Hi, > > I have tried to set up the distutils config files for a custom module > installation. Using the suggested snippet from > > http://docs.python.org/2/install/ > > [install] > install-base=$HOME/python > install-purelib=lib > install-platlib=lib.$PLAT > install-scripts=scripts > install-data=data did not work for me. > > Instead, I had to add install-headers and additionally modify all paths > to include $base: > > [install] > install-base=/some/dir > install-purelib=$base/lib > install-platlib=$base/lib.$PLAT > install-scripts=$base/scripts > install-headers=$base/include > install-data=$base/data > > > I'm unsure if this is actually a bug, but I could only resolve this with > the help of this answer on stackoverflow: > http://stackoverflow.com/a/12768721 > > Best regards, > Peter ---------- assignee: docs@python components: Distutils, Documentation messages: 209829 nosy: docs@python, zach.ware priority: normal severity: normal stage: test needed status: open title: Update distutils sample config file in Doc/install/index.rst type: behavior versions: Python 2.7, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue20464> _______________________________________

3 4

[issue22401] argparse: 'resolve' conflict handler damages the actions of the parent parser
by paul j3 27 Jan '21

27 Jan '21

New submission from paul j3: When there's a conflict involving an argument that was added via 'parents', and the conflict handler is 'resolve', the action in the parent parser may be damaged, rendering that parent unsuitable for further use. In this example, 2 parents have the same '--config' argument: parent1 = argparse.ArgumentParser(add_help=False) parent1.add_argument('--config') parent2 = argparse.ArgumentParser(add_help=False) parent2.add_argument('--config') parser = argparse.ArgumentParser(parents=[parent1,parent2], conflict_handler='resolve') The actions of the 3 parsers are (from the ._actions list): (id, dest, option_strings) parent1: [(3077384012L, 'config', [])] # empty option_strings parent2: [(3076863628L, 'config', ['--config'])] parser: [(3076864428L, 'help', ['-h', '--help']), (3076863628L, 'config', ['--config'])] # same id The 'config' Action from 'parent1' is first copied to 'parser' by reference (this is important). When 'config' from 'parent2' is copied, there's a conflict. '_handle_conflict_resolve()' attempts to remove the first Action, so it can add the second. But in the process it ends up deleting the 'option_strings' values from the original action. So now 'parent1' has an action in its 'optionals' argument group with an empty option_strings list. It would display as an 'optionals' but parse as a 'positionals'. 'parent1' can no longer be safely used as a parent for another (sub)parser, nor used as a parser itself. The same sort of thing would happen, if, as suggested in the documentation: "Sometimes (e.g. when using parents_) it may be useful to simply override any older arguments with the same option string." In test_argparse.py, 'resolve' is only tested once, with a simple case of two 'add_argument' statements. The 'parents' class tests a couple of cases of conflicting actions (for positionals and optionals), but does nothing with the 'resolve' handler. ------------------------------ Possible fixes: - change the documentation to warn against reusing such a parent parser - test the 'resolve' conflict handler more thoroughly - rewrite this conflict handler so it does not modify the action in the parent - possibly change the 'parents' mechanism so it does a deep copy of actions. References: http://stackoverflow.com/questions/25818651/argparse-conflict-resolver-for-… http://bugs.python.org/issue15271 argparse: repeatedly specifying the same argument ignores the previous ones http://bugs.python.org/issue19462 Add remove_argument() method to argparse.ArgumentParser http://bugs.python.org/issue15428 add "Name Collision" section to argparse docs ---------- assignee: docs@python components: Documentation, Library (Lib), Tests messages: 226862 nosy: docs@python, paul.j3 priority: normal severity: normal status: open title: argparse: 'resolve' conflict handler damages the actions of the parent parser type: behavior versions: Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue22401> _______________________________________

3 15

[issue24711] Document getpass.getpass behavior on ^C
by Markus Unterwaditzer 11 Jan '21

11 Jan '21

New submission from Markus Unterwaditzer: getpass.getpass doesn't enter a newline when the user aborts input with ^C, while input/raw_input does. This behavior is surprising and can lead to mis-formatting of subsequent output. However, since this behavior exists since 2.7 and applications may have started to rely on it, I'd add a note to the documentation. ---------- assignee: docs@python components: Documentation messages: 247302 nosy: docs@python, untitaker priority: normal severity: normal status: open title: Document getpass.getpass behavior on ^C versions: Python 2.7, Python 3.2, Python 3.3, Python 3.4, Python 3.5, Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue24711> _______________________________________

2 2

[issue34804] Repetition of 'for example' in documentation
by Aydin 10 Jan '21

10 Jan '21

New submission from Aydin <bagiyevaydin(a)gmail.com>: In the documentation of Python 3.7.0 there is an error in the usage of the world 'for example'. ---------- assignee: docs@python components: Documentation files: Functional Programming HOWTO — Python 3.7.0 documentation.png messages: 326418 nosy: docs@python, rarblack priority: normal severity: normal status: open title: Repetition of 'for example' in documentation versions: Python 3.7 Added file: https://bugs.python.org/file47825/Functional Programming HOWTO — Python 3.7.0 documentation.png _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue34804> _______________________________________

5 6

[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

[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

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

28 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

[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