Mailman 3 October 2014 - docs

[issue19071] Documentation on what self is for module-level functions is misleading/wrong.
by Graham Dumpleton 06 Oct '14

06 Oct '14

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 06 Oct '14

06 Oct '14

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 06 Oct '14

06 Oct '14

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

[issue12148] Clarify "or-ing together" doctest option flags
by ekorn 06 Oct '14

06 Oct '14

New submission from ekorn <jonovik(a)gmail.com>: Combining multiple option flags to doctest.testmod(optionflags=...) requires the bitwise or operator |, not plain "or". I therefore suggest rewording "or-ing together individual option flags." to "or-ing together individual option flags, using the 'bitwise or' operator |.", perhaps with a link to http://docs.python.org/reference/expressions.html#binary-bitwise-operations. Example: """ Doctest option flags must be or-ed together with '|', not 'or'. >>> print "A B C" A B... """ import doctest print "Combining option flags using bitwise '|'..." doctest.testmod(optionflags=doctest.NORMALIZE_WHITESPACE | doctest.ELLIPSIS) print "Combining option flags using logical 'or'..." doctest.testmod(optionflags=doctest.NORMALIZE_WHITESPACE or doctest.ELLIPSIS) ---------- assignee: docs@python components: Documentation messages: 136509 nosy: docs@python, ekorn priority: normal severity: normal status: open title: Clarify "or-ing together" doctest option flags versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12148> _______________________________________

6 8

[issue21782] hashable documentation error: shouldn't mention id
by Giacomo Alzetta 06 Oct '14

06 Oct '14

