Mailman 3 October 2020 - docs

[issue32553] venv says to use python3 which does not exist in 3.6.4
by Paul Watson 17 Mar '21

17 Mar '21

New submission from Paul Watson <paul.hermeneutic(a)gmail.com>: The 3.6.4 documentation on venv specifies using 'python3', but no python3 executable is in the 3.6.4 kit. https://docs.python.org/3/library/venv.html?highlight=venv#module-venv ---------- assignee: docs@python components: Documentation messages: 309943 nosy: Paul Watson, docs@python priority: normal severity: normal status: open title: venv says to use python3 which does not exist in 3.6.4 type: enhancement versions: Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue32553> _______________________________________

6 12

[issue15533] subprocess.Popen(cwd) documentation
by Chris Jerdonek 17 Mar '21

17 Mar '21

New submission from Chris Jerdonek: The sentence describing Popen()'s cwd argument in the subprocess documentation seems reversed to me: http://docs.python.org/dev/library/subprocess.html#subprocess.Popen It says, "If cwd is not None, the child’s current directory will be changed to cwd before it is executed. Note that this directory is not considered when searching the executable, so you can’t specify the program’s path relative to cwd." However, when cwd is not None, it seems like you *must* specify the program's path relative to cwd. For example, when running a script containing the following using `./python.exe` from a source checkout-- p = Popen(['./python.exe', '-V'], stdout=PIPE, stderr=PIPE, cwd='temp') you get an: "OSError: [Errno 2] No such file or directory." In contrast, when you *do* specify the program's path relative to cwd, it works-- p = Popen(['../python.exe', '-V'], stdout=PIPE, stderr=PIPE, cwd='temp') Issue 6374 seems to have made the same point in its second bullet, but the issue was closed without addressing that part of it. ---------- assignee: docs@python components: Documentation keywords: easy messages: 167194 nosy: cjerdonek, docs@python priority: normal severity: normal status: open title: subprocess.Popen(cwd) documentation versions: Python 2.7, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15533> _______________________________________

11 51

[issue31665] Edit "Setting [windows] environmental variables"
by Terry J. Reedy 16 Mar '21

16 Mar '21

New submission from Terry J. Reedy <tjreedy(a)udel.edu>: Python Setup and Usage, 3.3.1. Excursus: Setting environment variables https://docs.python.org/3/using/windows.html#excursus-setting-environment-v… The word 'excursus' is so rare and archaic that this is my first encounter with it. Could we drop it? The last paragraph starts with "To permanently modify the default environment variables, click Start and search for ‘edit environment variables’,". This part is fine on Windows 10 as it brings up "Edit the system environment variables" and "Edit environmental variables for your account". Both take one to an Environmental variables dialog. The former requires than one be or become an admin user (via UAC dialog). The paragraph continues "or open System properties, Advanced system settings and click the Environment Variables button. In this dialog, you can add or modify User and System variables. To change System variables, you need non-restricted access to your machine (i.e. Administrator rights)." On Windows 10, at least, this is confusing or wrong. Control Panel has 'System' linked to the System dialog. This has 'Advanced systems settings' linked to System Properties, but one only get there by being or becoming (via UAC) an admin user. This has the Environmental Properties button mentioned above. It opens Environmental Variables for the admin user you are or are acting as. This route cannot change EVs for non-admin users. I have the impression that this has changed since Win 7. ---------- assignee: docs@python components: Documentation, Windows messages: 303560 nosy: docs@python, paul.moore, steve.dower, terry.reedy, tim.golden, zach.ware priority: normal severity: normal stage: needs patch status: open title: Edit "Setting [windows] environmental variables" type: behavior versions: Python 3.6, Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue31665> _______________________________________

2 2

[issue41933] Wording of s * n in Common Sequence Operations is not optimal
by Julien Palard 15 Mar '21

15 Mar '21

New submission from Julien Palard <julien+python(a)palard.fr>: As reported by Graham Ewart on docs@, in https://docs.python.org/3/library/stdtypes.html#common-sequence-operations: s * n or n * s | equivalent to adding s to itself n times is badly worded. In fact it's more like n-1 times, but yet it's not adding s to itself. I'd go for "n times the s sequence" or "n copies of the s sequence" instead, which both avoid the "n-1" and the "to itself" parts. ---------- assignee: docs@python components: Documentation keywords: easy messages: 377958 nosy: docs@python, mdk priority: normal severity: normal status: open title: Wording of s * n in Common Sequence Operations is not optimal _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue41933> _______________________________________

2 4

[issue29586] Cannot run pip in fresh install of py 3.5.3
by Adrian Chan 15 Mar '21

15 Mar '21

New submission from Adrian Chan: I uninstalled python 2.7 and 3.4, then performed a fresh install of 3.5.3. Running pip with `python -m pip` as per https://docs.python.org/3.5/installing gives the following error: C:\Python\Python35-32\python.exe: No module named pip.__main__; 'pip' is a package and cannot be directly executed Installation details: * win 7 64 bit. * python 3.5.3 32 bit. * chose options for pip, tcl/tk/idle, test suite, py launcher, shortcuts, add to env, precompile std lib. * installed to non-standard directory. ---------- assignee: docs@python components: Documentation, Installation, Windows messages: 287986 nosy: Adrian Chan, docs@python, paul.moore, steve.dower, tim.golden, zach.ware priority: normal severity: normal status: open title: Cannot run pip in fresh install of py 3.5.3 type: behavior versions: Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue29586> _______________________________________

3 13

[issue31472] "Emulating callable objects" documentation misleading
by Nathan Marrow 14 Mar '21

14 Mar '21

