Mailman 3 July 2016 - docs

[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

[issue27561] Warn against subclassing builtins, and overriding their methods
by Kirk Hansen Aug. 22, 2019

Aug. 22, 2019

New submission from Kirk Hansen: I tried subclassing dict, and overriding its __setitem__ and __getitem__ and got some interesting results. See http://stackoverflow.com/questions/38362420/subclassing-dict-dict-update-re… for an example. I tried sub-classing UserDict.UserDict and experienced some of the same problems. Eventually, I discovered that subclassing MutableMapping was my best bet. After an hour or two of searching and reading I discovered that CPython will not call overridden built-in methods of the same object (https://pypy.readthedocs.io/en/latest/cpython_differences.html#subclasses-o…). This behaviour could (and did) cause some hard to track down bugs in code. I briefly looked at the later versions of python documentation and didn't see a mention of this (sorry if it's there), but python2.7 definitely does not mention this. In fact, python2.7 seems to __encourage__ users to subclass the built-ins (see the note https://docs.python.org/2.7/library/stdtypes.html?highlight=dict#built-in-t…). Subclassing dict to __extend__ functionality is great, but there should be a big bad warning when trying to __override__ built-ins like __setitem__ and __getitem__. ---------- assignee: docs@python components: Documentation messages: 270754 nosy: Kirk Hansen, docs@python priority: normal severity: normal status: open title: Warn against subclassing builtins, and overriding their methods type: enhancement 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/issue27561> _______________________________________

5 11