Mailman 3 April 2016 - docs

[issue12077] Harmonizing descriptor protocol documentation
by Davide Rizzo Aug. 29, 2019

Aug. 29, 2019

New submission from Davide Rizzo <sorcio(a)gmail.com>: There are three sources of information for the descriptor protocol: - Data model reference (Doc/reference/datamodel.rst) - Descriptor HowTo guide (Doc/howto/descriptor.rst) - PEP 252 A developer who already knows descriptor tipically reads the first one: object.__get__(self, instance, owner) "... owner is always the owner class ..." Reading a bit further there are the ways a descriptor can be called, and the "direct call" is x.__get__(a). That is, without the third argument (owner) specified. The how-to definition is slightly different: descr.__get__(self, obj, type=None) --> value Here the arguments have different names ("type" shadowing the type bultin) and it seems to be implied that the third argument is optional. The ClassMethod example at the end of the document seems to confirm this: def __get__(self, obj, klass=None): (though another example doesn't). And the method contains an explicit check on klass being None. Also it could be confusing that through the examples in the same document many different names are used for the same argument (type, objtype, klass), and all different than the name used in the reference. Lastly the PEP is more explicit: __get__(): a function callable with one or two arguments. [...] When X is None, the optional second argument, T, should be meta-object. [...] When both X and T are specified ... One more quirk: the reference explains the distinction between data and non-data descriptors, though says nothing about __set__ raising AttributeError for read-only data descriptors. My proposal: - use the same names for __get__ arguments throughout the documentation (both the reference and the tutorial), e.g. __get__(self, instance, owner) - decide whether the third argument should be optional, or state the common usage in the reference, and fix accordingly the examples in the howto - explain data, non-data and read-only descriptors in the __set__ reference, or more simply, how the defintion of __set__ affects these things. ---------- assignee: docs@python components: Documentation messages: 135974 nosy: davide.rizzo, docs@python priority: normal severity: normal status: open title: Harmonizing descriptor protocol documentation versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12077> _______________________________________

9 17

[issue23674] super() documentation isn't very clear
by Tapani Kiiskinen Aug. 29, 2019

Aug. 29, 2019

New submission from Tapani Kiiskinen: https://docs.python.org/3/library/functions.html#super There's no mention in the document which __mro__ is used in the case of a super(Type, obj) call. There's this mention 'The __mro__ attribute of the *type* lists the method resolution search order used by both getattr() and super().' but my understanding is that this only applies in the case of a super(type) call plus it doesn't state that it only applies in that case. (I'm fairly certain I'm not wrong; if only the __mro__ of the type was used then cooperative multiple inheritance (which is referenced three paragraphs down) could not work because the __mro__ of the type never has sibling types.) Isn't this misleading due to a super(Type, obj) call (or just super() inside a class in 3k) being the more normal way to use the function? Even now I can't find a single resource to confirm which exact mro is used in the case of a super(Type, obj) call, I've only been able to deduce that it probably uses the type(obj).__mro__ then finds the Type and then tries the entries after Type. Finally 'If the second argument is omitted, the super object returned is unbound. If the second argument is an object, isinstance(obj, type) must be true. If the second argument is a type, issubclass(type2, type) must be true (this is useful for classmethods).' I'm interpreting this is essentially saying that if the second argument is given that the returned object will be bound, given an object the super call would return a bound instance method and given a type a bound class method? I feel like stating this explicitly would be more clear than implicitly. ---------- assignee: docs@python components: Documentation messages: 238157 nosy: Tapani Kiiskinen, docs@python priority: normal severity: normal status: open title: super() documentation isn't very clear versions: Python 2.7, Python 3.2, Python 3.3, Python 3.4, Python 3.5, Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue23674> _______________________________________

7 19

[issue25435] Wrong function calls and referring to not removed concepts in descriptor HowTo (documentation)
by David Becher Aug. 29, 2019

Aug. 29, 2019

New submission from David Becher: Since Python 3 removed unbound methods, I found some references using the old terminology in this HowTo about descriptors (https://docs.python.org/3/howto/descriptor.html). Also, since unbound methods have been removed, the function call types.MethodType now only takes two arguments, namely the function to bind and the object to bind to. In the current documentation, however, the old function call with three arguments is still being used. I made a pull request on github, then I realized that it is just a mirror repo. Attached you will see a patch file with some of the obvious changes that could me made to the document ---------- assignee: docs@python components: Documentation files: 21.diff.txt messages: 253159 nosy: David Becher, docs@python priority: normal severity: normal status: open title: Wrong function calls and referring to not removed concepts in descriptor HowTo (documentation) versions: Python 3.6 Added file: http://bugs.python.org/file40812/21.diff.txt _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue25435> _______________________________________

8 15

[issue25777] Misleading descriptions in docs about invoking descriptors.
by Juchen Zeng Aug. 29, 2019

Aug. 29, 2019

New submission from Juchen Zeng: [Doc Link](https://docs.python.org/2/howto/descriptor.html#invoking-descriptors) In descriptions about how to invoke descriptors with super(), it says: The call super(B, obj).m() searches obj.__class__.__mro__ for the base class A immediately following B and then returns A.__dict__['m'].__get__(obj, B). If not a descriptor, m is returned unchanged. If not in the dictionary, m reverts to a search using object.__getattribute__(). But the call ` super(B, obj).m()` will not return `A.__dict__['m'].__get__(obj, B)`, it will trigger the `__call__` method of ` A.__dict__['m'].__get__(obj, B)` if it has that attr, and return what this `__call__` method returns. It could be anything. It's actually `super(B, obj).m` returns `A.__dict__['m'].__get__(obj, B)` if m is a descriptor. In short, the original description in the doc can be abbreviated to: `The call super(B, obj).m() [did something] and returns A.__dict__['m'].__get__(obj, B).` Which is obviously misleading. As the method/function call isn't the core part in this sentence. I suggest the doc to be fixed like this: The action super(B, obj).m searches obj.__class__.__mro__ for the base class A immediately following B and then returns A.__dict__['m'].__get__(obj, B). ---------- assignee: docs@python components: Documentation messages: 255712 nosy: Juchen Zeng, docs@python, martin.panter priority: normal severity: normal status: open title: Misleading descriptions in docs about invoking descriptors. versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue25777> _______________________________________

4 8

[issue15542] Documentation incorrectly suggests __init__ called after direct __new__ call
by Aaron Staley Aug. 26, 2019

Aug. 26, 2019

New submission from Aaron Staley: The documentation for __new__ at http://docs.python.org/reference/datamodel.html#object.__new__ is: """ object.__new__(cls[, ...]) Called to create a new instance of class cls. __new__() is a static method (special-cased so you need not declare it as such) that takes the class of which an instance was requested as its first argument. The remaining arguments are those passed to the object constructor expression (the call to the class). The return value of __new__() should be the new object instance (usually an instance of cls). Typical implementations create a new instance of the class by invoking the superclass’s __new__() method using super(currentclass, cls).__new__(cls[, ...]) with appropriate arguments and then modifying the newly-created instance as necessary before returning it. If __new__() returns an instance of cls, then the new instance’s __init__() method will be invoked like __init__(self[, ...]), where self is the new instance and the remaining arguments are the same as were passed to __new__(). If __new__() does not return an instance of cls, then the new instance’s __init__() method will not be invoked. __new__() is intended mainly to allow subclasses of immutable types (like int, str, or tuple) to customize instance creation. It is also commonly overridden in custom metaclasses in order to customize class creation. """ The problem is in this line: "If __new__() returns an instance of cls, then the new instance’s __init__() method will be invoked like __init__(self[, ...]), where self is the new instance and the remaining arguments are the same as were passed to __new__()." This is only true in the context of a constructor. In particular, directly calling cls.__new__(cls) will NOT call __init__. If I define a class: class C(object): def __new__(*args, **kwargs): print 'new', args, kwargs return object.__new__(*args,**kwargs) def __init__(self): print 'init' C() will result in __new__ and __init__ being both executed, but C.__new__(C) will only create the instance of C; it will not call __init__! The original documentation described in http://bugs.python.org/issue1123716 was more correct: "__new__ must return an object... If you return an existing object, the constructor call will still call its __init__ method unless the object is an instance of a different class..." That is __init__ is only being called in the context of an external constructor call. Proposed phrasing: "If __new__() is invoked during object construction (cls()) and it returns an instance of cls, then the new instance’s __init__() method will be invoked like __init__(self[, ...]), where self is the new instance and the remaining arguments are the same as were passed to the object constructor." ---------- assignee: docs@python components: Documentation messages: 167267 nosy: Aaron.Staley, docs@python priority: normal severity: normal status: open title: Documentation incorrectly suggests __init__ called after direct __new__ call versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15542> _______________________________________

6 9

[issue23423] XPath Support in ElementTree doc omission
by Mark Baker Aug. 25, 2019

Aug. 25, 2019

New submission from Mark Baker: The list of XPath supported features in section 20.5.2.2. "Supported XPath syntax" on page https://docs.python.org/3.4/library/xml.etree.elementtree.html does not list the use of a predicate based on an element value (it only list predicates based on an attribute value. However, testing in 3.4 shows that a predicate based on an element value also works. >>> import xml.etree.ElementTree as etree >>> x = '<foo><bar><baz y="bang">bing</baz></bar></foo>' >>> y = etree.XML(x) # Find by attribute value >>> z = y.find('bar/baz[@y="bang"]') >>> print(z) <Element 'baz' at 0x0000000003300368> # Find by element value >>> z = y.find('bar/[baz="bing"]') >>> print(z) <Element 'bar' at 0x000000000334AD18> # Find fails with incorrect element value >>> z = y.find('bar/[baz="bong"]') >>> z >>> print(z) None Below the line that says: [tag] Selects all elements that have a child named tag. Only immediate children are supported. It should say something like: [tag="value"] Selects all elements that have a child named tag with the given value. Only immediate children are supported. ---------- assignee: docs@python components: Documentation messages: 235627 nosy: docs@python, mbakeranalecta priority: normal severity: normal status: open title: XPath Support in ElementTree doc omission type: enhancement versions: Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue23423> _______________________________________

3 2

[issue23061] Update pep8 to specify explicitly 'module level' imports at top of file
by Ian Lee Aug. 25, 2019

Aug. 25, 2019

New submission from Ian Lee: Minor update pep8 to specify explicitly that "Imports at top of file" refers specifically to module level imports, per input from Nick Coghlan @ https://github.com/jcrocholl/pep8/pull/304#issuecomment-66939162 ---------- assignee: docs@python components: Documentation files: pep-0008.patch keywords: patch messages: 232708 nosy: IanLee1521, docs@python, ncoghlan priority: normal severity: normal status: open title: Update pep8 to specify explicitly 'module level' imports at top of file type: enhancement Added file: http://bugs.python.org/file37459/pep-0008.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue23061> _______________________________________

6 10

[issue14112] tutorial intro talks of "shallow copy" concept without explanation
by Tshepang Lekhonkhobe Aug. 24, 2019

Aug. 24, 2019

New submission from Tshepang Lekhonkhobe <tshepang(a)gmail.com>: Relevant line: http://hg.python.org/cpython/file/e2eccc906354/Doc/tutorial/introduction.rs… When the concept is introduced, it appears like there's an assumption that the reader would know what it means. I'm curious if it's that common a term that it should be taken for granted, or if it deserves a definition. ---------- assignee: docs@python components: Documentation messages: 154151 nosy: docs@python, tshepang priority: normal severity: normal status: open title: tutorial intro talks of "shallow copy" concept without explanation versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14112> _______________________________________

10 22

[issue22001] containers "same" does not always mean "__eq__".
by Jim Jewett Aug. 23, 2019

Aug. 23, 2019

New submission from Jim Jewett: https://docs.python.org/3.5/reference/expressions.html#not-in Containers are permitted to (and generally do) read "same as" as "is or __eq__), which can be confusing -- particularly in the section defining __eq__. Several suggested changes: """ The values float('NaN') and Decimal('NaN') are special. The are identical to themselves, x is x but are not equal to themselves, x != x. Additionally, comparing any value to a not-a-number value will return False. For example, both 3 < float('NaN') and float('NaN') < 3 will return False. """ --> ("the" -> "they"; add a comma; add a final sentence) --> """ The values float('NaN') and Decimal('NaN') are special. They are identical to themselves, x is x, but are not equal to themselves, x != x. Additionally, comparing any value to a not-a-number value will return False. For example, both 3 < float('NaN') and float('NaN') < 3 will return False. Note, however, that containers will normally implement item equality as "a is b or a==b", so that [f]==[f] and f in [f] may be true even when f!=f. """ also: """ Tuples and lists are compared lexicographically using comparison of corresponding elements. This means that to compare equal, each element must compare equal and the two sequences must be of the same type and have the same length. """ --> (re-order; add the NaN workaround) --> """ Tuples and lists are compared lexicographically using comparison of corresponding elements. This means that to compare equal, two sequences must be of the same type and have the same length, and each pair of corresponding elements must be identical or compare equal. (Sequences can assume that identical elements are equal, despite odd cases like float('NaN').) """ I *think* it is OK to leave that caveat out of the mapping case, because "have the same (key, value) pairs" would now refer to the above. ---------- assignee: docs@python components: Documentation messages: 223362 nosy: Jim.Jewett, docs@python priority: normal severity: normal status: open title: containers "same" does not always mean "__eq__". type: enhancement _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue22001> _______________________________________

7 9

[issue12634] Random Remarks in class documentation
by Ashutosh Swain Aug. 23, 2019

Aug. 23, 2019

New submission from Ashutosh Swain <ats.engg(a)gmail.com>: URL: http://docs.python.org/tutorial/classes.html section: 9.4 Random Remarks The first sentense is bit confusing: "Data attributes override method attributes with the same name" Is it possible to change the sentense something like this: "Data attributes set through instance override method attributes with the same name" ---------- assignee: docs@python components: Documentation messages: 141073 nosy: ats.engg, docs@python priority: normal severity: normal status: open title: Random Remarks in class documentation type: feature request versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12634> _______________________________________

9 18