Mailman 3 January 2020 - docs

[issue39199] Improve the AST documentation
by Pablo Galindo Salgado March 3, 2021

March 3, 2021

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 … [View More]

2 9

[issue24650] Error in yield expression documentation
by swanson Feb. 27, 2021

Feb. 27, 2021

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 … [View More]

4 4

[issue29045] Outdated C api doc about Windows error
by Xiang Zhang Feb. 26, 2021

Feb. 26, 2021

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: … [View More]

2 3

[issue24045] Behavior of large returncodes (sys.exit(nn))
by Ethan Furman Feb. 26, 2021

Feb. 26, 2021

New submission from Ethan Furman: Not sure if this is a bug, or just One of Those Things: sys.exit(large_value) can wrap around if the value is too large, but this is O/S dependent. linux (ubuntu 14.04) $ python Python 2.7.8 (default, Oct 20 2014, 15:05:29) [GCC 4.9.1] on linux2 Type "help", "copyright", "credits" or "license" for more information. --> import sys --> sys.exit(256) $ echo $? 0 $ python Python 2.7.8 (default, Oct 20 2014, 15:05:29) [GCC 4.9.1] … [View More]

4 5

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

Feb. 24, 2021

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 … [View More]

4 6

[issue16954] Add docstrings for ElementTree module
by Serhiy Storchaka Feb. 21, 2021

Feb. 21, 2021

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… [View More]

8 23

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

Feb. 21, 2021

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. … [View More]

3 8

[issue13433] String format documentation contains error regarding %g
by Christian Iversen Feb. 18, 2021

Feb. 18, 2021

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: >>> "… [View More]

6 11

[issue29086] Document C API that is not part of the limited API
by Serhiy Storchaka Feb. 18, 2021

Feb. 18, 2021

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 "… [View More]

5 6

[issue35295] Please clarify whether PyUnicode_AsUTF8AndSize() or PyUnicode_AsUTF8String() is preferred
by Marcin Kowalczyk Feb. 5, 2021

Feb. 5, 2021

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 … [View More]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> _______________________________________ [View Less]

4 9