Mailman 3 September 2018 - docs

[issue18576] Rename and document test.script_helper as test.support.script_helper
by Nick Coghlan Sept. 9, 2019

Sept. 9, 2019

New submission from Nick Coghlan: tests.script_helper provides various utilities for sensibly testing scripts in a subprocess. It isn't easy for CPython developers to discover, since it is isn't documented and the file is mixed in with actual tests in the main test directory. As discussed in #15494, it should be: 1. Moved from Lib/test/ to Lib/test/support (and imports in tests adjusted accordingly) 2. Documented in Doc/library/test.rst These changes should be made on both the 3.3 and default branches to avoid spurious merge conflicts. ---------- assignee: docs@python components: Documentation, Tests messages: 193819 nosy: docs@python, ncoghlan priority: normal severity: normal status: open title: Rename and document test.script_helper as test.support.script_helper type: enhancement versions: Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18576> _______________________________________

10 28

[issue30122] Added missing things to Windows docs.
by Decorater Sept. 9, 2019

Sept. 9, 2019

New submission from Decorater: I realized the Windows docs lacked some information so I added it. I will try to create an cherry pick for 3.6 and 3.6 as well. Also if desired I could also see if it can be applied to the 2.7 branch as well. ---------- assignee: docs@python components: Documentation messages: 292005 nosy: Decorater, docs@python priority: normal severity: normal status: open title: Added missing things to Windows docs. versions: Python 3.5, Python 3.6, Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue30122> _______________________________________

3 9

[issue27718] help('signal') incomplete (e.g: signal.signal not visible)
by Gabriel Pettier (Tshirtman) Sept. 9, 2019

Sept. 9, 2019

New submission from Gabriel Pettier (Tshirtman): Up to apparently python 3.5, using help('signal') used to show the 'signal.signal' function among others, now it's not in the list, while of course help('signal.signal') does work, it was reported to me to still be the case in 3.6a1. ---------- assignee: docs@python components: Documentation messages: 272240 nosy: Gabriel Pettier (Tshirtman), docs@python priority: normal severity: normal status: open title: help('signal') incomplete (e.g: signal.signal not visible) type: behavior versions: Python 3.5, Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue27718> _______________________________________

4 3

[issue20806] os.times document points to wrong section of non-Linux manual
by Geoffrey Spear Sept. 7, 2019

Sept. 7, 2019

New submission from Geoffrey Spear: The documentation for os.times directs the reader: "See the Unix manual page times(2) or the corresponding Windows Platform API documentation." However, the POSIX manual page in question is times(3P), and on OS X and BSD systems it's times(3). Falling back to "man times" without specifying a manual section also doesn't work, since this finds the bash builtin rather than the library function. ---------- assignee: docs@python components: Documentation messages: 212424 nosy: docs@python, geoffreyspear priority: normal severity: normal status: open title: os.times document points to wrong section of non-Linux manual versions: Python 2.7, Python 3.1, Python 3.2, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue20806> _______________________________________

6 13

[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