Mailman 3 June 2020 - docs

[issue40982] copytree example in shutil
by Alberto Torres Barrán 06 Mar '21

06 Mar '21

New submission from Alberto Torres Barrán <albertotb(a)gmail.com>: The copytree example in https://docs.python.org/3/library/shutil.html#copytree-example does not match the source code, even removing docstrings. In particular is missing parameters and the exceptions are in the wrong order (Error will never be reachable since it is n instance of OSError). ---------- assignee: docs@python components: Documentation messages: 371535 nosy: Alberto Torres Barrán, docs@python priority: normal severity: normal status: open title: copytree example in shutil versions: Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue40982> _______________________________________

3 2

[issue30295] msvcrt SetErrorMode not documented
by Giampaolo Rodola' 06 Mar '21

06 Mar '21

New submission from Giampaolo Rodola': Also SEM_FAILCRITICALERRORS and other SEM_constants. They should as setting error mode on Windows for console applications is a pretty common use case (in fact ./Lib/test/libregrtest/setup.py uses it). ---------- assignee: docs@python components: Documentation messages: 293189 nosy: docs@python, giampaolo.rodola priority: normal severity: normal status: open title: msvcrt SetErrorMode not documented versions: Python 3.4, Python 3.5, Python 3.6, Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue30295> _______________________________________

2 3

[issue8557] subprocess portability issue
by Dave Abrahams 05 Mar '21

05 Mar '21

New submission from Dave Abrahams <dave(a)boostpro.com>: On POSIX systems, the PATH environment variable is always used to look up directory-less executable names passed as the first argument to Popen(...), but on Windows, PATH is only considered when shell=True is also passed. Actually I think it may be slightly weirder than that when shell=False, because the following holds for me: C:\>rem ##### Prepare minimal PATH ##### C:\>set "PATH=C:\Python26\Scripts;C:\Python26;C:\WINDOWS\system32;C:\WINDOWS;C:\WINDOWS\System32\Wbem" C:\>rem ##### Prepare a minimal, clean environment ##### C:\>virtualenv --no-site-packages e:\zzz New python executable in e:\zzz\Scripts\python.exe Installing setuptools................done. C:\>rem ##### Show that shell=True makes the difference in determining whether PATH is respected ##### C:\>python Python 2.6.5 (r265:79096, Mar 19 2010, 18:02:59) [MSC v.1500 64 bit (AMD64)] on win32 Type "help", "copyright", "credits" or "license" for more information. >>> import subprocess >>> subprocess.Popen(['python', '-c', 'import sys; print sys.executable']) <subprocess.Popen object at 0x0000000001DBE080> >>> C:\Python26\python.exe >>> subprocess.Popen(['python', '-c', 'import sys; print sys.executable'], env={'PATH':r'e:\zzz\Scripts'}) <subprocess.Popen object at 0x0000000001F05A90> >>> C:\Python26\python.exe >>> subprocess.Popen(['python', '-c', 'import sys; print sys.executable'], env={'PATH':r'e:\zzz\Scripts'}, shell=True) <subprocess.Popen object at 0x0000000001F05B00> >>> e:\zzz\Scripts\python.exe That is, it looks like the environment at the time Python is invoked is what counts unless I pass shell=True. I don't even seem to be able to override this behavior by changing os.environ: you can clear() it and pass env={} and subprocess.Popen(['python']) still succeeds. This is a very important problem for portable code and one that took me hours to suss out. I think: a) the current behavior needs to be documented b) it needs to be fixed if possible c) otherwise, shell=True should be the default ---------- assignee: docs@python components: Documentation messages: 104422 nosy: dabrahams, docs@python priority: normal severity: normal status: open title: subprocess portability issue type: behavior versions: Python 2.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue8557> _______________________________________

8 23

[issue16272] C-API documentation clarification for tp_dictoffset
by Chris Colbert 05 Mar '21

05 Mar '21

