Mailman 3 August 2014 - docs

[issue21061] Is contextlib.redirect_stdout reentrant or not?
by Timothy Pederick Oct. 12, 2014

Oct. 12, 2014

New submission from Timothy Pederick: The docs are contradictory on whether or not contextlib.redirect_stdout is reentrant, or reusable-but-not-reentrant. This would seem to be an oversight from issue19403, which probably should have changed "reusable but not reentrant" to "reentrant". Present in both current and upcoming docs: http://docs.python.org/3/library/contextlib.html http://docs.python.org/3.5/library/contextlib.html contextlib.redirect_stdout(new_target) ... This context manager is reusable but not reentrant. 29.6.3.1. Reentrant context managers ... threading.RLock is an example of a reentrant context manager, as are suppress() and redirect_stdout(). ... Note also that being reentrant is not the same thing as being thread safe. redirect_stdout(), for example... ---------- assignee: docs@python components: Documentation messages: 214801 nosy: docs@python, perey priority: normal severity: normal status: open title: Is contextlib.redirect_stdout reentrant or not? versions: Python 3.4, Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue21061> _______________________________________

5 7

[issue18959] Create a "Superseded modules" section in standard library ToC
by Nick Coghlan Oct. 11, 2014

Oct. 11, 2014

New submission from Nick Coghlan: As discussed at the language summit earlier this year [1], it isn't alway easy to tell when glancing through the standard library docs which modules are merely hanging around because removing them would break backwards compatibility. However, after reviewing the current ToC, we currently appear to only have two genuinely superseded modules: optparse (superseded by argparse) and imp (superseded by importlib). Other cases where different modules touch on the same area are high level/low level splits (e.g. select vs selectors), or ones where the alternate modules are offering compatibility with different styles of API (e.g. etree vs DOM for XML, getopt vs argparse). In future, asyncore/asynchat will hopefully be superseded by the PEP 3156 code (as "concurrent.events" or similar) and would also be moved under the new heading. Marking as "easy" since the mechanics of the patch should be pretty simple: create a new heading and move the references to optparse and imp from their current locations. [1] http://python-notes.boredomandlaziness.org/en/latest/conferences/pyconus201… (I thought I had already created a bug for this, but can't find it, so I've created this new one. If I did already create an issue, we can close it as a duplicate and keep this one.) ---------- assignee: docs@python components: Documentation keywords: easy messages: 197154 nosy: docs@python, ncoghlan priority: normal severity: normal stage: needs patch status: open title: Create a "Superseded modules" section in standard library ToC type: enhancement versions: Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18959> _______________________________________

7 7

[issue21687] Py_SetPath: Path components separated by colons
by Florian Walch Oct. 11, 2014

Oct. 11, 2014

New submission from Florian Walch: The documentation for Py_SetPath [1] states: > The path components should be separated by semicolons. I believe this should not say "semicolons", but "colons"; the default path as output by Py_GetPath is separated by colons. [1] https://docs.python.org/3/c-api/init.html#c.Py_SetPath ---------- assignee: docs@python components: Documentation messages: 219944 nosy: docs@python, fwalch priority: normal severity: normal status: open title: Py_SetPath: Path components separated by colons type: behavior versions: Python 3.2, Python 3.3, Python 3.4, Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue21687> _______________________________________

3 2

[issue21675] Library - Introduction - paragraph 5 - wrong ordering
by Anthony Bartoli Oct. 11, 2014

Oct. 11, 2014

New submission from Anthony Bartoli: >From the library's introduction page: "This manual is organized “from the inside out:” it first describes the built-in data types..." The library manual first describes built-in functions, not data types. After built-in functions, it describes built-in constants, built-in types, and built-in exceptions. Lastly, it describes modules grouped by related functionality. A suggested re-write *for the entire paragraph*: "The library manual first documents built-in functions, built-in constants, built-in types, and built-in exceptions. Then it documents modules grouped by related functionality. I suggest eliminating the last sentence: "The ordering of the chapters as well as the ordering of the modules within each chapter is roughly from most relevant to least important." Importance is subjective and parts of the manual are organized alphabetically, not by relevance / importance. ---------- assignee: docs@python components: Documentation messages: 219860 nosy: AnthonyBartoli, docs@python priority: normal severity: normal status: open title: Library - Introduction - paragraph 5 - wrong ordering type: enhancement versions: Python 2.7, Python 3.2, Python 3.3, Python 3.4, Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue21675> _______________________________________

