Mailman 3 October 2010 - docs

[issue9724] help('nonlocal') missing
by Cherniavsky Beni 28 Apr '11

28 Apr '11

New submission from Cherniavsky Beni <cben(a)users.sf.net>: >>> help('nonlocal') no Python documentation found for 'nonlocal' As a language keyword, it clearly should have documentation. ---------- assignee: docs@python components: Documentation messages: 115266 nosy: cben, docs@python priority: normal severity: normal status: open title: help('nonlocal') missing versions: Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9724> _______________________________________

5 5

[issue9264] trace.py documentation is incomplete
by Eli Bendersky 27 Apr '11

27 Apr '11

New submission from Eli Bendersky <eliben(a)gmail.com>: The documentation of the standard 'trace' module (Doc/library/trace.rst) is sorely lacking. Arguments are not explained, some key methods are not documented at all, and the CoverageResults class isn't documented. Usage of these appears in the example but leaves the user confused as the only source of documentation for the example is the source code of the module. I'm attaching a patch that fixes this issue, by providing documentation for the missing parts. The patch was generated vs. the latest SVN trunk. ---------- assignee: docs@python components: Documentation files: tracedoc.3.patch keywords: patch messages: 110344 nosy: docs@python, eli.bendersky, tjreedy priority: normal severity: normal status: open title: trace.py documentation is incomplete type: behavior versions: Python 2.6, Python 2.7, Python 3.1, Python 3.2 Added file: http://bugs.python.org/file18009/tracedoc.3.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9264> _______________________________________

6 35

[issue9101] reference json format in file formats chapter
by anatoly techtonik 14 Apr '11

14 Apr '11

New submission from anatoly techtonik <techtonik(a)gmail.com>: Quite often people use .json files for storing configuration. Having a reference to json module from chapter "14. File Formats" would be a good pointer for those looking to .ini alternatives. ---------- assignee: docs@python components: Documentation messages: 108833 nosy: docs@python, techtonik priority: normal severity: normal status: open title: reference json format in file formats chapter versions: Python 2.6, Python 2.7, Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9101> _______________________________________

7 22

[issue9331] sys.setprofile is not described as CPython implementation detail
by Alexander Belopolsky 29 Mar '11

29 Mar '11

New submission from Alexander Belopolsky <belopolsky(a)users.sourceforge.net>: Unlike sys.settrace, sys.setprofile is not described as CPython implementation detail in Doc/library/sys.rst. ---------- assignee: docs@python components: Documentation messages: 111199 nosy: belopolsky, docs@python priority: normal severity: normal stage: needs patch status: open title: sys.setprofile is not described as CPython implementation detail type: feature request _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9331> _______________________________________

2 1

[issue9343] Document that argparse "parents" must be fully declared before children
by Steven Bethard 26 Mar '11

26 Mar '11

