Mailman 3 April 2016 - docs

[issue23139] syntax diagram after EBNF description?
by Friedrich Spee von Langenfeld Jan. 11, 2020

Jan. 11, 2020

New submission from Friedrich Spee von Langenfeld: In our full grammar specification (10th chapter of the language reference, https://docs.python.org/3/reference/grammar.html), the grammar of Python is comprehensively notated. What would you think of adding a picture with an equivalent syntax diagram (e. g. produced with the help of http://www.bottlecaps.de/rr/ui) to open a new way of understanding for readers? ---------- assignee: docs@python components: Documentation messages: 233236 nosy: Friedrich.Spee.von.Langenfeld, docs@python priority: normal severity: normal status: open title: syntax diagram after EBNF description? _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue23139> _______________________________________

2 1

[issue15718] Possible OverflowError in __len__ method undocumented (when called via len() function)
by Rostyslav Dzinko Jan. 10, 2020

Jan. 10, 2020

New submission from Rostyslav Dzinko: I've encountered that OverflowError which can happen in __len__ method is still undocumented, though one issue on this problem: http://bugs.python.org/issue12159 ended up with "need to be documented" comment. Link to documentation: http://docs.python.org/reference/datamodel.html#object.__len__ I think it must be clarified that __len__ return value is constrained to upper boundary (Py_ssize_t c type) when you plan to call it via len() built-in function. ---------- assignee: docs@python components: Documentation messages: 168439 nosy: Rostyslav.Dzinko, docs@python priority: normal severity: normal status: open title: Possible OverflowError in __len__ method undocumented (when called via len() function) versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15718> _______________________________________

7 18

[issue21995] Idle: pseudofiles have no buffer attribute.
by Terry J. Reedy Jan. 7, 2020

Jan. 7, 2020

New submission from Terry J. Reedy: sys.stdin on 3.4.1 is also 'missing' (among public names) 'line_buffering' (True) and 'mode' ('r'). It seems that these could be trivially added, so the focus of this issue is 'buffer'. The associated .detach method is a no-op, (It is also a bit dangerous for interactive operation.) 3.4.1 Console interpreter: >>> import sys; b = sys.stdin.buffer.readline() a line >>> b b'a line\r\n' 3.4.1 Idle: >>> import sys; b = sys.stdin.buffer.readline() Traceback (most recent call last): File "<pyshell#2>", line 1, in <module> import sys; b = sys.stdin.buffer.readline() AttributeError: 'PseudoInputFile' object has no attribute 'buffer' https://docs.python.org/3/library/sys.html#sys.stdin presents the idiom. It also warns (too narrowly -- 'if you are writing a library ...') that it might not. As far as I could find, the Idle doc does not mention the standard streams, let alone Idle specific limitations. I intentionally wrote the title as a statement of a problematical situation, rather than as a proposed solution, as there are two: change code and change doc. Code: add .buffer as a bytes-oriented Pseudofile. Doc: at least mention that standard streams are replaced by objects that ship text between processes, and use gui for input and display, and the consiquences of this. ---------- assignee: docs@python components: Documentation, IDLE messages: 223292 nosy: docs@python, terry.reedy priority: normal severity: normal stage: test needed status: open title: Idle: pseudofiles have no buffer attribute. type: enhancement versions: Python 2.7, Python 3.4, Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue21995> _______________________________________

3 6

[issue19038] Fix sort order in Misc/ACKS.
by Tae-Wong SEO Dec. 12, 2019

Dec. 12, 2019

New submission from Tae-Wong SEO: This patch fixes sort order in file Misc/ACKS. ---------- assignee: docs@python components: Documentation files: ACKS messages: 197945 nosy: docs@python, taewong.seo priority: normal severity: normal status: open title: Fix sort order in Misc/ACKS. type: enhancement Added file: http://bugs.python.org/file31803/ACKS _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue19038> _______________________________________

8 18

[issue18697] Unify arguments names in Unicode object C API documentation
by Serhiy Storchaka Dec. 9, 2019

Dec. 9, 2019

New submission from Serhiy Storchaka: In declarations of Unicode object C API functions in Doc/c-api/unicode.rst the first Unicode object argument has different names: "unicode", "str", "u", "s". It will be good to unify these names. Of course there is no need to change reasonable argument names for such functions as PyUnicode_Concat() or PyUnicode_CopyCharacters(). ---------- assignee: docs@python components: Documentation, Unicode keywords: easy messages: 194755 nosy: docs@python, ezio.melotti, haypo, serhiy.storchaka priority: normal severity: normal stage: needs patch status: open title: Unify arguments names in Unicode object C API documentation type: enhancement versions: Python 2.7, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18697> _______________________________________

8 17

[issue21063] Touch up one-line descriptions of modules for module index
by Brett Cannon Nov. 26, 2019

Nov. 26, 2019

New submission from Brett Cannon: E.g. linecache says "This module provides random access to individual lines from text files." That's a big awkward and could just drop "This module" to read more easily. ---------- assignee: docs@python components: Documentation keywords: easy messages: 214834 nosy: brett.cannon, docs@python priority: low severity: normal stage: needs patch status: open title: Touch up one-line descriptions of modules for module index versions: Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue21063> _______________________________________

4 12

[issue25866] Reference 3. Data Model: miscellaneous minor cleanups on the word "sequence".
by Andrew Barnert Nov. 17, 2019

Nov. 17, 2019

New submission from Andrew Barnert: None of the below are very serious or likely to mislead anyone using or implementing Python, but... --- 3.3.2. Customizing attribute access The docs for `__dir__` say: > A sequence must be returned. dir() converts the returned sequence to a list and sorts it. At least in CPython and PyPy, this isn't enforced; any iterable can be returned (and it's then converted to a list and sorted). You can even make `__dir__` a generator function. (I've never seen that in the wild--but I have seen code that returns a `map` iterator.) I think it would be better to say "An iterable must be returned. dir() converts the returned iterable to a list and sorts it." --- 3.3.2.3. __slots__ > This class variable can be assigned a string, iterable, or sequence of strings... While it's true that you can assign any iterable, it's at best misleading to assign an iterator. For example, if you use `__slots__ = iter('abc')`, you will get a class with descriptors named `a`, `b`, and `c`, but with an empty iterator in `__slots__`. There's probably no reason to actually outlaw that, but it might be worth noting in 3.3.2.3.1 along with the other weird possibilities like assigning a mapping. --- 3.3.6. Emulating container types The docs still say that the ABCs are in `collections` rather than `collections.abc`. > ... for mappings, __iter__() should be the same as keys() No; `__iter__()` should be an iterator over the keys; `keys()` _can_ be an iterator, but generally should be a view instead. > The membership test operators (in and not in) are normally implemented as an iteration through a sequence. However, container objects can supply the following special method with a more efficient implementation, which also does not require the object be a sequence. I don't think this should say "through a sequence". They're implemented as iteration through whatever the container is, whether it's a sequence, a set, a linked list, or anything else. The documentation on `__contains__` immediately below clarifies this, but it's probably better to be clear from the start. ---------- assignee: docs@python components: Documentation messages: 256445 nosy: abarnert, docs@python priority: normal severity: normal status: open title: Reference 3. Data Model: miscellaneous minor cleanups on the word "sequence". type: enhancement _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue25866> _______________________________________

7 14

[issue26011] Document necesities for cmp argument of sorted
by Karl Richter Nov. 16, 2019

Nov. 16, 2019

New submission from Karl Richter: The docstring of `sorted` doesn't explain what can be passed to the `cmp` and `key` argument of `sorted`. ---------- assignee: docs@python components: Documentation messages: 257505 nosy: docs@python, krichter priority: normal severity: normal status: open title: Document necesities for cmp argument of sorted type: enhancement versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue26011> _______________________________________

4 3

[issue18601] Example "command-line interface to difflib" has typographical error
by Stephen Paul Chappell Oct. 31, 2019

Oct. 31, 2019

New submission from Stephen Paul Chappell: The example at the bottom is good but has a line with a bad variable it is name. It says: with open(fromlines) as fromf, open(tofile) as tof: fromlines, tolines = list(fromf), list(tof) In the first line, fromlines does no even exist yet. should say: with open(fromlines) as fromf, open(tofile) as tof: from, tolines = list(fromf), list(tof) ---------- assignee: docs@python components: Demos and Tools, Documentation messages: 193948 nosy: Zero, docs@python priority: normal severity: normal status: open title: Example "command-line interface to difflib" has typographical error versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18601> _______________________________________

3 3

[issue25299] TypeError: __init__() takes at least 4 arguments (4 given)
by A. Skrobov Oct. 28, 2019

Oct. 28, 2019

New submission from A. Skrobov: Python 2.7.3 (default, Dec 18 2014, 19:10:20) [GCC 4.6.3] on linux2 Type "help", "copyright", "credits" or "license" for more information. >>> from argparse import ArgumentParser >>> parser = ArgumentParser() >>> parser.add_argument("--foo", help="foo", action='store_const') Traceback (most recent call last): File "<stdin>", line 1, in <module> File "/usr/lib/python2.7/argparse.py", line 1281, in add_argument action = action_class(**kwargs) TypeError: __init__() takes at least 4 arguments (4 given) >>> First, the exception message is entirely unhelpful (you wanted at least 4, you got 4, what's your problem?) Second, adding "const=None" to the invocation makes it succeed; but, according to https://docs.python.org/2/library/argparse.html#const this argument defaults to "None", so it shouldn't be necessary to specify it explicitly. Thus, either the documentation or the implementation is wrong. ---------- assignee: docs@python components: Documentation, Extension Modules messages: 252106 nosy: A. Skrobov, docs@python priority: normal severity: normal status: open title: TypeError: __init__() takes at least 4 arguments (4 given) type: behavior versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue25299> _______________________________________

6 17