Mailman 3 September 2018 - docs

[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

[issue34792] Tutorial doesn''t discuss / and * function arguments
by Mark Diekhans 18 Nov '19

18 Nov '19

New submission from Mark Diekhans <markd(a)kermodei.com>: https://docs.python.org/3/tutorial/controlflow.html doest not discuss / and * arguments (end of positional, keyword required) ---------- assignee: docs@python components: Documentation messages: 326277 nosy: diekhans, docs@python priority: normal severity: normal status: open title: Tutorial doesn''t discuss / and * function arguments type: enhancement versions: Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue34792> _______________________________________

4 4

[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 15 Nov '19

15 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 04 Nov '19

04 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

[issue30548] typo in documentation for create_autospec
by Erik Byström 30 Oct '19

30 Oct '19

New submission from Erik Byström: "a class" should most probably be replaced by "an instance" in the documentation for create_autospec. "You can use a class as the spec for an instance object by passing instance=True. The returned mock will only be callable if instances of the mock are callable." https://docs.python.org/3/library/unittest.mock.html#unittest.mock.create_a… ---------- assignee: docs@python components: Documentation messages: 294993 nosy: Erik Byström, docs@python priority: normal severity: normal status: open title: typo in documentation for create_autospec type: enhancement versions: Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue30548> _______________________________________

4 4