New submission from Nathan Marrow: The documentation for emulating callable objects with __call__ seems to imply only positional arguments are supported. For instance, it says __call__ is "object.__call__(self[, args…])" and describes: Called when the instance is “called” as a function; if this method is defined, x(arg1, arg2, ...) is a shorthand for x.__call__(arg1, arg2, ...). When it should be something like (Not sure exactly what the syntax would be here): "object.__call__(self[, args…] [,**kwargs...])" Called when the instance is “called” as a function; if this method is defined, x(arg1, arg2, ..., arg3=arg3) is a shorthand for x.__call__(arg1, arg2, ..., arg3=arg3). ---------- assignee: docs@python components: Documentation messages: 302185 nosy: docs@python, nmarrow priority: normal severity: normal status: open title: "Emulating callable objects" documentation misleading 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> <https://bugs.python.org/issue31472> _______________________________________

3 2

[issue18767] csv documentation does not note default quote constant
by Brian McLaughlin 14 Mar '21

14 Mar '21

New submission from Brian McLaughlin: Documentation should note default quoting behavior of the csv module is csv.QUOTE_MINIMAL http://hg.python.org/cpython/file/tip/Modules/_csv.c#l420 ---------- assignee: docs@python components: Documentation files: doc.patch keywords: patch messages: 195448 nosy: bemclaugh, docs@python priority: normal severity: normal status: open title: csv documentation does not note default quote constant versions: Python 2.6, Python 2.7, Python 3.1, Python 3.2, Python 3.3, Python 3.4, Python 3.5 Added file: http://bugs.python.org/file31333/doc.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18767> _______________________________________

4 3

[issue34538] Remove encouragement to author a base class for all Exception subclasses in a module
by Nathaniel Manista 14 Mar '21

14 Mar '21

New submission from Nathaniel Manista <nathaniel(a)google.com>: https://docs.python.org/3.8/tutorial/errors.html (and all other versions of that page back at least as far as 2.7) currently contain the guidance "When creating a module that can raise several distinct errors, a common practice is to create a base class for exceptions defined by that module, and subclass that to create specific exception classes for different error conditions: <code example>". It may have seemed like a good idea at the time, but we now know from years of experience that this is an experiment that didn't pan out and we can consider this guidance a Now-Contraindicated Best Practice Of Yesteryear™. Modules define subclasses of Exception for lots of reasons. Some of those subclasses have no relation to one another except that they are subclasses of Exception. Some of those subclasses define Exception instances that are never raised by code in the module, but that are expected to be raised by code passed to and called by the module. Yes, there are times when a common base class may be appropriate - such as when an inheritance hierarchy and polymorphism that satisfy the Liskov Substitution Principle make sense for the Exception subclasses, and when the base class itself is used (such as when the base class is an item in the Raises: section of a function's doc string). But these cases aren't so common as to justify the advice being offered generally about all Exception subclass definitions. Exception subclasses are just classes. Advising that authors may wish to define a common base class for all Exception subclasses in a module is like advising authors that they may wish to define a common base class for all object subclasses in a module - it's very, very, very occasionally a good idea in the particular circumstances of a particular module's implementation, but very generally not. ---------- assignee: docs@python components: Documentation messages: 324286 nosy: Nathaniel Manista, docs@python priority: normal severity: normal status: open title: Remove encouragement to author a base class for all Exception subclasses in a module type: enhancement 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/issue34538> _______________________________________

8 15

[issue40763] zipfile.extractall is safe by now
by Va 13 Mar '21

13 Mar '21

New submission from Va <d.python.dc54(a)indigo.re>: In documentation of all Python 3 versions, [ZipFile.extractall](https://docs.python.org/3/library/zipfile.html#zipfile.… states with a big red warning: > Warning > Never extract archives from untrusted sources without prior inspection. It is possible that files are created outside of path, e.g. members that have absolute filenames starting with "/" or filenames with two dots "..". This module attempts to prevent that. See extract() note. However, when looking at the implementation, it calls _extract_member() which seems to sanitize filenames. So the warning might not be relevant anymore. Furthermore, when looking at [Python 2](https://docs.python.org/2/library/zipfile.html#zipfile.ZipFile.extractal… documentation, we can see the same warning, along with a change note: > Changed in version 2.7.4: The zipfile module attempts to prevent that. See extract() note. So, the big red warning in Python 3 documentation might be relevant only for Python < 2.7.4, not for any Python 3 version. ---------- assignee: docs@python components: Documentation messages: 369854 nosy: VA, docs@python priority: normal severity: normal status: open title: zipfile.extractall is safe by now type: behavior versions: Python 3.10, 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/issue40763> _______________________________________

4 5

[issue30435] Documentation either unclear or incorrect on comparisons between bytes and strings in Python 3
by ipatrol 13 Mar '21

13 Mar '21

New submission from ipatrol: https://docs.python.org/3/reference/expressions.html#comparisons says that "Strings and binary sequences cannot be directly compared." That would seem to me to imply that an equality between them would raise an exception, as also claimed by https://wiki.python.org/moin/BytesStr However, that is manifestly incorrect. Bytes and strings can be compared: they are always unequal. This appears to be a result of the operation falling through to the default comparison, which returns False since they are not identical objects. Equality is a comparison, though it is not an order comparison. A brief search of the word "cannot" in the documentation suggest that saying a certain thing cannot be done usually implies that attempting to do so anyway will raise an exception, typically a TypeError. That this is not the case for string-bytes comparisons should be mentioned. ---------- assignee: docs@python components: Documentation messages: 294200 nosy: docs@python, ipatrol priority: normal severity: normal status: open title: Documentation either unclear or incorrect on comparisons between bytes and strings in Python 3 type: behavior versions: 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/issue30435> _______________________________________

5 7