2 1

[issue15414] os.path.join behavior on Windows (ntpath.join) is unexpected and not well documented
by R. David Murray Oct. 10, 2014

Oct. 10, 2014

New submission from R. David Murray <rdmurray(a)bitdance.com>: In looking at another os.path.join documentation issue I tried the Windows join to see if it matched the docs, and found that it was very unclear. I searched the tracker and found Issue 1669539, which contains much relevant discussion but also much discussion of possible enhancements. So I'm opening a new issue *just* about what I see as the current bugs in the os.path.join docs and ntpath.join implementation. I'm not qualified to fix this, not being a Windows user, but it is clear to me that the documentation of os.path.join for Windows is unclear (it does not indicate what is considered an absolute path on Windows) and wrong (\foo will *not* restart the path if it is the second element and follows a drive specification, but it does any other time), and that the current behavior may have a bug if, as seems to be implied by the issue 1669539 discussion, something that looks like a drive specification in the middle of a path is invalid on Windows. If this last is not a bug, it should be mentioned in the documentation, since the actual behavior is counter-intuitive. ---------- assignee: docs@python components: Documentation, Windows keywords: easy messages: 166065 nosy: brian.curtin, christian.heimes, docs@python, eckhardt, ezio.melotti, jorend, mhammond, r.david.murray, terry.reedy, tim.golden priority: normal severity: normal status: open title: os.path.join behavior on Windows (ntpath.join) is unexpected and not well documented type: behavior versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15414> _______________________________________

8 12

[issue21072] Python docs and downloads not available for Egypt
by Leo Butcher Oct. 6, 2014

Oct. 6, 2014

New submission from Leo Butcher: I can't seem to access docs.python.org, mail.python.org, or even legacy.python.org from my ISP in Egypt "LinkDotNet" the usual dynamic IP range is 41.130.xx.xx please tell me if you need any further info ---------- assignee: docs@python components: Documentation messages: 214917 nosy: Leo.Butcher, docs@python priority: normal severity: normal status: open title: Python docs and downloads not available for Egypt type: resource usage versions: 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/issue21072> _______________________________________

6 12

[issue10583] Encoding issue with chm help in 2.7.1
by flashk Oct. 6, 2014

Oct. 6, 2014

New submission from flashk <flashk(a)gmail.com>: I just updated to Python 2.7.1 and noticed a small issue with the chm help file. The search results tab displays incorrect characters for various topic titles. It seems to be an encoding issue. For example, searching for 'json' yields the following results: - 18.2 json â€” JSON encoder and decoder - Whatâ€™s New in Python 2.6 I noticed this issue on Windows XP 32-bit and Windows 7 64-bit. This issue does not exist with the 2.7 chm file. ---------- assignee: docs@python components: Documentation, Windows messages: 122857 nosy: docs@python, flashk priority: normal severity: normal status: open title: Encoding issue with chm help in 2.7.1 type: behavior versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10583> _______________________________________

7 11

[issue19071] Documentation on what self is for module-level functions is misleading/wrong.
by Graham Dumpleton Oct. 6, 2014

Oct. 6, 2014

