Mailman 3 July 2021 - Docs-bugs

[issue44135] issubclass documentation doesn't explain tuple semantic
by João Henrique Pimentel Aug. 31, 2021

Aug. 31, 2021

New submission from João Henrique Pimentel <joaozinho(a)gmail.com>: The second parameter (classinfo) of the issubclass built-in function can be a Tuple and, starting from 3.10, it can be a Union Type as well. The documentation states that in these cases "every entry in classinfo will be checked", but it doesn't explain if the check is AND (all) or OR (any). In contrast, the documentation of isinstance is clear: "return True if object is an instance of *any* of the types". Here's a possible rewriting that reduces the odds of incorrect interpretations, based on the text of isinstance: ORIGINAL: "in which case every entry in classinfo will be checked" PROPOSAL: "in which case return True if class is a subclass of any entry in classinfo" ---------- assignee: docs@python components: Documentation messages: 393684 nosy: docs@python, joaozinho priority: normal severity: normal status: open title: issubclass documentation doesn't explain tuple semantic type: enhancement versions: Python 3.10, Python 3.11, Python 3.6, Python 3.7, Python 3.8, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue44135> _______________________________________

5 12

[issue44756] In ./Doc, "make html" and "make build" should depend on "make venv"
by Jack DeVries Aug. 30, 2021

Aug. 30, 2021

New submission from Jack DeVries <jdevries3133(a)gmail.com>: In Doc/Makefile, all of the build rules should be dependent on the existence of a virtual environment. I could see this being controversial, because folks who have these tools installed elsewhere might prefer not to have a venv made for them, but my personal workflow is to strive to keep my system site-packages folder as empty as possible and to use virtual environments frequently. In any case, I'm interested to hear what we think. Momentarily, I will attach a PR where I went ahead and made these changes. Here is a summary of the changes: - venv rule is now conditional, and only does anything if $VENVDIR does not exist - add rule "clean-venv". This can be removed – what do you all think? - build rule is dependent on venv - as a result, rules dependent on build are dependent on venv - html - latex - etc. - update Doc/README.rst appropriately. Now users only need to type ``make html`` – nice! Let me know what you think. I may have a blind spot to others' workflows! Also, I'm not a Windows user, so I have no insight as to whether ``make.bat`` needs to be updated as well. ---------- assignee: docs@python components: Demos and Tools, Documentation messages: 398344 nosy: docs@python, jack__d priority: normal severity: normal status: open title: In ./Doc, "make html" and "make build" should depend on "make venv" type: enhancement versions: Python 3.11 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue44756> _______________________________________

7 26

[issue44508] asyncio: document failure mode for loop.call_soon_threadsafe
by Mark Dickinson Aug. 17, 2021

Aug. 17, 2021

New submission from Mark Dickinson <dickinsm(a)gmail.com>: `loop.call_soon_threadsafe` raises `RuntimeError` when the event loop has been closed, but that fact doesn't seem to be documented. It would be useful to document it so that that it's clear that that behaviour is part of the API, and can be depended on. Doc link: I'm looking at https://docs.python.org/3/library/asyncio-eventloop.html#asyncio.loop.call_… My use-case is that I have a background thread that's making use of `loop.call_soon_threadsafe` to place callbacks onto the main thread's event loop. The main thread at some point closes that event loop (e.g., as part of controlled application shutdown, or in the tearDown of a unit test). The background thread isn't in a position to know whether the event loop has been closed or not, and obviously checking that using the `is_closed` attribute runs into race condition issues. So I'd like to catch the potential exception from the `loop.call_soon_threadsafe`, but to do that I need to know what exception type to catch. It would probably also make sense to document the failure mode for `loop.call_soon`. ---------- assignee: docs@python components: Documentation, asyncio messages: 396523 nosy: asvetlov, docs@python, mark.dickinson, yselivanov priority: normal severity: normal status: open title: asyncio: document failure mode for loop.call_soon_threadsafe versions: Python 3.10, Python 3.11, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue44508> _______________________________________

4 8

[issue44522] [doc] open() function errors='surrogateescape' has inaccurate information
by Bupjae Lee Aug. 9, 2021

Aug. 9, 2021

New submission from Bupjae Lee <bupjae(a)gmail.com>: https://docs.python.org/3/library/functions.html#open error parameter of open() function says this: 'surrogateescape' will represent any incorrect bytes as code points in the Unicode Private Use Area ranging from U+DC80 to U+DCFF. However, U+DC80 to U+DCFF doesn't belong to "Unicode Private Use Area"; it belongs to "Low Surrogate Area". Suggested fix: 'surrogateescape' will represent any incorrect bytes as (unpaired) low surrogate code units ranging from U+DC80 to U+DCFF. ---------- assignee: docs@python components: Documentation messages: 396632 nosy: bupjae2, docs@python priority: normal severity: normal status: open title: [doc] open() function errors='surrogateescape' has inaccurate information type: enhancement versions: Python 3.10, Python 3.11, Python 3.6, Python 3.7, Python 3.8, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue44522> _______________________________________

4 10

[issue44702] Fix weakref doc
by Svyatoslav Aug. 9, 2021

Aug. 9, 2021