New submission from Giacomo Alzetta: The documentation for hashable in the glossary (https://docs.python.org/3.4/reference/datamodel.html#object.__hash__) is incorrect: they all compare unequal (except with themselves), **and their hash value is their id().** It is *not* true that their hash is their id (see relevant SO question: http://stackoverflow.com/questions/24249729/user-defined-class-hash-and-id-…) Also the documentation for __hash__ (https://docs.python.org/3.4/reference/datamodel.html#object.__hash__) doesn't even mention id(). ---------- assignee: docs@python components: Documentation messages: 220746 nosy: Giacomo.Alzetta, docs@python priority: normal severity: normal status: open title: hashable documentation error: shouldn't mention id type: enhancement versions: 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/issue21782> _______________________________________

3 4

[issue13101] Module Doc viewer closes when browser window closes on Windows 8
by Brian Curtin 06 Oct '14

06 Oct '14

New submission from Brian Curtin <brian(a)python.org>: Reported by Ryan Wells (v-rywel(a)microsoft.com) of Microsoft, in reference to a problem with the Module Doc viewer on Windows 8 when using Internet Explorer 10. This was reported on 3.2.2, but it's likely the same on 2.7. Reference #: 70652 Description of the Problem: The application Python Module Doc is automatically closed when Internet Explorer 10 is closed. Steps to Reproduce: 1. Install Windows Developer Preview 2. Install Python 3.2.2 3. Launch Module Doc. Start Menu -> All Program -> Python -> Manual Docs 4. Click on the button open browser 5. It should open the site http://localhost:7464/ In Internet Explorer 10 and the contents should be displayed 6. Should be able to view list of Modules, Scripts, DLLs, and Libraries etc. 7. Close Internet Explorer Expected Result: Internet Explorer 10 should only get closed and we should be able to work with the application Module Doc. Actual Result: The application Module Doc is closed with Internet Explorer 10. Developer Notes: There is likely a difference in return values between IE8 and IE9/10 when launched from the app. ---------- assignee: docs@python components: Documentation, Windows messages: 144918 nosy: brian.curtin, docs@python priority: normal severity: normal status: open title: Module Doc viewer closes when browser window closes on Windows 8 type: behavior versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13101> _______________________________________

5 7

[issue21784] __init__.py can be a directory
by abraithwaite 06 Oct '14

06 Oct '14

New submission from abraithwaite: Is this expected? It was very confusing when I cloned a repo that didn't have the __init__.py there when I had just made it, but of course git doesn't track files, only directories. I had accidentaly done mkdir instead of touch. $ mkdir pkg/__init__.py $ touch pkg/foobar.py $ python Python 3.4.1 (default, May 19 2014, 17:23:49) [GCC 4.9.0 20140507 (prerelease)] on linux Type "help", "copyright", "credits" or "license" for more information. >>> from pkg import foobar >>> foobar <module 'pkg.foobar' from '/home/abraithwaite/pkg/foobar.py'> >>> ---------- assignee: docs@python components: Documentation messages: 220787 nosy: abraithwaite, docs@python priority: normal severity: normal status: open title: __init__.py can be a directory type: behavior 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/issue21784> _______________________________________

6 9

[issue14303] Incorrect documentation for socket.py on linux
by Shane Hansen 06 Oct '14

06 Oct '14

New submission from Shane Hansen <shanemhansen(a)gmail.com>: The python docs state that for socket.makefile "The file object references a dup()ped version of the socket file descriptor, so the file object and socket object may be closed or garbage-collected independently." In fact for socket.py dup() is never called, and no additional files are opened. Instead an object is returned which uses the original socket and does buffering. For me, this is the desired behaviour, but just thought I'd mention the docs were off. ---------- assignee: docs@python components: Documentation, IO files: test.py messages: 155768 nosy: Shane.Hansen, docs@python, georg.brandl, pitrou priority: normal severity: normal status: open title: Incorrect documentation for socket.py on linux type: behavior versions: Python 2.6, Python 2.7 Added file: http://bugs.python.org/file24843/test.py _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14303> _______________________________________

4 3

[issue10031] Withdraw anti-recommendation of relative imports from documentation
by Darren Dale 06 Oct '14

06 Oct '14

New submission from Darren Dale <dsdale24(a)gmail.com>: Old-style relative imports have been strongly discouraged in some sections of the python documentation. This was discussed on the python-dev mailing list. Executive summary: "The issue is implementing a PEP with nice support for relative imports, and then documenting that it should never be used." To which Guido responded: --- "Isn't this mostly historical? Until the new relative-import syntax was implemented there were various problems with relative imports. The short-term solution was to recommend not using them. The long-term solution was to implement an unambiguous syntax. Now it is time to withdraw the anti-recommendation. Of course, without going overboard -- I still find them an acquired taste; but they have their place." --- It was suggested I open a ticket and suggest specific changes. They are listed below: The faq at http://docs.python.org/py3k/faq/programming.html#what-are-the-best-practice… could go from: "Never use relative package imports. If you’re writing code that’s in the package.sub.m1 module and want to import package.sub.m2, do not just write from . import m2, even though it’s legal. Write from package.sub import m2 instead. See PEP 328 for details." to: "Although the python community generally prefers absolute imports, relative imports may be useful in certain circumstances. See PEP 328 for details." The programming faq for python-2.7 at http://docs.python.org/faq/programming.html#what-are-the-best-practices-for… could go from: "Never use relative package imports. If you’re writing code that’s in the package.sub.m1 module and want to import package.sub.m2, do not just write import m2, even though it’s legal. Write from package.sub import m2 instead. Relative imports can lead to a module being initialized twice, leading to confusing bugs. See PEP 328 for details." to: "Although the python community generally prefers absolute imports, relative imports may be useful in certain circumstances. Support for relative imports has recently been improved, and the use of the old-style relative imports is strongly discouraged. See PEP 328 for details." There is also this warning against relative imports in PEP 8, that could go from: - Relative imports for intra-package imports are highly discouraged. Always use the absolute package path for all imports. Even now that PEP 328 [7] is fully implemented in Python 2.5, its style of explicit relative imports is actively discouraged; absolute imports are more portable and usually more readable. to: - While the python community generally prefers absolute imports, relative imports may be useful in certain circumstances. Now that PEP 328 [7] is fully implemented in Python 2.5 and later, the older style of implicit relative imports is strongly discouraged. ---------- assignee: docs@python components: Documentation messages: 118031 nosy: docs@python, dsdale24 priority: normal severity: normal status: open title: Withdraw anti-recommendation of relative imports from documentation 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/issue10031> _______________________________________

5 5

[issue22565] missing const in declaration of PyErr_WarnEx in C-API docs
by Lars Buitinck 06 Oct '14

06 Oct '14

New submission from Lars Buitinck: The declaration for PyErr_WarnEx in Doc/c-api/exceptions.rst is missing a const compared to Include/warnings.h. ---------- assignee: docs@python components: Documentation files: pyerr_warnex_const.patch keywords: patch messages: 228657 nosy: docs@python, larsmans priority: normal severity: normal status: open title: missing const in declaration of PyErr_WarnEx in C-API docs versions: Python 3.5 Added file: http://bugs.python.org/file36824/pyerr_warnex_const.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue22565> _______________________________________

2 1