Mailman 3 May 2020 - docs

[issue34398] Docs search does not index glossary
by Jonathan Fine 02 Apr '21

02 Apr '21

New submission from Jonathan Fine <jfine2358(a)gmail.com>: The docs contain a very useful page https://docs.python.org/3.5/glossary.html. However, the search feature does not index the glossary. Thus, the search https://docs.python.org/3.5/search.html?q=iterable does not produce the helpful glossary entry === iterable An object capable of returning its members one at a time. Examples of iterables include all sequence types (such as list, str, and tuple) and some non-sequence types like dict, file objects, and objects of any [...] === #788509 is the only docs issue I could find, whose title contains glossary. It gives insight into the thoughts then about the tutorial. In msg44460 Skip Montaro says (1) that the glossary is "for the tutorial", and (2) he'd like to improve links into the tutorial. I suggest that part of the fix for this issue is on the home page page Glossary in the first grouping "Parts of the documentation." ---------- assignee: docs@python components: Documentation messages: 323503 nosy: docs@python, jfine2358 priority: normal severity: normal status: open title: Docs search does not index glossary type: behavior versions: Python 2.7, Python 3.4, Python 3.5, Python 3.6, Python 3.7, Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue34398> _______________________________________

6 12

[issue35026] Winreg's documentation lacks mentioning required permission at some points
by George Fischhof 28 Mar '21

28 Mar '21

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

4 4

[issue39231] Mistaken notion in tutorial
by Robert 27 Mar '21

27 Mar '21

New submission from Robert <freshbob1337(a)gmail.com>: https://docs.python.org/3/tutorial/controlflow.html 4.7.8. Function Annotations [...] "The following example has a positional argument, a keyword argument, and the return value annotated:" It is not a "positional argument" but an "optional argument". ---------- assignee: docs@python components: Documentation messages: 359443 nosy: docs@python, r0b priority: normal severity: normal status: open title: Mistaken notion in tutorial type: enhancement _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue39231> _______________________________________

5 9

[issue39616] SSLContext.check_hostname description is inaccurate wrt match_hostname
by Ville Skyttä 27 Mar '21

27 Mar '21

New submission from Ville Skyttä <ville.skytta(a)iki.fi>: Doc says "Whether to match the peer cert’s hostname with match_hostname() in SSLSocket.do_handshake()." but match_hostname() is no longer used to do that in the first place, OpenSSL is used for that. check_hostname affects the OpenSSL usage, too. ---------- assignee: docs@python components: Documentation messages: 361892 nosy: docs@python, scop priority: normal severity: normal status: open title: SSLContext.check_hostname description is inaccurate wrt match_hostname type: enhancement _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue39616> _______________________________________

3 7

[issue39369] Doc: Update mmap readline method documentation
by Wellington PF 26 Mar '21

26 Mar '21

New submission from Wellington PF <wellpardim10(a)gmail.com>: Update mmap readline method description. The fact that the readline method does update the file position should not be ignored since this might give the impression for the programmer that it doesn't update it. ---------- assignee: docs@python components: Documentation messages: 360191 nosy: docs@python, wellpardim priority: normal pull_requests: 17435 severity: normal status: open title: Doc: Update mmap readline method documentation type: enhancement _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue39369> _______________________________________

3 2

[issue21297] skipinitialspace in the csv module only skips spaces, not "whitespace" in general
by Daniel Andersson 25 Mar '21

25 Mar '21

New submission from Daniel Andersson: Regarding the `skipinitialspace` parameter to the different CSV reader dialects in the `csv` module, the official documentation asserts: When True, whitespace immediately following the delimiter is ignored. and the `help(csv)` style module documentation says: * skipinitialspace - specifies how to interpret whitespace which immediately follows a delimiter. It defaults to False, which means that whitespace immediately following a delimiter is part of the following field. "Whitespace" is a bit too general in both cases (at least a red herring in the second case), since it only skips spaces and not e.g. tabs [1]. In `Modules/_csv.c`, it more correctly describes the parameter. At line 81: int skipinitialspace; /* ignore spaces following delimiter? */ and the actual implementation at line 638: else if (c == ' ' && dialect->skipinitialspace) /* ignore space at start of field */ ; No-one will probably assume that the whole UTF-8 spectrum of "whitespace" is skipped, but at least I initially assumed that the tab character was included. [1]: http://en.wikipedia.org/wiki/Whitespace_character ---------- assignee: docs@python components: Documentation, Library (Lib) messages: 216780 nosy: Daniel.Andersson, docs@python priority: normal severity: normal status: open title: skipinitialspace in the csv module only skips spaces, not "whitespace" in general type: behavior versions: Python 2.7, Python 3.1, Python 3.2, Python 3.3, Python 3.4, Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue21297> _______________________________________

6 9

[issue37405] socket.getsockname() returns string instead of tuple
by Brent Gardner 23 Mar '21

