Mailman 3 February 2020 - docs

[issue38387] Document PyDoc_STRVAR
by Brad Solomon April 26, 2020

April 26, 2020

New submission from Brad Solomon <brad.solomon.1124(a)gmail.com>: The C-API reference would benefit from a short mention of PyDoc_STRVAR usage, since it is used so frequently within Modules/. ---------- assignee: docs@python components: Documentation messages: 354053 nosy: bsolomon1124, docs@python priority: normal pull_requests: 16195 severity: normal status: open title: Document PyDoc_STRVAR type: enhancement _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue38387> _______________________________________

2 6

[issue14759] Berkeley DB License conditions are onerous (and poorly documented)
by Jeff Laing April 26, 2020

April 26, 2020

New submission from Jeff Laing <jefflaing(a)gmail.com>: As part of an audit of license compliance, I was looking at the terms in the LICENSE.txt that describe the Berkeley DB product. I had thought this would be under the standard Berkeley license, but Oracle have added their own zinger. * 3. Redistributions in any form must be accompanied by information on * how to obtain complete source code for the DB software and any * accompanying software that uses the DB software. The source code * must either be included in the distribution or be available for no * more than the cost of distribution plus a nominal fee, and must be * freely redistributable under reasonable conditions. So, my application, which embeds Python (rather than running it as python.exe) and includes the standard runtime library, must distribute my source code. This page: http://mail.python.org/pipermail/python-dev/2008-September/082316.html suggests that this is not the case for regular Python, but it makes no statement about "embedding". Sadly the Oracle page it links to suggesting this is not an issue, does not exist. The general "License" page on the Python websites makes no reference whatsoever to Berkeley DB license obligations. I note that there are other modules mentioned on the Licenses webpage that are not in the LICENSES.txt file, and vice versa. I have no idea whether this is deliberate, or an oversight. ---------- assignee: docs@python components: Documentation messages: 160238 nosy: Jeff.Laing, docs@python priority: normal severity: normal status: open title: Berkeley DB License conditions are onerous (and poorly documented) type: enhancement versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14759> _______________________________________

5 12

[issue22863] https://docs.python.org/ should make a true 2.7.8 version available
by Marc-Andre Lemburg April 26, 2020

April 26, 2020

