Mailman 3 August 2013 - docs

[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

[issue16574] clarify policy on updates to final peps
by Chris Jerdonek 21 Apr '15

21 Apr '15

New submission from Chris Jerdonek: This issue is to clarify the policy in PEP 1 regarding non-substantive changes to PEPs in the Final state (minor clarifications, rephrasings, etc). Currently, PEP 1 says, "In general, Standards track PEPs are no longer modified after they have reached the Final state." (from http://www.python.org/dev/peps/pep-0001/#pep-maintenance ) However, others have pointed out that minor clarifications and rephrasings are in fact allowed: http://bugs.python.org/issue15990#msg176575 The updated wording should also state the policy or process regarding such changes (who is allowed to make them and whether and from whom approval is needed to make such changes, etc). ---------- assignee: docs@python components: Documentation messages: 176598 nosy: barry, chris.jerdonek, docs@python, eric.araujo, ezio.melotti, goodger, ncoghlan priority: normal severity: normal status: open title: clarify policy on updates to final peps type: enhancement _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue16574> _______________________________________

11 21

[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

[issue13386] Document documentation conventions for optional args
by Ezio Melotti 19 Apr '15

19 Apr '15

New submission from Ezio Melotti <ezio.melotti(a)gmail.com>: AFAIU the conventions for optional argument in the doc are as follow: If a function has optional arguments and it accepts keyword arguments, the "func(arg=default)" notation should be used, for example: str.splitlines(keepends=False) If a function has optional arguments but it doesn't accept keyword arguments, the "func([arg1])" notation is used instead. This should apply only to some C functions, for example: str.strip([chars]) The notation "func([arg=default])" should never be used, and "func([arg])" should be used only when keyword args are not accepted. These rules apply to both Python 2 and Python 3. A thing that is still not clear is what to do in case the default value is a placeholder (like object(), None, -1) and the actual value is then computed in the function. ---------- assignee: docs@python components: Documentation messages: 147469 nosy: docs@python, eli.bendersky, eric.araujo, ezio.melotti, georg.brandl priority: normal severity: normal stage: needs patch status: open title: Document documentation conventions for optional args versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13386> _______________________________________

10 29

[issue15566] tarfile.TarInfo.frombuf documentation is out of date
by Sebastian Ramacher 18 Apr '15

18 Apr '15

New submission from Sebastian Ramacher: tarfile.TarInfo.frombuf has gained two more parameters: encoding and errors. The documentation of frombuf claims that the only parameter is buf, which is not true anymore. ---------- assignee: docs@python components: Documentation messages: 167553 nosy: docs@python, sebastinas priority: normal severity: normal status: open title: tarfile.TarInfo.frombuf documentation is out of date versions: Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15566> _______________________________________

6 5

[issue12652] Move documentation of test.support into the devguide
by Eli Bendersky 14 Apr '15

14 Apr '15

New submission from Eli Bendersky <eliben(a)gmail.com>: First step in transition: Attaching a patch to devguide's runtests.rst to incorporate existing test.support documentation from 3.3 head, with some small markup changes suitable for the devguide. ---------- components: Devguide files: devguide_test_support.1.patch keywords: patch messages: 141337 nosy: brett.cannon, docs@python, eli.bendersky, ncoghlan priority: low severity: normal stage: patch review status: open title: Move documentation of test.support into the devguide type: behavior Added file: http://bugs.python.org/file22790/devguide_test_support.1.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12652> _______________________________________

10 12

[issue17380] initproc return value is unclear
by Zbyszek Jędrzejewski-Szmek 12 Apr '15

12 Apr '15

New submission from Zbyszek Jędrzejewski-Szmek: initproc is declared to return an int, but what returned values mean is not documented. Noddy_init in http://docs.python.org/3/extending/newtypes.html?highlight=initproc#adding-… can be seen to return 0 on success and -1 on error, but that's about it. Also, when I wrote a function which return 1 on error, on every second invocation the exception would be ignored: static int Reader_init(Reader *self, PyObject *args, PyObject *keywds) { ... if (flags && path) { PyErr_SetString(PyExc_ValueError, "cannot use both flags and path"); return 1; } ... } >>> obj(123, '/tmp') >>> obj(123, '/tmp') ... ValueError >>> obj(123, '/tmp') >>> obj(123, '/tmp') ... ValueError I'm not sure how to interpret this since I couldn't find the documentation for the expected value. ---------- assignee: docs@python components: Documentation, Extension Modules messages: 183689 nosy: docs@python, zbysz priority: normal severity: normal status: open title: initproc return value is unclear type: behavior versions: Python 2.7, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue17380> _______________________________________

6 9