Mailman 3 December 2015 - docs

[issue23557] Misc/SpecialBuilds.txt contains outdated information about PYMALLOC_DEBUG
by Jakub Klama June 2, 2020

June 2, 2020

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

June 1, 2020

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 May 31, 2020

May 31, 2020

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

[issue13649] termios.ICANON is not documented
by anatoly techtonik May 31, 2020

May 31, 2020

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 May 31, 2020

May 31, 2020

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

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

May 31, 2020

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

[issue24256] threading.Timer is not a class
by John Runyon May 31, 2020

May 31, 2020

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 May 31, 2020

May 31, 2020

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 May 31, 2020

May 31, 2020

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 May 31, 2020

May 31, 2020

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