Mailman 3 November 2015 - docs

[issue17805] No such class: multiprocessing.pool.AsyncResult
by Takafumi Arakaki 03 Jul '20

03 Jul '20

New submission from Takafumi Arakaki: Document mentions AsyncResult but there is no such class. http://docs.python.org/2/library/multiprocessing.html#multiprocessing.pool.… You can check it by simply running: python -c 'from multiprocessing.pool import AsyncResult' I think it means ApplyResult so I made a patch (attached). Note that there managers.py also uses name 'AsyncResult': % hg grep AsyncResult Doc/library/multiprocessing.rst:83232:.. class:: AsyncResult Lib/multiprocessing/managers.py:81039: 'apply_async': 'AsyncResult', Lib/multiprocessing/managers.py:81039: 'map_async': 'AsyncResult', Lib/multiprocessing/managers.py:81039: 'starmap_async': 'AsyncResult', Lib/multiprocessing/managers.py:81039:SyncManager.register('AsyncResult', create_method=False) Probably renaming them would be better? ---------- assignee: docs@python components: Documentation files: ApplyResult.patch keywords: patch messages: 187466 nosy: docs@python, tkf priority: normal severity: normal status: open title: No such class: multiprocessing.pool.AsyncResult versions: Python 2.6, Python 2.7, Python 3.1, Python 3.2, Python 3.3, Python 3.4, Python 3.5 Added file: http://bugs.python.org/file29954/ApplyResult.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue17805> _______________________________________

6 8

[issue23427] Python should expose command when invoked with -c
by Jan-Philip Gehrcke 29 Jun '20

29 Jun '20