23 Mar '21

New submission from Brent Gardner <bggardner(a)gmail.com>: In Python 3.5.3, a socket with type AF_CAN returns a tuple in the form `(interface, )` from getsockname(). In Python 3.7.3, getsockname() returns a string (the name of the interface). The documentation states "a tuple is used for the AF_CAN address family". The string will break code that worked in 3.5.3 by raising errors such as "Value Error: too many values to unpack (expected 2)". Example: #3.5.3 import socket s = socket.socket(socket.AF_CAN, socket.SOCK_RAW, socket.CAN_RAW) s.bind(('vcan0',)) # requires tuple s.getsockname() # returns tuple: ('vcan0', 29) #3.7.3 import socket s = socket.socket(socket.AF_CAN, socket.SOCK_RAW, socket.CAN_RAW) s.bind(('vcan0',)) # requires tuple s.getsockname() # returns string: 'vcan0' ---------- assignee: docs@python components: Documentation messages: 346559 nosy: Brent Gardner, docs@python priority: normal severity: normal status: open title: socket.getsockname() returns string instead of tuple versions: Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue37405> _______________________________________

6 11

[issue35118] Add peek() or first() method in queue
by Windson Yang 23 Mar '21

23 Mar '21

New submission from Windson Yang <wiwindson(a)gmail.com>: I found other languages like Java and C++ have the method to access the first value in Queue like first() and peek(). Since we use deque_ to create Queue now, it's easy to implement in python using the index. Otherwise, we can add this to the document? I also found some discussion_ here. .. _deque: https://github.com/python/cpython/blob/master/Lib/queue.py#L205 .. _discussion https://mail.python.org/pipermail/python-list/2010-March/569930.html ---------- assignee: docs@python components: Documentation messages: 328963 nosy: Windson Yang, docs@python priority: normal severity: normal status: open title: Add peek() or first() method in queue type: enhancement versions: Python 2.7, Python 3.4, Python 3.5, Python 3.6, Python 3.7, Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue35118> _______________________________________

3 11

[issue37860] Add netlify deploy preview for docs
by Ashwin Ramaswami 22 Mar '21

22 Mar '21

New submission from Ashwin Ramaswami <aramaswamis(a)gmail.com>: It would be good to preview the cpython documentation on PRs using Netlify. See https://github.com/python/core-workflow/issues/348 ---------- assignee: docs@python components: Documentation messages: 349752 nosy: docs@python, epicfaace priority: normal severity: normal status: open title: Add netlify deploy preview for docs versions: Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue37860> _______________________________________

6 15

[issue37205] time.perf_counter() is not system-wide on Windows, in disagreement with documentation
by Ken Healy 21 Mar '21

21 Mar '21

New submission from Ken Healy <healykb+pythonbugs(a)gmail.com>: The documentation for time.perf_counter() indicates it should return a system-wide value: https://docs.python.org/3/library/time.html#time.perf_counter This is not true on Windows, as a process-specific offset is subtracted from the underlying QueryPerformanceCounter() value. The code comments indicate this is to reduce precision loss: https://github.com/python/cpython/blob/master/Python/pytime.c#L995-L997 This is relevant in multiprocess applications, where accurate timing is required across multiple processes. Here is a simple test case: ----------------------------------------------------------- import concurrent.futures import time def worker(): return time.perf_counter() if __name__ == '__main__': pool = concurrent.futures.ProcessPoolExecutor() futures = [] for i in range(3): print('Submitting worker {:d} at time.perf_counter() == {:.3f}'.format(i, time.perf_counter())) futures.append(pool.submit(worker)) time.sleep(1) for i, f in enumerate(futures): print('Worker {:d} started at time.perf_counter() == {:.3f}'.format(i, f.result())) ----------------------------------------------------------- Output: ----------------------------------------------------------- C:\...>Python37\python.exe -VV Python 3.7.3 (v3.7.3:ef4ec6ed12, Mar 25 2019, 22:22:05) [MSC v.1916 64 bit (AMD64)] C:\...>Python37\python.exe perf_counter_across_processes.py Submitting worker 0 at time.perf_counter() == 0.376 Submitting worker 1 at time.perf_counter() == 1.527 Submitting worker 2 at time.perf_counter() == 2.529 Worker 0 started at time.perf_counter() == 0.380 Worker 1 started at time.perf_counter() == 0.956 Worker 2 started at time.perf_counter() == 1.963 ----------------------------------------------------------- See my stackoverflow question for a comparison with Linux: https://stackoverflow.com/questions/56502111/should-time-perf-counter-be-co… ---------- assignee: docs@python components: Documentation, Library (Lib), Windows messages: 345057 nosy: docs@python, kh90909, paul.moore, steve.dower, tim.golden, vstinner, zach.ware priority: normal severity: normal status: open type: behavior 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/issue37205> _______________________________________

6 18