Mailman 3 March 2017 - docs

[issue18697] Unify arguments names in Unicode object C API documentation
by Serhiy Storchaka 09 Dec '19

09 Dec '19

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

[issue28805] Add documentation for METH_FASTCALL
by Stefan Krah 01 Dec '19

01 Dec '19

New submission from Stefan Krah: It looks like METH_FASTCALL gives nice speedups (#28754). Is this an internal interface or can it be documented like METH_KEYWORDS etc.? ---------- assignee: docs@python components: Documentation messages: 281766 nosy: docs@python, haypo, serhiy.storchaka, skrah priority: normal severity: normal stage: needs patch status: open title: Add documentation for METH_FASTCALL type: enhancement versions: Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue28805> _______________________________________

8 16

[issue21063] Touch up one-line descriptions of modules for module index
by Brett Cannon 26 Nov '19

26 Nov '19

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

[issue29275] time module still has Y2K issues note
by Elizabeth Myers 22 Nov '19

22 Nov '19

New submission from Elizabeth Myers: It's 2017. I think it's time to remove the Y2K warning from this: https://docs.python.org/3/library/time.html :P. It's 17 years past the sell-by date for that notice. ---------- assignee: docs@python components: Documentation messages: 285489 nosy: Elizacat, docs@python priority: normal severity: normal status: open title: time module still has Y2K issues note versions: Python 2.7, Python 3.3, Python 3.4, Python 3.5, Python 3.6, Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue29275> _______________________________________

6 10

[issue27724] PEP3119 inconsintent with actual CPython impl
by Daisuke Miyakawa 19 Nov '19

19 Nov '19

New submission from Daisuke Miyakawa: Python 3.5.2 (and Python 2.7.12) uses Py_TPFLAGS_IS_ABSTRACT while PEP 3119 menttions "Py_TPFLAGS_ABSTRACT" for it. At some point had the name of the flag been changed without modifying PEP? ---------- assignee: docs@python components: Documentation messages: 272321 nosy: Daisuke Miyakawa, docs@python priority: normal severity: normal status: open title: PEP3119 inconsintent with actual CPython impl versions: Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue27724> _______________________________________

4 3

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

17 Nov '19

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 16 Nov '19

16 Nov '19

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

[issue27994] In the argparse help(argparse) prints weird comments instead of good docstrings
by py.user 05 Nov '19

05 Nov '19

New submission from py.user: >>> import argparse >>> help(argparse) >>> Output: | add_subparsers(self, **kwargs) | # ================================== | # Optional/Positional adding methods | # ================================== | | convert_arg_line_to_args(self, arg_line) | | error(self, message) | error(message: string) | | Prints a usage message incorporating the message to stderr and | exits. | | If you override this in a subclass, it should not return -- it | should either exit or raise an exception. | | exit(self, status=0, message=None) | # =============== | # Exiting methods | # =============== | | format_help(self) | | format_usage(self) | # ======================= | # Help-formatting methods | # ======================= | | parse_args(self, args=None, namespace=None) | # ===================================== | # Command line argument parsing methods | # ===================================== | | parse_known_args(self, args=None, namespace=None) | | print_help(self, file=None) | | print_usage(self, file=None) | # ===================== | # Help-printing methods | # ===================== | | ---------------------------------------------------------------------- | Methods inherited from _AttributeHolder: ... There are no docstrings for methods, hence some internal comments picked up instead. ---------- assignee: docs@python components: Documentation, Library (Lib) messages: 274738 nosy: docs@python, py.user priority: normal severity: normal status: open title: In the argparse help(argparse) prints weird comments instead of good docstrings type: behavior versions: Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue27994> _______________________________________

3 3

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

31 Oct '19

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 28 Oct '19

28 Oct '19

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