Mailman 3 January 2021 - docs

[issue22128] patch: steer people away from codecs.open
by Frank van Dijk 17 Apr '21

17 Apr '21

New submission from Frank van Dijk: stackoverflow.com has a zillion answers recommending the use of codecs.open() as a unicode capable drop in replacement for open(). This probably means that there is still a lot of code being written that uses codecs.open(). That's bad thing because of codecs.open()'s lack of newline conversion. A lot of that code will - have compatibility issues when it is moved between unix and windows - silently break text files on windows, leading to issues further downstream (confusing other tools, messing up revision control histories) The problem has been fixed with io.open() in 2.x and open() in 3.x. Unfortunately the 2.7 unicode HOWTO still recommends the use of codecs.open(). The 2.7 and the 3.x documentation of codecs.open() doesn't refer the reader to better alternatives. The attached patches fix that. The only downside I see is that newly written code that uses the better alternatives would be incompatible with 2.5 and older. However croaking on a small minority of systems is better than silently disrupting workflows, causing platform incompatibilities, and inviting flaky workarounds. The 2.7 patch makes the unicode HOWTO recommend io.open() instead of codecs.open(). Both patches change the codecs.open() documentation to refer to io.open() or (on 3.x) open(). Additionally I removed the "data loss" explanation from codecs.open()'s note about its lack of newline conversion. It is not particularly helpful information and it is not entirely correct (data loss could also have been avoided by doing newline conversion before encoding and after decoding) ---------- assignee: docs@python components: Documentation files: codecsopen2.patch keywords: patch messages: 224632 nosy: Frank.van.Dijk, docs@python priority: normal severity: normal status: open title: patch: steer people away from codecs.open type: behavior versions: Python 2.7, Python 3.4, Python 3.5 Added file: http://bugs.python.org/file36234/codecsopen2.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue22128> _______________________________________

7 11

[issue42037] Documentation confusion in CookieJar functions
by Markus Israelsson 15 Apr '21

15 Apr '21

New submission from Markus Israelsson <markus.israelsson(a)surgicalscience.com>: The documentation in https://docs.python.org/3.8/library/http.cookiejar.html#http.cookiejar.Cook… claims the following for functions add_cookie_header and extract_cookies. *** The request object (usually a urllib.request.Request instance) must support the methods get_full_url(), get_host(), get_type(), unverifiable(), has_header(), get_header(), header_items(), add_unredirected_header() and origin_req_host attribute as documented by urllib.request. *** When reading the documentation for Request Objects https://docs.python.org/3.8/library/urllib.request.html?highlight=requests#… there is this: *** Changed in version 3.4: The request methods add_data, has_data, get_data, get_type, get_host, get_selector, get_origin_req_host and is_unverifiable that were deprecated since 3.3 have been removed. *** So basically the documentation claims that if the request object does not support functions that are removed then the headers will not be added. The code itself seem to do the correct thing however and add the header. ---------- assignee: docs@python components: Documentation messages: 378624 nosy: docs@python, markus priority: normal severity: normal status: open title: Documentation confusion in CookieJar functions type: enhancement versions: Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue42037> _______________________________________

4 10

[issue40006] enum: Add documentation for _create_pseudo_member_ and composite members
by Ram Rachum 15 Apr '21

15 Apr '21

New submission from Ram Rachum <ram(a)rachum.com>: Looking at the enum source code, there's a method `_create_pseudo_member_` that's used in a bunch of places. Its docstring says "Create a composite member iff value contains only members", which would have been useful if I had any idea what "composite member" meant. It would be good if the documentation for the enum module would include more information about these two concepts. ---------- assignee: docs@python components: Documentation messages: 364561 nosy: cool-RR, docs@python priority: normal severity: normal status: open title: enum: Add documentation for _create_pseudo_member_ and composite members type: enhancement versions: Python 3.8, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue40006> _______________________________________

3 4

[issue37741] importlib.metadata docs not showing up in the module index
by Brett Cannon 15 Apr '21

15 Apr '21

