Mailman 3 February 2020 - docs

[issue39634] Add clarification in documentation for heapq.heapify naming
by Steven D'Aprano 15 Feb '20

15 Feb '20

Change by Steven D'Aprano <steve+python(a)pearwood.info>: ---------- nosy: +rhettinger _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue39634> _______________________________________

1 0

[issue39634] Add clarification in documentation for heapq.heapify naming
by Steven D'Aprano 15 Feb '20

15 Feb '20

Change by Steven D'Aprano <steve+python(a)pearwood.info>: ---------- assignee: -> docs@python components: +Documentation -Library (Lib) nosy: +docs@python title: Add clarification in documentation for incorrect heapq heapify naming -> Add clarification in documentation for heapq.heapify naming type: -> enhancement _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue39634> _______________________________________

1 0

Portuguese-br translation problem
by Mateus Fernandes Réu Urban 14 Feb '20

14 Feb '20

Hello, I was studying Python documentation to learn about it and found a mistake in the translation of the third item from the 'try' statement how does it work on item 8.3 Handling Exceptions. In portuguese, instead of saying "Se ocorrer uma execução" should be "Se ocorrer uma exceção" that would be the correct translation for "If an exception occurs" Thanks, Mateus ------------------------------------------------------------------------------------------------ Mateus Fernandes Réu Urban Universidade Federal de São Paulo - UNIFESP Instituto de Ciência e Tecnologia - ICT ------------------------------------------------------------------------------------------------

1 0

[issue9305] Don't use east/west of UTC in date/time documentation
by Alexander Belopolsky 14 Feb '20

14 Feb '20

New submission from Alexander Belopolsky <belopolsky(a)users.sourceforge.net>: I am opening this to supersede issue7229. See discussion following msg107148. In many places offsets representing the difference between local time and UTC are described as minutes or seconds east or west of UTC. This is not correct because UTC is not a place and minutes and seconds don't measure distance in this context. Replacing UTC with the Prime Meridian will not fix that because some regions in the western hemisphere use positive offsets from UTC. or example, Madrid is at 3° 42' West, but uses Central European Time which is UTC+1. I believe geographical references in the python documentation are irrelevant. What users are interested in is how to convert local time to UTC and UTC to local time rather than what is the sign of time.timezone in Madrid. I suggest the following wording for time.timezone description: time.timezone: The number of seconds one must add to the local time to arrive at UTC. Similarly, tzinfo.utcoffset() can be defined as "Returns timedelta one must add to UTC to arrive at local time." ---------- assignee: docs@python components: Documentation keywords: easy messages: 110774 nosy: belopolsky, docs@python priority: normal severity: normal stage: needs patch status: open title: Don't use east/west of UTC in date/time documentation type: feature request versions: Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9305> _______________________________________

15 30

[issue39545] await is not supported in f-string in 3.6
by Serhiy Storchaka 14 Feb '20

14 Feb '20

New submission from Serhiy Storchaka <storchaka+cpython(a)gmail.com>: The following code is compiled in 3.7, but is a syntax error in 3.6. async def f(x): f"{await x}" I have not found mentioning this change in What's New, and it looks grammatically correct. It looks as a bug in 3.6. It may be too later to fix it in 3.6, but at least it should be documented. ---------- assignee: docs@python components: Documentation, Interpreter Core messages: 361317 nosy: docs@python, eric.smith, serhiy.storchaka priority: normal severity: normal status: open title: await is not supported in f-string in 3.6 type: behavior versions: Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue39545> _______________________________________

7 19

[issue39614] Documentation of attribute reference is unclear
by Dirk Herrmann 11 Feb '20

11 Feb '20