New submission from Graham Dumpleton: In the documentation for Python 2.X at: http://docs.python.org/2/extending/extending.html#a-simple-example it says: """ The self argument points to the module object for module-level functions; for a method it would point to the object instance. """ In respect of module-level functions this is misleading or arguably wrong. If one uses Py_InitModule() or Py_InitModule3(), then self is actually passed through as NULL for module-level functions in Python 2. There is a caveat on use of Py_InitModule4() which used to be mentioned in documentation for Python 2.6 at: http://docs.python.org/release/2.6.7/c-api/structures.html#METH_VARARGS where it says: """ This is the typical calling convention, where the methods have the type PyCFunction. The function expects two PyObject* values. The first one is the self object for methods; for module functions, it has the value given to Py_InitModule4() (or NULL if Py_InitModule() was used). """ Although one can supply a special argument to Py_InitModule4() which will be supplied as self, this still isn't the module object and in fact the module object for the module will not even exist at the point Py_InitModule4() is called so it is not possible to pass it in. Plus within the init function of an extension, the module object is not that which would end up being used in a specific interpreter due to how the init function is only called once and a copy then made of the module for each interpreter. This actual page in the documentation was changed in Python 2.7 and now in: http://docs.python.org/2/c-api/structures.html#METH_VARARGS says: """ The function expects two PyObject* values. The first one is the self object for methods; for module functions, it is the module object. """ So the reference to Py_InitModule4() was removed and simply says that module object is supplied, which isn't actually the case. Now, that NULL is always passed for Py_InitModule() and Py_InitModule3() is the case with Python 2. In Python 3 at some point, the code in Python internals was changed so the module object is actually passed as documented. So, maybe the intent was that when in Python 3 the code was changed to pass the module object to module-level functions that it be back ported to Python 2.7 and the documentation so changed, but looks like that back porting was never done, or if it was, it has been broken somewhere along the way. Code used to verify this is all attached. If compiled and installed for Python 3 one gets: >>> import mymodule._extension >>> id(mymodule._extension) 4480540328 >>> mymodule._extension.function() <module 'mymodule._extension' from '/Users/graham/Projects/python-c-extension-template/lib/python3.3/site-packages/mymodule/_extension.so'> >>> id(mymodule._extension.function()) 4480540328 If compiled and installed for Python 2.7 one gets: >>> import mymodule._extension >>> id(mymodule._extension) 4554745960 >>> mymodule._extension.function() Traceback (most recent call last): File "<stdin>", line 1, in <module> TypeError: no module supplied for self The function in the extension module was doing: static PyObject *extension_function(PyObject *self, PyObject *args) { if (!self) { PyErr_SetString(PyExc_TypeError, "no module supplied for self"); return NULL; } Py_INCREF(self); return self; } ---------- assignee: docs@python components: Documentation files: example.tar messages: 198265 nosy: docs@python, grahamd priority: normal severity: normal status: open title: Documentation on what self is for module-level functions is misleading/wrong. type: behavior versions: Python 2.7 Added file: http://bugs.python.org/file31841/example.tar _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue19071> _______________________________________

5 4

[issue16155] Some minor doc fixes in Doc/faq
by Ravi Sinha Oct. 6, 2014

Oct. 6, 2014

New submission from Ravi Sinha: - help(fn) which in the REPL leads to a new pager/ display - seems to be difficult to test with doctest - it does not seem to pick the whitespace in the docs and does not match - Doc/faq/general.rst - os.path.isdir returns True or False, not 0 or 1 as in the docs, but I didn't know if I should change that - Doc/faq/windows.rst ---------- assignee: docs@python components: Documentation files: doc_faq.patch keywords: patch messages: 172254 nosy: Ravi.Sinha, chris.jerdonek, docs@python, r.david.murray, terry.reedy priority: normal severity: normal status: open title: Some minor doc fixes in Doc/faq type: enhancement versions: Python 3.4 Added file: http://bugs.python.org/file27463/doc_faq.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue16155> _______________________________________

8 12

[issue17057] Data model documentation grammar
by Hobs Oct. 6, 2014

Oct. 6, 2014

New submission from Hobs: New-style and old-style class expalanation in the datamodel section has minor grammatical errors and one minor ambiguity that could be improved. http://docs.python.org/2/reference/datamodel.html#new-style-and-classic-cla… * "independently of" should always be "indepenent of" * single hyphens (-) should be double-hyphens (--) for an m-dash * "flavour" should be "flavor" (used 100x more often in docs.python) * "only the symantics of..." is ambiguous. can't tell if 'only' modifies 'symantics' or 'new-style classes'? ---------- assignee: docs@python components: Documentation files: datamodel-reference-docs.patch keywords: patch messages: 180812 nosy: Hobson.Lane, docs@python priority: normal severity: normal status: open title: Data model documentation grammar type: enhancement versions: Python 2.7 Added file: http://bugs.python.org/file28876/datamodel-reference-docs.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue17057> _______________________________________

3 2