New submission from Brett Cannon <brett(a)python.org>: If you look at https://docs.python.org/3.9/py-modindex.html#cap-i you will see that importlib.metadata isn't listed (same goes for the 3.8 docs). Or are you leaving it out due to it being provisional? ---------- assignee: docs@python components: Documentation messages: 348872 nosy: barry, brett.cannon, docs@python, jaraco priority: normal severity: normal status: open title: importlib.metadata docs not showing up in the module index versions: Python 3.8, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue37741> _______________________________________

7 19

[issue28197] range.index mismatch with documentation
by Vedran Čačić 14 Apr '21

14 Apr '21

New submission from Vedran Čačić: Look at this: >>> from collections.abc import Sequence >>> help(Sequence.index) index(self, value, start=0, stop=None) S.index(value, [start, [stop]]) -> integer -- return first index of value. Raises ValueError if the value is not present. >>> issubclass(range, Sequence) True >>> help(range.index) index(...) rangeobject.index(value, [start, [stop]]) -> integer -- return index of value. Raise ValueError if the value is not present. So far, so good. But: >>> range(9).index(2, 1, 5) TypeError: index() takes exactly one argument (3 given) Of course it's not essential, but the docs shouldn't lie. And if range _is_ a Sequence, then it should have the complete interface of a Sequence. Including start and end arguments for .index: they are optional from the point of call, not from the point of implementation. :-) ---------- assignee: docs@python components: Documentation, Library (Lib) messages: 276908 nosy: docs@python, veky priority: normal severity: normal status: open title: range.index mismatch with documentation type: behavior versions: Python 3.5, Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue28197> _______________________________________

6 17

[issue20364] Rename & explain sqlite3.Cursor.execute 'parameters' param
by Terry J. Reedy 14 Apr '21

14 Apr '21

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

7 12

[issue39774] Missing documentation on how to make package executable as script
by igo95862 12 Apr '21

12 Apr '21

New submission from igo95862 <igo9586(a)gmail.com>: This is package documentation: https://docs.python.org/3/tutorial/modules.html#packages To make package executable (python -m package) you need to create a file __main__.py in the package directory. This is pretty much not documented anyone aside of trying to run a package missing __main__.py This page already contains information on how to make module executable. (https://docs.python.org/3/tutorial/modules.html#executing-modules-as-scripts) ---------- assignee: docs@python components: Documentation messages: 362790 nosy: docs@python, igo95862 priority: normal severity: normal status: open title: Missing documentation on how to make package executable as script type: enhancement versions: Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue39774> _______________________________________

3 3

[issue39125] Type signature of @property not shown in help()
by Nguyễn Gia Phong 11 Apr '21

11 Apr '21

New submission from Nguyễn Gia Phong <vn.mcsinyx(a)gmail.com>: Dear Maintainer, I want to request a feature on the generative documentation of type-hinting. As of December 2019, I believe there is no support for generating such information in help(). For demonstration, I have this tiny piece of code class Foo: @property def bar(self) -> int: return 42 @bar.setter def bar(self, value: int) -> None: pass def baz(self, arg: float) -> str: pass whose documentation on CPython 3.7.5 (on Debian testing amd64 if that matters) is generated as class Foo(builtins.object) | Methods defined here: | | baz(self, arg: float) -> str | | ---------------------------------------------------------------------- | Data descriptors defined here: | | __dict__ | dictionary for instance variables (if defined) | | __weakref__ | list of weak references to the object (if defined) | | bar I expect the documentation for bar to be as informative as bar, i.e. something similar to ``bar: int''. As pointed out by ChrisWarrick on freenode#python, the annotations are already present, yet help() is not making use of them: >>> Foo.bar.fget.__annotations__ {'return': <class 'int'>} >>> Foo.bar.fset.__annotations__ {'value': <class 'int'>, 'return': None} Have a Merry Christmas or other holiday of your choice, Nguyễn Gia Phong ---------- assignee: docs@python components: Documentation messages: 358823 nosy: McSinyx, docs@python priority: normal severity: normal status: open title: Type signature of @property not shown in help() type: enhancement 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/issue39125> _______________________________________

