Mailman 3 September 2010 - docs

[issue9331] sys.setprofile is not described as CPython implementation detail
by Alexander Belopolsky March 29, 2011

March 29, 2011

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 March 26, 2011

March 26, 2011

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 March 15, 2011

March 15, 2011

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 March 4, 2011

March 4, 2011

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 Feb. 7, 2011

Feb. 7, 2011

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 Jan. 22, 2011

Jan. 22, 2011

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 Jan. 8, 2011

Jan. 8, 2011

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

[issue9370] Add reader redirect from test package docs to unittest module
by Nick Coghlan Jan. 1, 2011

Jan. 1, 2011

New submission from Nick Coghlan <ncoghlan(a)gmail.com>: Brett updated the docs for the test package to (correctly) point out that it is our internal testing package and isn't subject to the same stringent backwards compatibility rules as the rest of the standard library. A "see also" link pointing readers that have landed there over to the unittest module for their testing infrastructure needs would be a friendly thing to include. ---------- assignee: docs@python components: Documentation keywords: easy messages: 111450 nosy: docs@python, ncoghlan priority: normal severity: normal stage: needs patch status: open title: Add reader redirect from test package docs to unittest module versions: Python 2.7, Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9370> _______________________________________

3 3

[issue9891] Minor doc typo at datamodel.rst: "list" -> "alist"
by Rodrigo Bernardo Pimentel Dec. 26, 2010

Dec. 26, 2010

New submission from Rodrigo Bernardo Pimentel <rbp(a)isnomore.net>: The "Built-in methods" item of the "The standard type hierarchy" section of Doc/reference/datamodels.rst uses a list instance called "alist" as an example, and it says "__self__ is set to the object denoted by *list*." It should read "the object denoted by *alist*" This affects all releases, so I've marked them all. But I suppose we don't care about 2.5 anymore. All the others are listed on docs.python.org (or are "trunk"), and I think should be fixed. It's a trivial fix, and a single patch works 2.x and another for 3.x. ---------- assignee: docs@python components: Documentation files: alist_doc-2.x.patch keywords: patch messages: 116757 nosy: docs@python, rbp priority: normal severity: normal status: open title: Minor doc typo at datamodel.rst: "list" -> "alist" versions: Python 2.5, Python 2.6, Python 2.7, Python 3.1, Python 3.2, Python 3.3 Added file: http://bugs.python.org/file18914/alist_doc-2.x.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9891> _______________________________________

2 3

[issue8648] The UTF-7 codec functions are undocumented
by Daniel Stutzbach Dec. 26, 2010

Dec. 26, 2010

New submission from Daniel Stutzbach <daniel(a)stutzbachenterprises.com>: The UTF-7 codec functions are undocumented: PyUnicode_DecodeUTF7Stateful PyUnicode_DecodeUTF7 PyUnicode_EncodeUTF7 ---------- assignee: docs@python components: Documentation messages: 105207 nosy: docs@python, stutzbach priority: normal severity: normal stage: needs patch status: open title: The UTF-7 codec functions are undocumented versions: Python 2.6, Python 3.1 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue8648> _______________________________________

4 4