Mailman 3 July 2018 - docs

[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

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

May 31, 2020

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

May 31, 2020

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

May 31, 2020

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 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

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

May 31, 2020

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 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

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

May 31, 2020

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

May 31, 2020

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