Mailman 3 March 2019 - docs

[issue35105] Document that CPython accepts "invalid" identifiers
by STINNER Victor July 3, 2020

July 3, 2020

New submission from STINNER Victor <vstinner(a)redhat.com>: The Python 3 language has a strict definition for an identifier: https://docs.python.org/dev/reference/lexical_analysis.html#identifiers ... but in practice, it's possible to create "invalid" identifiers using setattr(). Example with PyPy: $ pypy Python 2.7.13 (0e7ea4fe15e82d5124e805e2e4a37cae1a402d4b, Apr 12 2018, 14:50:12) >>>> class A: pass >>>> >>>> a=A() >>>> setattr(a, "1", 2) >>>> getattr(a, "1") 2 >>>> vars(a) {'1': 2} >>>> a.__dict__ {'1': 2} >>>> a.1 File "<stdin>", line 1 a.1 ^ SyntaxError: invalid syntax The exact definition of "identifiers" is a common question. Recent examples: * bpo-25205 * [Python-Dev] Arbitrary non-identifier string keys when using **kwargs https://mail.python.org/pipermail/python-dev/2018-October/155435.html It would be nice to document the answer. Maybe in the Langage Specification, maybe in the setattr() documentation, maybe in a FAQ, maybe everywhere? ---------- assignee: docs@python components: Documentation messages: 328816 nosy: docs@python, serhiy.storchaka, steven.daprano, vstinner priority: normal severity: normal status: open title: Document that CPython accepts "invalid" identifiers versions: Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue35105> _______________________________________

11 21

[issue23427] Python should expose command when invoked with -c
by Jan-Philip Gehrcke June 29, 2020

June 29, 2020

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

[issue33553] possible documentation improvement proposal for multiprocessing
by Derek Kim June 28, 2020

June 28, 2020

New submission from Derek Kim <bluewhale8202(a)gmail.com>: >>> from multiprocessing import Pool >>> p = Pool(5) >>> def f(x): ... return x*x ... >>> p.map(f, [1,2,3]) This example in the document is confusing because this is already wrong code when run with fork method even if you run it as a script. With fork start method, f should be defined before p is created. Also, just advising that one shouldn't use interactive shell and should run multiprocessing code in if __name__ == '__main__' is not informative becuase those conditions are generally no problem with fork method. Can I try improving the documentation? ---------- assignee: docs@python components: Documentation messages: 316892 nosy: Derek Kim, docs@python priority: normal severity: normal status: open title: possible documentation improvement proposal for multiprocessing versions: Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue33553> _______________________________________

3 4

[issue31082] reduce takes iterable, not just sequence
by Stefan Pochmann June 28, 2020

June 28, 2020

New submission from Stefan Pochmann: functools.reduce has a parameter called "iterable" and it only needs to be an iterable, not a sequence. The paragraph documenting it says "sequence" instead of "iterable" six times: https://docs.python.org/3/library/functools.html#functools.reduce The help shown by executing "help(functools.reduce)" in Python additionally actually names the parameter "sequence" in the signature. ---------- assignee: docs@python components: Documentation messages: 299520 nosy: Stefan Pochmann, docs@python priority: normal severity: normal status: open title: reduce takes iterable, not just sequence type: enhancement versions: Python 3.6, Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue31082> _______________________________________

6 7

[issue30951] Documentation error in inspect module
by Alex Vig June 25, 2020

June 25, 2020

New submission from Alex Vig: The documentation for co_names in the inspect module is: "tuple of names of local variables" Local variable names are however in co_varnames while co_names contains global variable names. This description should read: "tuple of names of global variables" Relevant StackOverflow post here: https://stackoverflow.com/q/45147260/1953800 ---------- assignee: docs@python components: Documentation messages: 298545 nosy: Alex Vig, docs@python priority: normal severity: normal status: open title: Documentation error in inspect module versions: Python 2.7, Python 3.3, Python 3.4, Python 3.5, Python 3.6, Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue30951> _______________________________________

8 10

[issue17589] Make documentation about macros in C API explicit about rvalue vs statement
by Larry Hastings June 25, 2020

June 25, 2020

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 June 25, 2020

June 25, 2020

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 June 25, 2020

June 25, 2020

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 June 18, 2020

June 18, 2020

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

[issue34226] cgi.parse_multipart() requires undocumented CONTENT-LENGTH in Python 3.7
by Chih-Hsuan Yen June 15, 2020

June 15, 2020

New submission from Chih-Hsuan Yen <yan12125(a)gmail.com>: In Python 3.7, cgi.parse_multipart() requires "CONTENT-LENGTH" in the second parameter `pdict`. This is not necesary in Python 3.6. For example, the following code runs with 3.6: $ python3.6 Python 3.6.6 (default, Jun 27 2018, 13:11:40) [GCC 8.1.1 20180531] on linux Type "help", "copyright", "credits" or "license" for more information. >>> import cgi, io >>> data = b'--heyDavid\r\nContent-Disposition: form-data; name="cfield"\r\n\r\njust a string\r\n\r\n--heyDavid--\r\n' >>> cgi.parse_multipart(io.BytesIO(data), {"boundary": b"heyDavid"}) {'cfield': [b'just a string\r\n']} While not on 3.7: $ python3.7 Python 3.7.0 (default, Jul 15 2018, 10:44:58) [GCC 8.1.1 20180531] on linux Type "help", "copyright", "credits" or "license" for more information. >>> import cgi, io >>> data = b'--heyDavid\r\nContent-Disposition: form-data; name="cfield"\r\n\r\njust a string\r\n\r\n--heyDavid--\r\n' >>> cgi.parse_multipart(io.BytesIO(data), {"boundary": b"heyDavid"}) Traceback (most recent call last): File "<stdin>", line 1, in <module> File "/usr/lib/python3.7/cgi.py", line 220, in parse_multipart headers['Content-Length'] = pdict['CONTENT-LENGTH'] KeyError: 'CONTENT-LENGTH' I looked into the source code of CPython, and found CONTENT-LENGTH in nowhere but cgi.py and test_cgi.py. I guess it has the same meaning as the Content-Length header in HTTP or CONTENT_LENGTH environment variable in CGI? It would be great to document such a backward-incompatible behavior. Environment: Arch Linux with Python 3.6.6 from [extra] repo and 3.7.0 from [staging] repo. CC the author and the reviewer of issue29979, where relevant codes are introduced. ---------- assignee: docs@python components: Documentation, Library (Lib) messages: 322362 nosy: docs@python, orsenthil, quentel, yan12125 priority: normal severity: normal status: open title: cgi.parse_multipart() requires undocumented CONTENT-LENGTH in Python 3.7 type: behavior versions: Python 3.7, Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue34226> _______________________________________

11 19