Mailman 3 July 2016 - docs

[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

[issue24659] dict() built-in fails on iterators with a "keys" attribute
by Christian Barcenas Aug. 22, 2019

Aug. 22, 2019

New submission from Christian Barcenas: I noticed an inconsistency today between the dict() documentation vs. implementation. The documentation for the dict() built-in [1] states that the function accepts an optional positional argument that is either a mapping object [2] or an iterable object [3]. Consider the following: import collections.abc class MyIterable(object): def __init__(self): self._data = [('one', 1), ('two', 2)] def __iter__(self): return iter(self._data) class MyIterableWithKeysMethod(MyIterable): def keys(self): return "And now for something completely different" class MyIterableWithKeysAttribute(MyIterable): keys = "It's just a flesh wound!" assert issubclass(MyIterable, collections.abc.Iterable) assert issubclass(MyIterableWithKeysMethod, collections.abc.Iterable) assert issubclass(MyIterableWithKeysAttribute, collections.abc.Iterable) assert not issubclass(MyIterable, collections.abc.Mapping) assert not issubclass(MyIterableWithKeysMethod, collections.abc.Mapping) assert not issubclass(MyIterableWithKeysAttribute, collections.abc.Mapping) # OK assert dict(MyIterable()) == {'one': 1, 'two': 2} # Traceback (most recent call last): # File "<stdin>", line 1, in <module> # TypeError: 'MyIterableWithKeysMethod' object is not subscriptable assert dict(MyIterableWithKeysMethod()) == {'one': 1, 'two': 2} # Traceback (most recent call last): # File "<stdin>", line 1, in <module> # TypeError: attribute of type 'str' is not callable assert dict(MyIterableWithKeysAttribute()) == {'one': 1, 'two': 2} The last two assertions should not fail, and it appears that the offending code can be found in Objects/dictobject.c's dict_update_common: else if (arg != NULL) { _Py_IDENTIFIER(keys); if (_PyObject_HasAttrId(arg, &PyId_keys)) result = PyDict_Merge(self, arg, 1); else result = PyDict_MergeFromSeq2(self, arg, 1); } PyDict_Merge is used to merge key-value pairs if the optional parameter is a mapping, and PyDict_MergeFromSeq2 is used if the parameter is an iterable. My immediate thought was to substitute the _PyObject_HasAttrId call with PyMapping_Check which I believe would work in 2.7, but due to #5945 I don't think this fix would work in 3.x. Thoughts? [1] https://docs.python.org/3.6/library/stdtypes.html#dict [2] https://docs.python.org/3.6/glossary.html#term-mapping [3] https://docs.python.org/3.6/glossary.html#term-iterable ---------- assignee: docs@python components: Documentation, Interpreter Core messages: 246890 nosy: christian.barcenas, docs@python priority: normal severity: normal status: open title: dict() built-in fails on iterators with a "keys" attribute type: behavior 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/issue24659> _______________________________________

4 8

[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

[issue23560] Group the docs of similar methods in stdtypes.rst
by Ezio Melotti Aug. 9, 2019

Aug. 9, 2019

New submission from Ezio Melotti: The Doc/library/stdtypes.rst page describes in detail the built-in types and their methods. As suggested in #21777 (see the comments on Rietveld), it might be a good idea to group the documentation of some similar methods, such as {r|l|}just, {r|l|}strip, {r|}partition, {r|}index, and {r|}find. This will remove some duplication, make the page shorter and easier to navigate, and make the methods easier to discover. Adding tables containing the methods for each types has also been proposed. ---------- assignee: docs@python components: Documentation keywords: easy messages: 237036 nosy: docs@python, ezio.melotti priority: normal severity: normal stage: needs patch status: open title: Group the docs of similar methods in stdtypes.rst type: enhancement versions: Python 2.7, Python 3.4, Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue23560> _______________________________________

6 9

[issue11165] Document PyEval_Call* functions
by Nick Coghlan Aug. 8, 2019

Aug. 8, 2019

New submission from Nick Coghlan <ncoghlan(a)gmail.com>: There are currently undocumented PyEval_Call* equivalents to a number of the PyObject_Call* functions. Since there are resources out there on the web that direct people to use the currently undocumented PyEval functions, it would be good to document those properly, and recommend people typically use the PyObject_Call* variants instead (as the latter include all the stack and interpreter state integrity protection code, while the PyEval variants assume that has all already been handled). ---------- assignee: docs@python components: Documentation keywords: easy messages: 128248 nosy: docs@python, ncoghlan priority: normal severity: normal stage: needs patch status: open title: Document PyEval_Call* functions versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11165> _______________________________________

9 12

[issue26695] pickle and _pickle accelerator have different behavior when unpickling an object with falsy __getstate__ return
by Josh Rosenberg July 22, 2019

July 22, 2019

New submission from Josh Rosenberg: According to a note on the pickle docs ( https://docs.python.org/3/library/pickle.html#object.__getstate__ ): "If __getstate__() returns a false value, the __setstate__() method will not be called upon unpickling." The phrasing is a little odd (since according to the __setstate__ docs, there is a behavior for classes without __setstate__ where it just assigns the contents of the pickled state dict to the __dict__ of the object), but to me, this means that any falsy value should prevent any __setstate__-like behavior. But this is not how it works. Both the C accelerator and Python code treat None specially (they don't pickle state at all if it's None), which prevents __setstate__ or the __setstate__-like fallback from being executed. But if it's any other falsy value, the behaviors differ, and diverge from the docs. Specifically, on load of a pickle with a non-None falsy state (say, False itself, or 0, or () or []): Without __setstate__: Pure Python pickle: Does not execute fallback code, behaves as expected (it just stored state it will never use), matching spirit of docs C accelerated _pickle: Fails on anything but the empty dict with an UnpicklingError: state is not a dictionary, violating spirit of docs With __setstate__: Both versions call __setstate__ even though the documentation explicitly says they will not. Seems like if nothing else, the docs should agree with the code, and the C and Python modules should agree on behavior. I would not be at all surprised if outside code depends on being able to pickle falsy state and have its __setstate__ receive the falsy state (if nothing else, when the state is a container or number, being empty or 0 would be reasonable; failing to call __setstate__ in that case would be surprising). So it's probably not a good idea to make the implementation match the docs. My proposal would be that at pickle time, if the class lacks __setstate__, treat any falsy return value as None. This means: 1. pickles are smaller (no storing junk that the default __setstate__-like behavior can't use) 2. pickles are valid (no UnpicklingError from the default __setstate__-like behavior) The docs would also have to change, to indicate that, if defined, __setstate__ will be called even if __getstate__ returned a falsy (but not None) value. Downside is the description of what happens is a little complex, since the behavior for non-None falsy values differs depending on the presence of a real __setstate__. Upside is that any code depending on the current behavior of falsy state being passed to __setstate__ keeps working, CPython and other interpreters will match behavior, and classes without __setstate__ will have smaller pickles. ---------- assignee: docs@python components: Documentation messages: 262908 nosy: docs@python, josh.r priority: normal severity: normal status: open title: pickle and _pickle accelerator have different behavior when unpickling an object with falsy __getstate__ return 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/issue26695> _______________________________________

2 1

[issue25433] whitespace in strip()/lstrip()/rstrip()
by Dimitri Papadopoulos Orfanos July 14, 2019

July 14, 2019

New submission from Dimitri Papadopoulos Orfanos: The documentation of strip() / lstrip() / rstrip() should define "whitespace" more precisely. The Python 3 documentation refers to "ASCII whitespace" for bytes.strip() / bytes.lstrip() / bytes.rstrip() and "whitespace" for str.strip() / str.lstrip() / str.rstrip(). I suggest the following improvements: * add a link from "ASCII whitespace" to string.whitespace or bytes.isspace(), * define plain "whitespace" more precisely (possibly with a link to str.isspace()). The Python 2 documentation refers to plain "whitespace". As far as I know strip() removes ASCII whitespaces only. If so, please: * add a link to string.whitespace or str.isspace(), * improve the string.whitespace documentation and explain that it is locale-dependent (see documentation of str.isspace()). ---------- assignee: docs@python components: Documentation messages: 253152 nosy: Dimitri Papadopoulos Orfanos, docs@python priority: normal severity: normal status: open title: whitespace in strip()/lstrip()/rstrip() type: enhancement versions: Python 2.7, Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue25433> _______________________________________

10 14