New submission from Jan-Philip Gehrcke: When Python is invoked with the `-c command` switch, the command string does not get exposed in sys.argv: $ python -c "import sys; print(sys.argv)" ['-c'] $ python -c "import sys; print(sys.argv)" arg1 ['-c', 'arg1'] The command string does not get exposed anywhere, AFAIK, so it is inaccessible from within Python programs. There might be application scenarios in which it is useful to access the command string, such as for debugging purposes. One scenario is when a Python session should be able to "re-spawn" itself in a subprocess (I came across this question on StackOverflow: http://stackoverflow.com/q/28412903/145400) I propose to make the command string accessible. If you agree that it might make sense, the question is *how/where* to expose it. One possible way is to retain it in sys.argv, as in this example: $ python -c "import sys; print(sys.argv)" "arg1" ['-c', 'import sys; print(sys.argv)', 'arg1'] The current sys.argv docs say > If the command was executed using the -c command line option to > the interpreter, argv[0] is set to the string '-c'. This sentence could then be adjusted to "[...], argv[0] is set to the string '-c', and argv[1] contains the command." This method breaks existing applications that are started with the -c method and that consume command line arguments in a sys.argv[1:] fashion. The tests in Lib/test/test_cmd_line.py all pass, however. A second method would be to change sys.argv[0] from '-c' to '-c command'. This would break existing applications that check for sys.argv[0] == 'c'. A third method would be to leave sys.argv as it is, and expose the command with a new attribute in the sys module. I have attached a patch for variant 1 (passes all tests in Lib/test/test_cmd_line.py), to demonstrate which code is affected: the translation from the "real" argv to sys' argv is triggered in Modules/main.c. The patch does not change behavior of '-m' (it's funny, however, that the current version of main.c at first replaces the module string with '-m', whereas the runpy module later on replaces '-m' with the path to the module file anyway.). As a side node, I figure that the sys.argv documentation should be adjusted to properly reflect the -m behavior, which is: $ ./python -m testmodule foo testmodule sys.argv: ['/data/local/pythondev/pythontip/cpython/testmodule.py', 'foo'] Let me hear your comments, and I am willing to work on code and doc patches, thanks! ---------- assignee: docs@python components: Documentation, Interpreter Core files: sys_argv_cmd.patch keywords: patch messages: 235633 nosy: docs@python, georg.brandl, haypo, jgehrcke, pitrou priority: normal severity: normal status: open title: Python should expose command when invoked with -c type: enhancement versions: Python 3.5, Python 3.6 Added file: http://bugs.python.org/file38065/sys_argv_cmd.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue23427> _______________________________________

7 20

[issue17589] Make documentation about macros in C API explicit about rvalue vs statement
by Larry Hastings 25 Jun '20

25 Jun '20

New submission from Larry Hastings: CPython API "functions" implemented as macros can expand into either rvalues or statements. Most expand into statements (often using the do {} while (0) syntactic sugar trick), but occasionally they're legal as rvalues. As of this writing Py_INCREF works as an rvalue. But discussion on another tracker issue (#17206) proposes changing the implementation in such a way that it will only be usable as a statement. Although it's mildly unlikely, it's certainly possible that this will break somebody's code. I propose that the documentation make an explicit ruling on whether macros are usable as rvalues or as statements. Perhaps a blanket statement would suffice, "all macros are only supported for use as statements except where explicitly noted", then annotate specific macros that are supported for use as rvalues. Though that raises the question of acknowledging in the documentation that some things are macros--I think the documentation glosses over that fact right now. Note: I added you three (Georg, Mark, Martin) as I thought you might have an opinion on this one way or the other. If you're not interested, my apologies. ---------- assignee: docs@python components: Documentation messages: 185646 nosy: Mark.Shannon, docs@python, georg.brandl, larry, loewis priority: normal severity: normal stage: needs patch status: open title: Make documentation about macros in C API explicit about rvalue vs statement type: enhancement versions: Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue17589> _______________________________________

7 9

[issue21508] C API PyArg_ParseTuple doc is innacurate
by Steve 25 Jun '20

25 Jun '20

New submission from Steve: PyArg_ParseTuple is defined as returning an "int", but the documentation talks about returning a true/false value, and failling on false. In addition to being inaccurate, considering that most other functions fail on !=0 ("true"), it can lead to confusion. Doc: int PyArg_ParseTuple(PyObject *args, const char *format, ...) Parse the parameters of a function that takes only positional parameters into local variables. Returns true on success; on failure, it returns false and raises the appropriate exception. ---------- assignee: docs@python components: Documentation messages: 218536 nosy: Banger, docs@python priority: normal severity: normal status: open title: C API PyArg_ParseTuple doc is innacurate type: enhancement versions: Python 3.3, Python 3.4, Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue21508> _______________________________________

3 4

[issue20224] C API docs need a clear "defining custom extension types" section
by Nick Coghlan 25 Jun '20

25 Jun '20

New submission from Nick Coghlan: The main C API docs don't clearly explain how to define new types, so people almost always cargo cult an existing legacy type definition instead (I know I do). The extending and embedding docs have a guide (http://docs.python.org/3/extending/newtypes.html), but that describes the old legacy method based on static type declarations. New code should instead use the dynamic mechanism defined in PEP 384 (http://www.python.org/dev/peps/pep-0384/#type-objects). See also http://docs.python.org/3/c-api/type.html#PyType_FromSpec Note that PyType_Spec isn't defined in the C API docs *at all*. ---------- assignee: docs@python components: Documentation messages: 207927 nosy: docs@python, ncoghlan priority: normal severity: normal stage: needs patch status: open title: C API docs need a clear "defining custom extension types" section type: enhancement versions: Python 3.3, Python 3.4, Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue20224> _______________________________________

2 1

[issue17110] sys.argv docs should explaining how to handle encoding issues
by Nick Coghlan 18 Jun '20

18 Jun '20

New submission from Nick Coghlan: The sys.argv docs [1] currently contain no mention of the fact that they are Unicode strings decoded from bytes provided by the OS. They also don't explain how to correct a decoding error by reversing Python's implicit conversion and redoing it based on the application's knowledge of the correct encoding, as described at [2] [1] http://docs.python.org/3/library/sys#sys.argv [2] http://stackoverflow.com/questions/6981594/sys-argv-as-bytes-in-python-3k/ ---------- assignee: docs@python components: Documentation, Unicode messages: 181239 nosy: docs@python, ezio.melotti, ncoghlan priority: normal severity: normal stage: needs patch status: open title: sys.argv docs should explaining how to handle encoding issues type: enhancement versions: Python 3.2, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue17110> _______________________________________

8 15

[issue24914] Python: Not just OO style but this is not mentioned on python.org or in FAQ
by Paddy McCarthy 08 Jun '20

08 Jun '20

New submission from Paddy McCarthy: Just read http://www.ibmsystemsmag.com/ibmi/developer/general/different-world-python/… It states that they could have had an officially supported version of Python on that IBM platform much earlier but for this: > "The second was that everything we read on Python, and all the examples we encountered, led us to believe that it was a completely object oriented (OO) language" They may have used it earlier had they known then that Python can be written in a procedural style they having no love of Java's OO, but being able to use PHP and access PHP's OO bits. Looking again on python.org, the examples are not OO, but when you delve down, say to the FAQ - it gives the mistaken impression that OO is the _only_ style of programming supported: https://docs.python.org/2/faq/general.html#what-is-python Somehow we need to explain that OO is an implementation style, but the language allows code to be written in just as much - or as little, of proceedural/OO/functional styles as the programmer is comfortable with. ---------- assignee: docs@python components: Documentation messages: 248987 nosy: Paddy McCarthy, docs@python priority: normal severity: normal status: open title: Python: Not just OO style but this is not mentioned on python.org or in FAQ type: enhancement _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue24914> _______________________________________

4 12

[issue25377] Mention octal format of mode argument of os.chmod
by Karl Richter 04 Jun '20

04 Jun '20

New submission from Karl Richter: `help(os.chmod)` doesn't explain that it expects an octal number for its `mode` argument. This is very confusing for beginners and people who are not involved with filesystems and permissions every day. It doesn't need to be explained, just mentioned, maybe with a link to an extended explanation. Example for confusion: http://stackoverflow.com/questions/15607903/python-module-os-chmodfile-664-… ---------- assignee: docs@python components: Documentation messages: 252817 nosy: docs@python, krichter priority: normal severity: normal status: open title: Mention octal format of mode argument of os.chmod type: enhancement versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue25377> _______________________________________

5 5

[issue23557] Misc/SpecialBuilds.txt contains outdated information about PYMALLOC_DEBUG
by Jakub Klama 02 Jun '20

02 Jun '20

New submission from Jakub Klama: Section describing block layout under PYMALLOC_DEBUG is wrong - it doesn't contain information about API type byte instead of one of forbidden bytes. That may lead to wrong assumption that one of forbidden bytes is being overwritten until you dig into obmalloc.c code. ---------- assignee: docs@python components: Documentation, Interpreter Core messages: 236958 nosy: Jakub Klama, docs@python priority: normal severity: normal status: open title: Misc/SpecialBuilds.txt contains outdated information about PYMALLOC_DEBUG versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue23557> _______________________________________

3 2

[issue24921] Operator precedence table in 5.15 should be highest to lowest precedence
by Joseph Schachner 01 Jun '20

01 Jun '20

New submission from Joseph Schachner: We should not make people who need to read Python documentation do an extra transformation in their heads to correctly understand that in section 5.15 higher precedence is at the bottom of the table and lower precedence is at the top. Because the documentation has this table inverted from the way it is usually presented in other references, one of the top hits in a Google search shows an instructor felt the need to make a version in the usual "high to low precedence" order to show students, see: http://www.mathcs.emory.edu/~valerie/courses/fall10/155/resources/op_preced… That version is so much more comfortable for me to read, it seems almost strange, but it is true. Please consider changing section 5.15 so it would not need the top paragraph explaining that the table order is not what the reader probably expects, instead just present the table as at the link above - in the order the reader does expect - higher precedence on top, lower on the bottom. That only needs two short sentences of explanation that don't make the reader think "wait ... what?" ---------- assignee: docs@python components: Documentation messages: 249046 nosy: Joseph Schachner, docs@python priority: normal severity: normal status: open title: Operator precedence table in 5.15 should be highest to lowest precedence versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue24921> _______________________________________

6 6