New submission from Steven Bethard <steven.bethard(a)gmail.com>: [From http://code.google.com/p/argparse/issues/detail?id=61] It should be documented clearly that only the arguments present on the parent parser at the time ArgumentParser is called will be included in the parser. >>> parent = argparse.ArgumentParser(add_help=False) >>> child = argparse.ArgumentParser(parents=[parent]) >>> parent.add_argument('--foo', action='store_true') >>> child.parse_args(['--foo']) usage: [-h] : error: unrecognized arguments: --foo ---------- assignee: docs@python components: Documentation messages: 111306 nosy: bethard, docs@python priority: normal severity: normal status: open title: Document that argparse "parents" must be fully declared before children versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9343> _______________________________________

3 4

[issue9362] Make exit/quit hint more novice friendly
by Alexander Belopolsky 14 Mar '11

14 Mar '11

New submission from Alexander Belopolsky <belopolsky(a)users.sourceforge.net>: This bikeshed have been repainted several times already, but here is a true story. Cast: Me = myself Novice = a 14-year-old boy Laptop = a MacBook Air Novice: How do i exit [from python prompt]? Me: What's your best guess? Novice: [typing] exit [pressing Enter] Laptop: Use exit() or Ctrl-D (i.e. EOF) to exit Novice: [typing] Ctrl... Me: OMG, you don't know what Ctrl-D means? Look for the Ctrl key. Novice: There is no such key. --- curtains --- I suggest changing Use exit() or Ctrl-D (i.e. EOF) to exit to Type exit() or quit() and press the Enter key to exit or Type exit() or quit() and press Enter to exit or just Use exit() to exit My theory is that someone who knows what EOF is, will probably already know how to exit from common terminal oriented programs and Ctrl-D is not universally bound to EOF. TOOWTDI: two ways to exit is more than enough to teach a novice. ---------- assignee: docs@python components: Documentation keywords: easy messages: 111374 nosy: belopolsky, docs@python priority: normal severity: normal status: open title: Make exit/quit hint more novice friendly type: feature request versions: Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9362> _______________________________________

10 27

[issue9802] Document 'stability' of builtin min() and max()
by Matthew Woodcraft 04 Mar '11

04 Mar '11

New submission from Matthew Woodcraft <matthew(a)woodcraft.me.uk>: In CPython, the builtin max() and min() have the property that if there are items with equal keys, the first item is returned. From a quick look at their source, I think this is true for Jython and IronPython too. I propose making this a documented guarantee. On Python-dev, Raymond Hettinger said: << That seems like a reasonable request. This behavior has been around for a very long time is unlikely to change. Elsewhere, we've made efforts to document sort stability (i.e. sorted(), heapq.nlargest(), heapq.nsmallest, merge(), etc). >> (<http://mail.python.org/pipermail/python-dev/2010-September/103543.html>) I'm attaching a patch with a concrete suggestion for a change to functions.rst, modelled on the documentation of heapq.nlargest(). ---------- assignee: docs@python components: Documentation files: maxmin.patch keywords: patch messages: 115892 nosy: docs@python, mattheww priority: normal severity: normal status: open title: Document 'stability' of builtin min() and max() type: feature request Added file: http://bugs.python.org/file18802/maxmin.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9802> _______________________________________

5 8

[issue8691] Doc: left alignment is not the default for numbers
by Terry J. Reedy 07 Feb '11

07 Feb '11

New submission from Terry J. Reedy <tjreedy(a)udel.edu>: As reported on python-list by Alan G Isaac, Lib Ref 6.1.3.1. Format Specification Mini-Language, for instance http://docs.python.org/dev/py3k/library/string.html#formatstrings wrongly says in the alignment section "'<' Forces the field to be left-aligned within the available space (This is the default.)" This latter, of course, is not true for number fields. "(This is the default.)" could be replaced by "(the string default)." (in any case, the '.' should be outside the () unless one is added after 'space' before '(') and "(the number default)" added to the next line. Or instead the issue of defaults could be addressed in the text below the table. I am assuming that this issue affects 2.6/7. ---------- assignee: docs@python components: Documentation messages: 105536 nosy: docs@python, tjreedy priority: normal severity: normal status: open title: Doc: left alignment is not the default for numbers versions: Python 2.6, Python 2.7, Python 3.1, Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue8691> _______________________________________

4 5

[issue9723] pipes.quote() needs to be documented
by Brandon Craig Rhodes 22 Jan '11

22 Jan '11

New submission from Brandon Craig Rhodes <brandon(a)rhodesmill.org>: The only way to safely build shell command lines from inside of Python — which is necessary when sending commands across SSH, since that behaves like os.system() rather than like subprocess.call() — is to use the wonderful pipes.call() method to turn possibly-dangerous arguments, like filenames that might have spaces, special characters, and embedded "rm -r" calls, into perfectly quoted strings for an "sh"-like shell (say, bash or zsh). This call is already recommended on mailing lists, blog posts, and Stack Overflow — and since it doesn't start with a "_", I think its public use is fair game. But the "pipes" documentation itself doesn't officially mention or support it. I think it should be added to the Standard Library documentation for "pipes". So. Yeah. ---------- assignee: docs@python components: Documentation messages: 115263 nosy: brandon-rhodes, docs@python priority: normal severity: normal status: open title: pipes.quote() needs to be documented type: feature request versions: Python 2.5, 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/issue9723> _______________________________________

4 6

[issue9717] operator module - "in place" operators documentation
by Arnaud Delobelle 08 Jan '11

08 Jan '11

New submission from Arnaud Delobelle <arnodel(a)googlemail.com>: More detailed explanation of how in place operators work, and how they are related to the operator module iadd, isub, ... functions. Submitted following this message on python-list: http://mail.python.org/pipermail/python-list/2010-August/1254243.html ---------- assignee: docs@python components: Documentation files: operator_inplace.diff keywords: patch messages: 115237 nosy: arno, docs@python priority: normal severity: normal status: open title: operator module - "in place" operators documentation versions: Python 3.3 Added file: http://bugs.python.org/file18682/operator_inplace.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9717> _______________________________________

3 6