Mailman 3 February 2021 - docs

[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

[issue39774] Missing documentation on how to make package executable as script
by igo95862 12 Apr '21

12 Apr '21

New submission from igo95862 <igo9586(a)gmail.com>: This is package documentation: https://docs.python.org/3/tutorial/modules.html#packages To make package executable (python -m package) you need to create a file __main__.py in the package directory. This is pretty much not documented anyone aside of trying to run a package missing __main__.py This page already contains information on how to make module executable. (https://docs.python.org/3/tutorial/modules.html#executing-modules-as-scripts) ---------- assignee: docs@python components: Documentation messages: 362790 nosy: docs@python, igo95862 priority: normal severity: normal status: open title: Missing documentation on how to make package executable as script type: enhancement versions: Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue39774> _______________________________________

3 3

[issue39125] Type signature of @property not shown in help()
by Nguyễn Gia Phong 11 Apr '21

11 Apr '21

New submission from Nguyễn Gia Phong <vn.mcsinyx(a)gmail.com>: Dear Maintainer, I want to request a feature on the generative documentation of type-hinting. As of December 2019, I believe there is no support for generating such information in help(). For demonstration, I have this tiny piece of code class Foo: @property def bar(self) -> int: return 42 @bar.setter def bar(self, value: int) -> None: pass def baz(self, arg: float) -> str: pass whose documentation on CPython 3.7.5 (on Debian testing amd64 if that matters) is generated as class Foo(builtins.object) | Methods defined here: | | baz(self, arg: float) -> str | | ---------------------------------------------------------------------- | Data descriptors defined here: | | __dict__ | dictionary for instance variables (if defined) | | __weakref__ | list of weak references to the object (if defined) | | bar I expect the documentation for bar to be as informative as bar, i.e. something similar to ``bar: int''. As pointed out by ChrisWarrick on freenode#python, the annotations are already present, yet help() is not making use of them: >>> Foo.bar.fget.__annotations__ {'return': <class 'int'>} >>> Foo.bar.fset.__annotations__ {'value': <class 'int'>, 'return': None} Have a Merry Christmas or other holiday of your choice, Nguyễn Gia Phong ---------- assignee: docs@python components: Documentation messages: 358823 nosy: McSinyx, docs@python priority: normal severity: normal status: open title: Type signature of @property not shown in help() type: enhancement versions: Python 3.5, Python 3.6, Python 3.7, Python 3.8, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue39125> _______________________________________

4 5

[issue38963] multiprocessing processes seem to "bleed" user information (GID/UID/groups)
by Roman Joost 09 Apr '21

09 Apr '21

New submission from Roman Joost <roman(a)bromeco.de>: When running a process which changes UID/GID, some of the following processes will run as the user I change to per process. In order to reproduce (see the attached reproducer): 1. Change the 'USERNAME' to an unprivileged user on your system. 2. Run the reproducer as a user with elevated privileges (e.g. root or some secondary user you have on your system). Mind you, I don't think the user you run as needs elevated privileges, but that's the user I ran as when I observed this behaviour. 3. The reproducer iterates over a list (It stems from a test function which was checking permissions on log files). Observe the print out, which prints the process' GID, UID and secondary groups before we're changing to the users GID, UID and secondary groups. 4. You should observe that at some point the process prints the user information of the user we want to change to not the one which initially started the script. Example output when running locally as root: ('B', (0, 0, [0])) ('A', (0, 0, [0])) ('C', (0, 0, [0])) ('E', (0, 0, [0])) ('D', (0, 0, [0])) ('F', (1002, 1002, [10, 135, 1000, 1002])) ('H', (1002, 1002, [10, 135, 1000, 1002])) ('I', (1002, 1002, [10, 135, 1000, 1002])) ('J', (1002, 1002, [10, 135, 1000, 1002])) ('G', (1002, 1002, [10, 135, 1000, 1002])) ('K', (1002, 1002, [10, 135, 1000, 1002])) ('L', (1002, 1002, [10, 135, 1000, 1002])) ('M', (1002, 1002, [10, 135, 1000, 1002])) ('N', (1002, 1002, [10, 135, 1000, 1002])) I would have expected `0` all the way through. However, if I initialise the Pool with `maxtasksperchild=1` the isolation seems as expected. I don't know whether this is a bug or I'm foolish to invoke multiprocessing like this. I've run out of time to investigate this further. It's certainly strange behaviour to me and I thought I better report it, since reproducing seems fairly deterministic. ---------- assignee: docs@python components: Documentation, Library (Lib) files: reproducer.py messages: 357773 nosy: docs@python, romanofski priority: normal severity: normal status: open title: multiprocessing processes seem to "bleed" user information (GID/UID/groups) type: behavior versions: Python 3.6, Python 3.7 Added file: https://bugs.python.org/file48753/reproducer.py _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue38963> _______________________________________

2 1

[issue42999] `pathlib.Path.link_to()` documentation is misleading
by Barney Gale 07 Apr '21

07 Apr '21

New submission from Barney Gale <barney.gale(a)gmail.com>: Compare the documentation of `symlink_to()` and `link_to()`: .. method:: Path.symlink_to(target, target_is_directory=False) Make this path a symbolic link to *target*. .. method:: Path.link_to(target) Create a hard link pointing to a path named *target*. In fact, `link_to()` does something like: Make *target* a hard link to this path. Which is unexpected given the naming and inconsistency with `symlink_to()`, but it's the way the current implementation works, and so the documentation should reflect that. Adding a replacement `hardlink_to()` function is covered here in bpo-39950. ---------- assignee: docs@python components: Documentation messages: 385474 nosy: barneygale, docs@python priority: normal severity: normal status: open title: `pathlib.Path.link_to()` documentation is misleading type: behavior _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue42999> _______________________________________

3 9

[issue43325] Documentation should warn that 'is' is not a safe comparison operator for most values.
by Anthony Flury 06 Apr '21

06 Apr '21

New submission from Anthony Flury <anthony.flury(a)btinternet.com>: A frequent bug for beginners is to assume that 'is' is somehow 'better' then '==' when comparing values, and it is certainly a cause for confusion amongst beginners as to why: [1,2] is [1,2] evaluates to False but 'a' is 'a' evaluates to True and many similar examples. As far as I can see the first mention of the 'is' operator is under Section 5 - More on conditionals : https://docs.python.org/3/tutorial/datastructures.html?highlight=comparison…; and it is mentioned thus : The operators is and is not compare whether two objects are really the same object; this only matters for mutable objects like lists. As we know though this statement is misleading - it suggests that 'is' can be used to compare immutable values (ints, strings, tuples) etc, and while for some values of some immutables (small ints, shortish strings) 'is' can be used as an equivalent of '==' it wont be clear from this 'statement' that 'is' is simply not a safe way to compare values. There needs to be a warning here about 'is' and how it is not an equivalent to '==' in any general sense. ---------- assignee: docs@python components: Documentation messages: 387692 nosy: anthony-flury, docs@python priority: normal severity: normal status: open title: Documentation should warn that 'is' is not a safe comparison operator for most values. type: enhancement _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue43325> _______________________________________

4 8

[issue41283] The parameter name for imghdr.what in the documentation is wrong
by Adam Eltawla 02 Apr '21

02 Apr '21

New submission from Adam Eltawla <bekerpico(a)gmail.com>: I noticed the parameter name for imghdr.what in the documentation is wrong Link: https://docs.python.org/3.8/library/imghdr.html?highlight=imghdr function imghdr.what(filename, h=None) In reality: def what(file, h=None): It is 'file' not 'filename'. ---------- assignee: docs@python components: Documentation messages: 373551 nosy: aeltawela, docs@python priority: normal severity: normal status: open title: The parameter name for imghdr.what in the documentation is wrong type: enhancement versions: Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue41283> _______________________________________

3 4

[issue40932] subprocess docs don't qualify the instruction to use shlex.quote by OS
by Stephen Farris 02 Apr '21

02 Apr '21

New submission from Stephen Farris <stephen.farris(a)jhuapl.edu>: The subprocess docs state: "When using shell=True, the shlex.quote() function can be used to properly escape whitespace and shell metacharacters in strings that are going to be used to construct shell commands." While this is true on Unix, it is not true on Windows. On Windows it is easy to create scenarios where shell injection still exists despite using shlex.quote properly (e.g. subprocess.run(shlex.quote("'&calc '"), shell=True) launches the Windows calculator, which it wouldn't do if shlex.quote was able to prevent shell injection on Windows). While the shlex docs state that shlex is for Unix, the subprocess docs imply that shlex.quote will work on Windows too, possibly leading some developers to erroneously use shlex.quote on Windows to try to prevent shell injection. Recommend: 1) qualifying the above section in the subprocess docs to make it clear that this only works on Unix, and 2) updating the shlex docs with warnings that shlex.quote in particular is not for use on Windows. ---------- assignee: docs@python components: Documentation messages: 371140 nosy: Stephen Farris, docs@python priority: normal severity: normal status: open title: subprocess docs don't qualify the instruction to use shlex.quote by OS versions: Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue40932> _______________________________________

6 8

[issue34398] Docs search does not index glossary
by Jonathan Fine 02 Apr '21

02 Apr '21

New submission from Jonathan Fine <jfine2358(a)gmail.com>: The docs contain a very useful page https://docs.python.org/3.5/glossary.html. However, the search feature does not index the glossary. Thus, the search https://docs.python.org/3.5/search.html?q=iterable does not produce the helpful glossary entry === iterable An object capable of returning its members one at a time. Examples of iterables include all sequence types (such as list, str, and tuple) and some non-sequence types like dict, file objects, and objects of any [...] === #788509 is the only docs issue I could find, whose title contains glossary. It gives insight into the thoughts then about the tutorial. In msg44460 Skip Montaro says (1) that the glossary is "for the tutorial", and (2) he'd like to improve links into the tutorial. I suggest that part of the fix for this issue is on the home page page Glossary in the first grouping "Parts of the documentation." ---------- assignee: docs@python components: Documentation messages: 323503 nosy: docs@python, jfine2358 priority: normal severity: normal status: open title: Docs search does not index glossary type: behavior versions: Python 2.7, Python 3.4, Python 3.5, Python 3.6, Python 3.7, Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue34398> _______________________________________

6 12