Mailman 3 December 2010 - docs

[issue10771] descriptor protocol documentation has two different definitions of "owner" class
by Devin Jeanpierre March 23, 2011

March 23, 2011

New submission from Devin Jeanpierre <jeanpierreda(a)gmail.com>: In trunk/Doc/reference/datamodel.rst , under _Implementing Descriptors_, the documentation states: `The following methods only apply when an instance of the class containing the method (a so-called *descriptor* class) appears in the class dictionary of another new-style class, known as the *owner* class. [...]` Immediately below, in the documentation for __get__, it says, `*owner* is always the owner class [...]`. These two uses of "the owner class" are incompatible, because there is only one class which matches the first use: the class where the descriptor was initially assigned to a class attribute; however, for the second use, any descendant class may be called "the owner class". This is demonstrated in the attached doctest file. It is kind of hard to create a better definition for "owner" as used in `__get__`, though. It can't be said to be the class with the descriptor in its class dict, because it can be present in the class dict of some class in the MRO of the owner. It can't be said to be an attribute, because it has to be in a class dict of an ancestor node. It might be possible to change the definition to call the owner class something like, "the class from which the descriptor was invoked", and if that isn't clear enough, provide examples (TypeDescriptor from the attached doctest file might work as an example); however, this would involve reworking the structure of the paragraph substantially. I personally would prefer this option. The paragraph is already badly structured; for example, it defines two terms in a single and rather complex sentence, and should probably be split up into a list of definitions rather than an explanatory jumble paragraph. In addition, this paragraph is the only place in the documentation where this idea of "the owner class" is used in this way. In the descriptions of the descriptor protocol methods below it, "the owner class" always refers to the class from which the attribute was accessed, or the type from which an instance had the attribute accessed. Alternatively, it could be simpler to replace all references below from "the owner class" to "any class with the owner class in the MRO". ---------- assignee: docs@python components: Documentation files: descriptor.py.doctest messages: 124630 nosy: Devin Jeanpierre, docs@python priority: normal severity: normal status: open title: descriptor protocol documentation has two different definitions of "owner" class versions: Python 2.7 Added file: http://bugs.python.org/file20160/descriptor.py.doctest _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10771> _______________________________________

4 5

[issue10610] Correct the float(), int() and complex() documentation
by Marc-Andre Lemburg March 23, 2011

March 23, 2011

New submission from Marc-Andre Lemburg <mal(a)egenix.com>: The Python3 documentation for these numeric constructors is wrong. Python has supported Unicode numerals specified as code points from the Unicode category "Nd" (decimal digit) since Python 1.6.0 when Unicode was first introduced in Python. http://www.unicode.org/versions/Unicode5.2.0/ch04.pdf (see Section 4.5: General Category) The Python3 documentation adds a reference to the language spec which is not really ideal, since the language spec has different requirements than a number object constructor which has to deal with data input rather than program text: http://docs.python.org/dev/py3k/library/functions.html#float The Python2 documentation does not have such an implication: http://docs.python.org/library/functions.html#float The Python3 documentation needs to be extended to either mention that all Unicode code points from the Unicode category "Nd" (decimal digit) are accepted as digits and used with their corresponding decimal digit value, or include a copy of the referenced language spec section with this definition of ''digit'': digit := ::= "0"..."9" and any Unicode code point with property "Nd" Here's a complete list of the code point ranges that have this property: http://www.unicode.org/Public/5.2.0/ucd/extracted/DerivedNumericType.txt (scroll to the end of the file) It would also be worthwhile to add a note to the Python2 documentation. ---------- assignee: docs@python components: Documentation, Unicode messages: 123136 nosy: docs@python, lemburg priority: normal severity: normal status: open title: Correct the float(), int() and complex() documentation versions: Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10610> _______________________________________

6 14

[issue10787] [random.gammavariate] Add the expression of the distribution in a comprehensive form for random.gammavariate
by David Kremer March 23, 2011

March 23, 2011

New submission from David Kremer <david.kremer.dk(a)gmail.com>: Could you please add the exact form of the distribution, because it's rather confusing in the current form. In this url, the role of k and theta is precised with a formula : [http://tinyurl.com/24jxfrk]* It seems that in [http://docs.python.org/library/random.html#random.gammavariate] , alpha is playing the role of k and beta is playing the role of theta. But it's still not clear, because one can confuse beta with 1/beta and vice et versa, like there is two usual representation for the gamma distribution [http://en.wikipedia.org/wiki/Gamma_distribution] [http://docs.scipy.org/doc/numpy-1.5.x/reference/generated/numpy.random.gamm… Please update the documentation to avoid this ambiguity. I provide an indicative patch which is updating the doc string in random.py ---------- assignee: docs@python components: Documentation files: patch_documentation_random.py.diff keywords: patch messages: 124803 nosy: David.Kremer, docs@python priority: normal severity: normal status: open title: [random.gammavariate] Add the expression of the distribution in a comprehensive form for random.gammavariate versions: Python 2.7 Added file: http://bugs.python.org/file20181/patch_documentation_random.py.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10787> _______________________________________

6 8

[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

[issue10357] ** and "mapping" are poorly defined in python docs
by Fergal Daly Jan. 9, 2011

Jan. 9, 2011

New submission from Fergal Daly <fergald(a)gmail.com>: According to the index, the only place that mentions ** in argument lists is http://docs.python.org/tutorial/controlflow.html#index-1099 and gives no indication of what an object must support to allow **. When you attempt to ** an object the real attribute exception is suppressed and you get a message "argument after ** must be a mapping" "mapping" is quite loosely defined. There are 3 definitions, the glossary entry seems the most complete http://docs.python.org/library/stdtypes.html#index-625 http://docs.python.org/reference/datamodel.html#index-842 http://docs.python.org/glossary.html#term-mapping But even the glossary entry doesn't tell you what you need for **. Only by reading the C source code did I discover that to be usable in **, an object must implement .keys() and .__getitem__(). The docs either should add .keys() to the definition of mapping or the code should use some other term or simply allow the original exception to reach the user. ---------- assignee: docs@python components: Documentation messages: 120739 nosy: Fergal.Daly, docs@python priority: normal severity: normal status: open title: ** and "mapping" are poorly defined in python docs versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10357> _______________________________________

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