New submission from Dirk Herrmann <dirk.herrmann-privat(a)gmx.de>: Trying to understand attribute reference in Python, I was lost: * In the "Python Language Reference" (I will refer to this as PLR, sorry if that is uncommon, did not find an abbreviation in the glossary): Chapter 6.3.1 is about attribute reference. How the attribute reference actually works is not explained in detail, only with the sentence "This object is then asked to produce the attribute whose name is the identifier." which I find vague. Moreover, in PLR 6.3.1 it is said that it can be customized overriding "__getattr__()", but again, details are unclear. And, when following the link to "__getattr__()" it turns out that "__getattr__()" is not called for attribute access, but only in certain circumstances: * PLR 3.3.1 section "object.__getattr__(self, name)" explains that this is only called when "default attribute access" fails. There is nowhere an explanation of "default attribute access", it is also not mentioned in the index. There is some explanation in parentheses what it means if "default attribute access" fails, but the actual procedure of the "default attribute access" is still not clear. A bit further down in this section it is also mentioned that if an attribute is found using the "normal mechanism" then "__getattr__()" is not called - again not explaining what the "normal mechanism" is. There is some reference to "__getattribute__()" here, saying that with "__getattribute__()" there would be "total control over attribute access", but this leads again to confusion: * PLR 3.3.1 section "object.__getattribute__(self, name)" indicates that this "may still be bypassed" in certain circumstances, referring to PLR 3.3.10, special method lookup, which refers to the "conventional lookup process", to which this is an exception. The basis why this is an exception remains unclear - is it that certain method names are detected during attribute reference? Summary: There is not (or I was too stupid to find) a concise description of how attribute reference works. There are several terms used to refer to certain aspects of it: "default attribute access", "normal mechanism [of attribute access]", "conventional lookup process", which may or may not refer to the same thing, which seems not to be documented anyway. ---------- assignee: docs@python components: Documentation messages: 361837 nosy: Dirk Herrmann, docs@python priority: normal severity: normal status: open title: Documentation of attribute reference is unclear type: enhancement versions: Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue39614> _______________________________________

1 0

[issue39574] str.__doc__ is misleading
by Zachary Westrick 11 Feb '20

11 Feb '20

New submission from Zachary Westrick <zackzackzackw(a)gmail.com>: The docstring for the str() builtin reads str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to 'strict'. The statement "encoding defaults to sys.getdefaultencoding()." implies that the encoding argument defaults to sys.getdefaultencoding(), which would typically mean that str(X, encoding=sys.getdefaultencoding()) == str(X) However, this is not the case str(b'mystring', encoding=sys.getdefaultencoding()) -> 'mystring' str(b'mystring') -> "b'mystring'" It seems that the phrase "encoding defaults" is not referring to the argument named encoding. ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue39574> _______________________________________

5 10

[issue38374] Remove weakref.ReferenceError entry from documentation
by Martijn Pieters 11 Feb '20

11 Feb '20

New submission from Martijn Pieters <mj(a)python.org>: The weakref documentation still mentions weakref.ReferenceError: https://docs.python.org/3/library/weakref.html#weakref.ReferenceError But this alias for the built-in ReferenceError exception was removed in the 3.0 development cycle (https://github.com/python/cpython/commit/2633c69fae7e413b2b64b01d8c0c901ae6…), the last version where `weakref.ReferenceError` still exists is Python 2.7. Please remove it, it's just confusing now. ---------- assignee: docs@python components: Documentation messages: 353977 nosy: docs@python, mjpieters priority: normal severity: normal status: open title: Remove weakref.ReferenceError entry from documentation versions: Python 3.6, Python 3.7, Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue38374> _______________________________________

4 8

[issue13826] Having a shlex example in the subprocess.Popen docs is confusing
by Julian Berman 10 Feb '20

10 Feb '20

New submission from Julian Berman <Julian+Python.org(a)GrayVines.com>: The example at http://docs.python.org/dev/library/subprocess.html#popen-constructor seems a bit misplaced, as it seems to suggest that one should use the shlex module. Most of the other examples in the module seem to use a list to provide the args, so if there was a need to just point out that shlex could be used for a corner case perhaps it'd be better suited as a footnote or another subsection somewhere. ---------- assignee: docs@python components: Documentation messages: 151624 nosy: Julian, docs@python priority: normal severity: normal status: open title: Having a shlex example in the subprocess.Popen docs is confusing type: enhancement versions: Python 2.6, Python 2.7, Python 3.1, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13826> _______________________________________

9 14

[issue39594] Typo in documentation for os.times
by Chenyoo Hao 10 Feb '20

10 Feb '20

New submission from Chenyoo Hao <solitaire2312(a)gmail.com>: 1.Formatting error due to an extra space (After the MSDN link). 2.There are extra words. Original： See the Unix manual page :manpage:`times(2)` and :manpage:`times(3)` manual page on Unix or `the GetProcessTimes MSDN <https://docs.microsoft.com/windows/win32/api/processthreadsapi/nf-processth…>` _ on Windows. On Windows, only :attr:`user` and :attr:`system` are known; the other attributes are zero. After modification： See the manual page :manpage:`times(2)` and :manpage:`times(3)` on Unix or the `GetProcessTimes MSDN <https://docs.microsoft.com/windows/win32/api/processthreadsapi/nf-processth…>`_ on Windows. On Windows, only :attr:`user` and :attr:`system` are known; the other attributes are zero. ---------- assignee: docs@python components: Documentation messages: 361659 nosy: Chenyoo Hao, docs@python priority: normal severity: normal status: open title: Typo in documentation for os.times type: enhancement versions: Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue39594> _______________________________________

4 8