Mailman 3 August 2013 - docs

[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

[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

[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

[issue13211] urllib2.HTTPError does not have 'reason' attribute.
by Jason R. Coombs Oct. 4, 2014

Oct. 4, 2014

New submission from Jason R. Coombs <jaraco(a)jaraco.com>: The urllib2 docs indicate that HTTPError is a subclass of URLError and that URLError has an attribute of 'reason', but HTTPError does not have this attribute. The docs should be updated to reflect this deviance. It appears the Python 3.2 docs no longer include documentation for URLError Python 2.7.2 >>> try:urllib2.urlopen('http://api.wordnik.com/v4/word.json/foo/examples') ... except urllib2.HTTPError as exc: ... print(dir(exc)) ... ['_HTTPError__super_init', '__class__', '__delattr__', '__dict__', '__doc__', '__format__', '__getattribute__', '__getitem__', '__getslice__', '__hash__', '__init__', '__iter__', '__module__', '__new__', '__reduce__', '__reduce_ex__', '__repr__', '__setattr__', '__setstate__', '__sizeof__', '__str__', '__subclasshook__', '__unicode__', '__weakref__', 'args', 'close', 'code', 'errno', 'filename', 'fileno', 'fp', 'getcode', 'geturl', 'hdrs', 'headers', 'info', 'message', 'msg', 'next', 'read', 'readline', 'readlines', 'strerror', 'url'] The same issue exists in Python 3.2.2. Here's what I propose: - For Python 3.2 and 3.3, update HTTPError to supply a @property, aliasing .msg (will .msg always be a suitable .reason?). - For Python 2.7, document the deviance, such as by adding the following wording to the HTTPError docs: "Unlike URLError, HTTPError does not supply a reason attribute. The reason can be retrieved through the msg attribute." ---------- assignee: docs@python components: Documentation messages: 145805 nosy: docs@python, jason.coombs priority: normal severity: normal status: open title: urllib2.HTTPError does not have 'reason' attribute. versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13211> _______________________________________

8 23

[issue18729] In unittest.TestLoader.discover doc select the name of load_tests function
by py.user Oct. 2, 2014

Oct. 2, 2014

New submission from py.user: http://docs.python.org/3/library/unittest.html#unittest.TestLoader.discover "If load_tests exists then discovery does not recurse into the package" ---------- assignee: docs@python components: Documentation files: issue.diff keywords: patch messages: 195092 nosy: docs@python, py.user priority: normal severity: normal status: open title: In unittest.TestLoader.discover doc select the name of load_tests function type: enhancement versions: Python 3.3, Python 3.4 Added file: http://bugs.python.org/file31283/issue.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18729> _______________________________________

4 3

[issue16252] bytes and bytearray methods are undocumented
by Antoine Pitrou Sept. 27, 2014

Sept. 27, 2014

New submission from Antoine Pitrou: Everything is in the title. I couldn't find any doc for bytes.join, etc. (while str methods are documented in library/stdtypes.html#string-methods). ---------- assignee: docs@python components: Documentation messages: 173074 nosy: docs@python, pitrou priority: normal severity: normal stage: needs patch status: open title: bytes and bytearray methods are undocumented type: behavior versions: Python 3.2, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue16252> _______________________________________

5 6

[issue10702] bytes and bytearray methods are not documented
by Alexander Belopolsky Sept. 27, 2014

Sept. 27, 2014

New submission from Alexander Belopolsky <belopolsky(a)users.sourceforge.net>: Library reference manual has a section dedicated to string methods [1], but similar methods of bytes and bytearray types are not documented. Adding two new sections would probably be too repetitious, so I wonder if it would make sense to add notes about byte/bytearray methods to the matching string methods' entries. See also issue10587. [1] http://docs.python.org/dev/py3k/library/stdtypes.html#string-methods ---------- assignee: docs@python components: Documentation messages: 123960 nosy: belopolsky, docs@python priority: normal severity: normal status: open title: bytes and bytearray methods are not documented versions: Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10702> _______________________________________

6 7

[issue17462] argparse FAQ: how it is different from optparse
by anatoly techtonik Sept. 26, 2014

Sept. 26, 2014

New submission from anatoly techtonik: http://stackoverflow.com/questions/3217673/why-use-argparse-rather-than-opt… Too many votes. This should be confirmed by the official documentation. ---------- assignee: docs@python components: Documentation messages: 184468 nosy: docs@python, techtonik priority: normal severity: normal status: open title: argparse FAQ: how it is different from optparse _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue17462> _______________________________________

9 15