Mailman 3 June 2019 - docs

[issue37176] super() docs don't say what super() does
by Jeroen Demeyer 29 Aug '19

29 Aug '19

New submission from Jeroen Demeyer <J.Demeyer(a)UGent.be>: The documentation for super() at https://docs.python.org/3.8/library/functions.html#super does not actually say what super() does. It only says "Return a proxy object that delegates method calls to a parent or sibling class of type" and then gives a bunch of use cases and examples. If there is one place where we should define exactly what super() does (as opposed to give guidance on how to use it), the stdlib reference should be it. ---------- assignee: docs@python components: Documentation messages: 344827 nosy: docs@python, jdemeyer priority: normal severity: normal status: open title: super() docs don't say what super() does type: enhancement versions: Python 2.7, Python 3.5, Python 3.6, Python 3.7, Python 3.8, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue37176> _______________________________________

6 26

[issue35946] Ambiguous documentation for assert_called_with()
by Mark Forrer 29 Aug '19

29 Aug '19

New submission from Mark Forrer <mark.forrer(a)lbl.gov>: The documentation for assert_called_with() is ambiguous with regard to the fact that the method only checks the most recent call. This behavior for assert_called_with() is only documented under assert_any_call(), which users are unlikely to read when making quick reference to the documentation. ---------- assignee: docs@python components: Documentation messages: 335112 nosy: chimaerase, docs@python priority: normal severity: normal status: open title: Ambiguous documentation for assert_called_with() versions: Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue35946> _______________________________________

4 9

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

29 Aug '19

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 29 Aug '19

29 Aug '19

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 26 Aug '19

26 Aug '19

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 25 Aug '19

25 Aug '19

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 25 Aug '19

25 Aug '19

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 25 Aug '19

25 Aug '19

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

[issue32118] Docs: add note about sequence comparisons containing non-orderable elements
by Dubslow 24 Aug '19

24 Aug '19

New submission from Dubslow <bunslow(a)gmail.com>: In sequence comparisons, the enforcement of reflexivity of elements means that only non-identical elements are actually compared. The docs then note, with example, that non-reflexive elements thus always "compare" equal inside the sequence. This patch adds a second corollary, that non-orderable singletons (e.g. None) will also not break sequence comparison. Yes, the consequence is logically derivable from the statement "element identity is compared first, and element comparison is performed only for distinct elements", but the first example is given because "For non-reflexive elements, the result is different than for strict element comparison, and may be surprising", which also holds for the example I add here: different from strict element comparison, which may lead to otherwise surprising results (it sure was surprising to me when I expected a list with Nones to fail to compare, hence why I went trawling through the docs). In the manner of the first example, explicit is better than implicit, and (I believe) it will be helpful for readers to have this second consequence demonstrated. ---------- assignee: docs@python components: Documentation messages: 306780 nosy: Dubslow, docs@python priority: normal severity: normal status: open title: Docs: add note about sequence comparisons containing non-orderable elements versions: Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue32118> _______________________________________

6 12

[issue29352] provide the authorative source for s[i:j] negative slice indices (<-len(s)) behavior for standard sequences
by Akira Li 24 Aug '19

24 Aug '19

New submission from Akira Li: I've failed to find where the behavior for negative indices in s[i:j] expression (i, j < -len(s)) for standard sequences (str, list, etc) is formally defined. The observed behavior implemented in PySlice_GetIndicesEx(): If "len(s) + i" or "len(s) + j" is negative, use 0. [1] I don't see it in the docs. if (*start < 0) *start += length; if (*start < 0) *start = (*step < 0) ? -1 : 0; ... if (*stop < 0) *stop += length; if (*stop < 0) *stop = (*step < 0) ? -1 : 0; The tutorial mentions [2]: > out of range slice indexes are handled gracefully when used for > slicing" slice.indices() documentation says [3]: > Missing or out-of-bounds indices are handled in a manner consistent > with regular slices. Neither define it explicitly. The behavior for the upper boundary is defined explicitly [4]: > If *i* or *j* is greater than ``len(s)``, use ``len(s)`` I've added the documentation patch that defines the behavior for the lower boundary too. [1] Objects/sliceobject.c [2] Doc/tutorial/introduction.rst [3] Doc/reference/datamodel.rst [4] Doc/library/stdtypes.rst ---------- assignee: docs@python components: Documentation files: docs-negative-slice-indices.patch keywords: patch messages: 286098 nosy: akira, docs@python priority: normal severity: normal status: open title: provide the authorative source for s[i:j] negative slice indices (<-len(s)) behavior for standard sequences versions: Python 3.5, Python 3.6, Python 3.7 Added file: http://bugs.python.org/file46393/docs-negative-slice-indices.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue29352> _______________________________________

4 6