Mailman 3 October 2012 - docs

[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

[issue13211] urllib2.HTTPError does not have 'reason' attribute.
by Jason R. Coombs 04 Oct '14

04 Oct '14

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

[issue16252] bytes and bytearray methods are undocumented
by Antoine Pitrou 27 Sep '14

27 Sep '14

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 27 Sep '14

27 Sep '14

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

[issue14824] reprlib documentation references string module
by Jasper St. Pierre 18 Sep '14

18 Sep '14

New submission from Jasper St. Pierre <jstpierre(a)mecheye.net>: http://docs.python.org/dev/library/reprlib.html """ Formatting methods for specific types are implemented as methods with a name based on the type name. In the method name, TYPE is replaced by string.join(string.split(type(obj).__name__, '_')). Dispatch to these methods is handled by repr1(). Type-specific methods which need to recursively format a value should call self.repr1(subobj, level - 1). """ Outstanding. ---------- assignee: docs@python components: Documentation messages: 160805 nosy: docs@python, magcius priority: normal severity: normal status: open title: reprlib documentation references string module versions: Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14824> _______________________________________

5 8

[issue15418] 2to3 docs should mention setup.py fixes required to install compatible packages in Python 3
by anatoly techtonik 30 Aug '14

30 Aug '14

New submission from anatoly techtonik <techtonik(a)gmail.com>: http://docs.python.org/py3k/library/2to3.html should mention the practice of running 2to3 in setup.py for codebase compatible with both Python 2 and Python 3. ---------- assignee: docs@python components: Documentation messages: 166108 nosy: docs@python, techtonik priority: normal severity: normal status: open title: 2to3 docs should mention setup.py fixes required to install compatible packages in Python 3 versions: Python 3.1, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15418> _______________________________________

4 3

[issue13540] Document the Action API
by Jason R. Coombs 24 Aug '14

24 Aug '14

New submission from Jason R. Coombs <jaraco(a)jaraco.com>: In http://docs.python.org/dev/library/argparse.html#action, when describing an arbitrary action, the documentation states, "You can also specify an arbitrary action by passing an object that implements the Action API." This statement does not link to any documentation on the Action API and does not describe the API except to give an example. Furthermore, the example contradicts the description. The description says "pass an object" but the example passes a class. The documentation should clarify the text relating to the example and should document the expected interface for a custom action. ---------- assignee: docs@python components: Documentation messages: 148921 nosy: docs@python, jason.coombs priority: low severity: normal status: open title: Document the Action API type: behavior versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13540> _______________________________________

8 30

[issue15428] add "Name Collision" section to argparse docs
by Steven Bethard 07 Aug '14

07 Aug '14

New submission from Steven Bethard <steven.bethard(a)gmail.com>: Several bugs (e.g. Issue 15327 and Issue 15271) have been filed suggesting that people aren't really clear on how argparse handles argument name collisions or how they can get it to do what they want. I think these problems could probably be solved by a "Name Collision" section (or something like that) in the argparse documentation. It would give a few example problems and show how to resolve them. Some things to include: * What happens when two arguments have the same dest (Issue 15271), with solutions including action='append' or different dest= values combined with identical metavar= values. * What happens when a parser and a sub-parser share some of the same argument names (Issue 15327), with solutions including specifying different dest= values for the parser and sub-parser * A brief mention and cross-reference to the "conflict_handler" section. ---------- assignee: docs@python components: Documentation messages: 166185 nosy: bethard, docs@python priority: normal severity: normal status: open title: add "Name Collision" section to argparse docs versions: Python 2.7, Python 3.2, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15428> _______________________________________

3 3

[issue15759] "make suspicious" doesn't display instructions in case of failure
by Ezio Melotti 05 Aug '14

05 Aug '14

New submission from Ezio Melotti: I was running "make suspicious" in Doc/ and this was the output after finding 3 suspicious markups: writing output... [ 52%] library/inspect WARNING: [library/inspect:437] ":int" found in ">>> def foo(a, *, b:int, **kwargs):" WARNING: [library/inspect:437] ":int" found in "'(a, *, b:int, **kwargs)'" WARNING: [library/inspect:437] ":int" found in "'b:int'" writing output... [100%] whatsnew/index build finished with problems, 3 warnings. make: *** [build] Error 1 After figuring out how to mark these as false positives and adding the relevant entries to susp-ignored.csv, I ran "make suspicious" again, and got this useful message at the end: writing output... [100%] whatsnew/index build succeeded. Suspicious check complete; look for any errors in the above output or in build/suspicious /suspicious.csv. If all issues are false positives, append that file to tools/sphinxext/susp-ignored.csv. The problem is that this message should be displayed when there are failures, but it's not. Attached an attempt to fix the Makefile to avoid exiting in case of failures when the builder is "suspicious". Given that I'm not really familiar with makefiles, it probably doesn't make much sense. ---------- assignee: docs@python components: Documentation files: issue15759.diff keywords: patch messages: 168842 nosy: docs@python, eric.araujo, ezio.melotti, georg.brandl priority: normal severity: normal stage: patch review status: open title: "make suspicious" doesn't display instructions in case of failure type: behavior versions: Python 3.3 Added file: http://bugs.python.org/file26956/issue15759.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15759> _______________________________________

5 15