Mailman 3 December 2011 - docs

[issue13195] subprocess: args with shell=True is not documented on Windows
by anatoly techtonik Oct. 19, 2015

Oct. 19, 2015

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 Oct. 14, 2015

Oct. 14, 2015

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 July 21, 2015

July 21, 2015

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 June 24, 2015

June 24, 2015

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 June 20, 2015

June 20, 2015

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 May 17, 2015

May 17, 2015

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

[issue13386] Document documentation conventions for optional args
by Ezio Melotti April 20, 2015

April 20, 2015

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

[issue12652] Move documentation of test.support into the devguide
by Eli Bendersky April 14, 2015

April 14, 2015

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

[issue12955] urllib2.build_opener().open() is not friendly to "with ... as:"
by Valery Khamenya April 12, 2015

April 12, 2015

New submission from Valery Khamenya <khamenya(a)gmail.com>: The following intuitive construction with urllib2.build_opener().open() as: ... leads to AttributeError: addinfourl instance has no attribute '__exit__' http://docs.python.org/library/urllib2.html says almost nothing about concept of closing. Could it be possible to add a canonical "with ... as:" example for urllib2.build_opener() ? Thanks, Valery ---------- assignee: docs@python components: Documentation, IO, Library (Lib) messages: 143836 nosy: Valery.Khamenya, docs@python priority: normal severity: normal status: open title: urllib2.build_opener().open() is not friendly to "with ... as:" type: resource usage versions: Python 2.6, Python 2.7, Python 3.1, Python 3.2, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12955> _______________________________________

9 17

[issue11468] Improve unittest basic example in the doc
by Ezio Melotti March 24, 2015

March 24, 2015

New submission from Ezio Melotti <ezio.melotti(a)gmail.com>: The current example[0] uses assertTrue(element in self.seq) but it would be better to use assertIn instead. The whole example could be changed to something simpler that uses only the assertTrue/assertEqual/assertRaises methods correctly, e.g.: import unittest class TestStringMethods(unittest.TestCase): def test_upper(self): self.assertEqual('foo'.upper(), 'FOO') def test_isupper(self): self.assertTrue('FOO'.isupper()) self.assertFalse('Foo'.isupper()) def test_split(self): s = 'hello world' self.assertEqual(s.split(), ['hello', 'world']) # check that s.split fails when the separator is not a string with self.assertRaises(TypeError): s.split(2) if __name__ == '__main__': unittest.main() [0]: http://docs.python.org/py3k/library/unittest.html#basic-example ---------- assignee: docs@python components: Documentation keywords: easy messages: 130598 nosy: docs@python, eric.araujo, ezio.melotti, michael.foord, ncoghlan, rhettinger priority: low severity: normal stage: needs patch status: open title: Improve unittest basic example in the doc type: feature request versions: Python 2.7, Python 3.1, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11468> _______________________________________

9 19