Mailman 3 June 2014 - docs

[issue11975] Fix intersphinx-ing of built-in types (list, int, ...)
by Jonas H. April 29, 2021

April 29, 2021

New submission from Jonas H. <jonas(a)lophus.org>: Intersphinx-ing of int, list, float, ... should work with ":class:`int`" (list, float, ...). Also, intersphinx-ing list methods, e.g. ":meth:`list.insert`", should work. ---------- assignee: docs@python components: Documentation messages: 134923 nosy: docs@python, jonash priority: normal severity: normal status: open title: Fix intersphinx-ing of built-in types (list, int, ...) _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11975> _______________________________________

11 50

[issue20692] Tutorial section 9.4
by Jon Shemitz April 28, 2021

April 28, 2021

New submission from Jon Shemitz: The tutorial says "Each value is an object, and therefore has a class (also called its type). It is stored as object.__class__." So, I tried >>> 3.__class__ File "<stdin>", line 1 3.__class__ ^ SyntaxError: invalid syntax Yet, "foo".__class__ worked, as did 3j.__class__ and 3.5.__class__. When my son (!) suggested that I try (3).__class__, I did indeed get <type 'int'>, while (3,).__class__ gave <type 'tuple'>. This *looks like* a minor error in the parser, where seeing \d+\. puts it in a state where it expects \d+ and it can't handle \w+ This may be the sort of thing that only a newbie would even think to try, so may not be worth fixing. If so, it may be worth mentioning in the tutorial. ---------- assignee: docs@python components: Documentation, Interpreter Core messages: 211670 nosy: Jon.Shemitz, docs@python priority: normal severity: normal status: open title: Tutorial section 9.4 type: behavior versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue20692> _______________________________________

10 18

[issue16386] imp.find_module does not specify registry key it searches on windows
by Jan Duzinkiewicz April 24, 2021

April 24, 2021

New submission from Jan Duzinkiewicz: quote from http://docs.python.org/3/library/imp.html#imp.find_module: "...on some systems some other places are looked in as well (on Windows, it looks in the registry which may point to a specific file)." I actually didn't know the registry key is listed in "using Python on Window" guide until I grepped for PythonCore (which kind of requires to know the key already) - so I'm submitting a patch that cross references find_module docs and using Python on Windows guide. ---------- assignee: docs@python components: Documentation files: import_nt_reg.patch keywords: patch messages: 174508 nosy: dhgmgn, docs@python priority: normal severity: normal status: open title: imp.find_module does not specify registry key it searches on windows versions: Python 2.7, Python 3.3 Added file: http://bugs.python.org/file27843/import_nt_reg.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue16386> _______________________________________

4 5

[issue11977] Document int.conjugate, .denominator, ...
by Jonas H. April 23, 2021

April 23, 2021

New submission from Jonas H. <jonas(a)lophus.org>: Various `int` attributes and methods seem undocumented (at least it does not work to intersphinx them): * .conjugate * .denominator * .imag * .numerator * .real ---------- assignee: docs@python components: Documentation messages: 134926 nosy: docs@python, jonash priority: normal severity: normal status: open title: Document int.conjugate, .denominator, ... versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11977> _______________________________________

6 8

[issue21352] improve indexing
by bob gailer April 23, 2021

April 23, 2021

New submission from bob gailer: Inconsistencies / confusion with documentation Index Tab. Example (line numbers added for comments that follow): 1 max 2 built-in function 3 max (datetime.date attribute) 4 (datetime.datetime attribute) 5 (datetime.time attribute) 6 max() built-in function 7 (decimal.Context method) 8 (decimal.Decimal method) 9 (in module audioloop) The following all lead to confusion and frustration: Having 3 rows (1, 3, 6)that begin with max. Having an entry (1) that does nothing when double-clicked. double-clicking (2) takes us to a reference rather than a definition. RECOMMENDATION: change to: max() built-in function (sequence operation) (decimal.Context method) (decimal.Decimal method) max (datetime.date attribute) (datetime.datetime attribute) (datetime.time attribute) where double-clicking the first line goes to the max() definition in 2. Built-in Functions These comments apply, with a number of variations, to most built-in functions index entries. ---------- assignee: docs@python components: Documentation messages: 217170 nosy: bgailer, docs@python priority: normal severity: normal status: open title: improve indexing type: enhancement 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/issue21352> _______________________________________

7 6

[issue19023] ctypes docs: Unimplemented and undocumented features
by Sye van der Veen April 20, 2021

April 20, 2021

New submission from Sye van der Veen: In the ctypes documentation, there's mention of a BigEndianUnion/LittleEndianUnion that isn't actually implemented, and the "Arrays and pointers" section just reads "Not yet written". The attached patch adds the (Big|Little)EndianUnion classes (with tests), finishes the Array/_Pointer class docs (and adds missing cases to the tests), and makes some stylistic improvements to docs. The patch was made against default, but it's quite likely it could be back-ported all the way to Python 3.1. ---------- assignee: docs@python components: Documentation, Tests, ctypes hgrepos: 209 messages: 197764 nosy: docs@python, syeberman priority: normal severity: normal status: open title: ctypes docs: Unimplemented and undocumented features type: enhancement _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue19023> _______________________________________

8 15

[issue20364] Rename & explain sqlite3.Cursor.execute 'parameters' param
by Terry J. Reedy April 14, 2021

April 14, 2021

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

[issue21297] skipinitialspace in the csv module only skips spaces, not "whitespace" in general
by Daniel Andersson March 26, 2021

March 26, 2021

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

[issue14189] Documentation for some C APIs is missing clear specification of the type of reference they return
by Baruch Sterin March 22, 2021

March 22, 2021

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

[issue15533] subprocess.Popen(cwd) documentation
by Chris Jerdonek March 17, 2021

March 17, 2021

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