Mailman 3 August 2013 - docs

[issue10048] urllib.request documentation confusing
by Antoine Pitrou 26 Apr '19

26 Apr '19

New submission from Antoine Pitrou <pitrou(a)free.fr>: The urllib.request documentation intermingles old 2.x urllib (FancyURLopener, etc.) with urllib2-inherited (*Handler, build_opener, etc.) primitives without making any distinction. This makes it rather confusing for the reader to figure out which ones to use. Ideally, the use of the old primitives should also be discouraged. ---------- assignee: docs@python components: Documentation messages: 118179 nosy: docs@python, orsenthil, pitrou priority: normal severity: normal stage: needs patch status: open title: urllib.request documentation confusing versions: Python 3.1, Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10048> _______________________________________

4 5

[issue16663] Poor documentation for METH_KEYWORDS
by r3m0t 26 Apr '19

26 Apr '19

New submission from r3m0t: http://docs.python.org/3.3/c-api/structures.html#METH_KEYWORDS "Methods with these flags must be of type PyCFunctionWithKeywords. The function expects three parameters: self, args, and a dictionary of all the keyword arguments. The flag is typically combined with METH_VARARGS, and the parameters are typically processed using PyArg_ParseTupleAndKeywords()." The documentation doesn't mention the args/dictionary arguments will be NULL when there are no positional/keyword arguments. It might also be worth mentioning the arguments are in effect "borrowed" references. ---------- assignee: docs@python components: Documentation messages: 177341 nosy: docs@python, r3m0t priority: normal severity: normal status: open title: Poor documentation for METH_KEYWORDS 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/issue16663> _______________________________________

2 2

[issue16652] socket.getfqdn docs are not explicit enough about the algorithm.
by R. David Murray 26 Apr '19

26 Apr '19

New submission from R. David Murray: >From the docs it isn't quite clear if getfqnd() does the equivalent of: gethostbyaddr('127.0.0.1') or gethostbyaddr(gethostbyname(gethostname())) It matters which it is, when debugging a host's name configuration and DNS server problems. ---------- assignee: docs@python components: Documentation messages: 177236 nosy: docs@python, r.david.murray priority: normal severity: normal status: open title: socket.getfqdn docs are not explicit enough about the algorithm. type: behavior versions: Python 2.7, Python 3.2, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue16652> _______________________________________

2 2

[issue16242] Pickle and __getattr__
by Joseph Fall 26 Apr '19

26 Apr '19

New submission from Joseph Fall: This report is to re-raise an old issue from 2009: http://bugs.python.org/issue5370 Although that issue is marked as "fixed", I disagree that it was ever "fixed", and spent an evil day tracking it down. Use Case: - take two 3rd party packages: django and django-crispy-forms - django, deep in its inner-workings, uses Pickle - django-cripsy-forms implements the _getattr__ method in one of it's classes - when you put the two together such that django pickles a form, the python interpreter goes into a tailspin in very sinister and hard-to-track-down ways (different behaviour in 2.5, 2.6, 2.7, as noted in issue5370, which includes a simple test case) The "resolution" for issue5370 was to add some documentation to Pickle. But I would argue this is insufficient - the implementer of django-crispy-forms would have no reason to ever look at the Pickle docs, and so is very likely to implement this bug (which s/he did). Perhaps, if this issue cannot be resolved in code, as suggested by gagenellina back in 2009, at least some documentation could be added to __getattr__ (and others) warning that these methods could potentially be called before __init__ (similar to the documentation added to Pickle)? I'd be happy to draft a small bit of documentation for this, although if someone can think of a way to simply resolve this in Pickle so it does not cause the issue in the first place, that seems to me ideal. A test case is included with issue5370 ---------- assignee: docs@python components: Documentation, Library (Lib) messages: 172993 nosy: docs@python, powderflask priority: normal severity: normal status: open title: Pickle and __getattr__ type: behavior versions: Python 2.6, Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue16242> _______________________________________

2 2

[issue12957] mmap.resize changes memory address of mmap'd region
by Michael Schurter 26 Apr '19

26 Apr '19

