Mailman 3 July 2016 - docs

[issue13474] Mention of "-m" Flag Missing From Doc on Execution Model
by Eric Snow Sept. 12, 2019

Sept. 12, 2019

New submission from Eric Snow <ericsnowcurrently(a)gmail.com>: The doc on code execution[1] leaves out mention of the -m flag. Seems like it belongs there too. [1] Doc/reference/executionmodel.rst ---------- assignee: docs@python components: Documentation messages: 148288 nosy: docs@python, eric.snow priority: normal severity: normal status: open title: Mention of "-m" Flag Missing From Doc on Execution Model versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13474> _______________________________________

8 10

[issue9938] Documentation for argparse interactive use
by Jay T Sept. 12, 2019

Sept. 12, 2019

New submission from Jay T <jaytula(a)gmail.com>: I want to create a custom interactive shell where I continually do parse_args. Like the following: parser = argparse.ArgumentParser() command = raw_input() while(True): args = parser.parse_args(shlex.split(command)) # Do some magic stuff command = raw_input() The problem is that if I give it invalid input, it errors and exits with a help message. I learned from argparse-users group that you can override the exit method like the following: class MyParser(ArgumentParser): def exit(self, status=0, message=None): # do whatever you want here I would be nice to have this usage documented perhaps along with best practices for doing help messages in this scenario. ---------- assignee: docs@python components: Documentation messages: 117287 nosy: docs@python, jayt priority: normal severity: normal status: open title: Documentation for argparse interactive use type: feature request versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9938> _______________________________________

16 28

[issue27589] asyncio doc: issue in as_completed() doc
by STINNER Victor Sept. 12, 2019

Sept. 12, 2019

New submission from STINNER Victor: Remark on as_completed() doc by Hynek. https://docs.python.org/dev/library/asyncio-task.html#asyncio.as_completed Futures are yielded in an unexpected order: as soon as a future completes. ---------- assignee: docs@python components: Documentation, asyncio messages: 270982 nosy: docs@python, gvanrossum, haypo, yselivanov priority: normal severity: normal status: open title: asyncio doc: issue in as_completed() doc versions: Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue27589> _______________________________________

6 7

[issue25810] Python 3 documentation for eval is incorrect
by Andre Roberge Sept. 11, 2019

Sept. 11, 2019

New submission from Andre Roberge: The documentation for eval() indicates that it takes keyword arguments: eval(expression, globals=None, locals=None) However, that is incorrect, as indicated by the builtin help: >>> help(eval) Help on built-in function eval in module builtins: eval(...) eval(source[, globals[, locals]]) -> value ---------- assignee: docs@python components: Documentation messages: 255969 nosy: aroberge, docs@python priority: normal severity: normal status: open title: Python 3 documentation for eval is incorrect versions: 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/issue25810> _______________________________________

12 23

[issue16438] Numeric operator predecence confusing
by Yongzhi Pan Sept. 11, 2019

Sept. 11, 2019

New submission from Yongzhi Pan: http://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-comp… "All numeric types (except complex) support the following operations, sorted by ascending priority." It list '-' after '+', '/' after '*'. That is to mean '-' has higher precedence than '+'. That is wrong, and is contradicting with here: http://docs.python.org/3/reference/expressions.html#summary This should be made clear. ---------- assignee: docs@python components: Documentation messages: 175163 nosy: docs@python, fossilet priority: normal severity: normal status: open title: Numeric operator predecence confusing versions: Python 2.7, Python 3.2, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue16438> _______________________________________

13 23

[issue25461] Unclear language (the word ineffective) in the documentation for os.walk
by Bernt Røskar Brenna Sept. 10, 2019

Sept. 10, 2019

New submission from Bernt Røskar Brenna: At least for me (non-english speaker), the following is confusing: "Modifying dirnames when topdown is False is ineffective, because in bottom-up mode the directories in dirnames are generated before dirpath itself is generated." I suggest to replace "is ineffective" with "has no effect". Ineffective could also mean: "Has low performance", could it not? ---------- assignee: docs@python components: Documentation messages: 253338 nosy: Bernt.Røskar.Brenna, docs@python priority: normal severity: normal status: open title: Unclear language (the word ineffective) in the documentation for os.walk type: enhancement versions: Python 2.7, Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue25461> _______________________________________