New submission from Chris Colbert: The documentation of the tp_dictoffset is a bit unclear when describing the responsibilities of a base type with a nonzero tp_dictoffset. http://docs.python.org/c-api/typeobj.html I feel there should some statement to the effect of: """ If a type defines a nonzero tp_dictoffset, that type is responsible for defining a `__dict__` slot as part of the tp_getset structures. Failure to do so will result in the dict being inaccesible from Python via `obj.__dict__` from instances of the type or subtypes. """ The reasoning is twofold: 1) `PyType_Ready` does not add the default getset members like `type_new` does. This prevents the instances of the type itself from retrieving `obj.__dict__` 2) `type_new` will provide the default `subtype_dict` getset member for subclasses, but this calls `get_builtin_base_with_dict` which will resolve to the most base type which is not heap allocated; in this case, the C type. Since this type has no `__dict__` getset member, the lookup fails. Adding a bit of verbage about this "gotcha" would likely save some headaches in the future. ---------- assignee: docs@python components: Documentation messages: 173222 nosy: Chris.Colbert, docs@python priority: normal severity: normal status: open title: C-API documentation clarification for tp_dictoffset versions: Python 2.6, Python 2.7, Python 3.1, Python 3.2, Python 3.3, Python 3.4, Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue16272> _______________________________________

6 7

[issue39375] Document os.environ[x] = y and os.putenv() as thread unsafe
by Gregory P. Smith 04 Mar '21

04 Mar '21

New submission from Gregory P. Smith <greg(a)krypto.org>: The underlying API calls made by os.putenv() and os.environ[name] = value syntax are not thread safe on POSIX systems. POSIX _does not have_ any thread safe way to access the process global environment. In a pure Python program, the GIL prevents this from being an issue. But when embedded in a C/C++ program or using extension modules that launch their own threads from C, those threads could also make the invalid assumption that they can safely _read_ the environment. Which is a race condition when a Python thread is doing a putenv() at the same time. We should document the danger. CPython's os module snapshots a copy of the environment into a dict at import time (during CPython startup). But os.environ[] assignment and os.putenv() modify the actual process global environment in addition to updating this dict. (If an embedded interpreter is launched from a process with other threads already running, even that initial environment reading could be unsafe if the larger application has a thread that wrongly assumes it has exclusive environment access) For people modifying os.environ so that the change is visible to child processes, we can recommend using the env= parameter on subprocess API calls to supply a new environment. A broader issue of should we be modifying the process global environment state at all from os.putenv() and os.environ[] assignment still exists. I'll track that in another issue (to be opened). ---------- assignee: docs@python components: Documentation messages: 360221 nosy: docs@python, gregory.p.smith priority: normal severity: normal status: open title: Document os.environ[x] = y and os.putenv() as thread unsafe versions: Python 2.7, Python 3.7, Python 3.8, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue39375> _______________________________________

4 8

[issue29829] Documentation lacks clear warning of subprocess issue with pythonw
by Steve Barnes 04 Mar '21

04 Mar '21

New submission from Steve Barnes: When running under pythonw, or pyinstaller with the -w flag, modules that use subprocess calls such as popen, run, etc. will crash if the default `stdout=None, stderr=None` behaviour is used rather than PIPE. This is an obscure problem which is very hard to debug yet there is no warning in the documentation on this. I would like to suggest adding a :warning:`stdout=None, stderr=None` must not be used in any of the calls in this module when running under pythonw due to the lack of sys.stdout & sys.stderr in that case. Please use `stdout=PIPE, stderr=PIPE` instead. A patch against the default branch would be: diff -r 4243df51fe43 Doc/library/subprocess.rst --- a/Doc/library/subprocess.rst Fri Feb 10 14:19:36 2017 +0100 +++ b/Doc/library/subprocess.rst Thu Mar 16 16:56:24 2017 +0000 @@ -33,6 +33,13 @@ function for all use cases it can handle. For more advanced use cases, the underlying :class:`Popen` interface can be used directly. +.. warning:: Do not use default parameters on Windows with pythonw. + + As pythonw deletes `sys.stdout` & `sys.stderr` the use of the default + parameters, `stdout=None, stderr=None,`, which defaults to being + `stdout=sys.stdout, stderr=sys.stderr,` may cause unexpected crashes + it is recommended to use `stdout=PIPE, stderr=PIPE,` instead. + The :func:`run` function was added in Python 3.5; if you need to retain compatibility with older versions, see the :ref:`call-function-trio` section. ---------- assignee: docs@python components: Documentation messages: 289722 nosy: Steve Barnes, docs@python priority: normal severity: normal status: open title: Documentation lacks clear warning of subprocess issue with pythonw type: behavior versions: Python 2.7, Python 3.6, Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue29829> _______________________________________

