Mailman 3 January 2021 - docs

[issue13368] Possible problem in documentation of module subprocess, method send_signal
by Eli Bendersky 24 Feb '21

24 Feb '21

New submission from Eli Bendersky <eliben(a)gmail.com>: docs@ list report by Daniel Dieterle: in the documentation (http://docs.python.org/library/subprocess.html#subprocess.Popen.send_signal) is a bug. CTRL_C_EVENT can not be sent to processes started with a creationflags parameter which includes CREATE_NEW_PROCESS_GROUP. Why can be read in the msdn documentation http://msdn.microsoft.com/en-us/library/windows/desktop/ms683155%28v=vs.85%… . A workaround using CTRL_C_EVENT nevertheless is described here: http://stackoverflow.com/questions/7085604/sending-c-to-python-subprocess-o… -- I do not know why the subprocess.CREATE_NEW_PROCESS_GROUP parameter was introduced. But it is useless for terminating a process with os.kill() in combination with signal.SIGTERM, which corresponds to a CTRL-C-EVENT. A CTRL-C-EVENT is only forwarded to the process if the process group is zero. Therefore the Note in the documentation on Popen.send_signal() is wrong. ---------- assignee: docs@python components: Documentation messages: 147272 nosy: docs@python, eli.bendersky priority: normal severity: normal status: open title: Possible problem in documentation of module subprocess, method send_signal versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13368> _______________________________________

4 6

[issue43042] tutorial ambiguous about creation of local symbol table for recursive calls
by Jesse Silverman 22 Feb '21

22 Feb '21

New submission from Jesse Silverman <jessevsilverman(a)gmail.com>: In section 4.6 of the tutorial, we find: "When a function calls another function, a new local symbol table is created for that call." Now, perhaps because we were just looking at a function that people will often ask you to write both recursively and non-recursively and then ask which one you would use and why...I was thinking "Wait -- when a function calls itself recursively, obviously they need a new local symbol table or local variables won't work??" I may be confused, in which case the doc is fine and I personally need to better understand the moral equivalent of activation record / stack frame in Python. If I am not, given that recursion isn't much more computer science oriented or obscure than Fibonacci sequences, could it not be worth the investment of a few extra words as: "When a function calls another function, or calls itself recursively, a new local symbol table is created for that call." ---------- assignee: docs@python components: Documentation messages: 385800 nosy: docs@python, jessevsilverman priority: normal severity: normal status: open title: tutorial ambiguous about creation of local symbol table for recursive calls versions: Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue43042> _______________________________________

4 12

[issue16954] Add docstrings for ElementTree module
by Serhiy Storchaka 21 Feb '21

21 Feb '21

New submission from Serhiy Storchaka: Perhaps almost all Doxygen comments in ElementTree module should be converted to docstrings. ---------- assignee: docs@python components: Documentation, XML messages: 179881 nosy: docs@python, eli.bendersky, serhiy.storchaka priority: normal severity: normal stage: needs patch status: open title: Add docstrings for ElementTree module type: enhancement versions: Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue16954> _______________________________________

8 23

[issue27646] yield from expression can be any iterable
by Terry J. Reedy 21 Feb '21

21 Feb '21

New submission from Terry J. Reedy: https://docs.python.org/3/reference/expressions.html#yield-expressions says "When yield from <expr> is used, it treats the supplied expression as a subiterator. All values produced by that subiterator ...". To me "treats..expression as a subiterator" means that the expression must *be* an iterator, such as returned by iter or calling a generator function. Hence I was surprised upon reading "yield from <non-iterator iterable>" in stdlib code. I confirmed that this usage is correct by trying >>> def g(): yield from (1,2) >>> i = g() >>> next(i), next(i) (1, 2) and then reading the PEP380 Formal Semantics, which begins with "_i = iter(EXPR)". Hence I suggest the following replacement for the quote above: "When yield from <expr> is used, the expression must be an iterable. A subiterator is obtained with iter(<expr>). All values produced by that subiterator ...". Note that 'subiterator' is spelled in the following sentences 'underlying iterable' (which I am not sure I like) and 'sub-iterator' (and 'sub-generator'). I think we should be consistent for at least the two short 'yield from' paragraphs. ---------- assignee: docs@python components: Documentation messages: 271577 nosy: docs@python, terry.reedy priority: normal severity: normal stage: patch review status: open title: yield from expression can be any iterable type: behavior versions: Python 3.5, Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue27646> _______________________________________

3 8

[issue42402] Termios module documentation is extremely lacking
by Dan Merillat 19 Feb '21

19 Feb '21

New submission from Dan Merillat <dan.merillat(a)gmail.com>: "The interpretation of the flags and the speeds as well as the indexing in the cc array must be done using the symbolic constants defined in the |termios| module." (termios links to itself) These constants are not listed in the documentation and the termios module is installed as a shared library so you can't read it without going to the source. Furthermore the example in the documentation uses the following example: new = termios.tcgetattr(fd) new[3] = new[3] & ~termios.ECHO # lflags Which is explicitly against the documentation on the same page. This has led to most searches on the net turning up people using magic numbers in places instead of symbolic values. Inserting a list of constants with an extremely brief description would improve the module documentation dramatically. ---------- assignee: docs@python components: Documentation messages: 381393 nosy: dan.merillat, docs@python priority: normal severity: normal status: open title: Termios module documentation is extremely lacking versions: Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue42402> _______________________________________

2 2

[issue13433] String format documentation contains error regarding %g
by Christian Iversen 18 Feb '21

18 Feb '21

New submission from Christian Iversen <ci(a)sikkerhed.org>: The documentation for string format options state that both %f, %g and %e default to 6 digits after the decimal point. In fact, %g always seems to use 5 digits by default: >>> "%g" % 2.1234567 '2.12346' >>> "%f" % 2.1234567 '2.123457' >>> "%e" % 2.1234567 '2.123457e+00' But something much more insidious is wrong, because even when explicitly told how many digits to have, %g is one off: >>> "%.6g" % 2.1234567 '2.12346' >>> "%.6f" % 2.1234567 '2.123457' >>> "%.6e" % 2.1234567 '2.123457e+00' This can't be right? ---------- assignee: docs@python components: Documentation messages: 147940 nosy: Christian.Iversen, docs@python priority: normal severity: normal status: open title: String format documentation contains error regarding %g type: behavior versions: Python 2.6, Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13433> _______________________________________

6 11

[issue29086] Document C API that is not part of the limited API
by Serhiy Storchaka 18 Feb '21

18 Feb '21

New submission from Serhiy Storchaka: >From the documentation: https://docs.python.org/3/c-api/stable.html In the C API documentation, API elements that are not part of the limited API are marked as "Not part of the limited API." But they don't. Following sample patch adds the notes to Unicode Objects and Codecs C API. I'm going to add them to all C API. What are your though about formatting the note? Should it be before the description, after the description, but before the "deprecated" directive (as in the patch), or after the first paragraph of the description? Should it be on the separate line or be appended at the end of the previous paragraph, or starts the first paragraph (if before the description)? May be introduce a special directive for it? ---------- assignee: docs@python components: Documentation files: unicode-not-part-of-the-limited-api.patch keywords: patch messages: 284125 nosy: docs@python, georg.brandl, serhiy.storchaka priority: normal severity: normal status: open title: Document C API that is not part of the limited API type: enhancement versions: Python 3.5, Python 3.6, Python 3.7 Added file: http://bugs.python.org/file46057/unicode-not-part-of-the-limited-api.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue29086> _______________________________________

5 6

[issue42624] sqlite3 package document mistake
by LIU Qingyuan 12 Feb '21

12 Feb '21

New submission from LIU Qingyuan <possnioo2(a)gmail.com>: In the document about sqlite3 package, it was suggested that when users are trying to create a table already exists, sqlite3.ProgrammingError is going to be thrown. However, the actual exception thrown is sqlite3.OperationalError, which is inconsistent with the document. Doc: https://docs.python.org/3/library/sqlite3.html#exceptions ---------- assignee: docs@python components: Documentation messages: 382904 nosy: docs@python, seeker-Liu priority: normal severity: normal status: open title: sqlite3 package document mistake type: behavior versions: Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue42624> _______________________________________

4 8

[issue42982] Update suggested number of iterations for pbkdf2_hmac()
by Illia Volochii 07 Feb '21

07 Feb '21

New submission from Illia Volochii <illia.volochii(a)gmail.com>: Documentation [1] suggests using at least 100,000 iterations of SHA-256 as of 2013. Currently, it is 2021, and it is common to use much more iterations. For example, Django will use 260,000 by default in the next 3.2 LTS release and 320,000 in 4.0 [2][3]. I suggest suggesting at least 250,000 iterations that is a somewhat round number close to the one used by modern libraries. [1] https://docs.python.org/3/library/hashlib.html#hashlib.pbkdf2_hmac [2] https://github.com/django/django/commit/f2187a227f7a3c80282658e699ae9b04023… [3] https://github.com/django/django/commit/a948d9df394aafded78d72b1daa785a0abf… ---------- assignee: docs@python components: Documentation messages: 385365 nosy: docs@python, illia-v priority: normal severity: normal status: open title: Update suggested number of iterations for pbkdf2_hmac() _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue42982> _______________________________________

3 7

[issue35295] Please clarify whether PyUnicode_AsUTF8AndSize() or PyUnicode_AsUTF8String() is preferred
by Marcin Kowalczyk 05 Feb '21

05 Feb '21

New submission from Marcin Kowalczyk <qrczakmk(a)gmail.com>: The documentation is silent whether PyUnicode_AsUTF8AndSize() or PyUnicode_AsUTF8String() is preferred. We are under the assumption that both are acceptable for the given caller, i.e. the caller wants to access just the sequence of UTF-8 code units (e.g. for calling a C++ function which takes std::string_view or std::string as a parameter), and the caller either will copy the UTF-8 code units immediately or is willing to own a temporary object to ensure a lifetime of the UTF-8 code units. File comments in unicodeobject.h about PyUnicode_AsUTF8AndSize() have a warning: *** This API is for interpreter INTERNAL USE ONLY and will likely *** be removed or changed in the future. *** If you need to access the Unicode object as UTF-8 bytes string, *** please use PyUnicode_AsUTF8String() instead. The discrepancy between these comments and the documentation should be fixed. Either the documentation is correct and the comment is outdated, or the comment is correct and the documentation is lacking guidance. It is not even clear which function is better technically: - PyUnicode_AsUTF8String() always allocates the string. PyUnicode_AsUTF8AndSize() does not allocate the string if the unicode object is ASCII-only (this is common) or if PyUnicode_AsUTF8AndSize() was already called before. - If conversion must be performed, then PyUnicode_AsUTF8String() makes a single allocation, while PyUnicode_AsUTF8AndSize() first calls PyUnicode_AsUTF8String() and then copies the string. - If the string is converted multiple times, then PyUnicode_AsUTF8AndSize() caches the result - faster. If the string is converted once, then the result persists as long as the string persists - wastes memory. I see the following possible resolutions: 1a. Declare both functions equally acceptable. Remove comments claiming that PyUnicode_AsUTF8AndSize() should be avoided. 1b. 1a, and change the implementation of PyUnicode_AsUTF8AndSize() to avoid allocating the string twice if it needs to be materialized, so that PyUnicode_AsUTF8AndSize() is never significantly slower than PyUnicode_AsUTF8String(). 2a. Declare PyUnicode_AsUTF8String() preferred. Indicate this in the documentation. 2b. 2a, and provide a public interface to check and access UTF-8 code units without allocating a new string in case this is possible (I think PyUnicode_READY() + PyUnicode_IS_ASCII() + PyUnicode_DATA() + PyUnicode_GET_LENGTH() would work, but they are not documented; or possibly also check if the string has a cached UTF-8 representation without populating that cached representation), so that a combination of the check with PyUnicode_AsUTF8String() is rarely or never significantly slower than PyUnicode_AsUTF8AndSize(). ---------- assignee: docs@python components: Documentation, Interpreter Core, Unicode messages: 330249 nosy: Marcin Kowalczyk, docs@python, ezio.melotti, vstinner priority: normal severity: normal status: open title: Please clarify whether PyUnicode_AsUTF8AndSize() or PyUnicode_AsUTF8String() is preferred type: performance versions: Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue35295> _______________________________________

4 9