New submission from Svyatoslav <prometheus3375(a)gmail.com>: >From https://docs.python.org/3/library/weakref.html: "" Not all objects can be weakly referenced; those objects which can include class instances, functions written in Python (but not in C), instance methods, sets, frozensets, some file objects, generators, type objects, sockets, arrays, deques, regular expression pattern objects, and code objects. "" My first perception was that this is the list of objects without weakref support. Actually, the sentence lists objects which do support weakref. While writing this report I understood: "can" does not relate to "include" at all. The correct way of reading is "those objects | which can | include ...". Previously I had read it as "those objects | which can include ...". Even Google translates in such manner, commas do not help. To remove ambguity, I suggest such fix: "" Not all objects can be weakly referenced. Objects which support weak references include class instances, functions written in Python (but not in C), instance methods, sets, frozensets, some file objects, generators, type objects, sockets, arrays, deques, regular expression pattern objects, and code objects. "" or "" Not all objects can be weakly referenced. Сlass instances, functions written in Python (but not in C), instance methods, sets, frozensets, some file objects, generators, type objects, sockets, arrays, deques, regular expression pattern objects, and code objects support weak references. "" ---------- assignee: docs@python components: Documentation messages: 397960 nosy: Prometheus3375, docs@python priority: normal severity: normal status: open title: Fix weakref doc type: enhancement versions: Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue44702> _______________________________________

3 3

[issue44679] unittest.mock.sentinel documentation typo
by Andrii Haidai Aug. 6, 2021

Aug. 6, 2021

New submission from Andrii Haidai <gaydayav(a)gmail.com>: here: https://docs.python.org/3.3/library/unittest.mock.html#sentinel in code example block in last command line >>> sentinel.some_object according to the above 26.4.5.1 article context it looks like the other commad is expected: >>> result To ensure that at the end "result" equals sentinel.some_object we probably should print the "result" value to check, not the "sentinel.some_object" itself. ---------- assignee: docs@python components: Documentation messages: 397839 nosy: docs@python, gaydayav priority: normal severity: normal status: open title: unittest.mock.sentinel documentation typo versions: Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue44679> _______________________________________

5 8

[issue44760] Turtle Documentation - Contents Hyperlink conflict
by Ray Kinane Aug. 4, 2021

Aug. 4, 2021

New submission from Ray Kinane <raykinane(a)gmail.com>: In the Turtle module, there are 2 methods named "clear", one for turtle objects and one for screen objects. In the Turtle module documentation, in the contents section, in the "Turtle methods" section, under "More drawing control" the clear() method hyperlink does not point to the correct section in the article. It points to the section for the clear method for screen objects. There is another identical hyperlink issue in the same article due to 2 methods with the same name: "reset" ---------- assignee: docs@python components: Documentation messages: 398361 nosy: docs@python, ray_giraffe priority: normal severity: normal status: open title: Turtle Documentation - Contents Hyperlink conflict type: enhancement versions: Python 3.10, Python 3.11, Python 3.6, Python 3.7, Python 3.8, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue44760> _______________________________________

5 6

[issue44782] LRU class given as example in OrderedDict example not work on pop
by Maxime LEURENT Aug. 2, 2021

Aug. 2, 2021

New submission from Maxime LEURENT <maxime.leurent(a)gmx.fr>: Hello, I try to use a dictionnary with limited size, and I use class LRU given in docs on OrderedDict. Unfortunately this class is, somehow, not working on pop method. I say somehow because if I do OrderedDict pop method by hand I don't get any Exception. I do not understand how LRU.__getitem__ is call after del, and why "value = super().__getitem__(key)" work, when "self.move_to_end(key)" don't Code tested on python3.7 and python3.8: from collections import OrderedDict class LRU(OrderedDict): 'Limit size, evicting the least recently looked-up key when full' def __init__(self, maxsize=128, *args, **kwds): self.maxsize = maxsize super().__init__(*args, **kwds) def __getitem__(self, key): value = super().__getitem__(key) self.move_to_end(key) #<=== Bug here return value def __setitem__(self, key, value): if key in self: self.move_to_end(key) super().__setitem__(key, value) if len(self) > self.maxsize: oldest = next(iter(self)) del self[oldest] d = LRU() d["foo"] = "bar" d.pop("foo") #<= KeyError on mode_to_send in LRU.__getitem__ method #pop method by "hand" d["foo2"] = "bar" if "foo2" in d : result = d["foo2"] del d["foo2"] print(result) #work fine ---------- assignee: docs@python components: Documentation messages: 398571 nosy: docs@python, maximeLeurent priority: normal severity: normal status: open title: LRU class given as example in OrderedDict example not work on pop versions: Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue44782> _______________________________________

5 15

[issue44765] Misspelled Word In Docs
by Terry J. Reedy July 31, 2021

July 31, 2021

Terry J. Reedy <tjreedy(a)udel.edu> added the comment: Eesa, when responding by email, please delete the message you are responding to. When posted on the web page, the quoted copy becomes noisy and distracting. Visit https://bugs.python.org/issue44765 to see the result. ---------- nosy: +terry.reedy _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue44765> _______________________________________

1 0

[issue41983] Missing Documentation AF_PACKET
by Andrei Kulakov July 31, 2021

July 31, 2021

Change by Andrei Kulakov <andrei.avk(a)gmail.com>: ---------- type: -> behavior versions: +Python 3.10, Python 3.11, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue41983> _______________________________________

1 0