Mailman 3 October 2012 - docs

[issue13275] Recommend xml.etree for XML processing
by Alexey Shamrin 26 Nov '15

26 Nov '15

New submission from Alexey Shamrin <shamrin(a)gmail.com>: There are many libraries in Python stdlib [1] xml.dom xml.dom.minidom xml.dom.pulldom xml.sax xml.etree Tutorial mentions xml.dom and xml.sax. [2] In my experience xml.etree is the best library to quickly load some xml and mess with it. It would be nice to recommend people xml.etree in the tutorial [2] and in the beginning of section 19, "Structured Markup Processing Tools". [1] [1]: http://docs.python.org/library/markup.html [2]: http://docs.python.org/tutorial/stdlib.html#batteries-included ---------- assignee: docs@python components: Documentation messages: 146484 nosy: ash, docs@python priority: normal severity: normal status: open title: Recommend xml.etree for XML processing _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13275> _______________________________________

8 11

[issue12300] Document pydoc.help
by Éric Araujo 03 Nov '15

03 Nov '15

New submission from Éric Araujo <merwok(a)netwok.org>: The only public function in pydoc is help, and it’s not listed in the module docs. The existing doc in library/functions could be moved to library/pydoc. See also #12299. ---------- assignee: docs@python components: Documentation messages: 138002 nosy: docs@python, eric.araujo priority: normal severity: normal status: open title: Document pydoc.help versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12300> _______________________________________

3 4

[issue13195] subprocess: args with shell=True is not documented on Windows
by anatoly techtonik 18 Oct '15

18 Oct '15

New submission from anatoly techtonik <techtonik(a)gmail.com>: For UNIX, it is said that if shell=False then you need to pass `args` as a list (if you want to pass any parameters to executable). Is that true for Windows (and perhaps other platforms) as well? Again, for UNIX it is said that with shell=True, and args is a list - every item except the first one is an argument to the shell itself. Is it the same on Windows? It would be better to just give advice in `shell` parameter description to "pass args as a list with shell=False or else you'll lose params in Unix. If shell=True you need to pass args as a string, because list is needed only if you need to pass arguments to shell itself." ---------- assignee: docs@python components: Documentation, Library (Lib) messages: 145662 nosy: docs@python, techtonik priority: normal severity: normal status: open title: subprocess: args with shell=True is not documented on Windows _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13195> _______________________________________

5 9

[issue8952] Doc/c-api/arg.rst: fix documentation of number formats
by STINNER Victor 14 Oct '15

14 Oct '15

New submission from STINNER Victor <victor.stinner(a)haypocalc.com>: The documentation of PyArg_Parse*() number formats specify that only int / float / complex are accepted, whereas any int / float / complex compatible object is accepted. "compatible" means that it has an __int__() / __float__() / __complex__() method, or nb_int / nb_float of Py_TYPE(obj)->tp_as_number->nb_int is defined (tp_as_number has no nb_complex). I suppose that the following paragraph is also outdated: "It is possible to pass "long" integers (integers whose value exceeds the platform's :const:`LONG_MAX`) however no proper range checking is done --- the most significant bits are silently truncated when the receiving field is too small to receive the value (actually, the semantics are inherited from downcasts in C --- your mileage may vary)." Moreover, "without overflow checking" should be explained (Mark told me that the number is truncated to a power of 2). ---------- assignee: docs@python components: Documentation, Interpreter Core messages: 107379 nosy: docs@python, haypo, mark.dickinson priority: normal severity: normal status: open title: Doc/c-api/arg.rst: fix documentation of number formats versions: Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue8952> _______________________________________

3 6

[issue13124] Add "Running a Build Slave" page to the devguide
by Eric Snow 21 Jul '15

21 Jul '15

New submission from Eric Snow <ericsnowcurrently(a)gmail.com>: Here's a patch to add a page to the devguide on running a build slave. I copied pretty liberally from the wiki (http://wiki.python.org/moin/BuildBot). That page may or may not be up to date (I don't know), so the bulk of this new page may also be out of date... The current devguide buildbots page is oriented toward the use of buildbots in the dev process. In contrast, this new page is all about running one. I figured it is yet another easy way that people can contribute to Python. I didn't stick in the windows-specific buildbot info (http://wiki.python.org/moin/BuildbotOnWindows), but did link to the wiki page. I did include the info, as far as I understood it, from a recent python-dev thread (http://mail.python.org/pipermail/python-dev/2011-October/113935.html). I added a link to the devguide index page, but it may need to be shifted to the right spot (maybe right after "Running & Writing Tests"). I also renamed buildbots.rst to continuous_integration.rst (and updated reference accordingly). I want to be sure attribution is appropriate, regarding the text pulled from the wiki page and from the python-dev thread. Is linking to the thread sufficient? This is a rough stab (especially with the inclusion of the still-ongoing python-dev thread); but hopefully this gets a ball rolling and doesn't take much work to polish. :) ---------- assignee: docs@python components: Devguide, Documentation files: buildslaves.diff keywords: patch messages: 145120 nosy: brett.cannon, docs@python, eric.snow priority: normal severity: normal status: open title: Add "Running a Build Slave" page to the devguide type: feature request versions: Python 3.3 Added file: http://bugs.python.org/file23338/buildslaves.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13124> _______________________________________

8 21

[issue12920] Inspect.getsource fails to get source of local classes
by Popa Claudiu 23 Jun '15

23 Jun '15

