Mailman 3 April 2021 - docs

[issue40006] enum: Add documentation for _create_pseudo_member_ and composite members
by Ram Rachum 15 Apr '21

15 Apr '21

New submission from Ram Rachum <ram(a)rachum.com>: Looking at the enum source code, there's a method `_create_pseudo_member_` that's used in a bunch of places. Its docstring says "Create a composite member iff value contains only members", which would have been useful if I had any idea what "composite member" meant. It would be good if the documentation for the enum module would include more information about these two concepts. ---------- assignee: docs@python components: Documentation messages: 364561 nosy: cool-RR, docs@python priority: normal severity: normal status: open title: enum: Add documentation for _create_pseudo_member_ and composite members type: enhancement versions: Python 3.8, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue40006> _______________________________________

3 4

[issue37741] importlib.metadata docs not showing up in the module index
by Brett Cannon 14 Apr '21

14 Apr '21

New submission from Brett Cannon <brett(a)python.org>: If you look at https://docs.python.org/3.9/py-modindex.html#cap-i you will see that importlib.metadata isn't listed (same goes for the 3.8 docs). Or are you leaving it out due to it being provisional? ---------- assignee: docs@python components: Documentation messages: 348872 nosy: barry, brett.cannon, docs@python, jaraco priority: normal severity: normal status: open title: importlib.metadata docs not showing up in the module index versions: Python 3.8, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue37741> _______________________________________

7 19

exception not documented for popping from mutable sequences
by Alan G. Isaac 14 Apr '21

14 Apr '21

Should the documentation for Mutable Sequence Types https://docs.python.org/3/library/stdtypes.html#mutable-sequence-types specify for the `pop` operation that an `IndexError` will be raised if there is no item at that index? (E.g., this could be added to note (2).) Cheers, Alan Isaac

2 1

Docs clarification for subprocess.run
by Davis, Matthew 14 Apr '21

14 Apr '21

Hi, I think the documentation for subprocess.run is wrong, or at least unclear. https://docs.python.org/3/library/subprocess.html > The stdout and stderr arguments may not be supplied at the same time as capture_output. If you wish to capture and combine both streams into one, use stdout=PIPE and stderr=STDOUT instead of capture_output. Here’s what happens when I try that: >>> p = subprocess.run(['ls', '-l'], stdout=PIPE, stderr=STDOUT) Traceback (most recent call last): File "<stdin>", line 1, in <module> NameError: name 'PIPE' is not defined PIPE and STDOUT are not defined. Is the latter supposed to be quoted to become a string? Or should I use sys.stdout? If so, that’s what the docs should say. I have no idea what PIPE is. Is that supposed to be a generic file-like object? It’s not clear. Thanks, Matt

2 1

No downloadable python-3.9.4 docs available
by Somchai Smythe 14 Apr '21

14 Apr '21

No downloadable python-3.9.4 docs available I need at least this: python-3.9.4-docs-html.tar.bz to build python from source, right? I'd also like to have: python-3.9.4-docs-pdf-a4.tar.bz2 since I'm in S.E. Asia on a Linux machine....

2 1

[issue43849] Typo in calendar doc
by John 14 Apr '21

14 Apr '21

New submission from John <john(a)jcoppens.com>: I believe the parenthesis in calendar.firstweekday() should be removed. As it is, it produces 'int' cannot be called. ---------- assignee: docs@python components: Documentation messages: 391098 nosy: JohnCC330, docs@python priority: normal severity: normal status: open title: Typo in calendar doc versions: Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue43849> _______________________________________

1 1

[issue43848] gzip.py: explain optional argument mtime
by Joachim 14 Apr '21

14 Apr '21

New submission from Joachim <j.wuttke(a)fz-juelich.de>: Explain the data type of optional argument mtime: seconds since the epoch. As an alternative to mtime = None, recommend mtime = 0 for generating deterministic streams. ---------- assignee: docs@python components: Documentation messages: 391093 nosy: docs@python, j5w6 priority: normal severity: normal status: open title: gzip.py: explain optional argument mtime versions: Python 3.10 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue43848> _______________________________________

1 1

[issue28197] range.index mismatch with documentation
by Vedran Čačić 14 Apr '21

14 Apr '21

New submission from Vedran Čačić: Look at this: >>> from collections.abc import Sequence >>> help(Sequence.index) index(self, value, start=0, stop=None) S.index(value, [start, [stop]]) -> integer -- return first index of value. Raises ValueError if the value is not present. >>> issubclass(range, Sequence) True >>> help(range.index) index(...) rangeobject.index(value, [start, [stop]]) -> integer -- return index of value. Raise ValueError if the value is not present. So far, so good. But: >>> range(9).index(2, 1, 5) TypeError: index() takes exactly one argument (3 given) Of course it's not essential, but the docs shouldn't lie. And if range _is_ a Sequence, then it should have the complete interface of a Sequence. Including start and end arguments for .index: they are optional from the point of call, not from the point of implementation. :-) ---------- assignee: docs@python components: Documentation, Library (Lib) messages: 276908 nosy: docs@python, veky priority: normal severity: normal status: open title: range.index mismatch with documentation type: behavior versions: Python 3.5, Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue28197> _______________________________________

6 17

[issue20364] Rename & explain sqlite3.Cursor.execute 'parameters' param
by Terry J. Reedy 14 Apr '21

14 Apr '21

New submission from Terry J. Reedy: "execute(sql[, parameters]) Executes an SQL statement. The SQL statement may be parametrized (i. e. placeholders instead of SQL literals). The sqlite3 module supports two kinds of placeholders: question marks (qmark style) and named placeholders (named style)." Experimental facts based on experiments with the code example in the doc, using 3.4.b2: 'parameters' is a single subscriptable collection parameter, sequence or dict, that might be called seq_dict. It is positional only, so whatever name is used is a dummy. Only one placeholder style can be used in a given SQL statement string. If question marks are used, seq_dict must be a sequence. If names are used, seq_dict can be either a sequence or dict or subclass thereof. A UserDict is treated as a sequence and raises KeyError(0). Possible text that encompasses the above, replacing the last sentence: "A statement may use one of two kinds of placeholders: question marks (qmark style) or named placeholders (named style). For qmark style, seq_dict must be a sequence. For named style, it can be either a sequence or dict instance. Len(seq_dict) must match the number of placeholders." After cleaning up the test file, I will verify on 2.7 and upload. ---------- assignee: docs@python components: Documentation, Library (Lib) messages: 208908 nosy: docs@python, terry.reedy priority: normal severity: normal stage: patch review status: open title: Rename & explain sqlite3.Cursor.execute 'parameters' param type: behavior versions: Python 2.7, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue20364> _______________________________________

7 12

[issue43777] Remove description of "pip search" command from tutorial
by Bob Kline 14 Apr '21

14 Apr '21

New submission from Bob Kline <bkline(a)rksystems.com>: The official tutorial instructs users to find third-party packages by using the "pip search" command, which no longer works (and will be deprecated -- and presumably subsequently removed -- according to the error message). See https://docs.python.org/3.10/tutorial/venv.html#managing-packages-with-pip That passage should be removed from the tutorial. ---------- assignee: docs@python components: Documentation messages: 390550 nosy: bkline, docs@python priority: normal severity: normal status: open title: Remove description of "pip search" command from tutorial versions: Python 3.10 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue43777> _______________________________________

4 11