Mailman 3 September 2018 - docs

[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

[issue34226] cgi.parse_multipart() requires undocumented CONTENT-LENGTH in Python 3.7
by Chih-Hsuan Yen 15 Jun '20

15 Jun '20

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

[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

[issue33187] Document ElementInclude (XInclude) support in ElementTree
by Stefan Behnel 08 Jun '20

08 Jun '20

New submission from Stefan Behnel <stefan_ml(a)behnel.de>: The ElementInclude module in ElementTree seems undocumented. I couldn't find any documentation in the stdlib docs. Pretty much the only source that I could find is here: http://effbot.org/zone/element-xinclude.htm I noticed it while looking for a place to document the changes of #20928. ---------- assignee: docs@python components: Documentation messages: 314691 nosy: docs@python, scoder priority: normal severity: normal status: open title: Document ElementInclude (XInclude) support in ElementTree type: enhancement _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue33187> _______________________________________

8 23

[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

[issue16891] Fix docs about module search order
by Dmitry Mugtasimov 31 May '20

31 May '20

New submission from Dmitry Mugtasimov: http://docs.python.org/2/tutorial/modules.html should be rewritten. AS IS 6.1.2. The Module Search Path When a module named spam is imported, the interpreter first searches for a built-in module with that name. If not found, it then searches for a file named spam.py in a list of directories given by the variable sys.path. sys.path is initialized from these locations: TO BE 6.1.2. The Module Search Path When a module named spam is imported, the interpreter first searches for a built-in module with that name. If not found, it looks in the containing package (the package of which the current module is a submodule). If not found, it then searches for a file named spam.py in a list of directories given by the variable sys.path. sys.path is initialized from these locations: ------ Note that now "6.1.2. The Module Search Path" and "6.4.2. Intra-package References" are contradictary since in 6.4.2 it is said: "In fact, such references are so common that the import statement first looks in the containing package before looking in the standard module search path.", but this is not reflected in 6.1.2. ------ EXAMPLE (for more information see http://stackoverflow.com/questions/14183541/why-python-finds-module-instead… ): /home/dmugtasimov/tmp/name-res3/xyz __init__.py a.py b.py t.py xyz.py Files init.py, b.py and xyz.py are empty File a.py: import os, sys ROOT_DIRECTORY = os.path.abspath(os.path.join(os.path.dirname(__file__), '..')) if not sys.path or ROOT_DIRECTORY not in sys.path: print 'sys.path is modified in a.py' sys.path.insert(0, ROOT_DIRECTORY) else: print 'sys.path is NOT modified in a.py' print 'sys.path:', sys.path print 'BEFORE import xyz.b' import xyz.b print 'AFTER import xyz.b' File t.py: import os, sys ROOT_DIRECTORY = os.path.abspath(os.path.join(os.path.dirname(__file__), '..')) if not sys.path or ROOT_DIRECTORY not in sys.path: print 'sys.path is modified in t.py' sys.path.insert(0, ROOT_DIRECTORY) else: print 'sys.path is NOT modified in t.py' import xyz.a Run: python a.py Output: sys.path is modified in a.py sys.path: ['/home/dmugtasimov/tmp/name-res3', '/home/dmugtasimov/tmp/name-res3/xyz', '/usr/local/lib/python2.7/dist-packages/tornado-2.3-py2.7.egg', '/home/dmugtasimov/tmp/name-res3/xyz', '/usr/lib/python2.7', '/usr/lib/python2.7/plat-linux2', '/usr/lib/python2.7/lib-tk', '/usr/lib/python2.7/lib-old', '/usr/lib/python2.7/lib-dynload', '/usr/local/lib/python2.7/dist-packages', '/usr/local/lib/python2.7/dist-packages/setuptools-0.6c11-py2.7.egg-info', '/usr/lib/python2.7/dist-packages', '/usr/lib/python2.7/dist-packages/PIL', '/usr/lib/python2.7/dist-packages/gst-0.10', '/usr/lib/python2.7/dist-packages/gtk-2.0', '/usr/lib/python2.7/dist-packages/ubuntu-sso-client'] BEFORE import xyz.b AFTER import xyz.b Run: python -vv a.py Output: import xyz # directory /home/dmugtasimov/tmp/name-res3/xyz # trying /home/dmugtasimov/tmp/name-res3/xyz/__init__.so # trying /home/dmugtasimov/tmp/name-res3/xyz/__init__module.so # trying /home/dmugtasimov/tmp/name-res3/xyz/__init__.py # /home/dmugtasimov/tmp/name-res3/xyz/__init__.pyc matches /home/dmugtasimov/tmp/name-res3/xyz/__init__.py import xyz # precompiled from /home/dmugtasimov/tmp/name-res3/xyz/__init__.pyc # trying /home/dmugtasimov/tmp/name-res3/xyz/b.so # trying /home/dmugtasimov/tmp/name-res3/xyz/bmodule.so # trying /home/dmugtasimov/tmp/name-res3/xyz/b.py # /home/dmugtasimov/tmp/name-res3/xyz/b.pyc matches /home/dmugtasimov/tmp/name-res3/xyz/b.py import xyz.b # precompiled from /home/dmugtasimov/tmp/name-res3/xyz/b.pyc Run: python t.py Output: sys.path is modified in t.py sys.path is NOT modified in a.py sys.path: ['/home/dmugtasimov/tmp/name-res3', '/home/dmugtasimov/tmp/name-res3/xyz', '/usr/local/lib/python2.7/dist-packages/tornado-2.3-py2.7.egg', '/home/dmugtasimov/tmp/name-res3/xyz', '/usr/lib/python2.7', '/usr/lib/python2.7/plat-linux2', '/usr/lib/python2.7/lib-tk', '/usr/lib/python2.7/lib-old', '/usr/lib/python2.7/lib-dynload', '/usr/local/lib/python2.7/dist-packages', '/usr/local/lib/python2.7/dist-packages/setuptools-0.6c11-py2.7.egg-info', '/usr/lib/python2.7/dist-packages', '/usr/lib/python2.7/dist-packages/PIL', '/usr/lib/python2.7/dist-packages/gst-0.10', '/usr/lib/python2.7/dist-packages/gtk-2.0', '/usr/lib/python2.7/dist-packages/ubuntu-sso-client'] BEFORE import xyz.b Traceback (most recent call last): File "t.py", line 9, in <module> import xyz.a File "/home/dmugtasimov/tmp/name-res3/xyz/a.py", line 11, in <module> import xyz.b ImportError: No module named b Run: python -vv t.py Output: import xyz # directory /home/dmugtasimov/tmp/name-res3/xyz # trying /home/dmugtasimov/tmp/name-res3/xyz/__init__.so # trying /home/dmugtasimov/tmp/name-res3/xyz/__init__module.so # trying /home/dmugtasimov/tmp/name-res3/xyz/__init__.py # /home/dmugtasimov/tmp/name-res3/xyz/__init__.pyc matches /home/dmugtasimov/tmp/name-res3/xyz/__init__.py import xyz # precompiled from /home/dmugtasimov/tmp/name-res3/xyz/__init__.pyc # trying /home/dmugtasimov/tmp/name-res3/xyz/a.so # trying /home/dmugtasimov/tmp/name-res3/xyz/amodule.so # trying /home/dmugtasimov/tmp/name-res3/xyz/a.py # /home/dmugtasimov/tmp/name-res3/xyz/a.pyc matches /home/dmugtasimov/tmp/name-res3/xyz/a.py import xyz.a # precompiled from /home/dmugtasimov/tmp/name-res3/xyz/a.pyc # trying /home/dmugtasimov/tmp/name-res3/xyz/os.so # trying /home/dmugtasimov/tmp/name-res3/xyz/osmodule.so # trying /home/dmugtasimov/tmp/name-res3/xyz/os.py # trying /home/dmugtasimov/tmp/name-res3/xyz/os.pyc # trying /home/dmugtasimov/tmp/name-res3/xyz/sys.so # trying /home/dmugtasimov/tmp/name-res3/xyz/sysmodule.so # trying /home/dmugtasimov/tmp/name-res3/xyz/sys.py # trying /home/dmugtasimov/tmp/name-res3/xyz/sys.pyc # trying /home/dmugtasimov/tmp/name-res3/xyz/xyz.so # trying /home/dmugtasimov/tmp/name-res3/xyz/xyzmodule.so # trying /home/dmugtasimov/tmp/name-res3/xyz/xyz.py # /home/dmugtasimov/tmp/name-res3/xyz/xyz.pyc matches /home/dmugtasimov/tmp/name-res3/xyz/xyz.py import xyz.xyz # precompiled from /home/dmugtasimov/tmp/name-res3/xyz/xyz.pyc # clear[2] __file__ # clear[2] __package__ # clear[2] sys # clear[2] ROOT_DIRECTORY # clear[2] __name__ # clear[2] os sys.path is modified in t.py sys.path is NOT modified in a.py sys.path: ['/home/dmugtasimov/tmp/name-res3', '/home/dmugtasimov/tmp/name-res3/xyz', '/usr/local/lib/python2.7/dist-packages/tornado-2.3-py2.7.egg', '/home/dmugtasimov/tmp/name-res3/xyz', '/usr/lib/python2.7', '/usr/lib/python2.7/plat-linux2', '/usr/lib/python2.7/lib-tk', '/usr/lib/python2.7/lib-old', '/usr/lib/python2.7/lib-dynload', '/usr/local/lib/python2.7/dist-packages', '/usr/local/lib/python2.7/dist-packages/setuptools-0.6c11-py2.7.egg-info', '/usr/lib/python2.7/dist-packages', '/usr/lib/python2.7/dist-packages/PIL', '/usr/lib/python2.7/dist-packages/gst-0.10', '/usr/lib/python2.7/dist-packages/gtk-2.0', '/usr/lib/python2.7/dist-packages/ubuntu-sso-client'] BEFORE import xyz.b Traceback (most recent call last): File "t.py", line 9, in <module> import xyz.a File "/home/dmugtasimov/tmp/name-res3/xyz/a.py", line 11, in <module> import xyz.b ImportError: No module named b As you see sys.path is the same for both cases: sys.path: ['/home/dmugtasimov/tmp/name-res3', '/home/dmugtasimov/tmp/name-res3/xyz', '/usr/local/lib/python2.7/dist-packages/tornado-2.3-py2.7.egg', '/home/dmugtasimov/tmp/name-res3/xyz', '/usr/lib/python2.7', '/usr/lib/python2.7/plat-linux2', '/usr/lib/python2.7/lib-tk', '/usr/lib/python2.7/lib-old', '/usr/lib/python2.7/lib-dynload', '/usr/local/lib/python2.7/dist-packages', '/usr/local/lib/python2.7/dist-packages/setuptools-0.6c11-py2.7.egg-info', '/usr/lib/python2.7/dist-packages', '/usr/lib/python2.7/dist-packages/PIL', '/usr/lib/python2.7/dist-packages/gst-0.10', '/usr/lib/python2.7/dist-packages/gtk-2.0', '/usr/lib/python2.7/dist-packages/ubuntu-sso-client'] But the behaviour is different. For a.py python searches for package xyz first, and them for module b in it: import xyz # directory /home/dmugtasimov/tmp/name-res3/xyz # trying /home/dmugtasimov/tmp/name-res3/xyz/__init__.so # trying /home/dmugtasimov/tmp/name-res3/xyz/__init__module.so # trying /home/dmugtasimov/tmp/name-res3/xyz/__init__.py # /home/dmugtasimov/tmp/name-res3/xyz/__init__.pyc matches /home/dmugtasimov/tmp/name-res3/xyz/__init__.py import xyz # precompiled from /home/dmugtasimov/tmp/name-res3/xyz/__init__.pyc # trying /home/dmugtasimov/tmp/name-res3/xyz/b.so # trying /home/dmugtasimov/tmp/name-res3/xyz/bmodule.so # trying /home/dmugtasimov/tmp/name-res3/xyz/b.py # /home/dmugtasimov/tmp/name-res3/xyz/b.pyc matches /home/dmugtasimov/tmp/name-res3/xyz/b.py import xyz.b # precompiled from /home/dmugtasimov/tmp/name-res3/xyz/b.pyc In other words: Search PACKAGE xyz in directory sys.path[0] -> FOUND Search module b in PACKAGE xyz -> FOUND Continue execution For t.py it searches for moduel xyz in the same directory as a.py itself and then fails to find module b in module xyz: # trying /home/dmugtasimov/tmp/name-res3/xyz/xyz.so # trying /home/dmugtasimov/tmp/name-res3/xyz/xyzmodule.so # trying /home/dmugtasimov/tmp/name-res3/xyz/xyz.py # /home/dmugtasimov/tmp/name-res3/xyz/xyz.pyc matches /home/dmugtasimov/tmp/name-res3/xyz/xyz.py import xyz.xyz # precompiled from /home/dmugtasimov/tmp/name-res3/xyz/xyz.pyc In other words: Search MODULE xyz in directory in the same directory as a.py (or sys.path[1] ?) -> FOUND Search MODULE b in MODULE xyz -> NOT FOUND ImportError So it looks like if "import xyz.b" bahaves different depending on how a.py was initially loaded as a script or imported from another module. ---------- assignee: docs@python components: Documentation messages: 179321 nosy: dmugtasimov, docs@python priority: normal severity: normal status: open title: Fix docs about module search order type: behavior versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue16891> _______________________________________

6 10

[issue33740] PyByteArray_AsString C-API description lacks the assurance, that the trailing null-byte is appended.
by Egor Dranischnikow 31 May '20

31 May '20

New submission from Egor Dranischnikow <no-one(a)turm-lahnstein.de>: The C-API for Python2.7 https://docs.python.org/2/c-api/bytearray.html#c.PyByteArray_AsString lacks the sentence: "The returned array always has an extra null byte appended." which clarifies, that the returned C-string is null-terminated. This sentence is a part of Python3-documentation: https://docs.python.org/3/c-api/bytearray.html#c.PyByteArray_AsString I might be very wrong, but so far I understand the code this is the case for both versions, Python3 and Python2. Probably parts of this change https://github.com/python/cpython/commit/0a560a11af0ccc816d1172180f44e5afb3… could be integrated in Python2.7 ---------- assignee: docs@python components: Documentation messages: 318515 nosy: docs@python, realead priority: normal severity: normal status: open title: PyByteArray_AsString C-API description lacks the assurance, that the trailing null-byte is appended. versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue33740> _______________________________________

3 2