New submission from Popa Claudiu <pcmanticore(a)gmail.com>: inspect.getsource called with a class defined in the same file fails with TypeError: <module '__main__' (built-in)> is a built-in class, although the documentation says that: "The argument may be a module, class, method, function, traceback, frame, or code object. The source code is returned as a single string." I think that should be specified in documentation that this function works only for objects living in a module. ---------- assignee: docs@python components: Documentation messages: 143645 nosy: Popa.Claudiu, docs@python priority: normal severity: normal status: open title: Inspect.getsource fails to get source of local classes type: behavior versions: Python 2.7, Python 3.1, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12920> _______________________________________

5 8

[issue13213] generator.throw() behavior
by Petri Lehtinen 20 Jun '15

20 Jun '15

New submission from Petri Lehtinen <petri(a)digip.org>: The documentation of generator.throw() gives this signature: generator.throw(type[, value[, traceback]]) Looking at the code, it accepts the following arguments: g.throw(ExcType) --> raise ExcType() g.throw(ExcType, None) --> raise ExcType() g.throw(ExcType, None, tb) --> raise ExcType().with_traceback(tb) g.throw(ExcType, instace_of_ExcType) --> raise instance_of_ExcType g.throw(ExcType, instace_of_ExcType, tb) --> raise instance_of_ExcType.with_traceback(tb) g.throw(ExcType, other_value) --> raise ExcType(other_value) g.throw(ExcType, other_value, tb) --> raise ExcType(other_value).with_traceback(tb) Up to this point, I think everything is in line with the documentation. But it also accepts the following (now that issue 13188 is fixed): g.throw(exc_instance) --> raise exc_instance (preserving the traceback of exc_instance) g.throw(exc_instance, None) --> raise exc_instance (preserving the traceback of exc_instance) g.throw(exc_instance, None, tb) --> raise exc_instance.with_traceback(tb) It does not accept these, throwing a TypeError: g.throw(exc_instance, some_value_other_than_None) g.throw(exc_instance, some_value_other_than_None, tb) g.throw(exc_instance, tb) The documentation is really unclear on throwing existing exception instances with (exc_instance) or (exc_instance, None), and that calling with (type, value) or (type, value, tb) will create a new exception if not isinstance(value, type). ---------- assignee: docs@python components: Documentation, Interpreter Core messages: 145848 nosy: docs@python, ezio.melotti, ncoghlan, petri.lehtinen, pitrou priority: normal severity: normal status: open title: generator.throw() behavior type: behavior versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13213> _______________________________________

4 3

[issue10170] Relationship between turtle speed setting and actual speed is not documented
by Alexander Belopolsky 17 May '15

17 May '15

New submission from Alexander Belopolsky <belopolsky(a)users.sourceforge.net>: As Terry J. Reedy mentioned in his comment on issue 7061, turtle documentation is lacking information on how speed "codes" 0-10 translate into actual turtle speed. Attached script measures the speed of the two primitive operations that form the basis of turtle functionality at various speed settings. The results below show highly irregular pattern. The columns are: the speed code, time to draw a 200 unit line, time to complete a 360 degrees turn and the ratio of the two times. 0: 0.01 0.01 0.83 1: 1.04 2.05 0.51 2: 0.49 1.06 0.46 3: 0.30 0.72 0.42 4: 0.23 0.54 0.44 5: 0.17 0.44 0.38 6: 0.13 0.39 0.35 7: 0.08 0.32 0.26 8: 0.08 0.28 0.30 9: 0.10 0.27 0.37 10: 0.08 0.23 0.36 >From the source code, it appears that the on-screen speed is controlled by the number of animation steps while each step takes approximately time controlled by the "delay" setting that defaults to 10 milliseconds. The number of steps is determined by somewhat peculiar computations. For a rotation by angle of a degrees at speed setting s, the number of steps is n = 2 + int(a / (3 * s)) and for drawing a line of length d, n = 1 + int(d / (3 * 1.1**s * s)) I am not sure what was the reason for these choices, but I think it would be better if numeric speed code had a more direct relationship to the apparent speed. ---------- assignee: docs@python components: Demos and Tools, Documentation messages: 119334 nosy: belopolsky, docs@python, eric.araujo, georg.brandl, gregorlingl, terry.reedy priority: normal severity: normal status: open title: Relationship between turtle speed setting and actual speed is not documented versions: Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10170> _______________________________________

3 3

[issue15329] clarify which deque methods are thread-safe
by Chris Jerdonek 25 Apr '15

25 Apr '15

New submission from Chris Jerdonek <chris.jerdonek(a)gmail.com>: I think it would help to clarify which collections.deque methods are thread-safe: http://docs.python.org/dev/library/collections.html?highlight=deque#collect… Currently, the documentation says that "Deques support thread-safe, memory efficient appends and pops from either side...," but it isn't obvious if this is meant to apply to all methods, or just the methods named append*() and pop*(). For example, is rotate() thread-safe? The illustration given of d.appendleft(d.pop()) seems like it could be interleaved. ---------- assignee: docs@python components: Documentation keywords: easy messages: 165275 nosy: cjerdonek, docs@python, rhettinger priority: normal severity: normal status: open title: clarify which deque methods are thread-safe versions: Python 2.7, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15329> _______________________________________

6 10

[issue15183] it should be made clear that the statement in the --setup option and the setup kw arg aren't included in the count
by Tshepang Lekhonkhobe 21 Apr '15

21 Apr '15

New submission from Tshepang Lekhonkhobe <tshepang(a)gmail.com>: I looked at 'python -m time -h' and the timeit doc, and it was not clear to me (after a quick read) that the statement(s) inside --setup option and setup keyword argument weren't included in the speed test. I had to check for myself by writing code. ---------- assignee: docs@python components: Documentation messages: 163999 nosy: docs@python, tshepang priority: normal severity: normal status: open title: it should be made clear that the statement in the --setup option and the setup kw arg aren't included in the count versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15183> _______________________________________

4 4