4 5

[issue38963] multiprocessing processes seem to "bleed" user information (GID/UID/groups)
by Roman Joost 09 Apr '21

09 Apr '21

New submission from Roman Joost <roman(a)bromeco.de>: When running a process which changes UID/GID, some of the following processes will run as the user I change to per process. In order to reproduce (see the attached reproducer): 1. Change the 'USERNAME' to an unprivileged user on your system. 2. Run the reproducer as a user with elevated privileges (e.g. root or some secondary user you have on your system). Mind you, I don't think the user you run as needs elevated privileges, but that's the user I ran as when I observed this behaviour. 3. The reproducer iterates over a list (It stems from a test function which was checking permissions on log files). Observe the print out, which prints the process' GID, UID and secondary groups before we're changing to the users GID, UID and secondary groups. 4. You should observe that at some point the process prints the user information of the user we want to change to not the one which initially started the script. Example output when running locally as root: ('B', (0, 0, [0])) ('A', (0, 0, [0])) ('C', (0, 0, [0])) ('E', (0, 0, [0])) ('D', (0, 0, [0])) ('F', (1002, 1002, [10, 135, 1000, 1002])) ('H', (1002, 1002, [10, 135, 1000, 1002])) ('I', (1002, 1002, [10, 135, 1000, 1002])) ('J', (1002, 1002, [10, 135, 1000, 1002])) ('G', (1002, 1002, [10, 135, 1000, 1002])) ('K', (1002, 1002, [10, 135, 1000, 1002])) ('L', (1002, 1002, [10, 135, 1000, 1002])) ('M', (1002, 1002, [10, 135, 1000, 1002])) ('N', (1002, 1002, [10, 135, 1000, 1002])) I would have expected `0` all the way through. However, if I initialise the Pool with `maxtasksperchild=1` the isolation seems as expected. I don't know whether this is a bug or I'm foolish to invoke multiprocessing like this. I've run out of time to investigate this further. It's certainly strange behaviour to me and I thought I better report it, since reproducing seems fairly deterministic. ---------- assignee: docs@python components: Documentation, Library (Lib) files: reproducer.py messages: 357773 nosy: docs@python, romanofski priority: normal severity: normal status: open title: multiprocessing processes seem to "bleed" user information (GID/UID/groups) type: behavior versions: Python 3.6, Python 3.7 Added file: https://bugs.python.org/file48753/reproducer.py _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue38963> _______________________________________

2 1

[issue42999] `pathlib.Path.link_to()` documentation is misleading
by Barney Gale 07 Apr '21

07 Apr '21

New submission from Barney Gale <barney.gale(a)gmail.com>: Compare the documentation of `symlink_to()` and `link_to()`: .. method:: Path.symlink_to(target, target_is_directory=False) Make this path a symbolic link to *target*. .. method:: Path.link_to(target) Create a hard link pointing to a path named *target*. In fact, `link_to()` does something like: Make *target* a hard link to this path. Which is unexpected given the naming and inconsistency with `symlink_to()`, but it's the way the current implementation works, and so the documentation should reflect that. Adding a replacement `hardlink_to()` function is covered here in bpo-39950. ---------- assignee: docs@python components: Documentation messages: 385474 nosy: barneygale, docs@python priority: normal severity: normal status: open title: `pathlib.Path.link_to()` documentation is misleading type: behavior _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue42999> _______________________________________

3 9

[issue41283] The parameter name for imghdr.what in the documentation is wrong
by Adam Eltawla 02 Apr '21

02 Apr '21

New submission from Adam Eltawla <bekerpico(a)gmail.com>: I noticed the parameter name for imghdr.what in the documentation is wrong Link: https://docs.python.org/3.8/library/imghdr.html?highlight=imghdr function imghdr.what(filename, h=None) In reality: def what(file, h=None): It is 'file' not 'filename'. ---------- assignee: docs@python components: Documentation messages: 373551 nosy: aeltawela, docs@python priority: normal severity: normal status: open title: The parameter name for imghdr.what in the documentation is wrong type: enhancement versions: Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue41283> _______________________________________