New submission from Michael Schurter <m(a)schmichael.com>: Since mmap.resize uses MREMAP_MAYMOVE on Linux, it would be nice to warn users that pointers into their memory mapped regions will be invalid after resizes. Linux's manpage offers the following explanation: "If the mapping is relocated, then absolute pointers into the old mapping location become invalid (offsets relative to the starting address of the mapping should be employed)." Since the only way I know of to use pointers into mmaps from pure Python is to use ctypes.<type>.from_buffer(<mmap>), perhaps clarification would be better in the ctypes docs. ---------- assignee: docs@python components: Documentation files: killctypes.py messages: 143845 nosy: docs@python, schmichael priority: normal severity: normal status: open title: mmap.resize changes memory address of mmap'd region type: feature request versions: Python 2.7 Added file: http://bugs.python.org/file23126/killctypes.py _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12957> _______________________________________

4 4

[issue14945] Setup & Usage documentation for selected stdlib modules
by Nick Coghlan 26 Apr '19

26 Apr '19

New submission from Nick Coghlan <ncoghlan(a)gmail.com>: Some stdlib modules have officially documented and supported behaviour when executed via -m. These should be referenced from the Setup & Usage documentation at http://docs.python.org/dev/using/index.html Current candidates: python -m unittest python -m timeit ---------- assignee: docs@python components: Documentation messages: 161832 nosy: docs@python, ncoghlan priority: normal severity: normal stage: needs patch status: open title: Setup & Usage documentation for selected stdlib modules type: enhancement versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14945> _______________________________________

6 11

[issue13282] the table of contents in epub file is too long
by wrobell 11 Apr '19

11 Apr '19

New submission from wrobell <wrobell(a)pld-linux.org>: the table of contents in python documentation epub file is very very long. it takes several long minutes to jump from first page to a part containing language reference toc. imho it would be great if first page of epub file contained pointers to tutorial, lang ref, mod ref without detailed table of contents as it is at docs.python.org. ---------- assignee: docs@python components: Documentation messages: 146548 nosy: docs@python, wrobell priority: normal severity: normal status: open title: the table of contents in epub file is too long versions: Python 2.7, Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13282> _______________________________________

4 4

[issue13850] Summary tables for argparse add_argument options
by Nick Coghlan 24 Mar '19

24 Mar '19

New submission from Nick Coghlan <ncoghlan(a)gmail.com>: With the current argparse docs, it's very hard to get a quick reminder of how to spell the various parameters for add_argument, and just what they do. This issue suggests adding a "Quick Reference" section for add_argument, with the following elements: 1. Summary table with a one line description of each parameter 2. Summary table with a one line description of each alternative for the "action" parameter (including noting which other parameters are potentially relevant, such as 'choices' and 'metavar' for 'store' and 'const' for 'store_const') 3. Summary table with a one line description of each alternative for the "nargs" parameter ---------- assignee: docs@python components: Documentation messages: 151880 nosy: bethard, docs@python, ncoghlan priority: normal severity: normal status: open title: Summary tables for argparse add_argument options versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13850> _______________________________________

12 27

[issue18249] Incorrect and incomplete help docs for close() method
by Dave Angel 22 Mar '19

22 Mar '19

New submission from Dave Angel: Python 3.3.0 (default, Mar 7 2013, 00:24:38) [GCC 4.6.3] on linux q = open('/dev/null') help(q.close) the entire output is: ------------------------------- Help on built-in function close: close(...) (END) ------------------------------- But close() is NOT a built-in, it's a method. (In Python 2.7.* the output is: ------------------------------- Help on built-in function close: close(...) close() -> None or (perhaps) an integer. Close the file. Sets data attribute .closed to True. A closed file cannot be used for further I/O operations. close() may be called more than once without error. Some kinds of file objects (for example, opened by popen()) may return an exit status upon closing. (END) ------------------------------- which is only partially wrong. ---------- assignee: docs@python components: Documentation messages: 191382 nosy: DaveA, docs@python priority: normal severity: normal status: open title: Incorrect and incomplete help docs for close() method _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18249> _______________________________________

3 2

[issue14944] Setup & Usage documentation for pydoc
by Nick Coghlan 20 Mar '19

20 Mar '19

New submission from Nick Coghlan <ncoghlan(a)gmail.com>: pydoc is installed as a script by Python. It should be documented under http://docs.python.org/dev/using/index.html. ---------- assignee: docs@python components: Documentation messages: 161831 nosy: docs@python, ncoghlan priority: normal severity: normal stage: needs patch status: open title: Setup & Usage documentation for pydoc type: enhancement versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14944> _______________________________________

7 13