New submission from Marc-Andre Lemburg: The documentation shown for Python 2.7.8 currently includes 2.7.9 parts, e.g. for the ssl modules (https://docs.python.org/2.7/library/ssl.html). Since there were so many changes to the ssl module for 2.7.9 which are not available in 2.7.8, I think it would be good to be able to not only select "2.7.8" from the doc version drop-down, but to also really get that particular version of the documentation, and provide a separate "2.7.9" snapshop as well. I tried https://docs.python.org/2.7.8/library/ssl.html, but that doesn't seem to exist. PS: I'm not sure whether this is the right tracker to report this. Feel free to move it elsewhere. ---------- assignee: docs@python components: Documentation messages: 231113 nosy: docs@python, lemburg priority: normal severity: normal status: open title: https://docs.python.org/ should make a true 2.7.8 version available versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue22863> _______________________________________

5 6

[issue17904] bytes should be listed as built-in function for 2.7
by Florent Xicluna April 26, 2020

April 26, 2020

New submission from Florent Xicluna: Looking into the summary table, there's no information about the `bytes` built-in alias for `str`: http://docs.python.org/2/library/functions.html IMHO it should appear in this table (as str, unicode, bytearray) with the appropriate `.. versionadded:`. ---------- assignee: docs@python components: Documentation messages: 188349 nosy: docs@python, flox priority: normal severity: normal status: open title: bytes should be listed as built-in function for 2.7 type: behavior versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue17904> _______________________________________

5 6

[issue37626] Documentation：conflict between docs
by 徐靖 April 23, 2020

April 23, 2020

New submission from 徐靖 <shiyuchongf(a)gmail.com>: In https://docs.python.org/3/whatsnew/3.4.html#api-and-feature-removals,It is said "inspect.Signature: positional-only parameters are now required to have a valid name." But in https://docs.python.org/3/library/inspect.html?highlight=3.4#inspect.Signat…, the actual change happened in inspect.Parameter, " Changed in version 3.4: In Python 3.3 Parameter objects were allowed to have name set to None if their kind was set to POSITIONAL_ONLY. This is no longer permitted." So I wonder is it a mistake? ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue37626> _______________________________________

3 3

[issue37846] declare that Text I/O use buffer inside
by Windson Yang April 23, 2020

April 23, 2020

New submission from Windson Yang <wiwindson(a)outlook.com>: At the beginning of https://docs.python.org/3.7/library/io.html#io.RawIOBase, we declared that > Binary I/O (also called buffered I/O) and > Raw I/O (also called unbuffered I/O) But we didn't mention if Text I/O use buffer or not which led to confusion. Even though we talked about it later in https://docs.python.org/3.7/library/io.html#class-hierarchy > The TextIOBase ABC, another subclass of IOBase, deals with streams whose bytes represent text, and handles encoding and decoding to and from strings. TextIOWrapper, which extends it, is a buffered text interface to a buffered raw stream (BufferedIOBase). Finally, StringIO is an in-memory stream for text. IMO, it will be better to declare 'Reads and writes are internally buffered in order to speed things up' at the very beginning in > Text I/O > Text I/O expects and produces str objects... or maybe > class io.TextIOBase > Base class for text streams. This class provides a character and line based interface to stream I/O. It inherits IOBase. There is no public constructor. ---------- assignee: docs@python components: Documentation messages: 349633 nosy: Windson Yang, docs@python priority: normal severity: normal status: open title: declare that Text I/O use buffer inside type: enhancement versions: Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue37846> _______________________________________

2 3

[issue37465] Incorrect documentation for `s#` arguments in C API argument parsing
by Enrico Zini April 23, 2020

April 23, 2020

New submission from Enrico Zini <enrico(a)enricozini.org>: In https://docs.python.org/3.9/c-api/arg.html, in the documentation for parsing argument, there is: s# (str, read-only bytes-like object) [const char *, int or Py_ssize_t] In my amd64 system, `Py_ssize_t` is a different type than `int`, and passing a `Py_ssize_t` causes undefine behaviour. I assume this has been switched to an `int` in the API, and that thisinstance of the documentation has not been updated accordingly. At the bottom of the page in the documentation of `Py_BuildValue`, `s#` is correctly documented as using an `int` and no `Py_ssize_t`, for example. ---------- assignee: docs@python components: Documentation messages: 346974 nosy: docs@python, enrico priority: normal severity: normal status: open title: Incorrect documentation for `s#` arguments in C API argument parsing versions: Python 3.5, Python 3.6, Python 3.7, Python 3.8, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue37465> _______________________________________

5 7

[issue39285] PurePath.match indicates case-sensitive nature and presents a case-insensitive example
by Karthikeyan Singaravelan April 19, 2020

April 19, 2020

New submission from Karthikeyan Singaravelan <tir.karthi(a)gmail.com>: https://docs.python.org/3/library/pathlib.html#pathlib.PurePath.match Under PurePath.match there is a statement that case-sensitivity is followed but presents an example in Windows where case insensitive match returns True. This is confusing since match internally uses fnmatch.fnmatchcase that doesn't normalize case but in Windows files are case insensitive. Either the doc could be clarified that it's platform dependent or present a PosixPath example or present two examples with one for Linux and one for Windows that it's platform dependent. As with other methods, case-sensitivity is observed: >>> PureWindowsPath('b.py').match('*.PY') True ---------- assignee: docs@python components: Documentation messages: 359717 nosy: docs@python, pitrou, serhiy.storchaka, xtreak priority: normal severity: normal status: open title: PurePath.match indicates case-sensitive nature and presents a case-insensitive example type: behavior versions: Python 3.7, Python 3.8, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue39285> _______________________________________

4 7

[issue13743] xml.dom.minidom.Document class is not documented
by Sandro Tosi April 12, 2020

April 12, 2020

New submission from Sandro Tosi <sandro.tosi(a)gmail.com>: Hello, following up http://mail.python.org/pipermail/docs/2012-January/007026.html I noticed the whole Document class (and relative methods) is not documented. Maybe it is a choice to not document it, or maybe it's just a missing doc, dunno, the's why I'm opening this :) ---------- assignee: docs@python components: Documentation messages: 150935 nosy: docs@python, sandro.tosi priority: normal severity: normal stage: needs patch status: open title: xml.dom.minidom.Document class is not documented versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13743> _______________________________________

6 9

[issue21760] inspect documentation describes module type inaccurately
by Eric Snow April 11, 2020

April 11, 2020

New submission from Eric Snow: In the documentation for the inspect module, the module type is described with just 2 of its potential 7 attributes. The language reference[2] and importlib docs[3] both provide an accurate list of module attributes. Furthermore, the description for __file__ should be fixed. It should be clear that __file__ reflects the location from which the module was loaded, that location is not necessarily a filename, and the attribute may not exist if the module was not loaded from a specific location (e.g. builtin and frozen modules). The same goes for __cached__ [1] https://docs.python.org/dev/library/inspect.html#types-and-members [2] https://docs.python.org/3/reference/import.html#import-related-module-attri… [3] https://docs.python.org/3/library/importlib.html#importlib.machinery.Module… ---------- assignee: docs@python components: Documentation messages: 220576 nosy: docs@python, eric.snow priority: normal severity: normal stage: needs patch status: open title: inspect documentation describes module type inaccurately versions: Python 3.4, Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue21760> _______________________________________

4 5