3 4

[issue40932] subprocess docs don't qualify the instruction to use shlex.quote by OS
by Stephen Farris 02 Apr '21

02 Apr '21

New submission from Stephen Farris <stephen.farris(a)jhuapl.edu>: The subprocess docs state: "When using shell=True, the shlex.quote() function can be used to properly escape whitespace and shell metacharacters in strings that are going to be used to construct shell commands." While this is true on Unix, it is not true on Windows. On Windows it is easy to create scenarios where shell injection still exists despite using shlex.quote properly (e.g. subprocess.run(shlex.quote("'&calc '"), shell=True) launches the Windows calculator, which it wouldn't do if shlex.quote was able to prevent shell injection on Windows). While the shlex docs state that shlex is for Unix, the subprocess docs imply that shlex.quote will work on Windows too, possibly leading some developers to erroneously use shlex.quote on Windows to try to prevent shell injection. Recommend: 1) qualifying the above section in the subprocess docs to make it clear that this only works on Unix, and 2) updating the shlex docs with warnings that shlex.quote in particular is not for use on Windows. ---------- assignee: docs@python components: Documentation messages: 371140 nosy: Stephen Farris, docs@python priority: normal severity: normal status: open title: subprocess docs don't qualify the instruction to use shlex.quote by OS versions: Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue40932> _______________________________________

6 8

[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 26 Mar '21

26 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

[issue42444] pathlib.PurePath properties annotated with .. data directive
by Paul Ganssle 22 Mar '21

22 Mar '21

New submission from Paul Ganssle <p.ganssle(a)gmail.com>: Currently, it seems that the pathlib module uses `.. data::` to annotate the properties of the PurePath type (e.g. .parts, .drive, .root, etc). See: https://github.com/python/cpython/blob/ff420f0e08a2443339da0df7ace95e14177b… According to the documentation (https://devguide.python.org/documenting/#information-units), `data` is for module-level constants, specifically: > Describes global data in a module, including both variables and values used > as “defined constants.” Class and object attributes are not documented using > this directive. I believe that we should switch these over to use the `.. attribute:` directive instead. >From what I can tell, you can still link to these attributes using the `:attr:` role. I haven't checked if you can link to `:attribute:`s using the `:data:` role, though. If not, it might break some links to change these to `:attribute:`. ---------- assignee: docs@python components: Documentation messages: 381673 nosy: docs@python, eric.araujo, ezio.melotti, mdk, p-ganssle, willingc priority: low severity: normal status: open title: pathlib.PurePath properties annotated with .. data directive versions: Python 3.10 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue42444> _______________________________________

2 1

[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

[issue37891] Exceptions tutorial page does not mention raise from
by Niels Albers 21 Mar '21

21 Mar '21

New submission from Niels Albers <nralbers(a)gmail.com>: raise <Exception> from <exception instance> has been in the language since python 3, yet the tutorial page teaching about exceptions does not mention it. (see https://docs.python.org/3.7/tutorial/errors.html#raising-exceptions) It would be especially helpful to language newcomers to touch on the possibility of passing error context when raising a new exception in an exception handler. ---------- assignee: docs@python components: Documentation messages: 349994 nosy: Niels Albers, docs@python priority: normal severity: normal status: open title: Exceptions tutorial page does not mention raise from 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/issue37891> _______________________________________

4 7

[issue14189] Documentation for some C APIs is missing clear specification of the type of reference they return
by Baruch Sterin 21 Mar '21

21 Mar '21

New submission from Baruch Sterin <python(a)bsterin.com>: In addition to the description text, most C API functions have a one-line, emphasized specification whether they return a new or a borrowed reference. (e.g. 'Return value: New reference.'). The following API functions are missing that. Some of them, like PyMemoryView_FromBuffer(), have descriptions that are clear, but it would still be nice to have an unambiguous statement like most other API functions have. The list has been generated automatically, so it might contain some errors. Doc/c-api/arg.rst: Py_VaBuildValue Doc/c-api/buffer.rst: PyMemoryView_FromBuffer Doc/c-api/buffer.rst: PyMemoryView_FromObject Doc/c-api/buffer.rst: PyMemoryView_GetContiguous Doc/c-api/bytearray.rst: PyByteArray_Concat Doc/c-api/bytearray.rst: PyByteArray_FromObject Doc/c-api/bytearray.rst: PyByteArray_FromStringAndSize Doc/c-api/code.rst: PyCode_New Doc/c-api/codec.rst: PyCodec_BackslashReplaceErrors Doc/c-api/codec.rst: PyCodec_Decode Doc/c-api/codec.rst: PyCodec_Decoder Doc/c-api/codec.rst: PyCodec_Encode Doc/c-api/codec.rst: PyCodec_Encoder Doc/c-api/codec.rst: PyCodec_IgnoreErrors Doc/c-api/codec.rst: PyCodec_IncrementalDecoder Doc/c-api/codec.rst: PyCodec_IncrementalEncoder Doc/c-api/codec.rst: PyCodec_LookupError Doc/c-api/codec.rst: PyCodec_ReplaceErrors Doc/c-api/codec.rst: PyCodec_StreamReader Doc/c-api/codec.rst: PyCodec_StreamWriter Doc/c-api/codec.rst: PyCodec_StrictErrors Doc/c-api/codec.rst: PyCodec_XMLCharRefReplaceErrors Doc/c-api/exceptions.rst: PyUnicodeDecodeError_Create Doc/c-api/exceptions.rst: PyUnicodeDecodeError_GetEncoding Doc/c-api/exceptions.rst: PyUnicodeDecodeError_GetObject Doc/c-api/exceptions.rst: PyUnicodeDecodeError_GetReason Doc/c-api/exceptions.rst: PyUnicodeEncodeError_Create Doc/c-api/exceptions.rst: PyUnicodeTranslateError_Create Doc/c-api/float.rst: PyFloat_GetInfo Doc/c-api/import.rst: PyImport_GetImporter Doc/c-api/import.rst: PyImport_ImportModuleNoBlock Doc/c-api/import.rst: _PyImport_FindExtension Doc/c-api/import.rst: _PyImport_FixupExtension Doc/c-api/init.rst: PyEval_GetCallStats Doc/c-api/int.rst: PyInt_FromSize_t Doc/c-api/long.rst: PyLong_FromSize_t Doc/c-api/long.rst: PyLong_FromSsize_t Doc/c-api/number.rst: PyNumber_Index Doc/c-api/number.rst: PyNumber_ToBase Doc/c-api/object.rst: PyObject_Bytes Doc/c-api/object.rst: PyObject_GenericGetAttr Doc/c-api/unicode.rst: PyUnicode_AsUTF32String Doc/c-api/unicode.rst: PyUnicode_DecodeMBCSStateful Doc/c-api/unicode.rst: PyUnicode_DecodeUTF32 Doc/c-api/unicode.rst: PyUnicode_DecodeUTF32Stateful Doc/c-api/unicode.rst: PyUnicode_DecodeUTF7 Doc/c-api/unicode.rst: PyUnicode_DecodeUTF7Stateful Doc/c-api/unicode.rst: PyUnicode_EncodeUTF32 Doc/c-api/unicode.rst: PyUnicode_EncodeUTF7 Doc/c-api/veryhigh.rst: PyEval_EvalCodeEx Doc/c-api/veryhigh.rst: PyEval_EvalFrame Doc/c-api/veryhigh.rst: PyEval_EvalFrameEx ---------- assignee: docs@python components: Documentation messages: 154877 nosy: baruch.sterin, docs@python priority: normal severity: normal status: open title: Documentation for some C APIs is missing clear specification of the type of reference they return type: behavior versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14189> _______________________________________

9 9