Mailman 3 January 2015 - docs

[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

[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

[issue19441] itertools.tee improve documentation
by Alan Cristhian Aug. 22, 2019

Aug. 22, 2019

New submission from Alan Cristhian: I had some problems using itertools.tee function. Fortunately I found the following advice on the PEP-323: "Currently, the copied iterators remaintied to the original iterator. If the original advances, then so do all of the copies. Good practice is to overwrite the original So THAT anamolies do result: a, b = t (a)." I believe that such advice should be in the documentation as well: "Currently, the copied iterators remaintied to the original iterator. If the original advances, then so do all of the copies and vice versa. Good practice is to overwrite the original So THAT anamolies do result: a, b = t (a ). " Note that I added "and vice versa". ---------- assignee: docs@python components: Documentation messages: 201693 nosy: Alan.Cristhian, docs@python priority: normal severity: normal status: open title: itertools.tee improve documentation type: enhancement versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue19441> _______________________________________

2 4

[issue14050] Tutorial, list.sort() and items comparability
by Sandro Tosi Aug. 22, 2019

Aug. 22, 2019

New submission from Sandro Tosi <sandro.tosi(a)gmail.com>: I'm providing patches for what reported at http://mail.python.org/pipermail/docs/2012-February/007481.html . I'm not sure on wording or even if we want them in the tutorial section, but I think it would be nice to have it documented nonetheless. ---------- assignee: docs@python components: Documentation files: list_sort-py27.diff keywords: patch messages: 153648 nosy: docs@python, sandro.tosi priority: normal severity: normal stage: patch review status: open title: Tutorial, list.sort() and items comparability versions: Python 2.7, Python 3.2, Python 3.3 Added file: http://bugs.python.org/file24557/list_sort-py27.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14050> _______________________________________

9 20

[issue20727] Improved roundrobin itertools recipe
by David Lindquist Aug. 22, 2019

Aug. 22, 2019

New submission from David Lindquist: The roundrobin example in the Recipes section of the itertools documentation (http://docs.python.org/3/library/itertools.html#itertools-recipes) is overly complex. Here is a more straightforward implementation: def roundrobin(*iterables): "roundrobin('ABC', 'D', 'EF') --> A D E B F C" sentinel = object() it = chain.from_iterable(zip_longest(fillvalue=sentinel, *iterables)) return (i for i in it if i is not sentinel) Not only is it one-third the lines of the existing example, benchmarks show it to be more than twice as fast. See attached patch file. ---------- assignee: docs@python components: Documentation files: roundrobin.patch keywords: patch messages: 211907 nosy: david.lindquist, docs@python priority: normal severity: normal status: open title: Improved roundrobin itertools recipe versions: Python 2.7, Python 3.1, Python 3.2, Python 3.3, Python 3.4, Python 3.5 Added file: http://bugs.python.org/file34180/roundrobin.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue20727> _______________________________________

7 16

[issue19820] docs are missing info about module attributes
by Eric Snow Aug. 21, 2019

Aug. 21, 2019

New submission from Eric Snow: The docs for the inspect module and the types module do not list all the import-related module attributes. I'm guessing they've been out of sync a while. The docstring for for inspect.ismodule() is likewise missing information. ---------- assignee: docs@python components: Documentation messages: 204642 nosy: docs@python, eric.snow priority: low severity: normal stage: needs patch status: open title: docs are missing info about module attributes type: enhancement versions: Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue19820> _______________________________________

5 8

[issue16697] argparse kwarg 'choices' documentation
by wim glenn Aug. 18, 2019

Aug. 18, 2019

New submission from wim glenn: Any object that supports the in operator can be passed as the choices value, so dict objects, set objects, custom containers, etc. are all supported. (from http://docs.python.org/dev/library/argparse.html#choices ) Actual behaviour is contradicted by the docs - it seems the container must additionally be iterable. When using a custom container, argparse b0rks on trying to iterate through choices. Using a metavar prevents this, but it still breaks on cases where the element is not in the container. More details here: http://stackoverflow.com/questions/13833566/python-argparse-choices-from-an… ---------- assignee: docs@python components: Documentation messages: 177599 nosy: docs@python, wim.glenn priority: normal severity: normal status: open title: argparse kwarg 'choices' documentation type: enhancement versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue16697> _______________________________________

3 3