Mailman 3 August 2014 - docs

[issue17876] Doc issue with threading.Event
by Xavier Ordoquy Dec. 16, 2014

Dec. 16, 2014

New submission from Xavier Ordoquy: The documentation isn't correct for the threading.Event class under python 3.2. In the threading doc page (http://docs.python.org/3.2/library/threading.html), Event is said to be at the same time a function and a class. This is misleading and lead to a regression for celery under python 3.2 (https://github.com/celery/celery/pull/1333). Could the doc be updated under python 3.2 so that threading.Event leads to the function and threading._Event leads to the class ? Regards, Xavier. ---------- assignee: docs@python components: Documentation messages: 188127 nosy: docs@python, xordoquy priority: normal severity: normal status: open title: Doc issue with threading.Event type: enhancement versions: Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue17876> _______________________________________

4 5

[issue9536] defaultdict doc makes incorrect reference to __missing__ method
by John Posner Dec. 12, 2014

Dec. 12, 2014

New submission from John Posner <jjposner(a)optimum.net>: The documentation for collections.defaultdict is confusing with respect to the __missing__ method. The fact is that a programmer using defaultdict does not need to know anything about __missing__. The attached patch contains a rewrite of the entire section (but not the "defaultdict Examples" section, which is fine. ---------- assignee: docs@python components: Documentation files: defaultdict.patch keywords: patch messages: 113105 nosy: docs@python, jjposner priority: normal severity: normal status: open title: defaultdict doc makes incorrect reference to __missing__ method versions: Python 2.7 Added file: http://bugs.python.org/file18417/defaultdict.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9536> _______________________________________

7 11

[issue21514] update json module docs in light of RFC 7159 & ECMA-404
by Chris Rebert Nov. 27, 2014

Nov. 27, 2014

New submission from Chris Rebert: json module docs: https://docs.python.org/3/library/json.html New superseding JSON RFC: https://tools.ietf.org/html/rfc7159 Errata to the new RFC: http://www.rfc-editor.org/errata_search.php?rfc=7159 ECMA-404: http://www.ecma-international.org/publications/standards/Ecma-404.htm These updated specs are of particular relevance to the Standard Compliance section of the json module docs. There are also a bunch of new interoperability notes in the RFC that could probably bear repeating in the module's docs. ---------- assignee: docs@python components: Documentation messages: 218644 nosy: cvrebert, docs@python priority: normal severity: normal status: open title: update json module docs in light of RFC 7159 & ECMA-404 versions: Python 2.7, Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue21514> _______________________________________

7 18

[issue20351] Add doc examples for DictReader and DictWriter
by Charles-Axel Dein Nov. 24, 2014

Nov. 24, 2014

New submission from Charles-Axel Dein: IMO csv.DictWriter and csv.DictReader provides a nicer interface for complex CSV file. I see some people reinventing the DictReader and DictWriter pretty frequently, because when they rapidly scan the documentation all examples are about csv.reader and csv.writer. This patch adds examples. ---------- assignee: docs@python components: Documentation files: add_csvdict_examples.patch keywords: patch messages: 208835 nosy: charlax, docs@python priority: normal severity: normal status: open title: Add doc examples for DictReader and DictWriter Added file: http://bugs.python.org/file33629/add_csvdict_examples.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue20351> _______________________________________

7 16

[issue19796] urllib2.HTTPError.reason is not documented as "Added in 2.7"
by Alex Willmer Nov. 12, 2014

Nov. 12, 2014

New submission from Alex Willmer: issue13211 added a .reason attribute to urllib2.HTTPError in Python 2.7, issue16634 documented it (http://hg.python.org/cpython/rev/deb60efd32eb). The documentation for Python 2.7 doesn't mention that this attribute was added in that release. This (at least weakly) implies it's available to use in previous 2.x releases. ---------- assignee: docs@python components: Documentation files: HTTPError.reason-versionadded.diff keywords: patch messages: 204465 nosy: docs@python, moreati priority: normal severity: normal status: open title: urllib2.HTTPError.reason is not documented as "Added in 2.7" type: behavior versions: Python 2.7 Added file: http://bugs.python.org/file32855/HTTPError.reason-versionadded.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue19796> _______________________________________

3 4

[issue22242] Doc fix in the Import section in language reference.
by Jon Poler Nov. 7, 2014

Nov. 7, 2014

New submission from Jon Poler: It looks like there might be a contradiction in the documentation of import in the language reference. In the loading subsection https://docs.python.org/dev/reference/import.html#loading, first bulleted list of the section, it specifies that if a loader fails, it must remove only the failing module from sys.modules, while other side-effect imports by loader will stay in sys.modules. In the next subsection https://docs.python.org/dev/reference/import.html#loaders, second bulleted list (last bullet), the phrasing is confusing, and possibly contradictory. I believe that it meant to reiterate what was said above (see my previous paragraph). Attached is a potential patch, but if anyone finds that I am interpreting this wrong, I'll make adjustments accordingly. ---------- assignee: docs@python components: Documentation files: import_doc_fix.patch keywords: patch messages: 225610 nosy: docs@python, jon.poler priority: normal severity: normal status: open title: Doc fix in the Import section in language reference. type: enhancement versions: Python 3.5 Added file: http://bugs.python.org/file36427/import_doc_fix.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue22242> _______________________________________

5 5

[issue21759] URL Typo in Documentation FAQ
by are-you-watching-closely Nov. 3, 2014

Nov. 3, 2014

New submission from are-you-watching-closely: Under this question (https://docs.python.org/2/faq/programming.html#my-program-is-too-slow-how-d…) in the 2.7 programming FAQ, it gives a link to an anecdote that Guido van Rossum wrote. The URL it gives: http://www.python.org/doc/essays/list2str.html The correct URL (no .html): http://www.python.org/doc/essays/list2str I'm sure there are some people who didn't think to remove the '.html', and couldn't find the story. Just a quick typo fix. ---------- assignee: docs@python components: Documentation messages: 220575 nosy: are-you-watching-closely, docs@python priority: normal severity: normal status: open title: URL Typo in Documentation FAQ versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue21759> _______________________________________

5 5

[issue16518] add "buffer protocol" to glossary
by Chris Jerdonek Oct. 31, 2014

Oct. 31, 2014

New submission from Chris Jerdonek: This issue is to add "buffer protocol" (or perhaps "buffer object") to the glossary. The concept is currently described here: http://docs.python.org/dev/c-api/buffer.html#buffer-protocol Éric initially suggested doing this in the comments to issue 13538. Such a glossary entry would be useful because the buffer protocol (or buffer object) should likely be cited, for example, wherever a function accepts a bytes object, bytearray object, or any object that supports the buffer protocol. The str() constructor is one example where this is done: http://hg.python.org/cpython/file/59acd5cac8b5/Doc/library/functions.rst#l1… "Buffer object" might be the more useful term to add to the glossary because it would help to have a briefer way of saying "any object that supports the buffer protocol." (I'm assuming this is what "buffer object" actually means.) The patch for this issue should also do a comprehensive review of occurrences of buffer object/protocol throughout the docs and add or update links and index entries where appropriate. ---------- assignee: docs@python components: Documentation messages: 176042 nosy: chris.jerdonek, docs@python, eric.araujo, ezio.melotti, pitrou priority: normal severity: normal status: open title: add "buffer protocol" to glossary type: enhancement versions: Python 3.2, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue16518> _______________________________________

11 35

[issue22305] Documentation on deepcopy's problems is misleading
by Shailesh Hegde Oct. 28, 2014

Oct. 28, 2014

New submission from Shailesh Hegde: https://docs.python.org/<version>/library/copy.html "Two problems often exist with deep copy operations that don’t exist with shallow copy operations: Recursive objects (compound objects that, directly or indirectly, contain a reference to themselves) may cause a recursive loop. Because deep copy copies everything it may copy too much, e.g., administrative data structures that should be shared even between copies." I believe the last line in above paragraph is missing a 'not' ahead of 'be shared'. It should read: "administrative data structures that should be not shared even between copies" ---------- assignee: docs@python components: Documentation messages: 226123 nosy: docs@python, shlsh priority: normal severity: normal status: open title: Documentation on deepcopy's problems is misleading 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/issue22305> _______________________________________

3 3

[issue22249] Possibly incorrect example is given for socket.getaddrinfo()
by Alexander Patrakov Oct. 28, 2014

Oct. 28, 2014

New submission from Alexander Patrakov: See the example at https://docs.python.org/2/library/socket.html#socket.getaddrinfo >>> socket.getaddrinfo("www.python.org", 80, 0, 0, socket.SOL_TCP) As I am primarily a C programmer, it is quite surprising for me to see a SOL_* being passed into the proto argument. I thought that SOL_* is only for setsockopt(), and IPPROTO_* would be suitable. Yes, for TCP and UDP the SOL_* and IPPROTO_* constants are the same, but see e.g. http://msdn.microsoft.com/en-us/library/windows/desktop/ms737530%28v=vs.85%… which specifically points out that IPPROTO_* constants as acceptable values. ---------- assignee: docs@python components: Documentation messages: 225659 nosy: Alexander.Patrakov, docs@python priority: normal severity: normal status: open title: Possibly incorrect example is given for socket.getaddrinfo() type: behavior versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue22249> _______________________________________

2 2