Mailman 3 August 2014 - docs

[issue12148] Clarify "or-ing together" doctest option flags
by ekorn Oct. 6, 2014

Oct. 6, 2014

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 Oct. 6, 2014

Oct. 6, 2014

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 Oct. 6, 2014

Oct. 6, 2014

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 Oct. 6, 2014

Oct. 6, 2014

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 Oct. 6, 2014

Oct. 6, 2014

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 Oct. 6, 2014

Oct. 6, 2014

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

[issue18494] PyType_GenericSet/GetDict functions misnamed in docs?
by Wolf Ihlenfeldt Oct. 6, 2014

Oct. 6, 2014

New submission from Wolf Ihlenfeldt: Are the names of functions PyType_GenericSetDict and -GetDict correctly documented (for 3.3.2), or should they be documented as PyObject_GenericGet/SetDict instead? The PyType-prefixed names are out of place in the section, and functions of these names not in the source. The PyObject_-variants are present. ---------- assignee: docs@python components: Documentation messages: 193315 nosy: Wolf.Ihlenfeldt, docs@python priority: normal severity: normal status: open title: PyType_GenericSet/GetDict functions misnamed in docs? versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18494> _______________________________________

4 3

[issue19477] document tp_print() as being dead in Py3
by Stefan Behnel Oct. 5, 2014

Oct. 5, 2014

New submission from Stefan Behnel: The "tp_print" slot is still documented as it was in Py2, although it is no longer used in Py3. http://docs.python.org/3.4/c-api/typeobj.html?highlight=tp_print#PyTypeObje… Given that it no longer serves any purpose, it should at least be deprecated and documented as unused/ignored (and eventually removed completely, at the same time as tp_reserved). ---------- assignee: docs@python components: Documentation messages: 201933 nosy: docs@python, scoder priority: normal severity: normal status: open title: document tp_print() as being dead in Py3 type: behavior versions: Python 3.1, Python 3.2, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue19477> _______________________________________

4 6

[issue20997] Wrong URL fragment identifier in search result
by Baptiste Mispelon Oct. 5, 2014

Oct. 5, 2014

New submission from Baptiste Mispelon: When doing a search for "PYTHONDONTWRITEBYTECODE" on the 2.7 docs (http://docs.python.org/2/search.html?q=PYTHONDONTWRITEBYTECODE), the first (and only) search result is the following link: http://docs.python.org/2/using/cmdline.html?highlight=pythondontwritebyteco… (note the `#PYTHONDONTWRITEBYTECODE` at the end) Clicking this link takes you to the right page but the browser doesn't scroll to the correct position on the page as expected. This is because there's no element with an `id` of `PYTHONDONTWRITEBYTECODE`. The correct id is `envvar-PYTHONDONTWRITEBYTECODE`. Things work as expected when searching on version 3 docs (http://docs.python.org/3/search.html?q=PYTHONDONTWRITEBYTECODE), where the correct fragment identifier is generated in the search results. ---------- assignee: docs@python components: Documentation messages: 214245 nosy: bmispelon, docs@python priority: normal severity: normal status: open title: Wrong URL fragment identifier in search result type: behavior versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue20997> _______________________________________

4 3

[issue18043] No mention of `match.regs` in `re` documentation
by Ram Rachum Oct. 4, 2014

Oct. 4, 2014

New submission from Ram Rachum: There's no mention of `match.regs` in the documentation of the `re` module. ---------- assignee: docs@python components: Documentation messages: 189859 nosy: cool-RR, docs@python priority: normal severity: normal status: open title: No mention of `match.regs` in `re` documentation type: behavior versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18043> _______________________________________

6 7