Mailman 3 January 2019 - docs

[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

[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

[issue35026] Winreg's documentation lacks mentioning required permission at some points
by George Fischhof 28 Mar '21

28 Mar '21

New submission from George Fischhof <george(a)fischhof.hu>: Winreg's documentation lacks mentioning required permission at some points Hi there, on page https://docs.python.org/3/library/winreg.html it is not mentioned in the description of the following functions: winreg.DeleteKey winreg.DeleteKeyEx winreg.DeleteValue that they require KEY_SET_VALUE when the registry key is opened. It is mentioned for example at: winreg.SetValue with the following text: The key identified by the key parameter must have been opened with KEY_SET_VALUE access. BR, George ---------- assignee: docs@python components: Documentation messages: 328034 nosy: docs@python, georgefischhof priority: normal severity: normal status: open title: Winreg's documentation lacks mentioning required permission at some points type: enhancement versions: Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue35026> _______________________________________

4 4

[issue21297] skipinitialspace in the csv module only skips spaces, not "whitespace" in general
by Daniel Andersson 25 Mar '21

25 Mar '21

New submission from Daniel Andersson: Regarding the `skipinitialspace` parameter to the different CSV reader dialects in the `csv` module, the official documentation asserts: When True, whitespace immediately following the delimiter is ignored. and the `help(csv)` style module documentation says: * skipinitialspace - specifies how to interpret whitespace which immediately follows a delimiter. It defaults to False, which means that whitespace immediately following a delimiter is part of the following field. "Whitespace" is a bit too general in both cases (at least a red herring in the second case), since it only skips spaces and not e.g. tabs [1]. In `Modules/_csv.c`, it more correctly describes the parameter. At line 81: int skipinitialspace; /* ignore spaces following delimiter? */ and the actual implementation at line 638: else if (c == ' ' && dialect->skipinitialspace) /* ignore space at start of field */ ; No-one will probably assume that the whole UTF-8 spectrum of "whitespace" is skipped, but at least I initially assumed that the tab character was included. [1]: http://en.wikipedia.org/wiki/Whitespace_character ---------- assignee: docs@python components: Documentation, Library (Lib) messages: 216780 nosy: Daniel.Andersson, docs@python priority: normal severity: normal status: open title: skipinitialspace in the csv module only skips spaces, not "whitespace" in general type: behavior versions: 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/issue21297> _______________________________________

6 9

[issue35118] Add peek() or first() method in queue
by Windson Yang 23 Mar '21

23 Mar '21

New submission from Windson Yang <wiwindson(a)gmail.com>: I found other languages like Java and C++ have the method to access the first value in Queue like first() and peek(). Since we use deque_ to create Queue now, it's easy to implement in python using the index. Otherwise, we can add this to the document? I also found some discussion_ here. .. _deque: https://github.com/python/cpython/blob/master/Lib/queue.py#L205 .. _discussion https://mail.python.org/pipermail/python-list/2010-March/569930.html ---------- assignee: docs@python components: Documentation messages: 328963 nosy: Windson Yang, docs@python priority: normal severity: normal status: open title: Add peek() or first() method in queue 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/issue35118> _______________________________________

3 11

[issue14189] Documentation for some C APIs is missing clear specification of the type of reference they return
by Baruch Sterin 21 Mar '21

21 Mar '21

New submission from Baruch Sterin <python(a)bsterin.com>: In addition to the description text, most C API functions have a one-line, emphasized specification whether they return a new or a borrowed reference. (e.g. 'Return value: New reference.'). The following API functions are missing that. Some of them, like PyMemoryView_FromBuffer(), have descriptions that are clear, but it would still be nice to have an unambiguous statement like most other API functions have. The list has been generated automatically, so it might contain some errors. Doc/c-api/arg.rst: Py_VaBuildValue Doc/c-api/buffer.rst: PyMemoryView_FromBuffer Doc/c-api/buffer.rst: PyMemoryView_FromObject Doc/c-api/buffer.rst: PyMemoryView_GetContiguous Doc/c-api/bytearray.rst: PyByteArray_Concat Doc/c-api/bytearray.rst: PyByteArray_FromObject Doc/c-api/bytearray.rst: PyByteArray_FromStringAndSize Doc/c-api/code.rst: PyCode_New Doc/c-api/codec.rst: PyCodec_BackslashReplaceErrors Doc/c-api/codec.rst: PyCodec_Decode Doc/c-api/codec.rst: PyCodec_Decoder Doc/c-api/codec.rst: PyCodec_Encode Doc/c-api/codec.rst: PyCodec_Encoder Doc/c-api/codec.rst: PyCodec_IgnoreErrors Doc/c-api/codec.rst: PyCodec_IncrementalDecoder Doc/c-api/codec.rst: PyCodec_IncrementalEncoder Doc/c-api/codec.rst: PyCodec_LookupError Doc/c-api/codec.rst: PyCodec_ReplaceErrors Doc/c-api/codec.rst: PyCodec_StreamReader Doc/c-api/codec.rst: PyCodec_StreamWriter Doc/c-api/codec.rst: PyCodec_StrictErrors Doc/c-api/codec.rst: PyCodec_XMLCharRefReplaceErrors Doc/c-api/exceptions.rst: PyUnicodeDecodeError_Create Doc/c-api/exceptions.rst: PyUnicodeDecodeError_GetEncoding Doc/c-api/exceptions.rst: PyUnicodeDecodeError_GetObject Doc/c-api/exceptions.rst: PyUnicodeDecodeError_GetReason Doc/c-api/exceptions.rst: PyUnicodeEncodeError_Create Doc/c-api/exceptions.rst: PyUnicodeTranslateError_Create Doc/c-api/float.rst: PyFloat_GetInfo Doc/c-api/import.rst: PyImport_GetImporter Doc/c-api/import.rst: PyImport_ImportModuleNoBlock Doc/c-api/import.rst: _PyImport_FindExtension Doc/c-api/import.rst: _PyImport_FixupExtension Doc/c-api/init.rst: PyEval_GetCallStats Doc/c-api/int.rst: PyInt_FromSize_t Doc/c-api/long.rst: PyLong_FromSize_t Doc/c-api/long.rst: PyLong_FromSsize_t Doc/c-api/number.rst: PyNumber_Index Doc/c-api/number.rst: PyNumber_ToBase Doc/c-api/object.rst: PyObject_Bytes Doc/c-api/object.rst: PyObject_GenericGetAttr Doc/c-api/unicode.rst: PyUnicode_AsUTF32String Doc/c-api/unicode.rst: PyUnicode_DecodeMBCSStateful Doc/c-api/unicode.rst: PyUnicode_DecodeUTF32 Doc/c-api/unicode.rst: PyUnicode_DecodeUTF32Stateful Doc/c-api/unicode.rst: PyUnicode_DecodeUTF7 Doc/c-api/unicode.rst: PyUnicode_DecodeUTF7Stateful Doc/c-api/unicode.rst: PyUnicode_EncodeUTF32 Doc/c-api/unicode.rst: PyUnicode_EncodeUTF7 Doc/c-api/veryhigh.rst: PyEval_EvalCodeEx Doc/c-api/veryhigh.rst: PyEval_EvalFrame Doc/c-api/veryhigh.rst: PyEval_EvalFrameEx ---------- assignee: docs@python components: Documentation messages: 154877 nosy: baruch.sterin, docs@python priority: normal severity: normal status: open title: Documentation for some C APIs is missing clear specification of the type of reference they return type: behavior versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14189> _______________________________________

9 9

[issue29688] Document Path.absolute
by Jim Fasarakis-Hilliard 17 Mar '21

17 Mar '21

New submission from Jim Fasarakis-Hilliard: Method absolute of Path objects lacked documentation, proposed PR adds relevant method to docs. ---------- assignee: docs@python components: Documentation messages: 288767 nosy: Jim Fasarakis-Hilliard, docs@python priority: normal severity: normal status: open title: Document Path.absolute versions: Python 3.5, Python 3.6, Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue29688> _______________________________________

6 20

[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