9 23

[issue21018] [patch] added missing documentation about escaping characters for configparser
by Arun Persaud Sept. 10, 2019

Sept. 10, 2019

New submission from Arun Persaud: Couldn't find how to escape % and $ in the documentation, so I thought I add a short patch. ---------- assignee: docs@python components: Documentation files: mywork.patch keywords: patch messages: 214442 nosy: Arun.Persaud, docs@python priority: normal severity: normal status: open title: [patch] added missing documentation about escaping characters for configparser type: enhancement Added file: http://bugs.python.org/file34562/mywork.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue21018> _______________________________________

8 16

[issue18576] Rename and document test.script_helper as test.support.script_helper
by Nick Coghlan Sept. 9, 2019

Sept. 9, 2019

New submission from Nick Coghlan: tests.script_helper provides various utilities for sensibly testing scripts in a subprocess. It isn't easy for CPython developers to discover, since it is isn't documented and the file is mixed in with actual tests in the main test directory. As discussed in #15494, it should be: 1. Moved from Lib/test/ to Lib/test/support (and imports in tests adjusted accordingly) 2. Documented in Doc/library/test.rst These changes should be made on both the 3.3 and default branches to avoid spurious merge conflicts. ---------- assignee: docs@python components: Documentation, Tests messages: 193819 nosy: docs@python, ncoghlan priority: normal severity: normal status: open title: Rename and document test.script_helper as test.support.script_helper type: enhancement versions: Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18576> _______________________________________

10 28

[issue20806] os.times document points to wrong section of non-Linux manual
by Geoffrey Spear Sept. 7, 2019

Sept. 7, 2019

New submission from Geoffrey Spear: The documentation for os.times directs the reader: "See the Unix manual page times(2) or the corresponding Windows Platform API documentation." However, the POSIX manual page in question is times(3P), and on OS X and BSD systems it's times(3). Falling back to "man times" without specifying a manual section also doesn't work, since this finds the bash builtin rather than the library function. ---------- assignee: docs@python components: Documentation messages: 212424 nosy: docs@python, geoffreyspear priority: normal severity: normal status: open title: os.times document points to wrong section of non-Linux manual versions: Python 2.7, Python 3.1, Python 3.2, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue20806> _______________________________________

6 13

[issue12077] Harmonizing descriptor protocol documentation
by Davide Rizzo Aug. 29, 2019

Aug. 29, 2019

New submission from Davide Rizzo <sorcio(a)gmail.com>: There are three sources of information for the descriptor protocol: - Data model reference (Doc/reference/datamodel.rst) - Descriptor HowTo guide (Doc/howto/descriptor.rst) - PEP 252 A developer who already knows descriptor tipically reads the first one: object.__get__(self, instance, owner) "... owner is always the owner class ..." Reading a bit further there are the ways a descriptor can be called, and the "direct call" is x.__get__(a). That is, without the third argument (owner) specified. The how-to definition is slightly different: descr.__get__(self, obj, type=None) --> value Here the arguments have different names ("type" shadowing the type bultin) and it seems to be implied that the third argument is optional. The ClassMethod example at the end of the document seems to confirm this: def __get__(self, obj, klass=None): (though another example doesn't). And the method contains an explicit check on klass being None. Also it could be confusing that through the examples in the same document many different names are used for the same argument (type, objtype, klass), and all different than the name used in the reference. Lastly the PEP is more explicit: __get__(): a function callable with one or two arguments. [...] When X is None, the optional second argument, T, should be meta-object. [...] When both X and T are specified ... One more quirk: the reference explains the distinction between data and non-data descriptors, though says nothing about __set__ raising AttributeError for read-only data descriptors. My proposal: - use the same names for __get__ arguments throughout the documentation (both the reference and the tutorial), e.g. __get__(self, instance, owner) - decide whether the third argument should be optional, or state the common usage in the reference, and fix accordingly the examples in the howto - explain data, non-data and read-only descriptors in the __set__ reference, or more simply, how the defintion of __set__ affects these things. ---------- assignee: docs@python components: Documentation messages: 135974 nosy: davide.rizzo, docs@python priority: normal severity: normal status: open title: Harmonizing descriptor protocol documentation versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12077> _______________________________________

9 17