Mailman 3 January 2011 - docs

[issue10771] descriptor protocol documentation has two different definitions of "owner" class
by Devin Jeanpierre 22 Mar '11

22 Mar '11

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 22 Mar '11

22 Mar '11

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 22 Mar '11

22 Mar '11

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

[issue10988] Descriptor protocol documentation for super bindings is incorrect
by Joshua Arnold 22 Mar '11

22 Mar '11

New submission from Joshua Arnold <josharnold52(a)gmail.com>: In 'Doc/reference/datamodel.rst', the 'Invoking Descriptors' documentation specifies the following behavior for super objects: [snip] Super Binding If ``a`` is an instance of :class:`super`, then the binding ``super(B, obj).m()`` searches ``obj.__class__.__mro__`` for the base class ``A`` immediately preceding ``B`` and then invokes the descriptor with the call: ``A.__dict__['m'].__get__(obj, A)``. [snip] In the above paragrah, the call: A.__dict__['m'].__get__(obj, A) is incorrect. In reality, the descriptor is invoked via: A.__dict__['m'].__get__(obj, obj.__class__) Loosely speaking, the 'owner' argument is set to the subclass associated with the super object, not the superclass. There is a similar error in the 'Descriptor HowTo Guide' under 'Invoking Descriptors' (Strictly speaking, the specification is inaccurate on some other points. It assumes obj is not a class and doesn't state that the entire mro preceding 'B' is searched for 'm'. But those may be considered simplifications for the sake of brevity) I considered reporting this as a bug in the implementation rather than the specification. But I think the implementation's algorithm is the correct one. In particular, it yields the desired behavior for classmethods In any case, the current behavior has been around for a while (it was the fix for issue #535444, dating back to 2.2) Code demonstrating the current behavior: class Desc(object): def __get__(self, instance, owner): return owner class A(object): attr = Desc() class B(A): pass class C(B): pass instance = C() assert super(B,instance).attr == C assert super(B,C).attr == C #According to the specification, the assertions should be: #assert super(B,instance).attr == A #assert super(B,C).attr == A ---------- assignee: docs@python components: Documentation messages: 126895 nosy: Joshua.Arnold, docs@python priority: normal severity: normal status: open title: Descriptor protocol documentation for super bindings is incorrect versions: Python 2.5, Python 2.6, Python 2.7, Python 3.1, Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10988> _______________________________________

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

[issue10999] os.chflags refers to stat constants, but the constants are not documented in the stat module
by R. David Murray 10 Mar '11

10 Mar '11

New submission from R. David Murray <rdmurray(a)bitdance.com>: Title pretty much says it all. The constants are there in the stat module, but they aren't documented. When they are documented the mentions in the os.chflags entry can be turned into cross reference links. ---------- assignee: docs@python messages: 126947 nosy: docs@python, r.david.murray priority: normal severity: normal stage: needs patch status: open title: os.chflags refers to stat constants, but the constants are not documented in the stat module type: behavior _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10999> _______________________________________

3 7

[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

chaos
by Colin Reveley 04 Mar '11

04 Mar '11

here: http://docs.python.org/library/turtle.html#demo-scripts you say that chaotic behavior "proves that you cannot trust a computer's computations" well, the opposite is the case. it proves you can trust computations absolutely. the computations are deterministic. they are correct. that's how the lorenz attractor was discovered. you do need to know what a computer does (and to what) when it computes, and what it doesn't, and how to interpret it. it's misleading to say that computation is untrustworthy. computation is a particular thing, that's all. it might seem pedantic but I think it's a much more interesting and important thing for a student to think about than "untrustworthy". which is just false anyway. as you know I'm sure. I'm not trying to be patronising.

2 2

plistlib doc
by David Cotter 03 Mar '11

03 Mar '11

http://docs.python.org/library/plistlib.html does not list all the available methods of each new class please document: for example: what are the methods of "Dict" ? 'clear', 'copy', 'fromkeys', 'get', 'has_key', 'items', 'iteritems', 'iterkeys', 'itervalues', 'keys', 'pop', 'popitem', 'setdefault', 'update', 'values' these are not documented and what about all the other classes? ------------------------------------------------------------------------------ David M. Cotter mailto:david.cotter@adobe.com Interface Surgeon, After Effects http://www.adobe.com/aftereffects/ Adobe Systems, Inc. (206) 675-7437

2 1

Bug viewing docs.python.org from IPod/IPhone
by Anton Chikin 01 Mar '11

01 Mar '11

Hi, I've noticed that code sample blocks long lines are truncated with the right edge of the screen while browsing documentation on docs.python.org with Safari browser from IPod/IPhone 3G(S). You can find screenshots from http://docs.python.org/tutorial/datastructures.html page in the attachment. With best regards, Anton CHikin.

2 1