Mailman 3 October 2019 - docs

[issue37674] Is imp module deprecated or pending deprecation?
by Mariatta 13 Jun '20

13 Jun '20

New submission from Mariatta <mariatta(a)python.org>: The doc https://docs.python.org/3.7/library/imp.html says "Deprecated since version 3.4: The imp package is pending deprecation in favor of importlib." Is it in "deprecated" state, or "pendingdeprecation" state? Should it just be removed in 3.9? Maybe I just don't understand the difference of "deprecated" and "pending deprecation" :( ---------- assignee: docs@python components: Documentation, Library (Lib) messages: 348411 nosy: Mariatta, docs@python priority: normal severity: normal status: open title: Is imp module deprecated or pending deprecation? _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue37674> _______________________________________

5 11

[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

[issue36783] No documentation for _FromXandFold C API functions
by Paul Ganssle 05 Jun '20

05 Jun '20

New submission from Paul Ganssle <p.ganssle(a)gmail.com>: In Python 3.6, Time_FromTimeAndFold and PyDateTime_FromDateAndTimeAndFold were added as part of the PEP 495 implementation, but no documentation was added for the C API portions of this change: https://docs.python.org/3.7/c-api/datetime.html The functions were added to this portion of the C API capsule: https://github.com/python/cpython/blob/master/Include/datetime.h#L173 Macros are here: https://github.com/python/cpython/blob/master/Include/datetime.h#L222 These functions should be documented, with `..versionadded:: 3.6` ---------- assignee: docs@python components: Documentation keywords: easy messages: 341337 nosy: docs@python, p-ganssle priority: low severity: normal status: open title: No documentation for _FromXandFold C API functions versions: Python 3.8, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue36783> _______________________________________

6 17

[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

[issue31743] Proportional Width Font on Generated Python Docs PDFs
by Ante Perić 31 May '20

31 May '20

New submission from Ante Perić <synthmeat(a)gmail.com>: Fonts in the generated documentation PDFs, for all Python versions, are proportional width in code blocks, unlike in HTML version, where they are fixed-width. Example https://docs.python.org/2.7/archives/python-2.7.14-docs-pdf-a4.zip ---------- assignee: docs@python components: Documentation files: Screenshot 2017-10-10 12.41.34.png messages: 304024 nosy: docs@python, synthmeat priority: normal severity: normal status: open title: Proportional Width Font on Generated Python Docs PDFs type: enhancement versions: Python 2.7 Added file: https://bugs.python.org/file47203/Screenshot 2017-10-10 12.41.34.png _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue31743> _______________________________________

3 2

[issue34249] Full set of format codes applies to strftime only
by v kats 31 May '20

31 May '20

New submission from v kats <vkatsikaros(a)gmail.com>: Section "strftime() and strptime() Behavior" says: "The full set of format codes supported varies across platforms, because Python calls the platform C library’s strftime() function, and platform variations are common. To see the full set of format codes supported on your platform, consult the strftime(3) documentation." It implies that this applies for strftime only, and indeed it refers to C library’s strftime(). However, it's easy to miss (at least I got confused and lost some time), so I propose to clarify the paragraph. strptime and %s # python Python 2.7.6 (default, Nov 23 2017, 15:49:48) [GCC 4.8.4] on linux2 Type "help", "copyright", "credits" or "license" for more information. >>> from datetime import datetime >>> datetime.strptime('1532689414','%s') Traceback (most recent call last): File "<stdin>", line 1, in <module> strftime and %s python Python 2.7.6 (default, Nov 23 2017, 15:49:48) [GCC 4.8.4] on linux2 Type "help", "copyright", "credits" or "license" for more information. >>> from datetime import datetime >>> datetime.now().strftime('%s') '1532702817' File "/usr/lib/python2.7/_strptime.py", line 317, in _strptime (bad_directive, format)) ValueError: 's' is a bad directive in format '%s' ---------- assignee: docs@python components: Documentation messages: 322498 nosy: docs@python, v kats priority: normal severity: normal status: open title: Full set of format codes applies to strftime only type: enhancement versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue34249> _______________________________________

4 4

[issue13649] termios.ICANON is not documented
by anatoly techtonik 31 May '20

31 May '20

New submission from anatoly techtonik <techtonik(a)gmail.com>: http://docs.python.org/library/termios.html is missing documentation for ICANON flag used to put terminal to "raw" mode. It is also worth to place `termios` raw/canonical mode equivalent on `tty` pages, so that people porting C code to Python could understand the hidden magic. ---------- assignee: docs@python components: Documentation, IO, Library (Lib) messages: 150098 nosy: docs@python, techtonik priority: normal severity: normal status: open title: termios.ICANON is not documented versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13649> _______________________________________

3 3

[docs] [issue21889] https://docs.python.org/2/library/multiprocessing.html#process-and-exceptions doesn't explain exception
by Karl Richter 31 May '20

31 May '20

New submission from Karl Richter: Although the section https://docs.python.org/2/library/multiprocessing.html#process-and-exceptio… (of the multiprocessing module documentation) is titled "... and exceptions" it doesn't say anything about exceptions. I assume that it behaves like the thread API (as stated and referenced in the introduction of the module doc). This implies though that either the reference is limited to that statement (-> remove "and exceptions" from the header as there's no special section on them because everything can be found in thread API) or add an explicit reference to the thread API. If this assumption is wrong the section is badly organized or doesn't make any sense at all. I'm not yet sure about exception handling in the multiprocessing module in case it's different from threads, but that shouldn't matter for this doc issue report. I'd also like to suggest a more detailed section on exceptions with usage of queues to pass them as objects to the parent or another process. ---------- assignee: docs@python components: Documentation messages: 221987 nosy: docs@python, krichter priority: normal severity: normal status: open title: https://docs.python.org/2/library/multiprocessing.html#process-and-exceptio… doesn't explain exception type: enhancement versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue21889> _______________________________________

4 4

[issue35151] Python 2 xml.etree.ElementTree documentation tutorial uses undocumented arguments
by Joshua Honeycutt 31 May '20

31 May '20

New submission from Joshua Honeycutt <joshua.honeycutt(a)gmail.com>: In python 2 documentation 19.7.1.6 (https://docs.python.org/2/library/xml.etree.elementtree.html#parsing-xml-wi…) a second argument (ns) is passed to find and findall. However 19.7.3.2 (https://docs.python.org/2/library/xml.etree.elementtree.html#xml.etree.Elem…) only specifies the single match argument. If we compare the python 3 documentation the namespaces argument is included in the find method. (https://docs.python.org/3/library/xml.etree.elementtree.html#xml.etree.Elem…) Maybe the tutorial was created for python 3 version? I assume the function arguments are automatically generated, but I have not tested or tried these functions in python 2. I just stumbled on the docs while working with python 3. ---------- assignee: docs@python components: Documentation messages: 329174 nosy: docs@python, epakai priority: normal severity: normal status: open title: Python 2 xml.etree.ElementTree documentation tutorial uses undocumented arguments versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue35151> _______________________________________

3 2

[issue33491] mistype of method's name
by Ivan Gushchin 31 May '20

31 May '20

New submission from Ivan Gushchin <gui74327(a)gmail.com>: This link https://docs.python.org/2/library/unittest.html#unittest.SkipTest names method from Capital letter. At the same time method name (according to help(unittest) ) is skipTest (starting lowercase). For those who reads documentation online this mistype leads to error. ---------- assignee: docs@python components: Documentation messages: 316493 nosy: Ivan Gushchin, docs@python priority: normal severity: normal status: open title: mistype of method's name type: enhancement versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue33491> _______________________________________

3 2

[issue16700] Document that bytes OS API can returns unusable results on Windows
by Serhiy Storchaka 31 May '20

31 May '20

New submission from Serhiy Storchaka: Some OS functions which returns bytes (os.environb, os.getenvb(), os.getcwdb(), os.listdir(), os.readlink(), os.walk(), os.path.abspath(), os.path.expanduser(), os.path.expandvars(), os.path.realpath() and may be other) can return unusable result on Windows (see for example issue13247 and issue16656). The documentation should contains strong warnings about this. ---------- assignee: docs@python components: Documentation, Windows messages: 177613 nosy: docs@python, serhiy.storchaka priority: normal severity: normal stage: needs patch status: open title: Document that bytes OS API can returns unusable results on Windows type: enhancement versions: Python 2.7, Python 3.2, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue16700> _______________________________________

6 12

[issue29236] 'an ASCII string of one or more PEM-encoded certificates' needs to be unicode
by Maciej Piechorka 31 May '20

31 May '20

New submission from Maciej Piechorka: In documentation it is specified that cadata parameter in load_verify_locations is 'an ASCII string of one or more PEM-encoded certificates'. However the code is actually determining it based on PyUnicode_Check function so the 'ASCII string' actually needs to be unicode object. In Python 3 it seems to be fixed by checking by PyObject_GetBuffer. ---------- assignee: docs@python components: Documentation, SSL messages: 285176 nosy: docs@python, uzytkownik priority: normal severity: normal status: open title: 'an ASCII string of one or more PEM-encoded certificates' needs to be unicode versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue29236> _______________________________________

4 3

[issue29257] Possible error in discussion of Abstract Base Classes and abstract properties
by Gerald Britton 31 May '20

31 May '20

New submission from Gerald Britton: I was rereading the 2.7 docs about abstract base classes the other day. I found this: "This defines a read-only property; you can also define a read-write abstract property using the ‘long’ form of property declaration:" along with an example. so I copied the example and put in a little surrounding code: from abc import ABCMeta, abstractproperty class C: __metaclass__ = ABCMeta def getx(self): pass def setx(self, value): pass x = abstractproperty(getx, setx) class D(C): @property def x(self):self._x d = D() print(d) When I ran this, I expected an exception, since I defined a read/write abstract property but only implemented the read operation. However, the example runs fine. That is the class D can be instantiated without error. Of course I cannot set the property since I didn't implement that part. Now, If I don't implement the property at all, I can' instantiate the class. I get: "TypeError: Can't instantiate abstract class D with abstract methods x" which is what I would expect. What I don't understand is why I don't get a similar error when I implement the read operation for the property but not the write operation. If this actually doesn't work (catching the non-implementation at instantiation time), then why is it documented this way? To me at least the doc implies that it *will* raise on the missing write property implementation. If ABCs are working as intended, can the documentation be changed to reflect that as per my experience above? If the documentation is correct, can the ABC implementation be modified to function that way? ---------- assignee: docs@python components: Documentation messages: 285356 nosy: docs@python, gbritton priority: normal severity: normal status: open title: Possible error in discussion of Abstract Base Classes and abstract properties versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue29257> _______________________________________

2 1

[issue29323] Wrong documentation (Library) for unicode and str comparison
by RK-5wWm9h 31 May '20

31 May '20

New submission from RK-5wWm9h: PROBLEM (IN BRIEF): In the currently published 2.7.13 The Python Standard Library (Library Reference manual) section 5.6 "Sequence Types" (https://docs.python.org/2/library/stdtypes.html#sequence-types-str-unicode-…): "to compare equal, ... the two sequences must be of the same type" This an *incorrect (and misleading) statement*, for the unicode and str case. PROPOSED FIX: Current full paragraph: "Sequence types also support comparisons. In particular, tuples and lists are compared lexicographically by comparing corresponding elements. This means that to compare equal, every element must compare equal and the two sequences must be of the same type and have the same length. (For full details see Comparisons in the language reference.)" Proposed replacement text: "Sequence types also support comparisons. In particular, tuples and lists are compared lexicographically by comparing corresponding elements. This means that to compare equal, every element must compare equal and the two sequences must be of the same type and have the same length. (Unicode and str are treated as the same type here; for full details see Comparisons in the language reference.)" DETAILS, JUSTIFICATION, CORRECTNESS, ETC: The current incorrect text is really misleading. The behaviour that a str and a unicode object -- despite being objects of different types -- may compare equal, is explicitly stated in the 2.7.13 The Python Language Reference manual, section 5.9 "Comparisons" (https://docs.python.org/2/reference/expressions.html#comparisons): "* Strings are compared lexicographically using the numeric equivalents (the result of the built-in function ord()) of their characters. Unicode and 8-bit strings are fully interoperable in this behavior. [4]" (Aside: Incidentally an earlier paragraph in the Language Ref fails to cover the unicode and str case; see separately filed bug Issue 29321.) ---------- assignee: docs@python components: Documentation messages: 285792 nosy: RK-5wWm9h, docs@python priority: normal severity: normal status: open title: Wrong documentation (Library) for unicode and str comparison type: behavior versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue29323> _______________________________________

4 5

[issue26433] urllib.urlencode() does not explain how to handle unicode
by Thomas Güttler 31 May '20

31 May '20

New submission from Thomas Güttler: The current docs for Python2, don't explain how to handle unicode: https://docs.python.org/2/library/urllib.html#urllib.urlencode It seems to be a common problem. See http://stackoverflow.com/questions/6480723/urllib-urlencode-doesnt-like-uni… It would be nice to document the most pythonic way to handle unicode in urllib.urlencode() ---------- assignee: docs@python components: Documentation messages: 260845 nosy: Thomas Güttler, docs@python priority: normal severity: normal status: open title: urllib.urlencode() does not explain how to handle unicode versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue26433> _______________________________________

2 1

[issue24256] threading.Timer is not a class
by John Runyon 31 May '20

31 May '20

New submission from John Runyon: the documentation (https://docs.python.org/2/library/threading.html#threading.Timer) lists "threading.Timer" as a class. It is not, which means that (for example) you can not use it in isinstance(). "threading._Timer" is a class. "threading.Timer(...).__class__" is a class. "threading.Timer" is a function. >>> import threading >>> threading.Timer <function Timer at 0x7f99cae23848> ---------- assignee: docs@python components: Documentation messages: 243735 nosy: docs@python, jrunyon priority: normal severity: normal status: open title: threading.Timer is not a class versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue24256> _______________________________________

5 6

[issue25511] multiprocessing pool blocks SIGTERM from being handled
by David Jones 31 May '20

31 May '20

New submission from David Jones: This is probably related to #21913, but more specifically concerns the documentation. I have a sub process of a larger program that handles a SIGTERM sent by the main process for a clean shutdown. However, if I launch a parallel task in the sub process, via multiprocessing.Pool.imap_unordered, all signals are blocked until pool finishes running the task. If this isn't going to be fixed, then it ought to at least be clearly documented. It took a very long time to diagnose this problem. It requires a programmer to understand the underlying implementation of a high-level construct, thus defeating the purpose of using a high level construct. Also, is there a way to work around this? ---------- assignee: docs@python components: Documentation messages: 253678 nosy: djones, docs@python priority: normal severity: normal status: open title: multiprocessing pool blocks SIGTERM from being handled type: behavior versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue25511> _______________________________________

2 1

[issue22052] Comparison operators called in reverse order for subclasses with no override.
by Mark Dickinson 31 May '20

31 May '20

New submission from Mark Dickinson: As reported in a StackOverflow question [1]: the order in which the special comparison methods are called seems to be contradictory to the docs [2]. In the following snippet, __eq__ is called with reversed operands first: >>> class A: ... def __eq__(self, other): ... print(type(self), type(other)) ... return True ... >>> class B(A): ... pass ... >>> A() == B() <class '__main__.B'> <class '__main__.A'> True However, the docs note that: """If the right operand’s type is a subclass of the left operand’s type and that subclass provides the reflected method for the operation, this method will be called before the left operand’s non-reflected method. This behavior allows subclasses to override their ancestors’ operations.""" ... which suggests that this reversal should only happen when the subclass B *overrides* A's definition of __eq__ (and indeed that's the usual behaviour for arithmetic operations like __add__). Looking more closely, that statement in the docs is in the 'numeric-types' section, so it's not clear that its rules should apply to the comparison operators. But either way, some doc clarification could be useful. [1] http://stackoverflow.com/q/24919375/270986 [2] https://docs.python.org/3.5/reference/datamodel.html#emulating-numeric-types ---------- assignee: docs@python components: Documentation messages: 223778 nosy: docs@python, mark.dickinson priority: normal severity: normal status: open title: Comparison operators called in reverse order for subclasses with no override. versions: Python 2.7, Python 3.4, Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue22052> _______________________________________

4 9

[issue23514] multiprocessing documentation - little more examples for parallel computing
by Cezary Wagner 31 May '20

31 May '20

New submission from Cezary Wagner: I am little confused with multiprocessing documentation since it does not contain enough examples. Parallel computing is not simple by design so documentation can be little improved to make it simpler. No pattern to use pool with classes. No pattern to exchange objects between processes. Understanding usage of Queue and SimpleQueue or JoinableQueue is not very clear. Current documentation in majority is good reference with very rare examples / patterns. ---------- assignee: docs@python components: Documentation messages: 236519 nosy: Cezary.Wagner, docs@python priority: normal severity: normal status: open title: multiprocessing documentation - little more examples for parallel computing _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue23514> _______________________________________

3 4

[issue20296] PyArg_ParseTuple 2.X docs mention int for "t#", but "Py_ssize_t" for "w#", etc.
by Rob Browning 31 May '20

31 May '20

New submission from Rob Browning: Here (http://docs.python.org/2/c-api/arg.html), the documentation for "t#" says: t# (read-only character buffer) [char *, int]... while the documentation for "w#" says: w# (read-write character buffer) [char *, Py_ssize_t]... However, from getargs.c, it looks like they're handled the same with respect to the size type. At a minimum, it seems like it might make sense to change these docs to match, and if "w#" and "t#" are actually handled similarly to "s#", it would be even better to just change their docs to match (or refer to) "s#"'s which are more detailed, i.e. they mention the PY_SSIZE_T_CLEAN issues, etc. Thanks ---------- assignee: docs@python components: Documentation messages: 208410 nosy: docs@python, rlb priority: normal severity: normal status: open title: PyArg_ParseTuple 2.X docs mention int for "t#", but "Py_ssize_t" for "w#", etc. versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue20296> _______________________________________

3 3

[issue21547] '!s' formatting documentation bug
by Joshua Landau 31 May '20

31 May '20

New submission from Joshua Landau: In the docs for 2.x about the formatting syntax: https://docs.python.org/2/library/string.html#format-string-syntax it says "Two conversion flags are currently supported: '!s' which calls str() on the value, and '!r' which calls repr()." but for unicode formatters, '!s' calls unicode() instead. See http://stackoverflow.com/questions/23773816/why-python-str-format-doesnt-ca… for the question that found this. ---------- assignee: docs@python components: Documentation messages: 218863 nosy: Joshua.Landau, docs@python priority: normal severity: normal status: open title: '!s' formatting documentation bug versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue21547> _______________________________________

5 4

[issue9196] Improve docs for string interpolation "%s" re Unicode strings
by Craig McQueen 31 May '20

31 May '20

New submission from Craig McQueen <python(a)craig.mcqueen.id.au>: I have just been trying to figure out how string interpolation works for "%s", when Unicode strings are involved. It seems it's a bit complicated, but the Python documentation doesn't really describe it. It just says %s "converts any Python object using str()". Here is what I have found (I think), and it could be worth improving the documentation of this somehow. Example 1: "%s" % test_object >From what I can tell, in this case: 1. test_object.__str__() is called. 2. If test_object.__str__() returns a string object, then that is substituted. 3. If test_object.__str__() returns a Unicode object (for some reason), then test_object.__unicode__() is called, then _that_ is substituted instead. The output string is turned into Unicode. This behaviour is surprising. [Note that the call to test_object.__str__() is not the same as str(test_object), because the former can return a Unicode object without causing an error, while the latter, if it gets a Unicode object, will then try to encode('ascii') to a string, possibly generating a UnicodeEncodeError exception.] Example 2: u"%s" % test_object In this case: 1. test_object.__unicode__() is called, if it exists, and the result is substituted. The output string is Unicode. 2. If test_object.__unicode__() doesn't exist, then test_object.__str__() is called instead, converted to Unicode, and substituted. The output string is Unicode. Example 3: "%s %s" % (u'unicode', test_object) In this case: 1. The first substitution causes the output string to be Unicode. 2. It seems that (1) causes the second substitution to follow the same rules as Example 2. This is a little surprising. ---------- assignee: docs@python components: Documentation messages: 109516 nosy: cmcqueen1975, docs@python priority: normal severity: normal status: open title: Improve docs for string interpolation "%s" re Unicode strings versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9196> _______________________________________

5 10

[issue20686] Confusing statement
by Daniel U. Thibault 31 May '20

31 May '20

New submission from Daniel U. Thibault: Near the end of 3.1.3 http://docs.python.org/2/tutorial/introduction.html#unicode-strings you can read: "When a Unicode string is printed, written to a file, or converted with str(), conversion takes place using this default encoding." This can be interpreted as stating that stating that printing a Unicode string (using the print function or the shell's default print behaviour) results in ASCII printout. It can likewise be interpreted as stating that any write of a Unicode string to a file converts the string to ASCII. Experimentation shows this is not true. Perhaps you meant something like this: "When a Unicode string is converted with str() in order to be printed or written to a file, conversion takes place using this default encoding." Grammatical comments: In the statement "When a Unicode string is printed, written to a file, or converted with str(), conversion takes place using this default encoding.", the ", or" puts the three elements of the enumeration on the same level (respectively "printed", "written to a file", and "converted with str()"). The confusion seems to arise because "with str()" was meant to apply to the list as a whole, not just its last element. ---------- assignee: docs@python components: Documentation messages: 211627 nosy: Daniel.U..Thibault, docs@python priority: normal severity: normal status: open title: Confusing statement type: enhancement _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue20686> _______________________________________

4 9

[issue17387] Error in C API documentation of PySequenceMethods
by Alex Orange 31 May '20

31 May '20

New submission from Alex Orange: The documentation at http://docs.python.org/2/c-api/typeobj.html#PySequenceMethods is missing sq_slice between sq_item and sq_ass_item. This will mess up anyone trying to use anything after sq_item (that isn't using designated initializers). ---------- assignee: docs@python components: Documentation messages: 183779 nosy: Alex.Orange, docs@python priority: normal severity: normal status: open title: Error in C API documentation of PySequenceMethods versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue17387> _______________________________________

5 10

[issue15952] format(value) and value.__format__() behave differently with unicode format
by Chris Jerdonek 31 May '20

31 May '20

New submission from Chris Jerdonek: format(value) and value.__format__() behave differently even though the documentation says otherwise: "Note: format(value, format_spec) merely calls value.__format__(format_spec)." (from http://docs.python.org/library/functions.html?#format ) The difference happens when the format string is unicode. For example: >>> format(10, u'n') u'10' >>> (10).__format__(u'n') # parentheses needed to prevent SyntaxError '10' So either the documentation should be changed, or the behavior should be changed to match. Related to this: neither the "Format Specification Mini-Language" documentation nor the string.Formatter docs seem to say anything about the effect that a unicode format string should have on the return value (in particular, should it cause the return value to be unicode or not): http://docs.python.org/library/string.html#formatspec http://docs.python.org/library/string.html#string-formatting See also issue 15276 (int formatting), issue 15951 (empty format string), and issue 7300 (unicode arguments). ---------- assignee: docs@python components: Documentation messages: 170575 nosy: cjerdonek, docs@python priority: normal severity: normal status: open title: format(value) and value.__format__() behave differently with unicode format type: behavior versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15952> _______________________________________

5 8

[issue26369] doc for unicode.decode and str.encode is unnecessarily confusing
by Ben Spiller 30 May '20

30 May '20

New submission from Ben Spiller: It's well known that lots of people struggle writing correct programs using non-ascii strings in python 2.x, but I think one of the main reasons for this could be very easily fixed with a small addition to the documentation for str.encode and unicode.decode, which is currently quite vague. The decode/encode methods really make most sense when called on a unicode string i.e. unicode.encode() to produce a byte string, or on a byte string e.g. str.decode() to produce a unicode object from a byte string. However, the additional presence of the opposite methods str.encode() and unicode.decode() is quite confusing, and a frequent source of errors - e.g. calling str.encode('utf-8') first DECODES the str object (which might already be in utf8) to a unicode string **using the default encoding of "ascii"** (!) before ENCODING to a utf-8 byte str as requested, which of course will fail at the first stage with the classic error "UnicodeDecodeError: 'ascii' codec can't decode byte" if there are any non-ascii chars present. It's unfortunate that this initial decode/encode stage ignores both the "encoding" argument (used only for the subsequent encode/decode) and the "errors" argument (commonly used when the programmer is happy with a best-effort conversion e.g. for logging purposes). Anyway, given this behaviour, a lot of time would be saved by a simple sentence on the doc for str.encode()/unicode.decode() essentially warning people that those methods aren't that useful and they probably really intended to use str.decode()/unicode.encode() - the current doc gives absolutely no clue about this extra stage which ignores the input arguments and sues 'ascii' and 'strict'. It might also be worth stating in the documentation that the pattern (u.encode(encoding) if isinstance(u, unicode) else u) can be helpful for cases where you unavoidably have to deal with both kinds of input, string calling str.encode is such a bad idea. In an ideal world I'd love to see the implementation of str.encode/unicode.decode changed to be more useful (i.e. instead of using ascii, it would be more logical and useful to use the passed-in encoding to perform the initial decode/encode, and the apss-in 'errors' value). I wasn't sure if that change would be accepted so for now I'm proposing better documentation of the existing behaviour as a second-best. ---------- assignee: docs@python components: Documentation messages: 260359 nosy: benspiller, docs@python priority: normal severity: normal status: open title: doc for unicode.decode and str.encode is unnecessarily confusing type: behavior versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue26369> _______________________________________

7 16

[issue31869] commentary on ssl.PROTOCOL_TLS
by J Sloot 30 May '20

30 May '20

New submission from J Sloot <jsloot(a)gmail.com>: on https://docs.python.org/2/library/ssl.html#ssl.PROTOCOL_TLS for ssl.PROTOCOL_TLS When the commentary from ssl.PRTOCOL_TLS moved from PROTOCOL_SSLv23 to PROTOCOL_TLS the note {Despite the name, this option can select "TLS" protocols as well as "SSL"} didn't change. Suggested new wording {Despite the name, this option can select "SSL" protocols as well as "TLS"} ---------- assignee: docs@python components: Documentation messages: 304996 nosy: J Sloot, docs@python priority: normal severity: normal status: open title: commentary on ssl.PROTOCOL_TLS versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue31869> _______________________________________

5 6

[issue29017] Docs: PySide is provided by 'The Qt Company' and not by 'Nokia'
by Ettore Atalan 30 May '20

30 May '20

New submission from Ettore Atalan: Regarding URL: http://docs.python.org/3/library/othergui.html Section: PySide PySide is provided by 'The Qt Company' and no longer by 'Nokia' like mentioned in the documentation. ---------- assignee: docs@python components: Documentation messages: 283646 nosy: Ettore Atalan, docs@python priority: normal severity: normal status: open title: Docs: PySide is provided by 'The Qt Company' and not by 'Nokia' versions: Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue29017> _______________________________________

4 8

[issue37218] Default hmac.new() digestmod has not been removed from documentation
by Alex Willmer 28 May '20

28 May '20

New submission from Alex Willmer <alex(a)moreati.org.uk>: Until Python 3.8 hmc.new() defaulted the digestmod argument to 'hmac-md5'. This was deperecated, to be removed in Python 3.8. In Python 3.8.0b1 it is gone, e.g. Python 3.8.0b1 (default, Jun 6 2019, 03:44:52) [GCC 7.4.0] on linux Type "help", "copyright", "credits" or "license" for more information. >>> import hmac >>> hmac.new(b'qwertyuiop').name Traceback (most recent call last): File "<stdin>", line 1, in <module> File "/usr/lib/python3.8/hmac.py", line 146, in new return HMAC(key, msg, digestmod) File "/usr/lib/python3.8/hmac.py", line 49, in __init__ raise ValueError('`digestmod` is required.') ValueError: `digestmod` is required. but the deprecation note, and the documented signature haven't been updated. PR incoming ---------- assignee: docs@python components: Documentation messages: 345144 nosy: Alex.Willmer, docs@python priority: normal severity: normal status: open title: Default hmac.new() digestmod has not been removed from documentation versions: Python 3.8, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue37218> _______________________________________

4 5

[issue37878] sub-ineterpreters : Document PyThreadState_DeleteCurrent() ?
by Joannah Nanjekye 28 May '20

28 May '20

New submission from Joannah Nanjekye <nanjekyejoannah(a)gmail.com>: I just noticed that PyThreadState_DeleteCurrent()in Python/pystate.c is not documented. Relevant documentation should go in Doc/c-api/init.rst If no one objects to this. ---------- assignee: docs@python components: Documentation keywords: easy messages: 349881 nosy: docs@python, eric.snow, nanjekyejoannah, ncoghlan, vstinner priority: normal severity: normal stage: needs patch status: open title: sub-ineterpreters : Document PyThreadState_DeleteCurrent() ? versions: Python 3.8, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue37878> _______________________________________

5 24

[issue27779] Sync-up docstrings in C version of the the decimal module
by Raymond Hettinger 27 May '20

27 May '20

New submission from Raymond Hettinger: The pure python version of decimal has extensive docstrings with text and explanatory examples drawn directly from the decimal arithmetic specification. Those should all be copied to the C version as well. This will improve usability for interactive use and improve help(). I would like to leave this work for one of the new aspiring core devs (perhaps Elizabeth, Lisa, or Nofar). ---------- assignee: docs@python components: Documentation keywords: easy messages: 272875 nosy: docs@python, rhettinger priority: normal severity: normal stage: needs patch status: open title: Sync-up docstrings in C version of the the decimal module versions: Python 3.5, Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue27779> _______________________________________

4 18

[issue35714] Document that the null character '\0' terminates a struct format spec
by Dan Snider 26 May '20

26 May '20

New submission from Dan Snider <mr.assume.away(a)gmail.com>: ie.: >>> from struct import calcsize >>> calcsize('\144\u0064\000xf\U00000031000\60d\121\U00000051') 16 I'm sure some people think it's obvious or even expect the null character to signal EOF but it probably isn't obvious at all to those without experience in lower level languages. It actually seems like Python goes out of its way to make sure everything treats the null character no more special than the letter "H", which is good. At first glance I'd think something like this was just another trivial quirk of the language and not bring it up, but because the documentation doesn't mention it I actually got stuck on something related for half an hour when unit testing some dynamically generated format specs. Without going into unnecessary detail, what happened was that a typo in another tangentially related part of the test was enabling the generation of a rogue null byte. I'm bad at those "find face in the crowd" puzzles and this was hardly different, being literally camouflaged within a 300 character format spec containing a random mixture of escaped and non-escaped source characters in the forms: \Uffffffff, \uffff, \777, \xff, \x00, + latin/ascii. If I'm not the only one who sees this as a slightly bigger deal than poor documentation, the fix is trivial with an extra call to PyBytes_GET_SIZE when null is found. But just because I can't think of a use case in allowing the null character to precede other characters in the format string doesn't mean there isn't one, which is why only documentation is currently selected. ---------- assignee: docs@python components: Documentation, Library (Lib) messages: 333424 nosy: bup, docs@python priority: normal severity: normal status: open title: Document that the null character '\0' terminates a struct format spec versions: Python 3.6, Python 3.7, Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue35714> _______________________________________

6 16

[issue37973] improve docstrings of sys.float_info
by Sergey Fedoseev 24 May '20

24 May '20

New submission from Sergey Fedoseev <fedoseev.sergey(a)gmail.com>: In [8]: help(sys.float_info) ... | | dig | DBL_DIG -- digits | This is not very helpful, https://docs.python.org/3/library/sys.html#sys.float_info is more verbose, so probably docstrings should be updated from where. ---------- assignee: docs@python components: Documentation messages: 350703 nosy: docs@python, sir-sigurd priority: normal severity: normal status: open title: improve docstrings of sys.float_info type: enhancement _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue37973> _______________________________________

5 8

[issue23738] Clarify documentation of positional-only default values
by Martin Panter 22 May '20

22 May '20

New submission from Martin Panter: This patch adds the PEP 457 positional-only slash “/” indicator to some function signatures in the documentation. I only looked at the the os, builtin, binascii, zlib and fcntl modules, and their functions where the documentation incorrectly suggests that they accept keyword arguments. For example, I changed eval(expression, globals=None, locals=None) to eval(expression, globals=None, locals=None, /) References: * Issue 22832: “fcntl” module changed to look like accepting keyword arguments * Ongoing discussion: <https://mail.python.org/pipermail/python-dev/2015-March/138847.html> There are many more instances where square brackets are used, or the arguments are mandatory. See the PEP for examples, but I do not think it is so important to “fix” them. I also fixed parameter name mismatches that I discovered for a quite a few functions that do take keyword arguments. One more thing I noticed, that I do not know how to fix, is the Argument Clinic signatures list invalid default values for zlib.compressobj(zdict=None) and os.utime(ns=None): >>> zlib.compressobj(zdict=None) Traceback (most recent call last): File "<stdin>", line 1, in <module> TypeError: 'NoneType' does not support the buffer interface >>> os.utime("dummy", ns=None) Traceback (most recent call last): File "<stdin>", line 1, in <module> TypeError: utime: 'ns' must be a tuple of two ints ---------- assignee: docs@python components: Documentation files: pos-defaults.patch keywords: patch messages: 238890 nosy: docs@python, serhiy.storchaka, vadmium priority: normal severity: normal status: open title: Clarify documentation of positional-only default values versions: Python 3.4, Python 3.5 Added file: http://bugs.python.org/file38632/pos-defaults.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue23738> _______________________________________

6 18

[issue34431] Docs does not eval allows code object as argument
by Jonathan Fine 17 May '20

17 May '20

New submission from Jonathan Fine <jfine2358(a)gmail.com>: See https://docs.python.org/3.6/library/functions.html#eval This says the following won't happen. But it does. Python 3.6.2 (default, Jul 29 2017, 00:00:00) [GCC 4.8.4] on linux Type "help", "copyright", "credits" or "license" for more information. >>> def fn(): print(3); return 4 ... >>> eval(fn.__code__) 3 4 Compare with https://docs.python.org/3.6/library/functions.html#exec Search for eval in title of open issues bring up related #22057 (The doc say all globals are copied on eval(), but only __builtins__ is copied) #25810 (Python 3 documentation for eval is incorrect) ---------- assignee: docs@python components: Documentation messages: 323716 nosy: docs@python, jfine2358 priority: normal severity: normal status: open title: Docs does not eval allows code object as argument versions: Python 2.7, 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/issue34431> _______________________________________

4 8

[issue18262] ZipInfo.external_attr are not documented
by anatoly techtonik 17 May '20

17 May '20

New submission from anatoly techtonik: zipfile doesn't restore file attributes when extracting. Documentation should at least contain example how to do this manually, because the ony way to do this - through ZipInfo.external_attr is too cryptic. ---------- assignee: docs@python components: Documentation messages: 191447 nosy: docs@python, techtonik priority: normal severity: normal status: open title: ZipInfo.external_attr are not documented versions: Python 2.6, Python 2.7, Python 3.1, Python 3.2, Python 3.3, Python 3.4, Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18262> _______________________________________

6 12

[issue11425] Cleanup sample codes in tutorial.
by INADA Naoki 14 May '20

14 May '20

New submission from INADA Naoki <songofacandy(a)gmail.com>: * Insert spaces around operators and after commas. * Split one liner blocks (ex. def foo(x, y): return x + y) to multi-line blocks. * Insert empty line after def block for scripts (not interactive mode). * Use new-style raise (s/ralse KeyboardInterrupt/raise KeyboardInterrupt()/) * Use x ** 3 instead of x * x * x. Attached patch is for Python 2.6. I'll make same changes for Python 3.1 if this patch is accepted. ---------- assignee: docs@python components: Documentation files: cleanup_tutorial_codes.patch keywords: patch messages: 130225 nosy: docs@python, naoki priority: normal severity: normal status: open title: Cleanup sample codes in tutorial. versions: Python 2.6, Python 2.7, Python 3.1, Python 3.2, Python 3.3 Added file: http://bugs.python.org/file21027/cleanup_tutorial_codes.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11425> _______________________________________

5 5

[issue23677] Mention dict and set comps in library reference
by Frank Millman 10 May '20

10 May '20

New submission from Frank Millman: This is from the documentation at Section 4.6.4. Lists """ Lists may be constructed in several ways: Using a pair of square brackets to denote the empty list: [] Using square brackets, separating items with commas: [a], [a, b, c] Using a list comprehension: [x for x in iterable] Using the type constructor: list() or list(iterable) """ Comprehensions are mentioned as a constructor. This is from the documentation at Section 4.10. Mapping Types """ Dictionaries can be created by placing a comma-separated list of key: value pairs within braces, for example: {'jack': 4098, 'sjoerd': 4127} or {4098: 'jack', 4127: 'sjoerd'}, or by the dict constructor. class dict(**kwarg) class dict(mapping, **kwarg) class dict(iterable, **kwarg) Return a new dictionary initialized from an optional positional argument and a possibly empty set of keyword arguments. """ There is no mention of dictionary comprehensions. For consistency, I believe that the documentation for Dicts and Sets should mention comprehensions. ---------- assignee: docs@python components: Documentation messages: 238186 nosy: FrankMillman, docs@python priority: normal severity: normal status: open title: Mention dict and set comps in library reference versions: Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue23677> _______________________________________

8 11

[issue26817] Docs for StringIO should link to io.BytesIO
by Thomas Guettler 10 May '20

10 May '20

New submission from Thomas Guettler: I think a warning at the top of StringIO docs is needed. And it should link to io.BytesIO. Maybe even deprecate StringIO and cStringIO in Python2? StringIO docs: https://docs.python.org/2/library/stringio.html io.BytesIO docs: https://docs.python.org/2/library/io.html#io.BytesIO I would like to see this at the top of StringIO: {{{ Please use io.BytesIO and io.StringIO since this module is not supported in Python3 }} ---------- assignee: docs@python components: Documentation messages: 263917 nosy: docs@python, guettli priority: normal severity: normal status: open title: Docs for StringIO should link to io.BytesIO versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue26817> _______________________________________

3 2

[issue21596] asyncio.wait fails when futures list is empty
by Sebastian Kreft 04 May '20

04 May '20

New submission from Sebastian Kreft: Passing an empty list/set of futures to asyncio.wait raises an Exception, which is a little annoying in some use cases. Probably this was the intended behavior as I see there's a test case for that. If such, then I would propose to document that behavior. ---------- assignee: docs@python components: Documentation messages: 219290 nosy: Sebastian.Kreft.Deezer, docs@python priority: normal severity: normal status: open title: asyncio.wait fails when futures list is empty versions: Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue21596> _______________________________________

5 9

[issue33649] asyncio docs overhaul
by Yury Selivanov 04 May '20

04 May '20

New submission from Yury Selivanov <yselivanov(a)gmail.com>: An overhaul of asyncio documentation is long overdue. Here's the structure for it that I have in mind: - Introduction (what is asyncio and async/await) - A quick tutorial (show how to use asyncio.run() and basic functions like asyncio.sleep() and teach that asyncio programs are all about async/await and *not* about callbacks or event loops) - High-level APIs (Tasks, Streams, Subprocesses, few other functions) - Low-level APIs - Preface (talk a bit about everything: what's an event loop, what is a Future and a Transport) - Futures - Event loop APIs - Transports and Protocols (when to use and when not to use them) - Tutorials - High-level networking server - HTTP application - Low-level protocol implementation using Transports - etc ---------- assignee: docs@python components: Documentation, asyncio messages: 317709 nosy: akuchling, asvetlov, docs@python, yselivanov priority: normal severity: normal status: open title: asyncio docs overhaul type: enhancement versions: Python 3.7, Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue33649> _______________________________________

17 74

[issue8940] *HTTPServer need a summary page with API inheritance table
by anatoly techtonik 27 Apr '20

27 Apr '20

New submission from anatoly techtonik <techtonik(a)gmail.com>: The abundance of methods and hierarchy depth of various servers from "Internet Protocols and Support" section makes it extremely hard to navigate information. You need a strong OOP background to be able to use this doc effectively, as examples are not intuitive otherwise. Usually you need a decent IDE (such as Eclipse) to get a picture of class hierarchy and a table of all available methods with a mark where they were inherited from. Such table (at least Class Hierarchy view screenshot from Eclipse) should be available in reference for descendant classes. ---------- assignee: docs@python components: Documentation messages: 107321 nosy: docs@python, techtonik priority: normal severity: normal status: open title: *HTTPServer need a summary page with API inheritance table versions: Python 2.7, Python 3.1, Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue8940> _______________________________________

6 7

[issue14418] Document differences in SocketServer between Python 2.6 and 2.7
by Geoffrey Bache 27 Apr '20

27 Apr '20

New submission from Geoffrey Bache <gjb1002(a)users.sourceforge.net>: Here I'm referring to the section about RequestHandler objects under the SocketServer page. http://docs.python.org/release/2.7.2/library/socketserver.html#requesthandl… This appears to be the same in Python 2.6 and Python 2.7. But the objects don't behave the same, in two respects: 1) For finish() "If setup() or handle() raise an exception, this function will not be called." This is true in Python 2.6. It appears to no longer be true in Python 2.7, where finish() is called in a "finally" clause. 2) For handle(). "The default implementation does nothing". This is true up to a point, but using the default implementation has different effects. Specifically, if I try to read from a socket when the server has not written anything, I get an exception in Python 2.6 and an empty string in Python 2.7. Consider this code: ## server.py from SocketServer import TCPServer, StreamRequestHandler import sys, socket server = TCPServer((socket.gethostname(), 0), StreamRequestHandler) host, port = server.socket.getsockname() address = host + ":" + str(port) print "Started server at", address sys.stdout.flush() server.serve_forever() ## client.py import sys, socket servAddr = sys.argv[1] host, port = servAddr.split(":") serverAddress = (host, int(port)) sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM) sock.connect(serverAddress) sock.sendall("Some Message") sock.shutdown(1) response = sock.makefile().read() print "Got reply:", response sock.close() and compare the following: $ python2.7 server.py & Started server at 127.0.1.1:42759 $ python2.7 client.py 127.0.1.1:42759 Got reply: $ python2.6 server.py & Started server at 127.0.1.1:42758 $ python client.py 127.0.1.1:42758 Traceback (most recent call last): File "client.py", line 12, in <module> response = sock.makefile().read() File "/usr/lib/python2.7/socket.py", line 351, in read data = self._sock.recv(rbufsize) socket.error: [Errno 104] Connection reset by peer (doesn't matter which Python runs the client in the last case) I am unsure whether this is a bug in Python 2.6, or really what the reasoning behind the behaviour difference is, but I think this change in behaviour is worth a small note in the documentation (how it will behave if you try to read when nothing has been written) ---------- assignee: docs@python components: Documentation messages: 156869 nosy: docs@python, gjb1002 priority: normal severity: normal status: open title: Document differences in SocketServer between Python 2.6 and 2.7 versions: Python 2.6, Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14418> _______________________________________

5 5

[issue26665] pip is not bootstrapped by default
by Axel Luttgens 27 Apr '20

27 Apr '20

New submission from Axel Luttgens: Relevant page: https://docs.python.org/2/library/ensurepip.html One may read: In most cases, end users of Python shouldn’t need to invoke this module directly (as pip should be bootstrapped by default), but it may be needed if installing pip was skipped when installing Python (or when creating a virtual environment) or after explicitly uninstalling pip. As far as I correctly read the configure file that comes with the 2.7.11 tarball, the default is to behave as if --with-ensurepip=no had been passed. As a result, that sentence fragment: (as pip should be bootstrapped by default) may appear somewhat ambiguous for those compiling Python themselves. Perhaps could this one avoid some head scratching: (as packagers are expected to have bootstrapped pip) HTH, Axel ---------- assignee: docs@python components: Documentation messages: 262610 nosy: Axel, docs@python priority: normal severity: normal status: open title: pip is not bootstrapped by default type: enhancement versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue26665> _______________________________________

4 5

[issue30882] Built-in list disappeared from Python 2.7 intersphinx inventory
by Christoph Deil 27 Apr '20

27 Apr '20

New submission from Christoph Deil: We have a project where we sub-class `list`. Since recently our docs build is failing because the intersphinx inventory entry for `list` on Python 2.7 doesn't exist any more. I think this is a regression, because Python 2.7 is supposed to be stable and other functions and classes here are still there, just "list" is missing: https://docs.python.org/2.7/library/functions.html#func-list Just in case someone else sees this issue, the Sphinx warning looks like this: ``` docs/api/pyregion.ShapeList.rst:7: WARNING: py:class reference target not found: list ``` if you have something like ``` class ShapeList(list): """My list sub-class""" ``` ---------- assignee: docs@python components: Documentation messages: 297993 nosy: Christoph.Deil, docs@python priority: normal severity: normal status: open title: Built-in list disappeared from Python 2.7 intersphinx inventory versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue30882> _______________________________________

5 4

[issue33586] 2.7.15 missing release notes on download page
by Eric N. Vander Weele 27 Apr '20

27 Apr '20

New submission from Eric N. Vander Weele <ericvw(a)gmail.com>: When visiting https://www.python.org/downloads/ and attempting to look at the 2.7.15 release notes, the 'Release Notes' link on the far right of the table, it resolves to https://www.python.org/downloads/. ---------- assignee: docs@python components: Documentation messages: 317185 nosy: docs@python, ericvw priority: normal severity: normal status: open title: 2.7.15 missing release notes on download page versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue33586> _______________________________________

4 3

[issue38387] Document PyDoc_STRVAR
by Brad Solomon 27 Apr '20

27 Apr '20

New submission from Brad Solomon <brad.solomon.1124(a)gmail.com>: The C-API reference would benefit from a short mention of PyDoc_STRVAR usage, since it is used so frequently within Modules/. ---------- assignee: docs@python components: Documentation messages: 354053 nosy: bsolomon1124, docs@python priority: normal pull_requests: 16195 severity: normal status: open title: Document PyDoc_STRVAR type: enhancement _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue38387> _______________________________________

2 6

[issue14759] Berkeley DB License conditions are onerous (and poorly documented)
by Jeff Laing 27 Apr '20

27 Apr '20

New submission from Jeff Laing <jefflaing(a)gmail.com>: As part of an audit of license compliance, I was looking at the terms in the LICENSE.txt that describe the Berkeley DB product. I had thought this would be under the standard Berkeley license, but Oracle have added their own zinger. * 3. Redistributions in any form must be accompanied by information on * how to obtain complete source code for the DB software and any * accompanying software that uses the DB software. The source code * must either be included in the distribution or be available for no * more than the cost of distribution plus a nominal fee, and must be * freely redistributable under reasonable conditions. So, my application, which embeds Python (rather than running it as python.exe) and includes the standard runtime library, must distribute my source code. This page: http://mail.python.org/pipermail/python-dev/2008-September/082316.html suggests that this is not the case for regular Python, but it makes no statement about "embedding". Sadly the Oracle page it links to suggesting this is not an issue, does not exist. The general "License" page on the Python websites makes no reference whatsoever to Berkeley DB license obligations. I note that there are other modules mentioned on the Licenses webpage that are not in the LICENSES.txt file, and vice versa. I have no idea whether this is deliberate, or an oversight. ---------- assignee: docs@python components: Documentation messages: 160238 nosy: Jeff.Laing, docs@python priority: normal severity: normal status: open title: Berkeley DB License conditions are onerous (and poorly documented) type: enhancement versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14759> _______________________________________

5 12

[issue22863] https://docs.python.org/ should make a true 2.7.8 version available
by Marc-Andre Lemburg 27 Apr '20

27 Apr '20

New submission from Marc-Andre Lemburg: The documentation shown for Python 2.7.8 currently includes 2.7.9 parts, e.g. for the ssl modules (https://docs.python.org/2.7/library/ssl.html). Since there were so many changes to the ssl module for 2.7.9 which are not available in 2.7.8, I think it would be good to be able to not only select "2.7.8" from the doc version drop-down, but to also really get that particular version of the documentation, and provide a separate "2.7.9" snapshop as well. I tried https://docs.python.org/2.7.8/library/ssl.html, but that doesn't seem to exist. PS: I'm not sure whether this is the right tracker to report this. Feel free to move it elsewhere. ---------- assignee: docs@python components: Documentation messages: 231113 nosy: docs@python, lemburg priority: normal severity: normal status: open title: https://docs.python.org/ should make a true 2.7.8 version available versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue22863> _______________________________________

5 6

[issue17904] bytes should be listed as built-in function for 2.7
by Florent Xicluna 27 Apr '20

27 Apr '20

New submission from Florent Xicluna: Looking into the summary table, there's no information about the `bytes` built-in alias for `str`: http://docs.python.org/2/library/functions.html IMHO it should appear in this table (as str, unicode, bytearray) with the appropriate `.. versionadded:`. ---------- assignee: docs@python components: Documentation messages: 188349 nosy: docs@python, flox priority: normal severity: normal status: open title: bytes should be listed as built-in function for 2.7 type: behavior versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue17904> _______________________________________

5 6

[issue37626] Documentation：conflict between docs
by 徐靖 23 Apr '20

23 Apr '20

New submission from 徐靖 <shiyuchongf(a)gmail.com>: In https://docs.python.org/3/whatsnew/3.4.html#api-and-feature-removals,It is said "inspect.Signature: positional-only parameters are now required to have a valid name." But in https://docs.python.org/3/library/inspect.html?highlight=3.4#inspect.Signat…, the actual change happened in inspect.Parameter, " Changed in version 3.4: In Python 3.3 Parameter objects were allowed to have name set to None if their kind was set to POSITIONAL_ONLY. This is no longer permitted." So I wonder is it a mistake? ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue37626> _______________________________________

3 3

[issue37846] declare that Text I/O use buffer inside
by Windson Yang 23 Apr '20

23 Apr '20

New submission from Windson Yang <wiwindson(a)outlook.com>: At the beginning of https://docs.python.org/3.7/library/io.html#io.RawIOBase, we declared that > Binary I/O (also called buffered I/O) and > Raw I/O (also called unbuffered I/O) But we didn't mention if Text I/O use buffer or not which led to confusion. Even though we talked about it later in https://docs.python.org/3.7/library/io.html#class-hierarchy > The TextIOBase ABC, another subclass of IOBase, deals with streams whose bytes represent text, and handles encoding and decoding to and from strings. TextIOWrapper, which extends it, is a buffered text interface to a buffered raw stream (BufferedIOBase). Finally, StringIO is an in-memory stream for text. IMO, it will be better to declare 'Reads and writes are internally buffered in order to speed things up' at the very beginning in > Text I/O > Text I/O expects and produces str objects... or maybe > class io.TextIOBase > Base class for text streams. This class provides a character and line based interface to stream I/O. It inherits IOBase. There is no public constructor. ---------- assignee: docs@python components: Documentation messages: 349633 nosy: Windson Yang, docs@python priority: normal severity: normal status: open title: declare that Text I/O use buffer inside type: enhancement versions: Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue37846> _______________________________________

2 3

[issue37465] Incorrect documentation for `s#` arguments in C API argument parsing
by Enrico Zini 23 Apr '20

23 Apr '20

New submission from Enrico Zini <enrico(a)enricozini.org>: In https://docs.python.org/3.9/c-api/arg.html, in the documentation for parsing argument, there is: s# (str, read-only bytes-like object) [const char *, int or Py_ssize_t] In my amd64 system, `Py_ssize_t` is a different type than `int`, and passing a `Py_ssize_t` causes undefine behaviour. I assume this has been switched to an `int` in the API, and that thisinstance of the documentation has not been updated accordingly. At the bottom of the page in the documentation of `Py_BuildValue`, `s#` is correctly documented as using an `int` and no `Py_ssize_t`, for example. ---------- assignee: docs@python components: Documentation messages: 346974 nosy: docs@python, enrico priority: normal severity: normal status: open title: Incorrect documentation for `s#` arguments in C API argument parsing versions: Python 3.5, Python 3.6, Python 3.7, Python 3.8, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue37465> _______________________________________

5 7

[issue13743] xml.dom.minidom.Document class is not documented
by Sandro Tosi 12 Apr '20

12 Apr '20

New submission from Sandro Tosi <sandro.tosi(a)gmail.com>: Hello, following up http://mail.python.org/pipermail/docs/2012-January/007026.html I noticed the whole Document class (and relative methods) is not documented. Maybe it is a choice to not document it, or maybe it's just a missing doc, dunno, the's why I'm opening this :) ---------- assignee: docs@python components: Documentation messages: 150935 nosy: docs@python, sandro.tosi priority: normal severity: normal stage: needs patch status: open title: xml.dom.minidom.Document class is not documented versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13743> _______________________________________

6 9

[issue21760] inspect documentation describes module type inaccurately
by Eric Snow 11 Apr '20

11 Apr '20

New submission from Eric Snow: In the documentation for the inspect module, the module type is described with just 2 of its potential 7 attributes. The language reference[2] and importlib docs[3] both provide an accurate list of module attributes. Furthermore, the description for __file__ should be fixed. It should be clear that __file__ reflects the location from which the module was loaded, that location is not necessarily a filename, and the attribute may not exist if the module was not loaded from a specific location (e.g. builtin and frozen modules). The same goes for __cached__ [1] https://docs.python.org/dev/library/inspect.html#types-and-members [2] https://docs.python.org/3/reference/import.html#import-related-module-attri… [3] https://docs.python.org/3/library/importlib.html#importlib.machinery.Module… ---------- assignee: docs@python components: Documentation messages: 220576 nosy: docs@python, eric.snow priority: normal severity: normal stage: needs patch status: open title: inspect documentation describes module type inaccurately versions: Python 3.4, Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue21760> _______________________________________

4 5

[issue32377] Difference in ressurrection behavior with __del__ in py2 vs. py3
by Eric Cousineau 09 Apr '20

09 Apr '20

New submission from Eric Cousineau <eric.cousineau(a)tri.global>: Due to how `PyObject_CallFinalizer` is written in python3, `__del__` will only *ever* be called once. In my use case, I am experimenting with a feature in `pybind11` to prevent slicing with Python class instances that inherit from pybind11-C++ base classes, which involves detecting when an instance loses all reference in Python (`Py_REFCNT(...) == 0`) but still has reference in C++ (`shared_ptr::count() > 0`), and reviving the Python portion when this situation happens. In python2, I could do this without a hitch, as a resurrected object could have its `__del__` method called multiple times (through `tp_dealloc` I believe?). But in python3, the object is marked with `_PyGC_SET_FINALIZED(...)`, thus preventing `__del__` from being called again. It'd be nice to either (a) somehow allow `__del__` to be called naturally without too much fuss or, at the least, (b) have this reflected in the documentation: https://docs.python.org/3/reference/datamodel.html#object.__del__ See attached `revive_test`. Example execution: ``` $ python2 ./revive_test.py Revive Destroy [ Done ] $ python3 ./revive_test.py Revive [ Done ] ``` ---------- assignee: docs@python components: Documentation files: revive_test.py messages: 308660 nosy: Eric Cousineau, docs@python priority: normal severity: normal status: open title: Difference in ressurrection behavior with __del__ in py2 vs. py3 type: behavior versions: Python 3.4, Python 3.5, Python 3.6 Added file: https://bugs.python.org/file47339/revive_test.py _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue32377> _______________________________________

3 11

[issue15140] PEP 384 inconsistent with implementation
by Antoine Pitrou 01 Apr '20

01 Apr '20

New submission from Antoine Pitrou <pitrou(a)free.fr>: In PEP 384, the PyType_Spec struct has a "const char *doc" that is not present in the implementation (Include/object.h). ---------- assignee: docs@python components: Documentation messages: 163449 nosy: docs@python, loewis, pitrou priority: normal severity: normal stage: needs patch status: open title: PEP 384 inconsistent with implementation type: behavior _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15140> _______________________________________

4 3

[issue37390] Generate table of audit events for docs
by Steve Dower 30 Mar '20

30 Mar '20

New submission from Steve Dower <steve.dower(a)python.org>: All audit events are marked in the docs with the ".. audit-event:: <name> <args>" syntax. We should automatically collate these into a single table and generate a new doc page as part of docs build. ---------- assignee: docs@python components: Documentation messages: 346417 nosy: christian.heimes, docs@python, steve.dower priority: normal severity: normal stage: needs patch status: open title: Generate table of audit events for docs type: enhancement versions: Python 3.8, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue37390> _______________________________________

3 17

[issue15436] __sizeof__ is not documeneted
by Serhiy Storchaka 22 Mar '20

22 Mar '20

New submission from Serhiy Storchaka <storchaka(a)gmail.com>: __sizeof__ is not mentioned on page Doc/reference/datamodel.rst together with other special methods. There is no __sizeof__ in index. ---------- assignee: docs@python components: Documentation messages: 166245 nosy: docs@python, storchaka priority: normal severity: normal status: open title: __sizeof__ is not documeneted versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15436> _______________________________________

14 24

[issue21108] Add doc examples for importlib
by Saimadhav Heblikar 18 Mar '20

18 Mar '20

New submission from Saimadhav Heblikar: The imp module was the defacto module to access the import internals,upto 3.3 It has been deprecated(pending) in 3.4 in favor of importlib. There are plenty of examples on how to use imp around the web, but very little (even in doc.python.org), on how to use importlib. The proposed patch adds couple of examples. These examples are aimed towards people, who were earlier using imp's load_module(). Inspiration for the patch from this SO answer, where user had to go through source code. http://stackoverflow.com/questions/19009932/import-abitrary-python-source-f… ---------- assignee: docs@python components: Documentation files: importlib-example.patch keywords: patch messages: 215220 nosy: docs@python, sahutd priority: normal severity: normal status: open title: Add doc examples for importlib versions: Python 3.4 Added file: http://bugs.python.org/file34675/importlib-example.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue21108> _______________________________________

5 6

[issue22014] Add summary table for OS exception <-> errno mapping
by Nick Coghlan 18 Mar '20

18 Mar '20

New submission from Nick Coghlan: It would be handy if the main OS exception docs at https://docs.python.org/3/library/exceptions.html#os-exceptions included a summary table mapping between exception types and errno names, akin to the one in the original PEP (http://www.python.org/dev/peps/pep-3151/#new-exception-classes) ---------- assignee: docs@python components: Documentation keywords: easy messages: 223499 nosy: docs@python, ncoghlan priority: normal severity: normal status: open title: Add summary table for OS exception <-> errno mapping versions: Python 3.4, Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue22014> _______________________________________

5 10

[issue20039] Missing documentation for argparse.ArgumentTypeError
by Arnaut Billings 11 Mar '20

11 Mar '20

New submission from Arnaut Billings: There is no documentation for argparse.ArgumentTypeError: http://docs.python.org/3/library/unittest.html Though it does appear in an example and its usage is simple enough to decipher what it means, it would none the less look more professional if there was formal documentation for it. Not only on what it is, but when it should actually be used, etc... ---------- assignee: docs@python components: Documentation messages: 206723 nosy: arnaut-billings, docs@python priority: normal severity: normal status: open title: Missing documentation for argparse.ArgumentTypeError versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue20039> _______________________________________

5 6

[issue17422] language reference should specify restrictions on class namespace
by Eric Snow 10 Mar '20

10 Mar '20

New submission from Eric Snow: (related to PEP 422 and issue #17044) The execution namespace from a class definition is passed as the third argument to the metaclass (see builtin___build_class__() in Python/bltinmodule.c). When applicable, which is almost always, the subsequent call to type.__new__() copies that namespace into a new dict which is in turn exposed via the class's __dict__. This matters in the case where a metaclass with __prepare__() gets used (or the PEP 422 equivalent). The language reference[1] should note that the object returned by __prepare__() is copied into a new dict when the class is finally created via the metaclass. [1] http://docs.python.org/3.4/reference/datamodel.html#customizing-class-creat… ---------- assignee: docs@python components: Documentation messages: 184188 nosy: docs@python, eric.snow, ncoghlan priority: normal severity: normal stage: needs patch status: open title: language reference should specify restrictions on class namespace type: enhancement versions: Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue17422> _______________________________________

8 25

[issue13077] Unclear behavior of daemon threads on main thread exit
by etuardu 09 Mar '20

09 Mar '20

New submission from etuardu <edonan(a)gmail.com>: The definition of daemon thread in the current documentation reads: «A thread can be flagged as a "daemon thread". The significance of this flag is that the entire Python program exits when only daemon threads are left. [...]» (http://docs.python.org/library/threading.html#thread-objects) I think it's not very clear from this that daemon threads themselves terminate when the program (main thread plus other non-daemon threads) terminates. I think this have to be said more explicitly. I'd propose a change with something like: «A thread can be flagged as a "daemon thread", which means it will get shut down when the overall program terminates. The entire Python program exits when only daemon threads are left.» ---------- assignee: docs@python components: Documentation messages: 144691 nosy: docs@python, etuardu priority: normal severity: normal status: open title: Unclear behavior of daemon threads on main thread exit type: behavior versions: Python 2.6, 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/issue13077> _______________________________________

5 7

[issue18269] Clarify which integer is required in os.chmod() exception
by anatoly techtonik 06 Mar '20

06 Mar '20

New submission from anatoly techtonik: (<type 'int'>, '0755') (<type 'int'>, '0644') Traceback (most recent call last): File "./tools/bootstrap.py", line 185, in extract_zip os.fchmod(outfile, unixperm) TypeError: an integer is required Here the integer that is required is not `unixperm`, but `outfile`. ---------- assignee: docs@python components: Documentation messages: 191502 nosy: docs@python, techtonik priority: normal severity: normal status: open title: Clarify which integer is required in os.chmod() exception versions: Python 2.6, Python 2.7, Python 3.1, Python 3.2, Python 3.3, Python 3.4, Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18269> _______________________________________

3 8

[issue17231] Mark __del__ not being called in cycles as an impl detail
by Maciej Fijalkowski 06 Mar '20

06 Mar '20

New submission from Maciej Fijalkowski: Here: http://docs.python.org/2/reference/datamodel.html, as per python-dev discussion ---------- assignee: docs@python components: Documentation messages: 182364 nosy: docs@python, fijall priority: normal severity: normal status: open title: Mark __del__ not being called in cycles as an impl detail type: behavior _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue17231> _______________________________________

5 5

[issue36490] Modernize function signature format in Archiving section of shutil doc
by C.A.M. Gerlach 04 Mar '20

04 Mar '20

New submission from C.A.M. Gerlach <CAM.Gerlach(a)Gerlach.CAM>: In the process of updating the documentation for another issue, I noticed that unlike the rest of the shutil doc (and the Python docs in general, not to mention those of virtually every Python package), all the functions in the [Archiving operations section](https://docs.python.org/3/library/shutil.html#archiving-operations) uses the old style, difficult to parse nested-bracket notation for the function signatures, rather then the modern style displaying them as they would be expected to appear in Python code, with clearly and explicitly indicated defaults. Therefore, given all bracketed items are keyword arguments with defaults, and there are no cases more complex then the standard linearly-nested brackets, is there a particular reason why this was retained? Otherwise, I can go ahead and submit a PR to update this. ---------- assignee: docs@python components: Documentation messages: 339243 nosy: CAM-Gerlach, docs@python priority: normal severity: normal status: open title: Modernize function signature format in Archiving section of shutil doc versions: Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue36490> _______________________________________

4 5

[issue8824] Improve documentation of exec
by Terry J. Reedy 28 Feb '20

28 Feb '20

New submission from Terry J. Reedy <tjreedy(a)udel.edu>: This doc improvement suggestion is inspired by #991196 (and subsequent duplicates) and the current discussion on py-dev in the thread 'variable name resolution in exec is incorrect' (which is not a correct claim). I believe there is consensus that the doc for exec needs improving. My suggestion (which others may amend) is that the following paragraph (from the 3.x builtin functions exec entry) "In all cases, if the optional parts are omitted, the code is executed in the current scope. If only globals is provided, it must be a dictionary, which will be used for both the global and the local variables. If globals and locals are given, they are used for the global and local variables, respectively. If provided, locals can be any mapping object." have these two sentences added: "If only globals is provided or if onedict is provided as both globals and locals, the code is executed in a new top-level scope. If different objects are given as globals and locals, the code is executed as if it were in a class statement in a new top-level scope." ---------- assignee: docs@python components: Documentation messages: 106552 nosy: docs@python, tjreedy priority: normal severity: normal status: open title: Improve documentation of exec versions: Python 2.6, Python 2.7, Python 3.1, Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue8824> _______________________________________

6 19

[issue15474] Differentiate decorator and decorator factory in docs
by Éric Araujo 27 Feb '20

27 Feb '20

New submission from Éric Araujo <merwok(a)netwok.org>: Some of the confusion encountered when writing decorators arise from the difference between a decorator (@something) and a decorator factory (@something(args)). It would help to adopt this clearer terminology in our docs: a decorator takes the decorated function as argument and does its business, a decorator factory takes some arguments and returns a decorator which wraps the decorated function. (I think it was Nick who suggested this in a recent-ish mailing list thread.) ---------- assignee: docs@python components: Documentation messages: 166600 nosy: docs@python, eric.araujo, ncoghlan priority: normal severity: normal status: open title: Differentiate decorator and decorator factory in docs versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15474> _______________________________________

8 14

[issue23164] "pydoc filter" documentation restrictive
by Eric O. LEBIGOT 26 Feb '20

26 Feb '20

New submission from Eric O. LEBIGOT: The pydoc documentation for filter reads: filter(function or None, sequence) -> list, tuple, or string Return those items of sequence for which function(item) is true. If function is None, return the items that are true. If sequence is a tuple or string, return the same type, else return a list. It would be nicer to know (e.g. when offline and with no local access to the HTML documentation) that filter() can actually be used more generally with an iterable: filter(function or None, **iterable**) -> list, tuple, or string Return those items of **iterable** for which… ---------- assignee: docs@python components: Documentation messages: 233416 nosy: docs@python, lebigot priority: normal severity: normal status: open title: "pydoc filter" documentation restrictive type: enhancement versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue23164> _______________________________________

2 1

[issue22714] target of 'import statement' entry in general index for 'i' is wrong
by Van Ly 26 Feb '20

26 Feb '20

New submission from Van Ly: The target points to within '__import__()' but should point to 'import()' method function. For example, # 'import statement' entry at index for 'i' on the following page python-2.7.5-docs-html/genindex-I.html # points to python-2.7.5-docs-html/library/functions.html#index-8 # but should point to python-2.7.5-docs-html/reference/simple_stmts.html#import ---------- assignee: docs@python components: Documentation messages: 229914 nosy: docs@python, vy0123 priority: normal severity: normal status: open title: target of 'import statement' entry in general index for 'i' is wrong type: enhancement versions: Python 2.7, Python 3.3, Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue22714> _______________________________________

2 1

[issue18837] multiprocessing.reduction is undocumented
by Tomi Pieviläinen 24 Feb '20

24 Feb '20

New submission from Tomi Pieviläinen: In older versions (2.x, 3.2, 3.3) multiprocessing.reduction was only mentioned in a one example, with a one comment after it. In the 3.4dev documentation even this was dropped. ---------- assignee: docs@python components: Documentation messages: 196184 nosy: docs@python, tpievila priority: normal severity: normal status: open title: multiprocessing.reduction is undocumented versions: Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18837> _______________________________________

3 2

[issue37970] urllib.parse docstrings incomplete
by Zachary Ware 23 Feb '20

23 Feb '20

New submission from Zachary Ware <zachary.ware(a)gmail.com>: For example, urlsplit: >>> from urllib.parse import urlsplit >>> help(urlsplit) Help on function urlsplit in module urllib.parse: urlsplit(url, scheme='', allow_fragments=True) Parse a URL into 5 components: <scheme>://<netloc>/<path>?<query>#<fragment> Return a 5-tuple: (scheme, netloc, path, query, fragment). Note that we don't break the components up in smaller bits (e.g. netloc is a single string) and we don't expand % escapes. The current docstring does not describe the `scheme` or `allow_fragments` arguments. Also, the note about not splitting netloc is misleading; the components of netloc (username, password, hostname, and port) are available as extra attributes of the returned SplitResult. urlparse has similar issues; other functions could stand to be checked. ---------- assignee: docs@python components: Documentation, Library (Lib) keywords: newcomer friendly messages: 350668 nosy: docs@python, zach.ware priority: normal severity: normal stage: needs patch status: open title: urllib.parse docstrings incomplete versions: Python 3.7, Python 3.8, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue37970> _______________________________________

6 17

[issue38101] Update devguide triaging keywords
by Lisa Roach 23 Feb '20

23 Feb '20

New submission from Lisa Roach <lisaroach14(a)gmail.com>: Currently the devguide triaging keywords page is out of date: https://devguide.python.org/triaging/#keywords It is missing keywords like "easy (C)", "security_issue", and "pep3121". ---------- assignee: docs@python components: Documentation keywords: easy messages: 351781 nosy: docs@python, lisroach priority: normal severity: normal status: open title: Update devguide triaging keywords _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue38101> _______________________________________

4 6

[issue9056] Adding additional level of bookmarks and section numbers in python pdf documents.
by pengyu.ut 18 Feb '20

18 Feb '20

New submission from pengyu.ut <pengyu.ut(a)gmail.com>: Current pdf version of python documents don't have bookmarks for sussubsection. For example, there is no bookmark for the following section in python_2.6.5_reference.pdf. Also the bookmarks don't have section numbers in them. I suggest to include the section numbers. Could these features be added in future release of python document. 3.4.1 Basic customization ---------- assignee: docs@python components: Documentation messages: 108334 nosy: docs@python, pengyu.ut priority: normal severity: normal status: open title: Adding additional level of bookmarks and section numbers in python pdf documents. versions: Python 2.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9056> _______________________________________

7 9

[issue9305] Don't use east/west of UTC in date/time documentation
by Alexander Belopolsky 14 Feb '20

14 Feb '20

New submission from Alexander Belopolsky <belopolsky(a)users.sourceforge.net>: I am opening this to supersede issue7229. See discussion following msg107148. In many places offsets representing the difference between local time and UTC are described as minutes or seconds east or west of UTC. This is not correct because UTC is not a place and minutes and seconds don't measure distance in this context. Replacing UTC with the Prime Meridian will not fix that because some regions in the western hemisphere use positive offsets from UTC. or example, Madrid is at 3° 42' West, but uses Central European Time which is UTC+1. I believe geographical references in the python documentation are irrelevant. What users are interested in is how to convert local time to UTC and UTC to local time rather than what is the sign of time.timezone in Madrid. I suggest the following wording for time.timezone description: time.timezone: The number of seconds one must add to the local time to arrive at UTC. Similarly, tzinfo.utcoffset() can be defined as "Returns timedelta one must add to UTC to arrive at local time." ---------- assignee: docs@python components: Documentation keywords: easy messages: 110774 nosy: belopolsky, docs@python priority: normal severity: normal stage: needs patch status: open title: Don't use east/west of UTC in date/time documentation type: feature request versions: Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9305> _______________________________________

15 30

[issue38374] Remove weakref.ReferenceError entry from documentation
by Martijn Pieters 11 Feb '20

11 Feb '20

New submission from Martijn Pieters <mj(a)python.org>: The weakref documentation still mentions weakref.ReferenceError: https://docs.python.org/3/library/weakref.html#weakref.ReferenceError But this alias for the built-in ReferenceError exception was removed in the 3.0 development cycle (https://github.com/python/cpython/commit/2633c69fae7e413b2b64b01d8c0c901ae6…), the last version where `weakref.ReferenceError` still exists is Python 2.7. Please remove it, it's just confusing now. ---------- assignee: docs@python components: Documentation messages: 353977 nosy: docs@python, mjpieters priority: normal severity: normal status: open title: Remove weakref.ReferenceError entry from documentation versions: Python 3.6, Python 3.7, Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue38374> _______________________________________

4 8

[issue13826] Having a shlex example in the subprocess.Popen docs is confusing
by Julian Berman 10 Feb '20

10 Feb '20

New submission from Julian Berman <Julian+Python.org(a)GrayVines.com>: The example at http://docs.python.org/dev/library/subprocess.html#popen-constructor seems a bit misplaced, as it seems to suggest that one should use the shlex module. Most of the other examples in the module seem to use a list to provide the args, so if there was a need to just point out that shlex could be used for a corner case perhaps it'd be better suited as a footnote or another subsection somewhere. ---------- assignee: docs@python components: Documentation messages: 151624 nosy: Julian, docs@python priority: normal severity: normal status: open title: Having a shlex example in the subprocess.Popen docs is confusing type: enhancement versions: Python 2.6, Python 2.7, Python 3.1, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13826> _______________________________________

9 14

[issue16776] Document PyCFunction_New and PyCFunction_NewEx functions
by Andrew Svetlov 10 Feb '20

10 Feb '20

New submission from Andrew Svetlov: c-api docs has no documentation for those public API functions. ---------- assignee: docs@python components: Documentation keywords: easy messages: 178115 nosy: asvetlov, docs@python priority: normal severity: normal status: open title: Document PyCFunction_New and PyCFunction_NewEx functions type: enhancement versions: Python 2.7, Python 3.2, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue16776> _______________________________________

7 8

[issue20265] Bring Doc/using/windows up to date
by Zachary Ware 10 Feb '20

10 Feb '20

New submission from Zachary Ware: Doc/using/windows still mentions DOS, Windows 3.x, and Python 2.1, and that's just in the first short section. This is a catch-all issue for making sure that page is up to date. ---------- assignee: docs@python components: Documentation, Windows keywords: easy messages: 208136 nosy: docs@python, zach.ware priority: normal severity: normal stage: needs patch status: open title: Bring Doc/using/windows up to date type: enhancement versions: Python 2.7, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue20265> _______________________________________

11 35

[issue35318] Check accuracy of str() doc string for its encoding argument
by Raymond Hettinger 08 Feb '20

08 Feb '20

New submission from Raymond Hettinger <raymond.hettinger(a)gmail.com>: The "encoding" parameter is documented to default to sys.getdefaultencoding(). That may be true but there doesn't seem to be a way to use that default because objects will all have a __str__ or __repr__ that will be run instead. ------------------------------------------- >>> import sys >>> sys.getdefaultencoding() # Default encoding is utf-8 'utf-8' >>> buffer = b'lim x \xe2\x9f\xb6 \xe2\x88\x9e, 1/sin\xc2\xb2(x)' >>> str(buffer, 'utf-8') # Explicit argument decodes properly 'lim x ⟶ ∞, 1/sin²(x)' >>> str(buffer) # Despite the default, repr is shown "b'lim x \\xe2\\x9f\\xb6 \\xe2\\x88\\x9e, 1/sin\\xc2\\xb2(x)'" >>> print(str.__doc__) str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to 'strict'. ---------- assignee: docs@python components: Documentation messages: 330454 nosy: docs@python, rhettinger priority: normal severity: normal status: open title: Check accuracy of str() doc string for its encoding argument versions: Python 3.6, Python 3.7, Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue35318> _______________________________________

3 4

[issue28901] Embedded Release interactive mode documentation
by Matthias v/d Meent 05 Feb '20

05 Feb '20

New submission from Matthias v/d Meent: The Windows Embedded release (at least the x86_64 version) does not include the usual helper functions (exit, help, ...) when run interactively (~ python.exe). This is not documented at the docs of Windows Embedded release, which might mean that this is a bug. Documentation on Embedded release here (https://docs.python.org/3/using/windows.html#embedded-distribution) missing in interactive mode of embedded release: (output of diff): ['copyright', 'credits', 'exit', 'help', 'license', 'quit'] Notice that 'help', a builtin function according to the docs [0], is missing in the Embedded release. Even when embedded, a builtin should be available IMO. [0] https://docs.python.org/3.6/library/functions.html This comparison was only between running the python executable in the [zip] and python installed from this [installer]. It is very well possible this is a long-standing issue since 3.5 (the first Embedded release), and this may occur on other architectures as well. [zip] https://www.python.org/ftp/python/3.6.0/python-3.6.0rc1-embed-amd64.zip [installer] https://www.python.org/ftp/python/3.6.0/python-3.6.0rc1-amd64.exe ---------- assignee: docs@python components: Documentation, Windows messages: 282693 nosy: Matthias v/d Meent, docs@python, paul.moore, steve.dower, tim.golden, zach.ware priority: normal severity: normal status: open title: Embedded Release interactive mode documentation type: enhancement versions: Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue28901> _______________________________________

3 3

[issue33698] `._pth` does not allow to populate `sys.path` empty entry
by Vladimir Chebotarev 05 Feb '20

05 Feb '20

New submission from Vladimir Chebotarev <vladimir.chebotarev(a)gmail.com>: Moving from bpo-29326 ==== Hi Steve. I'll try to explain what is my motivation. I need a reliable way to run Python (not matter embedded or not) in isolated mode, but still having current directory in `sys.path` (empty entry). Ironically I could misuse normal mode to simulate isolated mode with specified %PYTHONPATH% (which is not much handy, by the way), but hiding Windows Registry keys would look pretty hard (it is impossible to make a bat/cmd wrapper). Possibility to search %PYTHONPATH% in HKLM entries makes it even worse. Empty entry in `sys.path` is a extremely popular thing, and many software depend on it. It looks like a bug that isolated mode cannot support such entry. # How would I fix it. Possibly we should allow another keyword for adding an empty entry (like we have an exclusion for `import site`). Ideas are appreciated. ---------- assignee: docs@python components: Documentation, Windows messages: 318202 nosy: docs@python, excitoon, paul.moore, steve.dower, tim.golden, zach.ware priority: normal pull_requests: 6878 severity: normal status: open title: `._pth` does not allow to populate `sys.path` empty entry type: behavior versions: Python 3.6, Python 3.7, Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue33698> _______________________________________

4 6

[issue38558] Data Structures documentation out of sync with new Walrus operator
by Matt Ward 03 Feb '20

03 Feb '20

New submission from Matt Ward <matt(a)matthewward.net>: The 3.8 documentation still includes the text. ```Note that in Python, unlike C, assignment cannot occur inside expressions. C programmers may grumble about this, but it avoids a common class of problems encountered in C programs: typing = in an expression when == was intended.``` https://docs.python.org/3.8/tutorial/datastructures.html#more-on-conditions This would seem to no longer be the case with with the inclusion of https://www.python.org/dev/peps/pep-0572/ in 3.8 unless I am misunderstanding the above statement. ---------- assignee: docs@python components: Documentation messages: 355151 nosy: Matt Ward, docs@python priority: normal severity: normal status: open title: Data Structures documentation out of sync with new Walrus operator type: enhancement versions: Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue38558> _______________________________________

7 11

[issue15867] It's hard to decypher how to build off of the provided objects from the importlib docs
by Julian Berman 29 Jan '20

29 Jan '20

New submission from Julian Berman: I find that the importlib documentation is a bit too low level. Import hooks are not that common, so requiring a bit of reading is OK with me, but I somewhat *understand* PEP 302, so I have a general idea of *what* I want to do and what kind of objects can accomplish that, and still find it hard to figure out how to take the pieces provided by importlib and use them to do what I want. If I provide a specific example, I want to create a path hook that "just" does the usual import behavior, but before executing the module, does some transformation on the source code, say. In trying to figure out the best way to do that I had a hard time using the docs to figure out which pieces I should assemble to do that. I'm going to just describe the rough series of steps I went through, and hopefully that will help give a picture of where in the docs I had trouble. `importlib.abc` has a few things that would appear to help. None of the things seem like an exact match, so immediately I'm confused -- after reading PEP 302 I'd have expected to need to find an object to implement one or both of `get_code` or `get_source` on, or one that has that implemented that I can subclass and extend. The closest thing there that I find is PyPycLoader, which seems to be saying it implements the standard import behavior, but the docs say its deprecated and to use SourceLoader. At this point, after checking out `SourceLoader` and seeing that it has me implementing two methods whose purpose I don't quite understand, even after reading the short descriptions of them, at least not in the context of what I want to do, I begin to suspect that what I really want is to combine SourceLoader with some things from the `imp` module, or maybe `importlib.__import__`, but am left wondering again how much I need to implement before I just can use that. I then notice `importlib.util.module_for_loader`, and add that to the simple loader I've written which I'm still waiting to plug `imp` into, before realizing that that decorator eats the `fullname` attribute and *only* passes along the module, which confuses me, since now I don't know how to retrieve the source for the module object that I'm being passed -- so I save the path name in `__init__` for the class, and assume that's what I should be doing, despite not seeing an example doing that. Assuming that's even correct as-is, it took me quite a bit to put those pieces together. So I apologize for rambling -- I think essentially what'd improve things is providing more examples, or perhaps a HOWTO entry, that targeted assembling the pieces provided in the module into a few clear, complete examples of finders, loaders and importers. ---------- assignee: docs@python components: Documentation messages: 169901 nosy: Julian, docs@python priority: normal severity: normal status: open title: It's hard to decypher how to build off of the provided objects from the importlib docs versions: Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15867> _______________________________________

8 11

[issue38423] Event loop implementation docs advertise set_event_loop
by Hrvoje Nikšić 27 Jan '20

27 Jan '20

New submission from Hrvoje Nikšić <hniksic(a)gmail.com>: The docs of SelectorEventLoop and ProactorEventLoop contain examples that call asyncio.set_event_loop: selector = selectors.SelectSelector() loop = asyncio.SelectorEventLoop(selector) asyncio.set_event_loop(loop) But this won't have any effect on code that uses asyncio.run(), because asyncio.run() creates a fresh event loop. Since asyncio.run() is the recommended way to execute async code and is used consistently throughout the documentation, this might be confusing to someone who tries to e.g. use the proactor loop on Windows. I propose the following: * add a disclaimer that instantiating the event loop won't affect calls to asyncio.run(), and that loop.run_until_complete() must be used; and * link to asyncio.set_event_loop_policy(), which does work with asyncio.run(), but doesn't allow fine-tuning the details, such as which selector to use for the SelectorEventLoop. ---------- assignee: docs@python components: Documentation, asyncio messages: 354288 nosy: asvetlov, docs@python, hniksic, yselivanov priority: normal severity: normal status: open title: Event loop implementation docs advertise set_event_loop versions: Python 3.7, Python 3.8, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue38423> _______________________________________

3 4

[issue36654] Add example to tokenize.tokenize
by Windson Yang 25 Jan '20

25 Jan '20

New submission from Windson Yang <wiwindson(a)outlook.com>: > The tokenize() generator requires one argument, readline, which must be a callable object which provides the same interface as the io.IOBase.readline() method of file objects. Each call to the function should return one line of input as bytes. Add an example like this should be easier to understand: # example.py def foo: pass # tokenize_example.py import tokenize f = open('example.py', 'rb') token_gen = tokenize.tokenize(f.readline) for token in token_gen: # Something like this # TokenInfo(type=1 (NAME), string='class', start=(1, 0), end=(1, 5), line='class Foo:\n') # TokenInfo(type=1 (NAME), string='Foo', start=(1, 6), end=(1, 9), line='class Foo:\n') # TokenInfo(type=53 (OP), string=':', start=(1, 9), end=(1, 10), line='class Foo:\n') print(token) ---------- assignee: docs@python components: Documentation messages: 340467 nosy: Windson Yang, docs@python priority: normal severity: normal status: open title: Add example to tokenize.tokenize type: enhancement versions: Python 3.5, Python 3.6, Python 3.7, Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue36654> _______________________________________

5 10

[issue15243] Misleading documentation for __prepare__
by William Schwartz 25 Jan '20

25 Jan '20

New submission from William Schwartz <wkschwartz(a)gmail.com>: Section 3.3.3.2. "Preparing the class namespace" of the documentation (http://docs.python.org/dev/reference/datamodel.html#preparing-the-class-nam…) states that "If the metaclass has a __prepare__ attribute, it is called as ``namespace = metaclass.__prepare__(name, bases, **kwds)``...." This isn't quite true. By just defining a ``__prepare__`` method in a metaclass, the interpreter calls it as it would a static method -- there is no implicit first argument referring to ``metaclass`` as the documentation implies. The documentation should be amended to say that users can decorate ``__prepare__`` as a class method to get ``metaclass`` passed in as the implicit first argument. ---------- assignee: docs@python components: Documentation, Tests messages: 164606 nosy: William.Schwartz, docs@python priority: normal severity: normal status: open title: Misleading documentation for __prepare__ type: behavior versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15243> _______________________________________

11 22

[issue37955] mock.patch incorrect reference to Mock
by Paulo Henrique Silva 25 Jan '20

25 Jan '20

New submission from Paulo Henrique Silva <ph.silva(a)gmail.com>: When explaining the usage of keyword arguments on mock.patch: ``` patch() takes arbitrary keyword arguments. These will be passed to the Mock (or new_callable) on construction. ``` default new_callable is MagicMock and it should be mentioned here instead of Mock (even tough MagickMock inherits from it). ---------- assignee: docs@python components: Documentation messages: 350537 nosy: docs@python, phsilva priority: normal severity: normal status: open title: mock.patch incorrect reference to Mock versions: Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue37955> _______________________________________

2 3

[issue11553] Docs for: import, packages, site.py, .pth files
by Graham Wideman 24 Jan '20

24 Jan '20

New submission from Graham Wideman <initcontact(a)grahamwideman.com>: The overall scope of this issue is that current Python documentation gives vague, sometimes incorrect, information about the set of Python features involved in modularizing functionality. This issue presents an obstacle to programmers making smooth transitions from a single module, to collections of modules and packages, then on to neatly organized common packages shared between projects. The problem affects documentation of: import and from...import statements ------------------------------------ The Language Reference is way too complicated for the mainstream case. Exactly what variants of arguments are possible, and what are their effects? What are the interactions with package features, such as whether or not modules have been explicitly imported into package __init_.py? sys.path --------- Typical consituents; range of alternatives for adding more dirs Module site.py -------------- Multiple serious errors in the file docstring, relating to site-packages directories and .pth files .pth files ----------- Incorrectly described in site.py, and then vaguely described in other docs. Are .pth files processed everywhere on sys.path? Can they be interative? (No to both). package structure ----------------- Details of package structure have evidently changed over Python versions. Current docs are unclear on points such as: -- is __init__.py needed on subpackage directories? -- the __all__ variable: Does it act generally to limit visibility of a module or package's attributes, or does pertain only to the 'from...import *' statement? Details: ========= Language Reference ------------------- http://docs.python.org/py3k/reference/simple_stmts.html#the-import-statement The description of the import statement is extensive, but dauntingly complicated for the reader trying to understand the mainstream case of simply importing modules or packages that are on sys.path. This is because the algorithm for finding modules tries numerous esoteric strategies before falling back on the plain-old-file-system method. (Even now that I have a good understanding of the plain-old-file variations of import, I reread this and find it hard to comprehend, and disorganized and incomplete in presenting the available variations of the statement.) Grammar issue: the grammar shown for the import statement shows: relative_module ::= "."* module | "."+ ... which implies that relative module could have zero leading dots. I believe an actual relative path is required to have at least one dot (PEP 328). Evidently, in this grammar, 'relative_module' really means "relative or absolute path to module or package", so it would be quite helpful to change to: relative_path ::= "."+ module | "."+ from_path ::= (relative_path | module) etc. (Really 'module' is not quite right here either since it's used to mean module-or-package.) site.py: -------- Module site.py implements the site-package related features. The docstring has multiple problems with consequences in other docs. 1. Does not mention user-specific site-package directories (implemented by addusersitepackages() ) 2. Seriously misleading discussion of .pth files. In the docstring the example shows using pth files, called "package configuration files" in their comments, to point to actual package directories bar and foo located within the site-packages directory. This is an absolutely incorrect use of pth files: If foo and bar are packages in .../site-packages/, they do not need to be pointed to, they are already on sys.path. If the package dirs ARE pointed to by foo.pth and bar.pth, the modules inside them will be exposed directly to sys.path, possibly precipitating name collisions. Further, programmers following this example will create packages in which import statements will appear to magically perform relative imports without leading dots, leading to confusion over how the import statement is supposed to work. It may be that this discussion is held over from a time when "package" perhaps meant "Just a Bunch of Files in a Directory"? 3. The docstring (or other docs) should make clear that .pth files are ONLY processed within site-package directories (ie: only by site.py). 4. Bug: Minor: In addsitepackages(), the library directory for Windows (the else clause) is shown as lower-case 'lib' instead of 'Lib'. This has some possibility of causing problems when running from a case-sensitive server. In any case, if read as documentation it is misleading. Tutorial --------- 6. Modules: http://docs.python.org/py3k/tutorial/modules.html 1. Discussion (6.1.2. The Module Search Path) is good as far as it goes, but it doesn't mention the site-package directories. 2. Section 6.4. Packages: Discussion of __init__.py does describe the purpose of these files. However, the discussion in relation to subpackages should mention that for subdirectories to be accessible they must in fact be made into subpackages. I.e.: there is not form of import that can reach into a subdir of a package *unless* it's flagged as a subpackage using __init__.py. I have read elsewhere that there were some versions of Python where __init__.py was not needed on subdirs within a package. 3. Section 6.4. Packages: The discussion of __all__ should note that it works *only* in conjunction with 'from...import *', and is not a general mechanism for limiting visibility of attributes. Attributes not in the __all__ list are still accessible using other forms of import. 4. Section 6.4. Packages: "Note that when using from package import item" and following. Draws a contrast between: from package import item vs import item.subitem.subsubitem However, this muddles the roles of the arguments to import, and notably uses 'item' in two different ways. Instead the discussion can be presented as a comparison of: from PackageOrModule import ModuleOrAttribute vs import PackageOrModule ... where it can be pointed out that the PackageOrModule 'dotted path' argument follows the *same* rules in both cases (except for relative paths). The *salient* contrast is that only the 'from' form has a *second* argument which can be an attribute. 5. Footnote: (somewhat unrelated, but...) says "the execution of a module-level function enters the function name in the module’s global symbol table." This is surely incorrect -- it is the execution of the function's *def* that enters the function name in the symbol table. Standard Library Reference --------------------------- 1) 27.13. site — Site-specific configuration hook http://docs.python.org/py3k/library/site.html This is documentation for site.py, and is a page that might well come up in a search for '.pth'. 1a) This page may simply be importing the docstring from site.py? In any case it repeats the ommissions and errors noted above for site.py. 2) 27.1. sys — System-specific parameters and functions http://docs.python.org/py3k/library/sys.html Documentation for sys.path. OK as far as it goes, but: 2a) Could helpfully point to a discussion of the typical items to be found in sys.path under normal circumstances 2b) It does point to the site.py module documentation as the authoritative info on using .pth files (which is seriously flawed as noted above). 3) 29.3. pkgutil — Package extension utility. http://docs.python.org/py3k/library/pkgutil.html 3a) The info for pkgutil.extend_path() describes how .pkg files are similar to .pth files, and their entries should point to package directories. As I noted above, so far as I can see, package directories should be within a directory on sys,path, but should not themselves be included in the path, otherwise it breaks their capability to work properly as packages. 'Installing Python Modules' document: -------------------------------------- http://docs.python.org/py3k/install/index.html This may well be consulted for info on how to organize source files, though it is basically the doc for Distutils. 1. Main problem is that it seems quite out-of-date; "Windows has no concept of a user’s home directory, " and so on. 2. 'How installation works' > table. For Windows suggests 'prefix' (default: C:\Python) as an installation directory. This is indeed one of the possible 'site-package' directories, but surely it is deprecated in favor of C:\Python\Lib\site-packages, which this section does not mention. 3. Does not mention user-specific site-package directories. 4. 'Modifying Python's Search Path' > "The most convenient way is to add a path configuration file to a directory that’s already on Python’s path". This is incorrect. (a) .pth files are only processed in site-package directories. (b) Clarifying an additional point of confusion -- as a consequence of (a) .pth files cannot be chained. 5. Points to docs for site.py... with it's flaws noted above. PEP 302 New Import Hooks ------------------------ Given the vagueness elsewhere in the docs, one might go hunting for ground truth in the PEPs. One must allow for PEPs having been superceeded, but nonetheless, outdated info that is now wrong is an additional stumbling block for learners. 1. Section 'Specification part 1: The importer Protocol'. Discussion says that in an import statement, a path (with no leading '.') is first treated as relative. This is now incorrect (as spelled out in PEP 328.) It would be helpful to insert a note in PEP 302 pointing out that the later revision invalidates this passage. ---------- assignee: docs@python components: Documentation messages: 130964 nosy: docs@python, gwideman priority: normal severity: normal status: open title: Docs for: import, packages, site.py, .pth files type: behavior versions: Python 3.1, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11553> _______________________________________

6 14

[issue36892] "Modules" section in Tutorial contains incorrect description about __init__.py
by musou1500 20 Jan '20

20 Jan '20

New submission from musou1500 <musou1500(a)gmail.com>: "Modules" section in the tutorial says that https://docs.python.org/3/tutorial/modules.html "The __init__.py files are required to make Python treat directories containing the file as packages. " But, thanks to PEP 420, __init__.py is not required after Python 3.3. https://www.python.org/dev/peps/pep-0420/ ---------- assignee: docs@python components: Documentation messages: 342228 nosy: docs@python, musou1500 priority: normal severity: normal status: open title: "Modules" section in Tutorial contains incorrect description about __init__.py type: enhancement versions: Python 3.5, Python 3.6, Python 3.7, Python 3.8, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue36892> _______________________________________

4 3

[issue36417] unicode.isdecimal bug in online Python 2 documentation
by PEW's Corner 19 Jan '20

19 Jan '20

New submission from PEW's Corner <pewscorner(a)gmail.com>: The online Python 2 documentation for unicode.isdecimal (https://docs.python.org/2/library/stdtypes.html#unicode.isdecimal) incorrectly states: "Decimal characters include digit characters". This is wrong (decimal characters are actually a subset of digit characters), and u'\u00b3' is an example of a character that is a digit but not a decimal. Issue 26483 (https://bugs.python.org/issue26483) corrected the same bug in the Python 3 documentation, and a similar correction should be applied to the Python 2 documentation. ---------- assignee: docs@python components: Documentation messages: 338736 nosy: docs@python, pewscorner priority: normal severity: normal status: open title: unicode.isdecimal bug in online Python 2 documentation type: behavior versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue36417> _______________________________________

4 4

[issue19557] ast - docs for every node type are missing
by anatoly techtonik 12 Jan '20

12 Jan '20

New submission from anatoly techtonik: http://docs.python.org/2/library/ast.html AST module doc is incomplete. To write node visitor, you need to know possible types of parameters and expected values for every node type. They are different. http://hg.python.org/cpython/file/1ee45eb6aab9/Parser/Python.asdl For example, visit_Assign expects: Assign(targets, value) `targets` can be List, Tuple or Name When there is List, and when there is Tuple? It should be documented. ---------- assignee: docs@python components: Devguide, Documentation messages: 202675 nosy: docs@python, ezio.melotti, techtonik priority: normal severity: normal status: open title: ast - docs for every node type are missing _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue19557> _______________________________________

6 11

[issue23139] syntax diagram after EBNF description?
by Friedrich Spee von Langenfeld 11 Jan '20

11 Jan '20

New submission from Friedrich Spee von Langenfeld: In our full grammar specification (10th chapter of the language reference, https://docs.python.org/3/reference/grammar.html), the grammar of Python is comprehensively notated. What would you think of adding a picture with an equivalent syntax diagram (e. g. produced with the help of http://www.bottlecaps.de/rr/ui) to open a new way of understanding for readers? ---------- assignee: docs@python components: Documentation messages: 233236 nosy: Friedrich.Spee.von.Langenfeld, docs@python priority: normal severity: normal status: open title: syntax diagram after EBNF description? _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue23139> _______________________________________

2 1

[issue15718] Possible OverflowError in __len__ method undocumented (when called via len() function)
by Rostyslav Dzinko 10 Jan '20

10 Jan '20

New submission from Rostyslav Dzinko: I've encountered that OverflowError which can happen in __len__ method is still undocumented, though one issue on this problem: http://bugs.python.org/issue12159 ended up with "need to be documented" comment. Link to documentation: http://docs.python.org/reference/datamodel.html#object.__len__ I think it must be clarified that __len__ return value is constrained to upper boundary (Py_ssize_t c type) when you plan to call it via len() built-in function. ---------- assignee: docs@python components: Documentation messages: 168439 nosy: Rostyslav.Dzinko, docs@python priority: normal severity: normal status: open title: Possible OverflowError in __len__ method undocumented (when called via len() function) versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15718> _______________________________________

7 18

[issue28617] Why isn't "in" called a comparison operation?
by wim glenn 09 Jan '20

09 Jan '20

New submission from wim glenn: Regarding https://docs.python.org/3/library/stdtypes.html#comparisons There is a line at the bottom claiming: > Two more operations with the same syntactic priority, in and not in, are supported only by sequence types (below). The claim is incorrect because `in` and `not in` are also supported by non-sequence types such as sets, mappings, etc for membership testing. Is there any good reason why we don't include them in the table of comparison operations, and say that there are ten comparison operations in python? They do support comparison chaining in the same way: >>> 'x' in 'xy' in 'xyz' True >>> 0 in {0} in [{0}] True ---------- assignee: docs@python components: Documentation files: patch.diff keywords: patch messages: 280080 nosy: docs@python, wim.glenn priority: normal severity: normal status: open title: Why isn't "in" called a comparison operation? type: enhancement versions: Python 2.7, Python 3.3, Python 3.4, Python 3.5, Python 3.6, Python 3.7 Added file: http://bugs.python.org/file45359/patch.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue28617> _______________________________________

8 19

[issue38623] Python documentation should mention how to find site-packages
by Peter Bittner 08 Jan '20

08 Jan '20

New submission from Peter Bittner <peter.bittner(a)gmx.net>: A popular question on StackOverflow is, "How do I find the location of my Python site-packages directory?" [1] While this may hint at a deeper problem that needs to be solved, a user suggested [2] the accepted answer to be added to Python's official documentation. The most appropriate place I could find to add related information is ``Doc/tutorial/modules.rst``. [1] https://stackoverflow.com/questions/122327/how-do-i-find-the-location-of-my… [2] https://stackoverflow.com/questions/122327/how-do-i-find-the-location-of-my… ---------- assignee: docs@python components: Documentation messages: 355599 nosy: bittner, docs@python priority: normal severity: normal status: open title: Python documentation should mention how to find site-packages type: enhancement versions: Python 2.7, Python 3.5, Python 3.6, Python 3.7, Python 3.8, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue38623> _______________________________________

6 17

[issue21995] Idle: pseudofiles have no buffer attribute.
by Terry J. Reedy 07 Jan '20

07 Jan '20

New submission from Terry J. Reedy: sys.stdin on 3.4.1 is also 'missing' (among public names) 'line_buffering' (True) and 'mode' ('r'). It seems that these could be trivially added, so the focus of this issue is 'buffer'. The associated .detach method is a no-op, (It is also a bit dangerous for interactive operation.) 3.4.1 Console interpreter: >>> import sys; b = sys.stdin.buffer.readline() a line >>> b b'a line\r\n' 3.4.1 Idle: >>> import sys; b = sys.stdin.buffer.readline() Traceback (most recent call last): File "<pyshell#2>", line 1, in <module> import sys; b = sys.stdin.buffer.readline() AttributeError: 'PseudoInputFile' object has no attribute 'buffer' https://docs.python.org/3/library/sys.html#sys.stdin presents the idiom. It also warns (too narrowly -- 'if you are writing a library ...') that it might not. As far as I could find, the Idle doc does not mention the standard streams, let alone Idle specific limitations. I intentionally wrote the title as a statement of a problematical situation, rather than as a proposed solution, as there are two: change code and change doc. Code: add .buffer as a bytes-oriented Pseudofile. Doc: at least mention that standard streams are replaced by objects that ship text between processes, and use gui for input and display, and the consiquences of this. ---------- assignee: docs@python components: Documentation, IDLE messages: 223292 nosy: docs@python, terry.reedy priority: normal severity: normal stage: test needed status: open title: Idle: pseudofiles have no buffer attribute. type: enhancement versions: Python 2.7, Python 3.4, Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue21995> _______________________________________

3 6

[issue33095] Cross-reference isolated mode from relevant locations
by Nick Coghlan 04 Jan '20

04 Jan '20

New submission from Nick Coghlan <ncoghlan(a)gmail.com>: In https://bugs.python.org/issue33053#msg313966, jwilk noted that it isn't obvious from https://docs.python.org/3/using/cmdline.html#cmdoption-m how to keep the current directory from being added to `sys.path` when using the -m switch. The answer is to pass the `-I` switch as well (to activate isolated mode), but there's no cross reference to help readers discover that fact. https://docs.python.org/3/using/cmdline.html#id2 is the main documentation for isolated mode, so the steps needed to close this issue are: 1. At least add a reference from the -m switch documentation to the -I switch documentation 2. Review the other parts of the `using` docs that describe how `sys.path` is initialised, and reference the -I switch documentation where relevant ---------- assignee: docs@python components: Documentation keywords: easy messages: 314022 nosy: docs@python, jwilk, ncoghlan priority: normal severity: normal stage: needs patch status: open title: Cross-reference isolated mode from relevant locations type: enhancement versions: Python 3.6, Python 3.7, Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue33095> _______________________________________

5 10

[issue34118] Fix some class entries entries in 'Built-in Functions'
by Terry J. Reedy 30 Dec '19

30 Dec '19

New submission from Terry J. Reedy <tjreedy(a)udel.edu>: The Library Reference 'Built-in Functions' chapter includes build-in classes because classes are functions in the sense of being callable with arguments and returning objects. A proposal to change the name to Built-in Functions and Classes was rejected (by Raymond, as I remember). I suspect that 'Built-in Callables' has also been proposed. Some of the current entries need one or both of two fixes. 1. Most, but not all, of the classes are tagged with '*class*' before the class name. Classes classmethod and staticmethed are instead tagged with '@' since they are mostly used as decorators, although property is tagged *class*. Classes enumerate, filter, map, memoryview, range, reversed, tuple, and zip are untagged. I think, to be consistent, that they should all get the *class* tag. 2. Nearly all entries fully describe the arguments and return values. The exceptions are those for 6 collection classes. The first 3 have an abbreviated description of the result and a reference for further details on the relationship of input to result. class dict(iterable, **kwarg) Create a new dictionary. The dict object is the dictionary class. See dict and Mapping Types — dict for documentation about this class. For other containers see the built-in list, set, and tuple classes, as well as the collections module. class frozenset([iterable]) Return a new frozenset object, optionally with elements taken from iterable. frozenset is a built-in class. See frozenset and Set Types — set, frozenset for documentation about this class. For other containers see the built-in set, list, tuple, and dict classes, as well as the collections module. class set([iterable]) Return a new set object, optionally with elements taken from iterable. set is a built-in class. See set and Set Types — set, frozenset for documentation about this class. For other containers see the built-in frozenset, list, tuple, and dict classes, as well as the collections module. The next 3 replace 'Return a ___' with 'Rather than being a function'. (This is from Nick's patch 6 years ago. https://github.com/python/cpython/commit/83c0ae5de642145ec225d29e7b239aa410….) I object to this because it is wrong if one uses the broad definition of function used in the chapter title. It is also wrong in the implication there is anything special about these classes in regard to being functions verses classess. class list([iterable]) Rather than being a function, list is actually a mutable sequence type, as documented in Lists and Sequence Types — list, tuple, range. range(start, stop[, step]) Rather than being a function, range is actually an immutable sequence type, as documented in Ranges and Sequence Types — list, tuple, range. tuple([iterable]) Rather than being a function, tuple is actually an immutable sequence type, as documented in Tuples and Sequence Types — list, tuple, range. I propose that the 2nd 3 follow the model of the 1st 3, except that the final line should be: "For other collections see the built-in range, tuple, list, frozenset, set, and dict classes, as well as the collections module." (with 1 of the 6 omitted as appropriate). (Range represents a collection, but is not a container in the sense that the others are.) ---------- assignee: docs@python components: Documentation messages: 321674 nosy: docs@python, ncoghlan, rhettinger, terry.reedy priority: normal severity: normal stage: needs patch status: open title: Fix some class entries entries in 'Built-in Functions' type: behavior versions: Python 3.6, Python 3.7, Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue34118> _______________________________________

5 16

[issue33961] Inconsistency in exceptions for dataclasses.dataclass documentation
by Chris Cogdon 25 Dec '19

25 Dec '19

New submission from Chris Cogdon <chris(a)cogdon.org>: The documentation for dataclasses.dataclass includes this text: "If any of the added methods already exist on the class, a TypeError will be raised." However, the documentation for various options has ONE case of TypeError, some cases of ValueError and other cases of "does nothing". I'll attempt a fix and create a PR for this. ---------- assignee: docs@python components: Documentation messages: 320444 nosy: chriscog, docs@python priority: normal severity: normal status: open title: Inconsistency in exceptions for dataclasses.dataclass documentation versions: Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue33961> _______________________________________

6 12

[issue33609] Document that dicts preserve insertion order
by Yury Selivanov 25 Dec '19

25 Dec '19

New submission from Yury Selivanov <yselivanov(a)gmail.com>: I don't see it documented that dicts preserve insertion order. 3.7 what's new points to [1], but that section doesn't have a "version changed" tag. IMO, [1] should have two version changed tags: one for 3.6, and one for 3.7. Also, it would be great if we could document how the order is preserved when a key is deleted from the dict etc. [1] https://docs.python.org/3.7/library/stdtypes.html#mapping-types-dict ---------- assignee: docs@python components: Documentation messages: 317346 nosy: docs@python, inada.naoki, ned.deily, vstinner, yselivanov priority: normal severity: normal status: open title: Document that dicts preserve insertion order type: enhancement versions: Python 3.7, Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue33609> _______________________________________

8 14

[issue38316] docs: Code object's "co_stacksize" field is described with mistake
by Paul Sokolovsky 19 Dec '19

19 Dec '19

New submission from Paul Sokolovsky <pfalcon(a)users.sourceforge.net>: CPython's Data Model -> Internal types -> Code objects, direct link as of version 3.7 is: https://docs.python.org/3.7/reference/datamodel.html?highlight=co_stacksize… , states following: * "co_nlocals is the number of local variables used by the function (including arguments);" * "co_stacksize is the required stack size (including local variables);" However, practical checking shows that co_stacksize is the required stack size WITHOUT local variables. One could argue about the meaning of "local variables" in the description of co_stacksize above, saying that what is meant is temporary stack variables of something. That's why I quoted above co_nlocals description too, it clearly shows that local variebles are local function variables (include functions args), and nothing else. Code to reproduce: ====== def func(): a = 1 b = 2 c = 3 print("co_stacksize", func.__code__.co_stacksize) print("co_nlocals", func.__code__.co_nlocals) ====== Result of running: ====== $ python3.7 script_under_test.py co_stacksize 1 co_nlocals 3 ====== Clearly, co_stacksize doesn't include the size of local vars, or it would have been larger than co_nlocals in printout. ---------- assignee: docs@python components: Documentation messages: 353508 nosy: docs@python, pfalcon priority: normal severity: normal status: open title: docs: Code object's "co_stacksize" field is described with mistake versions: Python 3.5, Python 3.6, Python 3.7, Python 3.8, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue38316> _______________________________________

6 9

[issue34000] Document when compile returns a code object v. AST
by Geoffrey Sneddon 15 Dec '19

15 Dec '19

New submission from Geoffrey Sneddon <geoffers+pythonbugs(a)gmail.com>: The compile built-in documentation says: > Compile the source into a code or AST object. It doesn't however go on to say when it returns each! It does however note: > If you want to parse Python code into its AST representation, see ast.parse(). So compile can compile the source into an AST object, but if I want to parse Python code into an AST I should use ast.parse? As far as I can tell, this goes back to Python 2.5: https://docs.python.org/2/whatsnew/2.5.html#build-and-c-api-changes >From the What's New page: > It’s possible for Python code to obtain AST objects by using the compile() built-in and specifying _ast.PyCF_ONLY_AST as the value of the flags parameter So that would seem to be the case when compile returns an AST! Interestingly, the implementation of ast.parse *literally just calls compile* (https://github.com/python/cpython/blob/58ed7307ea0b5c5aa052291ebc3030f314f9…). Note, however, this means a further part of the compile documentation is wrong: > The optional arguments flags and dont_inherit control which future statements (see PEP 236) affect the compilation of source. flags is therefore something more general than just controlling which future statements affect the source, given it also controls the output type of the function. In short, we should: * document the flags argument can take _ast.PyCF_ONLY_AST *or* change the documentation to say it returns a code object (and not an AST object) ---------- assignee: docs@python components: Documentation messages: 320721 nosy: docs@python, gsnedders priority: normal severity: normal status: open title: Document when compile returns a code object v. AST versions: Python 2.7, Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue34000> _______________________________________

3 2

[issue19038] Fix sort order in Misc/ACKS.
by Tae-Wong SEO 12 Dec '19

12 Dec '19

New submission from Tae-Wong SEO: This patch fixes sort order in file Misc/ACKS. ---------- assignee: docs@python components: Documentation files: ACKS messages: 197945 nosy: docs@python, taewong.seo priority: normal severity: normal status: open title: Fix sort order in Misc/ACKS. type: enhancement Added file: http://bugs.python.org/file31803/ACKS _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue19038> _______________________________________

8 18

[issue38594] importlib.metadata documentation deficiencies
by Gregory Szorc 11 Dec '19

11 Dec '19

New submission from Gregory Szorc <gregory.szorc(a)gmail.com>: As I was attempting to implement the find_distributions() interface for PyOxidizer, I got confused by importlib.metadata's documentation. The documentation for this module states: ``` What this means in practice is that to support finding distribution package metadata in locations other than the file system, you should derive from ``Distribution`` and implement the ``load_metadata()`` method. Then from your finder, return instances of this derived ``Distribution`` in the ``find_distributions()`` method. ``` The reference to `load_metadata()` is the only occurrence of the string `load_metadata` in the CPython and importlib_metadata code bases. I therefore believe the documentation in both CPython and the importlib_metadata standalone package are wrong because they are referring to a method that is never implemented nor called. Looking at the documentation and source code for importlib.metadata, I'm also a bit confused about how exactly I'm supposed to implement a custom Distribution which isn't based on filesystems. For example, I see that certain APIs return Path-like objects (which I will need to implement). But it isn't clear exactly which attributes are mandated to exist! Am I expected to implement the full pathlib.Path interface or just a subset? Regarding how find_distributions() is called, I also don't understand why the Context is optional and how Context could be used in some situations. For example, the implementation of discover() can construct Context instances with no arguments, which is then fed into find_distributions(). So I guess context=None or context.name=None implies "return Distribution's for every known package?" If so, this behavior is undocumented. I'm also not sure what Context.path is for. I /think/ it is only used for the path-based finder/distribution. But the way it is documented implies it should always exist, which doesn't seem appropriate for cases like PyOxidizer which will retrieve metadata from in-memory without filesystem I/O. I think what I'm trying to say is that the existing documentation for importlib.metadata is not sufficient to robustly implement a custom find_distributions() + Distribution type. I would kindly request that a domain expert revise the documentation such that a 3rd party can implement a custom solution. My preferred solution would be for there to be formal interfaces in importlib.abc like there are for everything else in the importlib realm. (The interfaces for finders and loaders are super useful when implementing a finder/loader from scratch.) FWIW I think I like the new metadata API and I think it is flexible enough to allow tools like PyOxidizer to do crazy things like divorce resources from the filesystem! But it is hard to say for sure since the interfaces aren't clearly defined at present. ---------- assignee: docs@python components: Documentation messages: 355402 nosy: barry, docs@python, indygreg, jaraco priority: normal severity: normal status: open title: importlib.metadata documentation deficiencies type: enhancement versions: Python 3.8, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue38594> _______________________________________

3 9

[issue35827] C API dictionary views type checkers are not documented
by Ori Avtalion 10 Dec '19

10 Dec '19

New submission from Ori Avtalion <ori(a)avtalion.name>: dictobject.h defines several helpers to ease checking of dictionary view types. If they are meant to be part of the API, they should be documented. PyDictKeys_Check PyDictItems_Check PyDictValues_Check PyDictViewSet_Check Should they be added to dict.rst, or a separate file? ---------- assignee: docs@python components: Documentation messages: 334355 nosy: docs@python, salty-horse priority: normal severity: normal status: open title: C API dictionary views type checkers are not documented type: enhancement versions: Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue35827> _______________________________________

3 2

[issue18697] Unify arguments names in Unicode object C API documentation
by Serhiy Storchaka 09 Dec '19

09 Dec '19

New submission from Serhiy Storchaka: In declarations of Unicode object C API functions in Doc/c-api/unicode.rst the first Unicode object argument has different names: "unicode", "str", "u", "s". It will be good to unify these names. Of course there is no need to change reasonable argument names for such functions as PyUnicode_Concat() or PyUnicode_CopyCharacters(). ---------- assignee: docs@python components: Documentation, Unicode keywords: easy messages: 194755 nosy: docs@python, ezio.melotti, haypo, serhiy.storchaka priority: normal severity: normal stage: needs patch status: open title: Unify arguments names in Unicode object C API documentation type: enhancement versions: Python 2.7, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18697> _______________________________________

8 17

[issue38652] Remove/update provisional note for asyncio.BufferedProtocol
by Kyle Stanley 07 Dec '19

07 Dec '19

New submission from Kyle Stanley <aeros167(a)gmail.com>: In the documentation (https://docs.python.org/3.9/library/asyncio-protocol.html#buffered-streamin…) for asyncio.BufferedProtocol there is a provisional API note. This should be updated/removed for 3.8 and 3.9 since it became a part of the stable API in 3.8. Current: > New in version 3.7: Important: this has been added to asyncio in Python 3.7 on a provisional basis! This is as an experimental API that might be changed or removed completely in Python 3.8. I would propose to changing it to: > New in version 3.7. ---------- assignee: docs@python components: Documentation messages: 355739 nosy: aeros, asvetlov, docs@python, yselivanov priority: normal severity: normal status: open title: Remove/update provisional note for asyncio.BufferedProtocol versions: Python 3.8, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue38652> _______________________________________

6 10

[issue34344] Fix the docstring for AbstractEventLoopPolicy.get_event_loop
by Vlad Starostin 02 Dec '19

02 Dec '19

New submission from Vlad Starostin <drtyrsa(a)yandex.ru>: The docstring says "This may be None or an instance of EventLoop". But docs explicitly state that get_event_loop "must never return None". The same docstring is also in the example in docs: https://docs.python.org/3.6/library/asyncio-eventloops.html#customizing-the… I propose changing it to: def get_event_loop(self): """Get the event loop. Returns an instance of EventLoop or raises an exception. """ If the wording is ok, I'll make a PR. ---------- assignee: docs@python components: Documentation, asyncio messages: 323190 nosy: asvetlov, docs@python, drtyrsa, yselivanov priority: normal severity: normal status: open title: Fix the docstring for AbstractEventLoopPolicy.get_event_loop versions: Python 3.6, Python 3.7, Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue34344> _______________________________________

7 13

[issue37883] threading.Lock.locked is not documented
by Rémi Lapeyre 01 Dec '19

01 Dec '19

New submission from Rémi Lapeyre <remi.lapeyre(a)henki.fr>: As far as I can tell, it has never been documented. I'm not sure if it is deprecated but it has a docstring so it seems to me, that it just needs documentation in Doc/Library/threading.rst PS: I don't know how to set the beginner friendly flag. ---------- assignee: docs@python components: Documentation, Library (Lib) messages: 349923 nosy: docs@python, remi.lapeyre priority: normal severity: normal status: open title: threading.Lock.locked is not documented type: enhancement versions: Python 3.7, Python 3.8, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue37883> _______________________________________

5 16

[issue28805] Add documentation for METH_FASTCALL
by Stefan Krah 01 Dec '19

01 Dec '19

New submission from Stefan Krah: It looks like METH_FASTCALL gives nice speedups (#28754). Is this an internal interface or can it be documented like METH_KEYWORDS etc.? ---------- assignee: docs@python components: Documentation messages: 281766 nosy: docs@python, haypo, serhiy.storchaka, skrah priority: normal severity: normal stage: needs patch status: open title: Add documentation for METH_FASTCALL type: enhancement versions: Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue28805> _______________________________________

8 16

[issue38462] Typo (nam ing) in import system docs
by Roy Smith 27 Nov '19

27 Nov '19

New submission from Roy Smith <roy(a)panix.com>: In https://docs.python.org/3.5/reference/import.html#importsystem, section "5.2 Packages", second sentence, the word "naming" is broken across two lines. In 3.7.5rc1 as well. Didn't check any others. ---------- assignee: docs@python components: Documentation messages: 354581 nosy: docs@python, roysmith priority: normal severity: normal status: open title: Typo (nam ing) in import system docs versions: Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue38462> _______________________________________

2 4

[issue21063] Touch up one-line descriptions of modules for module index
by Brett Cannon 26 Nov '19

26 Nov '19

New submission from Brett Cannon: E.g. linecache says "This module provides random access to individual lines from text files." That's a big awkward and could just drop "This module" to read more easily. ---------- assignee: docs@python components: Documentation keywords: easy messages: 214834 nosy: brett.cannon, docs@python priority: low severity: normal stage: needs patch status: open title: Touch up one-line descriptions of modules for module index versions: Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue21063> _______________________________________

4 12

[issue37073] clarify functions docs in IO modules and Bytes Objects
by Windson Yang 23 Nov '19

23 Nov '19

New submission from Windson Yang <wiwindson(a)outlook.com>: > PyBytes_FromStringAndSize(const char *v, Py_ssize_t len): > Return a new bytes object with a copy of the string v as value and length len on success, and NULL on failure. If v is NULL, the contents of the bytes object are uninitialized. The function actually copies `len` bytes from string v instead of the whole string. (link 1) I suggested we can change to > Return a new bytes object with a copy of the first len bytes of string v as value and length len on success... > readinto(b) > Read bytes into a pre-allocated, writable bytes-like object b and return the number of bytes read. For example, b might be a bytearray. The function will call _bufferediobase_readinto_generic(link 2) which may return NULL. Maybe we can change to > and return the number of bytes that read succeed (it may be smaller than b or NULL if failed)... 1. https://github.com/python/cpython/blob/master/Objects/bytesobject.c#L126 2. https://github.com/python/cpython/blob/master/Modules/_io/bufferedio.c#L962 ---------- assignee: docs@python components: Documentation messages: 343741 nosy: Windson Yang, docs@python priority: normal severity: normal status: open title: clarify functions docs in IO modules and Bytes Objects type: enhancement versions: Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue37073> _______________________________________

3 6

[issue29275] time module still has Y2K issues note
by Elizabeth Myers 22 Nov '19

22 Nov '19

New submission from Elizabeth Myers: It's 2017. I think it's time to remove the Y2K warning from this: https://docs.python.org/3/library/time.html :P. It's 17 years past the sell-by date for that notice. ---------- assignee: docs@python components: Documentation messages: 285489 nosy: Elizacat, docs@python priority: normal severity: normal status: open title: time module still has Y2K issues note 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/issue29275> _______________________________________

6 10

[issue38526] zipfile.Path has the wrong method name
by Alex Walters 22 Nov '19

22 Nov '19

New submission from Alex Walters <tritium-list(a)sdamon.com>: https://docs.python.org/3.8/library/zipfile.html#zipfile.Path.listdir The docs for zipfile.Path list a method named 'listdir', the closest approximation to the functionality described in the actual code is a method named 'iterdir' ---------- assignee: docs@python components: Documentation messages: 354936 nosy: docs@python, tritium priority: normal severity: normal status: open title: zipfile.Path has the wrong method name versions: Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue38526> _______________________________________

5 6

[issue36277] pdb's recursive debug command is not listed in the docs
by Antony Lee 21 Nov '19

21 Nov '19

New submission from Antony Lee <anntzer.lee(a)gmail.com>: pdb's recursive debug command (mentioned e.g. in https://bugs.python.org/issue35931) is not listed in https://docs.python.org/3/library/pdb.html#debugger-commands. (I haven't checked whether any other command is missing.) ---------- assignee: docs@python components: Documentation messages: 337828 nosy: Antony.Lee, docs@python priority: normal severity: normal status: open title: pdb's recursive debug command is not listed in the docs _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue36277> _______________________________________

5 11

[issue27724] PEP3119 inconsintent with actual CPython impl
by Daisuke Miyakawa 19 Nov '19

19 Nov '19

New submission from Daisuke Miyakawa: Python 3.5.2 (and Python 2.7.12) uses Py_TPFLAGS_IS_ABSTRACT while PEP 3119 menttions "Py_TPFLAGS_ABSTRACT" for it. At some point had the name of the flag been changed without modifying PEP? ---------- assignee: docs@python components: Documentation messages: 272321 nosy: Daisuke Miyakawa, docs@python priority: normal severity: normal status: open title: PEP3119 inconsintent with actual CPython impl versions: Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue27724> _______________________________________

4 3

[issue34792] Tutorial doesn''t discuss / and * function arguments
by Mark Diekhans 19 Nov '19

19 Nov '19

New submission from Mark Diekhans <markd(a)kermodei.com>: https://docs.python.org/3/tutorial/controlflow.html doest not discuss / and * arguments (end of positional, keyword required) ---------- assignee: docs@python components: Documentation messages: 326277 nosy: diekhans, docs@python priority: normal severity: normal status: open title: Tutorial doesn''t discuss / and * function arguments type: enhancement versions: Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue34792> _______________________________________

4 4

[issue37083] Document TYPE_COMMENT in documentation reference for compound statements
by Pablo Galindo Salgado 18 Nov '19

18 Nov '19

New submission from Pablo Galindo Salgado <pablogsal(a)gmail.com>: The last changes in the grammar regarding TYPE_COMMENTS should be added to this section: https://docs.python.org/3/reference/compound_stmts.html#function-definitions ---------- assignee: docs@python components: Documentation messages: 343820 nosy: docs@python, gvanrossum, levkivskyi, pablogsal priority: normal severity: normal stage: needs patch status: open title: Document TYPE_COMMENT in documentation reference for compound statements type: behavior versions: Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue37083> _______________________________________

4 5

[issue25866] Reference 3. Data Model: miscellaneous minor cleanups on the word "sequence".
by Andrew Barnert 17 Nov '19

17 Nov '19

New submission from Andrew Barnert: None of the below are very serious or likely to mislead anyone using or implementing Python, but... --- 3.3.2. Customizing attribute access The docs for `__dir__` say: > A sequence must be returned. dir() converts the returned sequence to a list and sorts it. At least in CPython and PyPy, this isn't enforced; any iterable can be returned (and it's then converted to a list and sorted). You can even make `__dir__` a generator function. (I've never seen that in the wild--but I have seen code that returns a `map` iterator.) I think it would be better to say "An iterable must be returned. dir() converts the returned iterable to a list and sorts it." --- 3.3.2.3. __slots__ > This class variable can be assigned a string, iterable, or sequence of strings... While it's true that you can assign any iterable, it's at best misleading to assign an iterator. For example, if you use `__slots__ = iter('abc')`, you will get a class with descriptors named `a`, `b`, and `c`, but with an empty iterator in `__slots__`. There's probably no reason to actually outlaw that, but it might be worth noting in 3.3.2.3.1 along with the other weird possibilities like assigning a mapping. --- 3.3.6. Emulating container types The docs still say that the ABCs are in `collections` rather than `collections.abc`. > ... for mappings, __iter__() should be the same as keys() No; `__iter__()` should be an iterator over the keys; `keys()` _can_ be an iterator, but generally should be a view instead. > The membership test operators (in and not in) are normally implemented as an iteration through a sequence. However, container objects can supply the following special method with a more efficient implementation, which also does not require the object be a sequence. I don't think this should say "through a sequence". They're implemented as iteration through whatever the container is, whether it's a sequence, a set, a linked list, or anything else. The documentation on `__contains__` immediately below clarifies this, but it's probably better to be clear from the start. ---------- assignee: docs@python components: Documentation messages: 256445 nosy: abarnert, docs@python priority: normal severity: normal status: open title: Reference 3. Data Model: miscellaneous minor cleanups on the word "sequence". type: enhancement _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue25866> _______________________________________

7 14

[issue26011] Document necesities for cmp argument of sorted
by Karl Richter 16 Nov '19

16 Nov '19

New submission from Karl Richter: The docstring of `sorted` doesn't explain what can be passed to the `cmp` and `key` argument of `sorted`. ---------- assignee: docs@python components: Documentation messages: 257505 nosy: docs@python, krichter priority: normal severity: normal status: open title: Document necesities for cmp argument of sorted type: enhancement versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue26011> _______________________________________

4 3

[issue38351] Modernize email example from %-formatting to f-string
by Mariatta 15 Nov '19

15 Nov '19

New submission from Mariatta <mariatta(a)python.org>: A string was formatted with %s in the code example https://github.com/python/cpython/blob/b3e7045f8314e7b62cd95861d207fe2f97e4… ``` msg['Subject'] = 'The contents of %s' % textfile ``` It would be great to modernize that into fstring. Doc can be read at: https://docs.python.org/3.7/library/email.examples.html ---------- assignee: docs@python components: Documentation keywords: easy, newcomer friendly messages: 353749 nosy: Mariatta, docs@python priority: normal severity: normal stage: needs patch status: open title: Modernize email example from %-formatting to f-string versions: Python 3.7, Python 3.8, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue38351> _______________________________________

12 24

[issue35666] Update design FAQ about assignment expression
by Carl Bordum Hansen 12 Nov '19

12 Nov '19

New submission from Carl Bordum Hansen <carl(a)bordum.dk>: Hi there, In ``Doc/faq/design.rst`` there is an explanation of why Python does not have assignment in expressions. This is dated since PEP 572 / Python 3.8. Online version: https://docs.python.org/3/faq/design.html#why-can-t-i-use-an-assignment-in-… I suggest updating it to the attached file. `git diff`: ``` diff --git a/Doc/faq/design.rst b/Doc/faq/design.rst index e2d63a0323..e61284611d 100644 --- a/Doc/faq/design.rst +++ b/Doc/faq/design.rst @@ -149,7 +149,15 @@ to tell Python which namespace to use. Why can't I use an assignment in an expression? ----------------------------------------------- -Many people used to C or Perl complain that they want to use this C idiom: +In Python 3.8 and newer, you can use assignment in an expression with the +``:=`` operator (as described in :pep:`572`):: + + while line := f.readline(): + ... # do something with line + +For more than 25 years it was not possible to do assignments in expressions in +Python. Naturally, many people used to C or Perl would complain that they want +to use this C idiom: .. code-block:: c @@ -157,7 +165,7 @@ Many people used to C or Perl complain that they want to use this C idiom: // do something with line } -where in Python you're forced to write this:: +where in Python you would be forced to write this:: while True: line = f.readline() @@ -165,8 +173,10 @@ where in Python you're forced to write this:: break ... # do something with line -The reason for not allowing assignment in Python expressions is a common, -hard-to-find bug in those other languages, caused by this construct: +The reason different operators are used for assignment and assignment in +expressions (``=`` and ``:=``, respectively), and why Python didn't allow +assignment in expressions for a long time is a common, hard-to-find bug in +those other languages, caused by this construct: .. code-block:: c @@ -180,11 +190,6 @@ hard-to-find bug in those other languages, caused by this construct: The error is a simple typo: ``x = 0``, which assigns 0 to the variable ``x``, was written while the comparison ``x == 0`` is certainly what was intended. -Many alternatives have been proposed. Most are hacks that save some typing but -use arbitrary or cryptic syntax or keywords, and fail the simple criterion for -language change proposals: it should intuitively suggest the proper meaning to a -human reader who has not yet been introduced to the construct. - An interesting phenomenon is that most experienced Python programmers recognize the ``while True`` idiom and don't seem to be missing the assignment in expression construct much; it's only newcomers who express a strong desire to ``` ---------- assignee: docs@python components: Documentation files: design.rst messages: 333063 nosy: carlbordum, docs@python priority: normal severity: normal status: open title: Update design FAQ about assignment expression type: enhancement versions: Python 3.8 Added file: https://bugs.python.org/file48025/design.rst _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue35666> _______________________________________

3 5

[issue38385] statistics: incorrect documentation
by Eric O. LEBIGOT 12 Nov '19

12 Nov '19

New submission from Eric O. LEBIGOT <eric.lebigot(a)normalesup.org>: The documentation for the statistics package indicates that many of its functions (like median()) accept iterators. They seem to actually accept something more convenient, namely iterables. Thus, iterator could probably be usefully replaced by iterable on many of the functions (when applicable, which I would expect is everywhere). ---------- assignee: docs@python components: Documentation messages: 354043 nosy: docs@python, lebigot priority: normal severity: normal status: open title: statistics: incorrect documentation versions: Python 3.5, Python 3.6, Python 3.7, Python 3.8, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue38385> _______________________________________

3 6

[issue27994] In the argparse help(argparse) prints weird comments instead of good docstrings
by py.user 05 Nov '19

05 Nov '19

New submission from py.user: >>> import argparse >>> help(argparse) >>> Output: | add_subparsers(self, **kwargs) | # ================================== | # Optional/Positional adding methods | # ================================== | | convert_arg_line_to_args(self, arg_line) | | error(self, message) | error(message: string) | | Prints a usage message incorporating the message to stderr and | exits. | | If you override this in a subclass, it should not return -- it | should either exit or raise an exception. | | exit(self, status=0, message=None) | # =============== | # Exiting methods | # =============== | | format_help(self) | | format_usage(self) | # ======================= | # Help-formatting methods | # ======================= | | parse_args(self, args=None, namespace=None) | # ===================================== | # Command line argument parsing methods | # ===================================== | | parse_known_args(self, args=None, namespace=None) | | print_help(self, file=None) | | print_usage(self, file=None) | # ===================== | # Help-printing methods | # ===================== | | ---------------------------------------------------------------------- | Methods inherited from _AttributeHolder: ... There are no docstrings for methods, hence some internal comments picked up instead. ---------- assignee: docs@python components: Documentation, Library (Lib) messages: 274738 nosy: docs@python, py.user priority: normal severity: normal status: open title: In the argparse help(argparse) prints weird comments instead of good docstrings type: behavior versions: Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue27994> _______________________________________

3 3

[issue38388] Pickle protocol v 5 needs to be documented
by Dima Tisnek 03 Nov '19

03 Nov '19

New submission from Dima Tisnek <dimaqq(a)gmail.com>: Python 3.8 brings new pickle protocol, version 5. It's not documented. ``` (venv) … ~/m/proj> python Python 3.7.4 (v3.7.4:e09359112e, Jul 8 2019, 14:54:52) [Clang 6.0 (clang-600.0.57)] on darwin Type "help", "copyright", "credits" or "license" for more information. >>> import pickle >>> pickle.HIGHEST_PROTOCOL 4 >>> ^D (venv) … ~/m/proj> python3.8 Python 3.8.0rc1 (v3.8.0rc1:34214de6ab, Oct 1 2019, 12:56:49) [Clang 6.0 (clang-600.0.57)] on darwin Type "help", "copyright", "credits" or "license" for more information. >>> import pickle >>> pickle.HIGHEST_PROTOCOL 5 >>> ^D ``` Yet there's no mention of "protocol version 5" at: https://github.com/python/cpython/blob/master/Doc/library/pickle.rst https://docs.python.org/3.9/library/pickle.html#data-stream-format https://docs.python.org/3.8/library/pickle.html#data-stream-format ---------- assignee: docs@python components: Documentation messages: 354054 nosy: Dima.Tisnek, docs@python priority: normal severity: normal status: open title: Pickle protocol v 5 needs to be documented versions: Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue38388> _______________________________________

5 7

[issue38279] multiprocessing example enhancement
by Max Voss 02 Nov '19

02 Nov '19

New submission from Max Voss <bruno.m.voss(a)gmail.com>: Hello all, I've been trying to understand multiprocessing for a while, I tried multiple times. The PR is a suggested enhancement to the example that made it "click" for me. Or should I say, produced a working result that made sense to me. Details for each change in the PR. It's short too. The concept of multiprocessing is easy enough, but the syntax is so unlike regular python and so much happens "behind the curtain" so to speak, it took me a while. When I looked for multiprocessing advice online, many answers seemed unsure if or how their solution worked. Generally I'd like to help write documentation. So this is a test to see how good your issue handling process is too. :) ---------- assignee: docs@python components: Documentation messages: 353222 nosy: BMV, docs@python priority: normal severity: normal status: open title: multiprocessing example enhancement versions: Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue38279> _______________________________________

5 4

[issue18601] Example "command-line interface to difflib" has typographical error
by Stephen Paul Chappell 31 Oct '19

31 Oct '19

New submission from Stephen Paul Chappell: The example at the bottom is good but has a line with a bad variable it is name. It says: with open(fromlines) as fromf, open(tofile) as tof: fromlines, tolines = list(fromf), list(tof) In the first line, fromlines does no even exist yet. should say: with open(fromlines) as fromf, open(tofile) as tof: from, tolines = list(fromf), list(tof) ---------- assignee: docs@python components: Demos and Tools, Documentation messages: 193948 nosy: Zero, docs@python priority: normal severity: normal status: open title: Example "command-line interface to difflib" has typographical error versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18601> _______________________________________

3 3

[issue18558] Iterable glossary entry needs clarification
by Stephen Paul Chappell 31 Oct '19

31 Oct '19

Change by Stephen Paul Chappell <Noctis.Skytower(a)gmail.com>: ---------- nosy: -Zero _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue18558> _______________________________________

1 0

[issue16575] ctypes: unions as arguments
by Vinay Sajip 31 Oct '19

31 Oct '19

Change by Vinay Sajip <vinay_sajip(a)yahoo.co.uk>: ---------- assignee: docs@python -> vinay.sajip resolution: -> fixed stage: patch review -> resolved status: open -> closed _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue16575> _______________________________________

1 0

[issue16575] ctypes: unions as arguments
by Vinay Sajip 31 Oct '19

31 Oct '19

Vinay Sajip <vinay_sajip(a)yahoo.co.uk> added the comment: New changeset 0118d109d54bf75c99a8b0fa9aeae1a478ac4b7e by Vinay Sajip in branch '3.7': [3.7] bpo-16575: Add checks for unions passed by value to functions. (GH-16799) (GH-17017) https://github.com/python/cpython/commit/0118d109d54bf75c99a8b0fa9aeae1a478… ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue16575> _______________________________________

1 0

[issue16575] ctypes: unions as arguments
by Vinay Sajip 31 Oct '19

31 Oct '19

Vinay Sajip <vinay_sajip(a)yahoo.co.uk> added the comment: New changeset 952899704800a5aa438e84d50f0b6fc498c72e89 by Vinay Sajip in branch '3.8': [3.8] bpo-16575: Add checks for unions passed by value to functions. (GH-16799) (GH-17016) https://github.com/python/cpython/commit/952899704800a5aa438e84d50f0b6fc498… ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue16575> _______________________________________

1 0

[issue16575] ctypes: unions as arguments
by Vinay Sajip 31 Oct '19

31 Oct '19

Change by Vinay Sajip <vinay_sajip(a)yahoo.co.uk>: ---------- pull_requests: +16536 pull_request: https://github.com/python/cpython/pull/17017 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue16575> _______________________________________

1 0

[issue16575] ctypes: unions as arguments
by Vinay Sajip 31 Oct '19

31 Oct '19

Change by Vinay Sajip <vinay_sajip(a)yahoo.co.uk>: ---------- pull_requests: +16535 pull_request: https://github.com/python/cpython/pull/17016 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue16575> _______________________________________

1 0

[issue9182] document “--” as a way to distinguish option w/ narg='+' from positional argument in argparse
by Jackson Riley 31 Oct '19

31 Oct '19

Jackson Riley <jacriley(a)cisco.com> added the comment: Hi all, I'm a newcomer and wanted to try to make this change, is it still wanted/needed? ---------- nosy: +jacksonriley _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue9182> _______________________________________

1 0

[issue38600] Change the mark up of NULL
by Serhiy Storchaka 31 Oct '19

31 Oct '19

New submission from Serhiy Storchaka <storchaka+cpython(a)gmail.com>: Currently NULL is mostly marked up as *NULL* in the C API documentation (although it is marked up as ``NULL`` outside of the C API documentation). It is rendered with italic font as function parameters and contradicts with formatting other macros and constants with monospace font. The proposed PR replaces all *NULL* with ``NULL``. ---------- assignee: docs@python components: Documentation messages: 355452 nosy: docs@python, serhiy.storchaka priority: normal severity: normal status: open title: Change the mark up of NULL type: enhancement versions: Python 3.7, Python 3.8, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue38600> _______________________________________

2 16

[issue16575] ctypes: unions as arguments
by Vinay Sajip 31 Oct '19

31 Oct '19

Vinay Sajip <vinay_sajip(a)yahoo.co.uk> added the comment: New changeset 79d4ed102a5069c6cebaed2627cb1645637f0429 by Vinay Sajip in branch 'master': bpo-16575: Add checks for unions passed by value to functions. (GH-16799) https://github.com/python/cpython/commit/79d4ed102a5069c6cebaed2627cb164563… ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue16575> _______________________________________

1 0

[issue38637] fix GROWTH_RATE comments bug
by toywei 30 Oct '19

30 Oct '19

New submission from toywei <g1e2t3(a)foxmail.com>: It also exists in 3.7/3.6/3.3. ---------- assignee: docs@python components: Documentation messages: 355688 nosy: docs@python, toywei priority: normal pull_requests: 16516 severity: normal status: open title: fix GROWTH_RATE comments bug type: resource usage versions: Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue38637> _______________________________________

3 2

[issue30548] typo in documentation for create_autospec
by Erik Byström 30 Oct '19

30 Oct '19

New submission from Erik Byström: "a class" should most probably be replaced by "an instance" in the documentation for create_autospec. "You can use a class as the spec for an instance object by passing instance=True. The returned mock will only be callable if instances of the mock are callable." https://docs.python.org/3/library/unittest.mock.html#unittest.mock.create_a… ---------- assignee: docs@python components: Documentation messages: 294993 nosy: Erik Byström, docs@python priority: normal severity: normal status: open title: typo in documentation for create_autospec type: enhancement versions: Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue30548> _______________________________________

4 4

[issue36971] Add subsections in C API "Common Object Structures" page
by Jeroen Demeyer 30 Oct '19

30 Oct '19

New submission from Jeroen Demeyer <J.Demeyer(a)UGent.be>: The page https://docs.python.org/3/c-api/structures.html could be better structured by arranging the content in sub-sections. ---------- assignee: docs@python components: Documentation messages: 342911 nosy: docs@python, jdemeyer priority: normal severity: normal status: open title: Add subsections in C API "Common Object Structures" page versions: Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue36971> _______________________________________

3 4

[issue35745] Add import statement in dataclass code snippet
by Windson Yang 29 Oct '19

29 Oct '19

New submission from Windson Yang <wiwindson(a)outlook.com>: Most of the example in https://docs.python.org/3/library/dataclasses.html miss code like from dataclasses import dataclass, field from typing import List I think we should add this statement in the code snippet. ---------- assignee: docs@python components: Documentation messages: 333707 nosy: Windson Yang, docs@python priority: normal severity: normal status: open title: Add import statement in dataclass code snippet type: enhancement versions: Python 3.7, Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue35745> _______________________________________

3 3

[issue38336] Remove the __set__ method restriction on data descriptors for attribute lookup precedence
by Géry 29 Oct '19

29 Oct '19

New submission from Géry <gery.ogam(a)gmail.com>: The [language documentation](https://docs.python.org/3/reference/datamodel.html#invoking-… states: > Data descriptors with __set__() and __get__() defined always override a redefinition in an instance dictionary. In contrast, non-data descriptors can be overridden by instances. This override is not limited to data descriptors defining `__set__()` (and `__get__()`). It is also true for data descriptors defining `__delete__()` (and `__get__()`) and data descriptors defining both `__set__()` and `__delete__()` (and `__get__()`). In other words, _any_ data descriptors (objects defining either `__set__()` or `__delete__()` or both) defining `__get__()` override an attribute redefinition in an instance dictionary. ---------- assignee: docs@python components: Documentation messages: 353685 nosy: docs@python, maggyero priority: normal severity: normal status: open title: Remove the __set__ method restriction on data descriptors for attribute lookup precedence type: enhancement versions: Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue38336> _______________________________________

2 8

[issue38125] Can' build document in Sphinx v2.2.0
by Windson Yang 29 Oct '19

29 Oct '19

New submission from Windson Yang <wiwindson(a)outlook.com>: I got two errors when I try to build python document with make venv make html The first one is > Since v2.0, Sphinx uses "index" as master_doc by default. Please add "master_doc = 'contents'" to your conf.py. After fixing this one, the second one is > /Users/windson/learn/cpython/Doc/library/email.message.rst:4:duplicate object description of email.message, other instance in library/email.compat32-message, use :noindex: for one of them ---------- assignee: docs@python components: Documentation messages: 352034 nosy: Windson Yang, docs@python priority: normal severity: normal status: open title: Can' build document in Sphinx v2.2.0 type: crash versions: Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue38125> _______________________________________

2 2

[issue25299] TypeError: __init__() takes at least 4 arguments (4 given)
by A. Skrobov 28 Oct '19

28 Oct '19

New submission from A. Skrobov: Python 2.7.3 (default, Dec 18 2014, 19:10:20) [GCC 4.6.3] on linux2 Type "help", "copyright", "credits" or "license" for more information. >>> from argparse import ArgumentParser >>> parser = ArgumentParser() >>> parser.add_argument("--foo", help="foo", action='store_const') Traceback (most recent call last): File "<stdin>", line 1, in <module> File "/usr/lib/python2.7/argparse.py", line 1281, in add_argument action = action_class(**kwargs) TypeError: __init__() takes at least 4 arguments (4 given) >>> First, the exception message is entirely unhelpful (you wanted at least 4, you got 4, what's your problem?) Second, adding "const=None" to the invocation makes it succeed; but, according to https://docs.python.org/2/library/argparse.html#const this argument defaults to "None", so it shouldn't be necessary to specify it explicitly. Thus, either the documentation or the implementation is wrong. ---------- assignee: docs@python components: Documentation, Extension Modules messages: 252106 nosy: A. Skrobov, docs@python priority: normal severity: normal status: open title: TypeError: __init__() takes at least 4 arguments (4 given) type: behavior versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue25299> _______________________________________

6 17

[issue37052] Add examples for mocking async for and async context manager in unittest.mock docs
by Karthikeyan Singaravelan 28 Oct '19

28 Oct '19

New submission from Karthikeyan Singaravelan <tir.karthi(a)gmail.com>: Since issue26467 implemented AsyncMock along with async dunder methods for MagicMock it enables users to mock async for and async with statements. Currently examples of how to use this is present only in tests and would be good to add it to docs. There is a docs page for mock that contains similar cookbook style examples [0] where I hope these can be added. I can raise a PR with these examples if it's okay. Do you think it's worthy enough to add these examples? Any additional examples you find around asyncio and mock that can be documented ? An example of mocking async for statement by setting return value for __aiter__ method : # aiter_example.py import asyncio from unittest.mock import MagicMock mock = MagicMock() mock.__aiter__.return_value = range(3) async def main(): print([i async for i in mock]) asyncio.run(main()) $ ./python.exe aiter_example.py [0, 1, 2] An example of mocking async with statement by implementing __aenter__ and __aexit__ method. In this example __aenter__ and __aexit__ are not called. __aenter__ and __aexit__ implementations are tested to have been called in the test at [1]. These tests work since MagicMock is returned during attribute access (mock_instance.entered) which is always True in boolean context under assertTrue. I will raise a separate PR to discuss this since normally while mocking __enter__ and __exit__ the class's __enter__ and __exit__ are not used as a side_effect for the mock calls unless they are set explicitly. # aenter_example.py import asyncio from unittest.mock import MagicMock class WithAsyncContextManager: async def __aenter__(self, *args, **kwargs): return self async def __aexit__(self, *args, **kwargs): pass instance = WithAsyncContextManager() mock_instance = MagicMock(instance) async def main(): async with mock_instance as result: print("entered") asyncio.run(main()) ./python.exe aenter_example.py entered [0] https://docs.python.org/3/library/unittest.mock-examples.html [1] https://github.com/python/cpython/blob/47dd2f9fd86c32a79e77fef1fbb1ce25dc92… ---------- assignee: docs@python components: Documentation messages: 343536 nosy: asvetlov, cjw296, docs@python, lisroach, mariocj89, michael.foord, xtreak, yselivanov priority: normal severity: normal status: open title: Add examples for mocking async for and async context manager in unittest.mock docs type: enhancement versions: Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue37052> _______________________________________

4 7

[issue38534] Version 3.8.0 has released with a wrong MS KB number reference
by Wator Sead 28 Oct '19

28 Oct '19

New submission from Wator Sead <seahoh(a)gmail.com>: https://bugs.python.org/msg347421 Maybe you forgot it, please fix it in next versions. ---------- assignee: docs@python components: Documentation, Installation, Windows messages: 354986 nosy: docs@python, paul.moore, seahoh, steve.dower, tim.golden, zach.ware priority: normal severity: normal status: open title: Version 3.8.0 has released with a wrong MS KB number reference type: resource usage versions: Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue38534> _______________________________________

4 11

[issue38619] [Doc] UUID.hex is lowercase
by Felipe 28 Oct '19

28 Oct '19

New submission from Felipe <felipe.nospam.ochoa(a)gmail.com>: The hex property of `UUID` is implemented as `'%032x' % self.int` Is it specified that this will always be lowercase? If so, can we add a note to the documentation indicating so? ---------- assignee: docs@python components: Documentation, Library (Lib) messages: 355553 nosy: docs@python, fov priority: normal severity: normal status: open title: [Doc] UUID.hex is lowercase type: enhancement versions: Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue38619> _______________________________________

4 3

Proposal for Python 3 dictionary.get()
by Jordan Kadish 28 Oct '19

28 Oct '19

Dear Python Development Team I propose that the dictionary.get() method should have some way of telling the user that the returned key result could have a value of None, or could be set up in a way that if value is None, default to the chosen default. Use case: dict_example = {'a',None} x = dict_example.get('a','default') Above, x will be None instead of 'default'. I propose a solution as such: x = dict_exmaple.get('a','default','default_if_value_is_None') This way, if the expected behaviour is to just get WHATEVER value 'a' points to, the normal get() params are passed in. But if the user is expecting x to always contain either a value or the default return, then they could set the default twice to ensure that None values are converted to default as well. To my knowledge of the Python language, this is cheaper than the programmer having to later use a try/catch to test if an operation was successful -- -- Jordan Kadish Python Developer e: jordank(a)roam.africa <jordank(a)roam.africa> p: +27 79 382 82 28 www.roam.africa <https://roam.africa/>[image: ROAM] [image: Connecting Africans to Opportunities]

2 1

Tiny fix in documentation for PEP 8
by Nat Dunn 28 Oct '19

28 Oct '19

Hi, Tiny fix in documentation for PEP 8: Immediately before the open *parenthesis* that starts an indexing or slicing: should be Immediately before the open *bracket* that starts an indexing or slicing: Nat -- Nat Dunn CIO, Webucator https://www.webucator.com <http://www.webucator.com/> 877-932-8228 x221 <(877)%20932-8228> 315-849-2724 x221 <(315)%20849-2724> - - - - - - - - - - - - - - - - - -

1 0

[issue38607] Document that cprofile/profile only profile the main thread
by Ben Spiller 27 Oct '19

27 Oct '19

New submission from Ben Spiller <spiller.ben(a)gmail.com>: The built-in profiling modules only provide information about the main thread (at least when invoked as documented). To avoid user confusion we should state this in the documentation at https://docs.python.org/3/library/profile.html. Potentially we could also suggest mitigations such as manually creating a Profile instance in the user's thread code, but the most important thing is to make clear what the module does/does not do out of the box. (see also https://bugs.python.org/issue9609 which discusses a possible non-doc change to help with multi-threading, but looks like that's stalled, so best to push ahead with doc'ng this. ---------- assignee: docs@python components: Documentation messages: 355492 nosy: benspiller, docs@python priority: normal severity: normal status: open title: Document that cprofile/profile only profile the main thread type: enhancement versions: Python 3.7, Python 3.8, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue38607> _______________________________________

1 0

[issue38557] PyTuple_GetSlice docs minor inaccuracy
by wim glenn 26 Oct '19

26 Oct '19

New submission from wim glenn <wim.glenn(a)gmail.com>: https://docs.python.org/3/c-api/tuple.html#c.PyTuple_GetSlice In the c-api it says (emphasis mine): PyObject* PyTuple_GetSlice(PyObject *p, Py_ssize_t low, Py_ssize_t high)¶ Return value: New reference. Take a slice of the tuple pointed to by p from low to high and return it **as a new tuple**. But when slicing the entire tuple, CPython will return already existing instance, not a new tuple. https://github.com/python/cpython/blob/3.8/Objects/tupleobject.c#L448-L451 I propose the language in the docs be loosened so as not to tie the hands of implementation ---------- assignee: docs@python components: Documentation messages: 355141 nosy: docs@python, wim.glenn priority: normal severity: normal status: open title: PyTuple_GetSlice docs minor inaccuracy type: enhancement versions: Python 2.7, Python 3.5, Python 3.6, Python 3.7, Python 3.8, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue38557> _______________________________________

4 11

[issue38434] sys.addaudithook event is not documented
by Steve Dower 26 Oct '19

26 Oct '19

New submission from Steve Dower <steve.dower(a)python.org>: The sys.addaudithook raises an audit event 'sys.addaudithook'. The docs for the function refer to the event, as it has slightly different semantics than most, but it is not named explicitly and does not appear in the table of events. ---------- assignee: docs@python components: Documentation messages: 354396 nosy: docs@python, steve.dower priority: normal severity: normal stage: needs patch status: open title: sys.addaudithook event is not documented type: enhancement versions: Python 3.8, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue38434> _______________________________________

2 6

[issue38595] io.BufferedRWPair doc warning may need clarification
by Ryan Govostes 26 Oct '19

26 Oct '19

New submission from Ryan Govostes <rgovostes(a)gmail.com>: The documentation for the io.BufferedRWPair class gives this warning: > BufferedRWPair does not attempt to synchronize accesses to its underlying raw streams. You should not pass it the same object as reader and writer; use BufferedRandom instead. I have a hard time understanding what this warning is trying to tell me. 1. What does it mean to "synchronize accesses"? 2. Why can't I pass the same object as reader and writer? The docstring in _pyio.py says, "This is typically used with a socket or two-way pipe." 3. How does BufferedRandom, which adds the seek() and tell() interfaces, address the issue of "synchroniz[ing] accesses"? Is synchronization automatic? What does this do for sockets or pipes which cannot seek? ---------- assignee: docs@python components: Documentation messages: 355404 nosy: docs@python, rgov priority: normal severity: normal status: open title: io.BufferedRWPair doc warning may need clarification type: behavior versions: Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue38595> _______________________________________

1 1

[issue38587] __set_name__ missing from descriptor howto documentation
by Mike Driscoll 25 Oct '19

25 Oct '19

New submission from Mike Driscoll <kyosohma(a)gmail.com>: I noticed that __set_name__ is not mentioned in https://docs.python.org/3/howto/descriptor.html even though it was added in https://www.python.org/dev/peps/pep-0487/ and mentioned here https://docs.python.org/3/whatsnew/3.6.html#pep-487-descriptor-protocol-enh… ---------- assignee: docs@python components: Documentation messages: 355345 nosy: Mike Driscoll, docs@python priority: normal severity: normal status: open title: __set_name__ missing from descriptor howto documentation versions: Python 3.6, Python 3.7, Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue38587> _______________________________________

3 2

[issue37911] Minor error in PEP567 code example
by Semyon 24 Oct '19

24 Oct '19

New submission from Semyon <simeon+bpo(a)maryasin.name>: In PEP-567 there is a code example in `contextvars.Context` section (https://www.python.org/dev/peps/pep-0567/#contextvars-context): ``` # Print all context variables and their values in 'ctx': print(ctx.items()) ``` But `ctx.items()` doesn't return a list of tuples as probably expected by this code; instead it returns a `items` object which, unlike `dict_items`, does not contain any sensible `repr` or `str`. So this print statement will output something like `<items at 0x7f7fbd91e468>`. I think this code example should be chaned to something like `print(list(ctx.items()))`. ---------- assignee: docs@python components: Documentation messages: 350129 nosy: MarSoft, docs@python priority: normal severity: normal status: open title: Minor error in PEP567 code example versions: Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue37911> _______________________________________

2 2

[issue27992] In the argparse there is a misleading words about %(prog)s value
by py.user 24 Oct '19

24 Oct '19

New submission from py.user: https://docs.python.org/3/library/argparse.html#argumentparser-objects "prog - The name of the program (default: sys.argv[0])" It doesn't take all sys.argv[0]. It splits sys.argv[0] and takes only the trailing part. An example: a.py #!/usr/bin/env python3 import argparse import sys parser = argparse.ArgumentParser() parser.add_argument("arg", help="The name is %(prog)s, the sys.argv[0] is " + sys.argv[0]) args = parser.parse_args() The output in the console: [guest@localhost bugs]$ ../bugs/a.py -h usage: a.py [-h] arg positional arguments: arg The name is a.py and sys.argv[0] is ../bugs/a.py optional arguments: -h, --help show this help message and exit [guest@localhost bugs]$ In the output we see that %(prog)s takes only trailing part of sys.argv[0] not all. Applied a patch to the issue that specifies about part of sys.argv[0]. ---------- assignee: docs@python components: Documentation, Library (Lib) files: argparse_sys-argv-0-part.diff keywords: patch messages: 274729 nosy: docs@python, py.user priority: normal severity: normal status: open title: In the argparse there is a misleading words about %(prog)s value type: behavior versions: Python 3.6 Added file: http://bugs.python.org/file44420/argparse_sys-argv-0-part.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue27992> _______________________________________

2 5

[issue38566] Description of '\w' behavior is vague in `re` documentation
by James Gerity 24 Oct '19

24 Oct '19

New submission from James Gerity <snoopjedi(a)gmail.com>: The documentation for the `re` library¹ describes the behavior of the specifier '\w' as matching "Unicode word characters," which is very vague. The closest thing I can find that corresponds to this language is the guidance offered in Unicode Technical Standard #18², which defines the class `<word_character>` to include all alphabetic and decimal codepoints, as well as U+200C ZERO WIDTH NON-JOINER and U+200D ZERO WIDTH JOINER. This does not appear to be a correct description of `re`, however, as these zero-width characters are not counted when matching '\w', e.g.: ``` >>> re.match('\w*', 'Auf\u200Clage') <re.Match object; span=(0, 3), match='Auf'> ``` It seems from examining the CPython source³ that SRE treats '\w' as meaning any alphanumeric character OR U+005F SPACING UNDERSCORE, which does not match any Unicode class definition I've been able to find. Can anyone provide clarification on what part of Unicode this documentation is referring to? If there is some other definition, the documentation should be more specific about referring to it (and including a link would be preferred). If instead the documentation is incorrect, this language should be changed to describe the true meaning of \w. ¹ https://docs.python.org/3/library/re.html#index-32 ² http://unicode.org/reports/tr18/ ³ https://github.com/python/cpython/blob/master/Modules/_sre.c#L125 ---------- assignee: docs@python components: Documentation messages: 355239 nosy: docs@python, snoopjedi priority: normal severity: normal status: open title: Description of '\w' behavior is vague in `re` documentation _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue38566> _______________________________________

3 3

[issue38574] Dataclasses documentation should show the necessary imports
by Leon Matthews 24 Oct '19

24 Oct '19

New submission from Leon Matthews <leon.matthews(a)gmail.com>: In the code sample documentation for other modules we show the necessary imports, we should do the same for dataclasses. For example, the very first example uses the `dataclass` decorator without importing it first. It should read:: from dataclasses import dataclass @dataclass class InventoryItem: ... ---------- assignee: docs@python components: Documentation messages: 355289 nosy: Leon Matthews, docs@python priority: normal severity: normal status: open title: Dataclasses documentation should show the necessary imports type: enhancement versions: Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue38574> _______________________________________

2 1

[issue34172] multiprocessing.Pool and ThreadPool leak resources after being deleted
by Josh Rosenberg 23 Oct '19

23 Oct '19

Josh Rosenberg <shadowranger+python(a)gmail.com> added the comment: It should probably be backport to all supported 3.x branches though, so people aren't required to move to 3.8 to benefit from it. ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue34172> _______________________________________

1 0

[issue34172] multiprocessing.Pool and ThreadPool leak resources after being deleted
by Josh Rosenberg 23 Oct '19

23 Oct '19

Josh Rosenberg <shadowranger+python(a)gmail.com> added the comment: Pablo's fix looks like a superset of the original fix applied here, so I'm assuming it fixes this issue as well. ---------- nosy: +josh.r _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue34172> _______________________________________

1 0

[issue34172] multiprocessing.Pool and ThreadPool leak resources after being deleted
by STINNER Victor 23 Oct '19

23 Oct '19

STINNER Victor <vstinner(a)python.org> added the comment: What's the status of this issue? ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue34172> _______________________________________

1 0

[issue38562] pip install --upgrade git submodule update --recursive does not exist
by Ayse 23 Oct '19

23 Oct '19

New submission from Ayse <adogan(a)okstate.edu>: Hi, I was trying to apply a github code, for that I need to get this first:git clone --recursive https://github.com/rbgirshick/py-faster-rcnn.git but it when I run this it is saying this: PS C:\Users\Ayse Dogan> python -m pip install --user --upgrade git clone --recursive https://github.com/rbgirshick/py-faste r-rcnn.git Usage: C:\ProgramData\Anaconda3\python.exe -m pip install [options] <requirement specifier> [package-index-options] ... C:\ProgramData\Anaconda3\python.exe -m pip install [options] -r <requirements file> [package-index-options] ... C:\ProgramData\Anaconda3\python.exe -m pip install [options] [-e] <vcs project url> ... C:\ProgramData\Anaconda3\python.exe -m pip install [options] [-e] <local project path> ... C:\ProgramData\Anaconda3\python.exe -m pip install [options] <archive url/path> ... no such option: --recursive As I see from Issue35135 this was happening for some other packages. Could you please help me about it? Sincerely, Ayse ---------- components: Installation messages: 355208 nosy: aysedogan, docs@python, pgacv2, xtreak priority: normal severity: normal status: open title: pip install --upgrade git submodule update --recursive does not exist versions: Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue38562> _______________________________________

2 1

[issue38460] 3.8 Release Notes: document asyncio exception changes
by Sebastian Rittau 23 Oct '19

23 Oct '19

New submission from Sebastian Rittau <srittau(a)rittau.biz>: In Python 3.8 asyncio exceptions were consolidated into the new module "asyncio.exceptions". Previously they were spread out over several modules. While the documentation always mandated to import the exceptions from top-level "asyncio", code that incorrectly imported directly from the submodules will break. ---------- assignee: docs@python components: Documentation messages: 354577 nosy: docs@python, srittau priority: normal severity: normal status: open title: 3.8 Release Notes: document asyncio exception changes versions: Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue38460> _______________________________________

4 7

[issue38419] The path of check-c-globals.py on README is wrong
by Dong-hee Na 23 Oct '19

23 Oct '19

Change by Dong-hee Na <donghee.na92(a)gmail.com>: ---------- assignee: -> docs@python components: +Documentation nosy: +docs@python _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue38419> _______________________________________

1 0

[issue13562] Notes about module load path
by Nam Nguyen 22 Oct '19

22 Oct '19

New submission from Nam Nguyen <bitsink(a)gmail.com>: A doc patch to remind Python embedder to set sys.path prior to Py_Initialize. This is to ensure a controlled module load path to work around these issues: http://bugs.python.org/issue12989 http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2008-5983 ---------- assignee: docs@python components: Documentation files: module.load.path.diff keywords: patch messages: 149071 nosy: Nam.Nguyen, docs@python priority: normal severity: normal status: open title: Notes about module load path type: feature request versions: Python 2.6, Python 2.7, Python 3.1, Python 3.2 Added file: http://bugs.python.org/file23888/module.load.path.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13562> _______________________________________

4 6

[issue38466] threading.excepthook doc talks about "object"
by Sebastian Rittau 22 Oct '19

22 Oct '19

New submission from Sebastian Rittau <srittau(a)rittau.biz>: The documentation of threading.excepthook (https://docs.python.org/3.8/library/threading.html#threading.excepthook) talks about "object", when it only has a "thread" attribute: "Storing object using a custom hook can resurrect it if it is set to an object which is being finalized. Avoid storing object after the custom hook completes to avoid resurrecting objects." I believe this is a copy and paste error from sys.unraisablehook. ---------- assignee: docs@python components: Documentation messages: 354588 nosy: docs@python, srittau, vstinner priority: normal severity: normal status: open title: threading.excepthook doc talks about "object" versions: Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue38466> _______________________________________

5 8

[issue38524] functools.cached_property is not supported for setattr
by Sergey Fedoseev 22 Oct '19

22 Oct '19

Change by Sergey Fedoseev <fedoseev.sergey(a)gmail.com>: ---------- nosy: +sir-sigurd _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue38524> _______________________________________

1 0

[issue38553] Document functools.cached_property supports value updating and clearing
by Laurie Opperman 22 Oct '19

22 Oct '19

New submission from Laurie Opperman <laurie_opperman(a)hotmail.com>: As I discovered during working on bpo-38545, `functools.cached_property` natively supports cached value setting/updating and clearing (via attribute assignment and deletion, respectively) through mechanisms defined in the language for non-data descriptors: class A: j = 0 @functools.cached_property def b(self): self.j += 1 return self.j a = A() print(a.b) # 1 print(a.b) # 1 del a.b print(a.b) # 2 print(a.b) # 2 a.b = 42 print(a.b) # 42 print(a.b) # 42 del a.b print(a.b) # 3 print(a.b) # 3 I propose that this functionality be documented, for two reasons: 1. To notify developers that this functionality is available, and how to access it 2. To notify developers that this functionality needs to be explicitly disabled. This is important as the built-in `property` is the reverse: property setting and deletion needs to be explicitly implemented Disabling the value can be achieved by subclassing `functools.cached_property` and overriding/implementing `__set__` and `__delete__` to raise: class immutable_cached_property(functools.cached_property): def __set__(self, instance, value): raise AttributeError("can't set attribute") def __delete__(self, instance): raise AttributeError("can't delete attribute") Further reading: - Defining descriptors: https://docs.python.org/3/reference/datamodel.html#implementing-descriptors - Descriptor how-to: https://docs.python.org/3/howto/descriptor.html - Class construction: https://docs.python.org/3/reference/datamodel.html#creating-the-class-object ---------- assignee: docs@python components: Documentation, Library (Lib) messages: 355110 nosy: Epic_Wink, docs@python priority: normal severity: normal status: open title: Document functools.cached_property supports value updating and clearing type: enhancement versions: Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue38553> _______________________________________

2 2

[issue38548] open() and file.write() without file.close()
by kryptomatrix 21 Oct '19

21 Oct '19

New submission from kryptomatrix <volker.weissmann(a)gmx.de>: Consider the following program: f = open("out.txt", "w") f.write("abc\n") exit(0) Please note the absence of f.close(). The documentation https://docs.python.org/3/tutorial/inputoutput.html#reading-and-writing-fil… says that you should use f.close() or with f = open(), but is not clear whether the program above without f.close() is guaranteed to write. The tutorial says: "If you don’t explicitly close a file, Python’s garbage collector will eventually destroy the object and close the open file for you, but the file may stay open for a while. Another risk is that different Python implementations will do this clean-up at different times." For me this sounds like even without f.close() the file is guaranteed to be written. If it is not guaranteed to be written, you should fix the documentation, if it is guaranteed to be written, then I will open another issue because the following program does not write into out.txt on my machine: from sympy.core import AtomicExpr class MyWeirdClass(AtomicExpr): def __init__(self): pass f = open("out.txt", "w") f.write("abc\n") exit(0) Note: sys.version is: "3.7.3 (default, Oct 7 2019, 12:56:13) \n[GCC 8.3.0]" ---------- assignee: docs@python components: Documentation messages: 355062 nosy: docs@python, kryptomatrix priority: normal severity: normal status: open title: open() and file.write() without file.close() type: enhancement versions: Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue38548> _______________________________________

2 1

[issue38531] argparse action "extend" not documented as new
by Christoph Zwerschke 20 Oct '19

20 Oct '19

New submission from Christoph Zwerschke <cito(a)online.de>: A new action "extend" has been added to argparse in https://github.com/python/cpython/commit/aa32a7e1116f7aaaef9fec453db910e90a… The documentation should specify that this is new in Python 3.8 addition. I wondered why it didn't work in Python 3.7. ---------- assignee: docs@python components: Documentation messages: 354966 nosy: cito, docs@python priority: normal severity: normal status: open title: argparse action "extend" not documented as new type: enhancement versions: Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue38531> _______________________________________

5 10

broken link in docs site
by Ant 20 Oct '19

20 Oct '19

Page: https://docs.python.org/3/library/http.client.html Contains a link under: "See also: The Requests package <http://docs.python-requests.org/> is recommended for a higher-level HTTP client interface." The requests package link, links to http://docs.python-requests.org/ (should it?) which redirects to https://2.python-requests.org/ which gives me the error: Secure Connection Failed An error occurred during a connection to 2.python-requests.org. Peer reports it experienced an internal error. Error code: SSL_ERROR_INTERNAL_ERROR_ALERT The page you are trying to view cannot be shown because the authenticity of the received data could not be verified. Please contact the website owners to inform them of this problem. I am not sure what is wrong here, so just reporting it. Thanks, Ant

2 1

Hyphenation problem at https://docs.python.org/3/library/functions.html#float
by Arthur Goldberg 20 Oct '19

20 Oct '19

Hello Docs Help Browser zoom and hyphenation interact to create problems. I reported a similar problem about another page previously, but this report is more detailed. Look at https://docs.python.org/3/library/functions.html#float and look for the text "Here floatnumber is the form of a Python floating-point literal, described in Floating point literals." See three attachments. zoom hyphenation bug- 100%.png zoom hyphenation bug- 110%.png zoom hyphenation bug- 90%.png The text is presented correctly at 100% - no hyphenation, and at 110% - 'Float-ing' hyphenated, but at 90% 'literals' wraps without a hyphen. I suspect that this problem is widespread. Environment: Google Chrome is up to date Version 77.0.3865.120 (Official Build) (64-bit) Mac OS High Sierra, ver. 10.13.6 (17G8030) Regards Arthur -- Arthur Goldberg https://www.linkedin.com/in/arthurgoldberg artgoldberg(a)gmail.com

1 0

[issue38524] functools.cached_property is not supported for setattr
by Nick Coghlan 20 Oct '19

20 Oct '19

Nick Coghlan <ncoghlan(a)gmail.com> added the comment: After writing my previous comment, I double-checked the code, and cached_propery is actually one of the cases where a simple "self.attrname = 'age3'" *will* do the right thing, as cached_property never checks the class information. That won't work in the general case though, and I think it makes more sense for the cached_property documentation to provide advice that will generalise to arbitrary descriptors (i.e. call `descr.__set_name__(target, "attr")`) ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue38524> _______________________________________

1 0

[issue38524] functools.cached_property is not supported for setattr
by Nick Coghlan 20 Oct '19

20 Oct '19

Nick Coghlan <ncoghlan(a)gmail.com> added the comment: Regarding the "attrname" property idea: unfortunately, that won't work, as `__set_name__` doesn't just provide the attribute name, it also provides a reference to the class itself. cached_property needs both pieces of information, not just the attribute name. ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue38524> _______________________________________

1 0

[issue38524] functools.cached_property is not supported for setattr
by Nick Coghlan 20 Oct '19

20 Oct '19

Nick Coghlan <ncoghlan(a)gmail.com> added the comment: Another interesting question this raises is whether type.__setattr__ should be checking for values that have `__set_name__` methods defined and calling those methods automatically. Unfortunately, I think the answer to that is "If we'd thought of that when writing PEP 487, then sure, but it's too late now, as too many folks will be calling it explicitly, and implicitly calling it a second time will cause other, potentially harder to find problems". So +1 for updating the cached_property docs specifically to mention this problem However, I'm also wondering if there's somewhere else we should be mentioning it as a general problem. Perhaps in the docs for __set_name__ itself, noting it as something that authors of descriptors *using* __set_name__ should mention in their docs, with suggested wording? Something like: === `__set_name__`` is only called implicitly as part of the ``type`` constructor, so it will need to be called explicitly with the appropriate parameters when a descriptor is added to a class after initial creation:: descr = custom_descriptor() cls.attr = descr descr.__set_name__(cls, 'attr') === (The normal sequence is for the descriptor to already be part of the class namespace before __set_name__ gets called) ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue38524> _______________________________________

1 0

I'd like to contribute [Assignment Expressions]
by Johannes Hofmeister 20 Oct '19

20 Oct '19

-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA256 Dear docs team, I would like to contribute to Python's documentation. With 3.8 the "Assignment Expression" operator was included, but all the docs seem to point towards PEP 572: Assignment Expressions. Is someone documenting this feature already? I would like to offer my help. I imagine there are a couple of sites where changes are needed. Some text needs to be written which will end up on docs.python.org; however I came across the lack of documentation when fiddling around with 'help'. The topics section mentions := expressions only with regards to operator precedence but other than that there is no info to be fond (I believe it should live with 'assignment' or 'augmented assignment'). If someone is taking care of the official rsts, would be glad to make sure it connects with pydoc (from my superficial look into the system it seems like topics.py are generated, but pydoc.help still needs an entry into a dictionary so that help(':=') knows what to produce ). Please note though that I am not a known member of the python dev community yet, just a passerby, this I am not familiar with all community processes. I am happy to be pointed in the right direction to raise the issue; I wrote this email after addressing it via #python-dev on irc. Kind regards, Johannes from Germany PS: If the topic is taken care of (after all, the operator is still fresh), I would be glad to help out with documentation elsewhere. -----BEGIN PGP SIGNATURE----- iQIzBAEBCAAdFiEEx6dttkxSSyFBXLWHqIl2XpId4X0FAl2sOgYACgkQqIl2XpId 4X2hIQ/9GmDrboRFClVOuXCYzbq7iwZC4/JQUiW0sk9os1koiiQHnIZbCZ5T8Izf jZAohP9+LQguBhla8/CCe+nqdftQtD7NzZAVOBira8ZfUji8y/69PRyW+QBISEeQ B/rHHLr1meszHQLY56aXVSdPZTABtzzQoLkJeILi0H8bYREf7dXzh6WyyF1UAMHj 8YcC45nwSb5AiJBsjrv6VOZb/G7IOOQwRbtKegAgVGR6ofcMEiwRcM9tnx/zDp7c jLwMTPfHL0huUD0cJ9K6UhCKBnRI8pTrDu3lmX2P0dXB0LZV8f18zg4qk6+qyVNT X/75rfnvFYqfjg72TfSEXeaZC46kITreKz7DkIoAUcHiAoTPPrV0fI6jUL2Iq7O5 hgpC5ABEn3rFJO4iSkd1V/SEu7eRfzEzcX3WclSmHHLuNm+91tv37lDSdICaw1oq d0+uVPXmNGvJvazxcfSdIOu+mSZVomHilK/1hMqdQP/1qfqt/8edFQmyqh7Ah4sj B44NGz/IaoWTovTrvAUWefu7bakc07DCAw2Xip5i8QCCDYQk4vAGXeb/EaAs0Fdc cY/quNIFeqxitOHQ3btLTYoE9qCQTRqVo+GAsBOEgAWcRhmCzPC4+ihy1lmyq/Ld oihlkZ3YwzYdJlRN9QK+1DYE6ZtDbuoyYVtsJvT8Q9y1T0LUavg= =BD2I -----END PGP SIGNATURE-----

1 0

[issue38528] Docs for 2.7 version switcher still shows 3.8 as pre
by Julin 19 Oct '19

19 Oct '19

New submission from Julin <julinshaji02(a)gmail.com>: The version switcher in the docs for Python2.7 still shows version 3.8 as `pre (3.8)`. Can we change it to `3.8.0` to mirror that in docs of 3.8? Also, 2.7 docs version switcher at the moment show `dev (3.9)` for 3.9 whereas the 3.8 docs say `3.9.0a0` can it be changed as well? ---------- assignee: docs@python components: Documentation messages: 354950 nosy: docs@python, ju-sh priority: normal severity: normal status: open title: Docs for 2.7 version switcher still shows 3.8 as pre versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue38528> _______________________________________

2 2

[issue38514] pathlib's mkdir documentation improvement
by Jérôme Laurens 19 Oct '19

19 Oct '19

New submission from Jérôme Laurens <jerome.laurens(a)u-bourgogne.fr>: There are some inconsistencies in the actual documentation of path lib's mkdir doc. Here is the 3.7 version, annotated and followed by a change proposal Path.mkdir(mode=0o777, parents=False, exist_ok=False) Create a new directory at this given path. If mode is given, it is combined with the process’ umask value to determine the file mode and access flags. If the path already exists, FileExistsError is raised. <<<<<<<<<<<<<<<<<< NOT ALWAYS due to exist_ok. If parents is true, any missing parents of this path are created as needed; they are created with the default permissions without taking mode into account (mimicking the POSIX mkdir -p command). If parents is false (the default), a missing parent raises FileNotFoundError. If exist_ok is false (the default), FileExistsError is raised if the target directory already exists. If exist_ok is true, FileExistsError exceptions will be ignored (same behavior as the POSIX mkdir -p command), but only if the last path component is not an existing non-directory file. <<<<<<<<<<<<<<<<<< UNCLEAR: 1) what is an ignored exception ? 2) The reference to POSIX should appear at the end, like above, 3) the last path component is a string 4) usage of a double negation ignore/is not ----- CHANGE ---- Path.mkdir(mode=0o777, parents=False, exist_ok=False) Create a new directory in the file system at this given path. If mode is given, it is combined with the process’ umask value to determine the file mode and access flags. If parents is false (the default), a missing parent raises FileNotFoundError. If parents is true, any missing parents of this path are created as needed; they are created with the default permissions without taking mode into account (mimicking the POSIX mkdir -p command). If exist_ok is false (the default), FileExistsError is raised if the given path already exists in the file system, whether a directory or not. If exist_ok is true, FileExistsError is raised only if the given path already exists in the file system and is not a directory (same behavior as the POSIX mkdir -p command). Thanks for reading JL ---------- assignee: docs@python components: Documentation messages: 354874 nosy: docs@python, jlaurens priority: normal severity: normal status: open title: pathlib's mkdir documentation improvement type: enhancement versions: Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue38514> _______________________________________

2 1

[issue38524] functools.cached_property is not supported for setattr
by Serhiy Storchaka 19 Oct '19

19 Oct '19

Serhiy Storchaka <storchaka+cpython(a)gmail.com> added the comment: See issue38517. For now we need to better document the use of __set_name__ with cached_property. ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue38524> _______________________________________

1 0

[issue38524] functools.cached_property is not supported for setattr
by hongweipeng 19 Oct '19

19 Oct '19

hongweipeng <hongweichen8888(a)sina.com> added the comment: Is it possible to add an attrname parameter? It is more convenient to use. class cached_property: def __init__(self, func, attrname=None): self.attrname = attrname ... cls.age3 = cached_property(age, 'age3') ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue38524> _______________________________________

1 0

[issue38524] functools.cached_property is not supported for setattr
by Serhiy Storchaka 19 Oct '19

19 Oct '19

Serhiy Storchaka <storchaka+cpython(a)gmail.com> added the comment: You have to call __set_name__() if you create a cached_property dynamically outside of the class namespace. p = cached_property(age) p.__set_name__(cls, 'age3') cls.age3 = p (And setattr() is not needed here.) ---------- nosy: +serhiy.storchaka _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue38524> _______________________________________

1 0

[issue38524] functools.cached_property is not supported for setattr
by Serhiy Storchaka 19 Oct '19

19 Oct '19

Change by Serhiy Storchaka <storchaka+cpython(a)gmail.com>: ---------- nosy: +carljm, ncoghlan _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue38524> _______________________________________

1 0

[issue38524] functools.cached_property is not supported for setattr
by Steven D'Aprano 19 Oct '19

19 Oct '19

Steven D'Aprano <steve+python(a)pearwood.info> added the comment: The documentation doesn't mention ``__set_name__``, but it does say that cached_property is useful for properties which are "effectively immutable". The ``__set_name__`` error message is pretty cryptic, that seems to have something to do with this PEP: https://www.python.org/dev/peps/pep-0487/ but why it is relevant here, I don't know. I would expect that cached_property should apply only to read-only properties. So I think that at the very least, this needs better documentation and a better error message. ---------- assignee: -> docs@python components: +Documentation nosy: +docs@python, steven.daprano _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue38524> _______________________________________

1 0

[issue38518] Pickle protocol 5 is not documented in the data-stream-format section for the pickle docs
by Pablo Galindo Salgado 18 Oct '19

18 Oct '19

New submission from Pablo Galindo Salgado <pablogsal(a)gmail.com>: The Data Stream format section of the pickle docs (https://docs.python.org/3/library/pickle.html#data-stream-format) fails to document protocol 5 in the list of protocols. ---------- assignee: docs@python components: Documentation messages: 354898 nosy: docs@python, pablogsal, pitrou priority: normal severity: normal status: open title: Pickle protocol 5 is not documented in the data-stream-format section for the pickle docs versions: Python 3.8, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue38518> _______________________________________

2 2

Manual em Português
by jonata paulino 18 Oct '19

18 Oct '19

Bom dia amigos do Python. Gostaria de saber qual o manual de referência mais atual em português que vocês tem, e se podem disponibilizar pra mim. Obrigado. -- *Jonatã Paulino da Costa* *Currículo Lattes: http://lattes.cnpq.br/8292374718844917 <http://lattes.cnpq.br/8292374718844917>* *Contato: (91) 98144-9074*

1 0

[issue32758] Stack overflow when parse long expression to AST
by Serhiy Storchaka 18 Oct '19

18 Oct '19

Change by Serhiy Storchaka <storchaka+cpython(a)gmail.com>: ---------- resolution: -> fixed stage: patch review -> resolved status: open -> closed _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue32758> _______________________________________

1 0

[issue32758] Stack overflow when parse long expression to AST
by Serhiy Storchaka 18 Oct '19

18 Oct '19

Serhiy Storchaka <storchaka+cpython(a)gmail.com> added the comment: New changeset dedb99acdb5bbc179872235f975248133d3fb440 by Serhiy Storchaka (Ashley Whetter) in branch '2.7': bpo-32758: Warn that ast.parse() and ast.literal_eval() can segfault the interpreter (GH-5960) (GH-16565) https://github.com/python/cpython/commit/dedb99acdb5bbc179872235f975248133d… ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue32758> _______________________________________

1 0

[issue32758] Stack overflow when parse long expression to AST
by Serhiy Storchaka 18 Oct '19

18 Oct '19

Serhiy Storchaka <storchaka+cpython(a)gmail.com> added the comment: New changeset 8eb27cc35489848596d9fb4b1c91fac00ae75d21 by Serhiy Storchaka (Ashley Whetter) in branch '2.7': bpo-32758: Warn that compile() can crash when compiling to an AST object (GH-6043) (GH-16566) https://github.com/python/cpython/commit/8eb27cc35489848596d9fb4b1c91fac00a… ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue32758> _______________________________________

1 0

string return error when param is used in requests
by 해영서 18 Oct '19

18 Oct '19

Hello I ran into a bug when a string is returned when params is used in requests the problem seems to appear after the % symbol. I an using requests to download data from an open API in korea and the service_key they provide includes the '%' symbol. so when the code is supposed to return '...%2F...' it returns '...%252F...'. Kind regards Heayoung Suh

1 0

[issue38509] Insufficient description of relative imports in docs.python.org
by Aniruddha Bhattacharjee 17 Oct '19

17 Oct '19

New submission from Aniruddha Bhattacharjee <aniruddha97bhatt(a)gmail.com>: In the section "relative imports" of the documentation for "import system", the use of relative imports is explained with the use of an example, however if you try the exact same thing it gives an error. This is nicely explained in https://stackoverflow.com/questions/14132789/relative-imports-for-the-billi… and https://www.python.org/dev/peps/pep-0395/. This has also been added as an open issue in the documentation . Is this still under consideration, then I would be happy to update the docs. Thanks ---------- assignee: docs@python components: Documentation messages: 354851 nosy: Aniruddha Bhattacharjee, docs@python priority: normal severity: normal status: open title: Insufficient description of relative imports in docs.python.org type: behavior versions: Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue38509> _______________________________________

1 0

[issue38507] Improve the documentation of the nested list initialization
by JUN-WEI SONG 17 Oct '19

17 Oct '19

New submission from JUN-WEI SONG <sungboss2004(a)gmail.com>: When I used the nested list, I need to initialize the nested list, so I used this expression: >>> nested_list = [[]] * 5 see also: https://stackoverflow.com/questions/12791501/python-initializing-a-list-of-… So I later learned that such an expression would make the list inside the list have the same reference, which would cause the problem that you modified one element would lead to all elements changed in the nested list. For example: >>> nested_list[0].append(1) >>> nested_list [[1], [1], [1], [1], [1]] Therefore, maybe we could tell users how to initialize the list on the documentation like below: If you need to initialize the nested list, you could follow the below example, also, be aware of the expression like ``[[]] * 5``, this will cause the five lists in the nested list to have the same reference. >>> nested_list = [[] for _ in range(5)] ---------- assignee: docs@python components: Documentation messages: 354844 nosy: docs@python, krnick priority: normal severity: normal status: open title: Improve the documentation of the nested list initialization type: enhancement versions: Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue38507> _______________________________________

2 2

[issue35297] untokenize documentation is not correct
by Zsolt Cserna 16 Oct '19

16 Oct '19

New submission from Zsolt Cserna <cserna.zsolt(a)gmail.com>: untokenize documentation (https://docs.python.org/3/library/tokenize.html#tokenize.untokenize) states the following: """ Converts tokens back into Python source code. The iterable must return sequences with at least two elements, the token type and the token string. Any additional sequence elements are ignored. """ This last sentence is clearly not true because here: https://github.com/python/cpython/blob/master/Lib/tokenize.py#L242 The code checks for the length of the input token there, and the code behaves differently, in terms of whitespace, when an iterator of 2-tuples are given and when there are more elements in the tuple. When there are more elements in the tuple, the function renders whitespaces as the same as they were present in the original source. So this code: tokenize.untokenize(tokenize.tokenize(source.readline)) And this: tokenize.untokenize([x[:2] for x in tokenize.tokenize(source.readline)]) Have different results. I don't know that it is a documentation issue or a bug in the module itself, so I created this bugreport to seek for assistance in this regard. ---------- assignee: docs@python components: Documentation messages: 330281 nosy: csernazs, docs@python priority: normal severity: normal status: open title: untokenize documentation is not correct versions: Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue35297> _______________________________________

4 4

[issue38497] Wrong argument name in documentation for pipes.Template.open
by Ilaï 16 Oct '19

16 Oct '19

New submission from Ilaï <ilaideutel(a)gmail.com>: Documentation for the pipes module indicates that the second argument of open() is "mode", but it is actually "rw". Python 3.7.4 (default, Oct 4 2019, 06:57:26) [GCC 9.2.0] on linux Type "help", "copyright", "credits" or "license" for more information. >>> from pipes import Template; Template().open('/tmp/f', mode='r') Traceback (most recent call last): File "<stdin>", line 1, in <module> TypeError: open() got an unexpected keyword argument 'mode' Python 2.7.16 (default, Mar 11 2019, 18:59:25) [GCC 8.2.1 20181127] on linux2 Type "help", "copyright", "credits" or "license" for more information. >>> from pipes import Template; Template().open('/tmp/f', mode='r') Traceback (most recent call last): File "<stdin>", line 1, in <module> TypeError: open() got an unexpected keyword argument 'mode' https://docs.python.org/3/library/pipes.html#pipes.Template.open ---------- assignee: docs@python components: Documentation messages: 354781 nosy: docs@python, ilai priority: normal severity: normal status: open title: Wrong argument name in documentation for pipes.Template.open versions: Python 2.7, Python 3.5, Python 3.6, Python 3.7, Python 3.8, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue38497> _______________________________________

2 1