docs October 2020

docs@python.org

14 participants
291 discussions

[issue39090] Document various options for getting the absolute path from pathlib.Path objects

by Brett Cannon

New submission from Brett Cannon <brett(a)python.org>: The question on how best to get an absolute path from a pathlib.Path object keeps coming up (see https://bugs.python.org/issue29688, https://discuss.python.org/t/add-absolute-name-to-pathlib-path/2882/, and https://discuss.python.org/t/pathlib-absolute-vs-resolve/2573 as examples). As pointed out across those posts, getting the absolute path is surprisingly subtle and varied depending on your needs. As such we should probably add a section somewhere in the pathlib docs explaining the various ways and why you would choose one over the other. ---------- assignee: docs@python components: Documentation messages: 358638 nosy: brett.cannon, docs@python priority: normal severity: normal stage: needs patch status: open title: Document various options for getting the absolute path from pathlib.Path objects type: enhancement _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue39090> _______________________________________

23 minutes

[issue16954] Add docstrings for ElementTree module

by Serhiy Storchaka

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> _______________________________________

2 days, 23 hours

[issue27646] yield from expression can be any iterable

by Terry J. Reedy

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 days, 12 hours

[issue13433] String format documentation contains error regarding %g

by Christian Iversen

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 days

[issue29086] Document C API that is not part of the limited API

by Serhiy Storchaka

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> _______________________________________

6 days, 4 hours

[issue20364] Rename & explain sqlite3.Cursor.execute 'parameters' param

by Terry J. Reedy

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> _______________________________________

1 week, 1 day

[issue35026] Winreg's documentation lacks mentioning required permission at some points

by George Fischhof

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> _______________________________________

1 week, 1 day

[issue32824] Docs: Using Python on a Macintosh has bad info per Apple site

by Frank Griswold

New submission from Frank Griswold <py.griswolf(a)spamgourmet.com>: This chunk of docs has bad info in both Python2 and Python3 docs: 4.1.3. Configuration Python on OS X honors all standard Unix environment variables such as PYTHONPATH, but setting these variables for programs started from the Finder is non-standard as the Finder does not read your .profile or .cshrc at startup. You need to create a file ~/.MacOSX/environment.plist. See Apple’s Technical Document QA1067 for details. If you search for QA1067, you are informed that the document is legacy and unsupported, with a suggestion for where to look now. That suggested link leads to a 404. Searching the apple site, I find that at least some thoughtful developers think that configuring the environment isn't even possible, generally; and isn't considered good form even if so. Here: https://forums.developer.apple.com/message/217422 I have no problem setting things for my terminal, as a longtime (unix) user, but for others, this section probably needs a complete examination with an eye toward making it current. quite possibly by reorganizing it. ---------- assignee: docs@python components: Documentation messages: 312023 nosy: docs@python, griswolf priority: normal severity: normal status: open title: Docs: Using Python on a Macintosh has bad info per Apple site type: enhancement _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue32824> _______________________________________

2 weeks, 2 days

[issue35295] Please clarify whether PyUnicode_AsUTF8AndSize() or PyUnicode_AsUTF8String() is preferred

by Marcin Kowalczyk

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> _______________________________________

2 weeks, 5 days

[issue20464] Update distutils sample config file in Doc/install/index.rst

by Zachary Ware

New submission from Zachary Ware: >From docs@: On Thu, Jan 16, 2014 at 2:56 AM, Peter Bröcker <peter.broecker(a)uni-koeln.de> wrote: > Hi, > > I have tried to set up the distutils config files for a custom module > installation. Using the suggested snippet from > > http://docs.python.org/2/install/ > > [install] > install-base=$HOME/python > install-purelib=lib > install-platlib=lib.$PLAT > install-scripts=scripts > install-data=data did not work for me. > > Instead, I had to add install-headers and additionally modify all paths > to include $base: > > [install] > install-base=/some/dir > install-purelib=$base/lib > install-platlib=$base/lib.$PLAT > install-scripts=$base/scripts > install-headers=$base/include > install-data=$base/data > > > I'm unsure if this is actually a bug, but I could only resolve this with > the help of this answer on stackoverflow: > http://stackoverflow.com/a/12768721 > > Best regards, > Peter ---------- assignee: docs@python components: Distutils, Documentation messages: 209829 nosy: docs@python, zach.ware priority: normal severity: normal stage: test needed status: open title: Update distutils sample config file in Doc/install/index.rst type: behavior versions: Python 2.7, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue20464> _______________________________________

2 weeks, 6 days

Jump to page:

2021

2020

2019

2018

2017

2016

2015

2014

2013

2012

2011

2010

docs October 2020