3 4

[issue12594] Docs for py3k still refer to "MacPython 2.5 folder"
by Christoph Schindler 04 Mar '21

04 Mar '21

New submission from Christoph Schindler <hop(a)30hopsmax.at>: In http://docs.python.org/py3k/using/mac.html#getting-and-installing-macpython and http://docs.python.org/py3k/using/mac.html#distributing-python-applications… . ---------- assignee: docs@python components: Documentation messages: 140744 nosy: docs@python, hop priority: normal severity: normal status: open title: Docs for py3k still refer to "MacPython 2.5 folder" versions: Python 3.1, Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12594> _______________________________________

7 11

[issue39199] Improve the AST documentation
by Pablo Galindo Salgado 03 Mar '21

03 Mar '21

New submission from Pablo Galindo Salgado <pablogsal(a)gmail.com>: The AST docs need some love as they can be a bit obscure to someone new to the module. Improvements to be considered in this issue: * Document all available nodes (as of 3.8 and not deprecated ones). This helps to know what classes to consider when implementing methods for the visitors. * Add some short practical examples for the visitors: one to query an AST and another to modify it. ---------- assignee: docs@python components: Documentation messages: 359235 nosy: docs@python, pablogsal priority: normal severity: normal status: open title: Improve the AST documentation versions: Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue39199> _______________________________________

2 9

[issue24650] Error in yield expression documentation
by swanson 27 Feb '21

27 Feb '21

New submission from swanson: https://docs.python.org/3/reference/expressions.html in 6.2.9. Yield expressions end of 1st paragraph: "Using a yield expression in a function’s body causes that function to be a generator." NO! As the very next sentence explains, a generator is what's returned by such a function, not the function itself. Basically, it should be sufficient to add the word "function" to the end of that sentence: "... generator function." However, this error does NOT exist in 3.0 to 3.2 - just in 3.3 to 3.6, so I suggest just using the same wording as 3.0 to 3.2: "Using a yield expression in a function definition is sufficient to cause that definition to create a generator function instead of a normal function." ---------- assignee: docs@python components: Documentation messages: 246841 nosy: docs@python, swanson priority: normal severity: normal status: open title: Error in yield expression documentation versions: Python 3.3, Python 3.4, Python 3.5, Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue24650> _______________________________________

4 4

[issue29045] Outdated C api doc about Windows error
by Xiang Zhang 26 Feb '21

26 Feb '21

New submission from Xiang Zhang: https://docs.python.org/3.7/c-api/exceptions.html#c.PyErr_SetFromWindowsErr… it stills refers to PyErr_SetFromWindowsErrWithFilenameObject but this function doesn't exist since Py3.4. I didn't find when and why it's deleted. And https://docs.python.org/3.4/c-api/exceptions.html#c.PyErr_SetFromWindowsErr raises OSError instead of WindowsError. ---------- assignee: docs@python components: Documentation messages: 283814 nosy: docs@python, xiang.zhang priority: normal severity: normal status: open title: Outdated C api doc about Windows error versions: Python 3.5, Python 3.6, Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue29045> _______________________________________

2 3