Mailman 3 August 2021 - Docs-bugs

[issue44213] LIST_TO_TUPLE placed below the sentence "all of the following use their opcodes" in dis library documentaiton.
by glubs9 08 Apr '22

08 Apr '22

New submission from glubs9 <jonte.fry(a)gmail.com>: in the dis library documentation where it lists all of the instructions in python bytecode, it includes a small sentence about half way dow "all of the following instructions use their arguments". After this sentence there is an instruction specified LIST_TO_TUPLE which does not in fact use its argument. It's a minor mistake but 100% on how it should be fixed so I have not yet made a pr. It could be fixed by removing the sentence or just moving it above the sentence. I'm not sure. ---------- assignee: docs@python components: Documentation messages: 394178 nosy: docs@python, glubs9 priority: normal severity: normal status: open title: LIST_TO_TUPLE placed below the sentence "all of the following use their opcodes" in dis library documentaiton. type: enhancement versions: Python 3.11 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue44213> _______________________________________

3 4

[issue44740] Lowercase "Internet" and "web" in docs
by Mariusz Felisiak 31 Mar '22

31 Mar '22

New submission from Mariusz Felisiak <felisiak.mariusz(a)gmail.com>: AP lowercased "internet" and "web" in all instances – web page, the web, web browser, etc. on June 1, 2016: https://twitter.com/APStylebook/status/716384777406922753 https://twitter.com/APStylebook/status/716279539052191746?s=20 I'd be happy to provide a patch, if accepted. We will update the Django docs to follow this recommendation, see https://code.djangoproject.com/ticket/32956. ---------- assignee: docs@python components: Documentation messages: 398223 nosy: docs@python, felixxm priority: normal severity: normal status: open title: Lowercase "Internet" and "web" in docs type: enhancement _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue44740> _______________________________________

5 12

[issue44544] Add full list of possible args to textwrap: wrap, fill, shorten
by Andrei Kulakov 19 Mar '22

19 Mar '22

New submission from Andrei Kulakov <andrei.avk(a)gmail.com>: https://docs.python.org/3.11/library/textwrap.html The 3 functions - wrap, fill, shorten -- have a signature like `(..., **kwargs)`, where kwargs are instance attrs of TextWrap. It would be better to list all possible args in the signature because: - more convenient for users rather than scrolling back and forth between description of the function and the list under TextWrap - the list under TextWrap is so long it doesn't fit on one screen. It would be great to have a compact list in the signature of these 3 functions - it's confusing -- at first sight, it seems like **kwargs will be taken in to be used by a subclass or maybe stored as attrs on the instance and not used, and it seems like arbitrary kwargs can be given. - the only reason it was done so, I guess, is that the list is long and unwieldy. But that's also the reason why the listing under TextWrap takes up more than a screenful and so more of an argument to have a compact list in the signature. - in case of fill, some args are a no-op, so they can be omitted from the signature, that will make it much easier to see all effective arguments. ---------- assignee: docs@python components: Documentation messages: 396817 nosy: andrei.avk, docs@python priority: normal severity: normal status: open title: Add full list of possible args to textwrap: wrap, fill, shorten type: enhancement versions: Python 3.10, Python 3.11, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue44544> _______________________________________

5 15

[issue44665] asyncio.create_task() documentation should mention user needs to keep reference to the task
by Vincent Bernat 06 Jan '22

06 Jan '22

New submission from Vincent Bernat <python(a)vincent.bernat.ch>: asyncio will only keep weak references to alive tasks (in `_all_tasks`). If a user does not keep a reference to a task and the task is not currently executing or sleeping, the user may get "Task was destroyed but it is pending!". I would suggest adding the following paragraph to `create_task()` documentation: Python only keeps weak references to the scheduled tasks. To avoid the task being destroyed by the garbage collector while still pending, a reference to it should be kept until the task is done. And maybe an example in case a user wants something "fire and forget"? ```python running_tasks = set() # [...] task = asyncio.create_task(some_background_function()) running_tasks.add(task) task.add_done_callback(lambda t: running_tasks.remove(t)) ``` The same applies to ensure_future as it now uses create_task, so maybe a "See create_task()". ---------- assignee: docs@python components: Documentation messages: 397741 nosy: bernat, docs@python priority: normal severity: normal status: open title: asyncio.create_task() documentation should mention user needs to keep reference to the task type: enhancement versions: Python 3.10, Python 3.11, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue44665> _______________________________________

4 5

[issue44875] Update dis.findlinestarts documentaiton to reflect new usage of `co_lines` (PEP 626)
by George King 03 Jan '22

03 Jan '22

New submission from George King <george.w.king(a)gmail.com>: `dis.findlinestarts()` has been changed to use the no `co_lines()` function. (Blame indicates commit 877df851c3e by Mark Shannon.) However the docs currently state that it uses the older `co_firstlineno` and `co_lnotab`: https://docs.python.org/3.10/library/dis.html#dis.findlinestarts. My cursory understanding of `dis.py` internals is that `get_instructions` relies on `findlinestarts`, implying that both of these APIs are going to return different line numbers than they did previously. I am perfectly fine with this, and hopeful that the PEP 626 changes will improve tool accuracy. At minimum the `dis` docs should be updated. I also suggest that some kind of note about this be added to the PEP 626 text, because the way it reads now suggests that it avoids breakage by creating the new `co_lines` API. However it seems that users of the higher level dis APIs are going to see subtly different behavior. FWIW I am fine with the change, and I hope this doesn't instigate a reversion to the old behavior. `lnotabs` semantics were very cryptic and seemed rather broken when I attempted to use it years ago. I am revisiting an experimental code coverage tool in part because of the PEP. ---------- assignee: docs@python components: Documentation messages: 399290 nosy: Mark.Shannon, docs@python, gwk priority: normal severity: normal status: open title: Update dis.findlinestarts documentaiton to reflect new usage of `co_lines` (PEP 626) versions: Python 3.10 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue44875> _______________________________________

2 2

[issue44534] unittest.mock.Mock.unsafe doc is garbled
by Roy Smith 04 Dec '21

04 Dec '21

New submission from Roy Smith <roy(a)panix.com>: At https://docs.python.org/3.9/library/unittest.mock.html#unittest.mock.Mock, it says: unsafe: By default if any attribute starts with assert or assret will raise an AttributeError. That's not an English sentence. I think what was intended was, "By default accessing an attribute which starts with assert or assret will raise an AttributeError." ---------- assignee: docs@python components: Documentation messages: 396719 nosy: docs@python, roysmith priority: normal severity: normal status: open title: unittest.mock.Mock.unsafe doc is garbled versions: Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue44534> _______________________________________

4 3

[issue44995] "Hide the prompts and output" works abnormal
by 杨青 12 Nov '21

12 Nov '21

New submission from 杨青 <nwpu.yangqing(a)qq.com>: 【url】https://docs.python.org/3/tutorial/classes.html 【chapter】9.4. Random Remarks 【problem description】 When I click on the demo "Hide the prompts and output" switch, the class definition statements were also hided. Please take a look as the appended screenshot. ---------- assignee: docs@python components: Documentation files: screenshot.png messages: 400245 nosy: docs@python, yangqing priority: normal severity: normal status: open title: "Hide the prompts and output" works abnormal versions: Python 3.9 Added file: https://bugs.python.org/file50235/screenshot.png _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue44995> _______________________________________

4 3

[issue44257] typo and verbous grammar in the grammar spec
by ShinWonho 04 Nov '21

04 Nov '21

New submission from ShinWonho <new170527(a)kaist.ac.kr>: In Python Language Reference 10.Full Grammar Specification typo: assigment_expression verbous grammar: expressions and star_expression ---------- assignee: docs@python components: Documentation messages: 394630 nosy: docs@python, orangebana15 priority: normal severity: normal status: open title: typo and verbous grammar in the grammar spec type: enhancement versions: Python 3.11 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue44257> _______________________________________

4 6

[issue44365] Bad dataclass post-init example
by Micael Jarniac 31 Oct '21

31 Oct '21

New submission from Micael Jarniac <micael(a)jarniac.com>: https://docs.python.org/3/library/dataclasses.html#post-init-processing https://github.com/python/cpython/blob/3.9/Doc/library/dataclasses.rst#post… In the example, a base class "Rectangle" is defined, and then a "Square" class inherits from it. On reading the example, it seems like the Square class is meant to be used like: >>> square = Square(5) Since the Square class seems to be supposed to be a "shortcut" to creating a Rectangle with equal sides. However, the Rectangle class has two required init arguments, and when Square inherits from it, those arguments are still required, so using Square like in the above example, with a single argument, results in an error: >>> square = Square(5) Traceback (most recent call last): File "<stdin>", line 1, in <module> TypeError: __init__() missing 2 required positional arguments: 'width' and 'side' To "properly" use the Square class, it'd need to be instantiated like so: >>> square = Square(0, 0, 5) >>> square Square(height=5, width=5, side=5) Which, in my opinion, is completely counter-intuitive, and basically invalidates this example. ---------- assignee: docs@python components: Documentation messages: 395427 nosy: MicaelJarniac, docs@python priority: normal severity: normal status: open title: Bad dataclass post-init example type: behavior versions: Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue44365> _______________________________________

5 12

[issue44344] Documentation for pow() should include the possibility of complex numbers as a return type
by Erik Y. Adams 21 Oct '21

21 Oct '21

New submission from Erik Y. Adams <erikyadams(a)outlook.com>: https://docs.python.org/3/library/functions.html#pow The built-in pow() function will return a complex number if the base is negative and the exponent is a float between 0 and 1. For example, the value returned by `pow(-1, 1.0/3)` is `(1.0000000000000002+1.7320508075688772j)` The answer is mathematically correct, but `-2.0` is also mathematically correct. There is nothing in the documentation currently to suggest that a complex number might be returned; in fact, given the statement "[with] mixed operand types, the coercion rules for binary arithmetic operators apply", one might reasonably expect `-2.0` as the answer. I suggest the following sentences be added to the end of the second paragraph: "If `base` is negative and the `exp` is a `float` between 0 and 1, a complex number will be returned. For example, `pow(-8, 1.0/3)` will return `(1.0000000000000002+1.7320508075688772j)`, and not `-2.0.`" ---------- assignee: docs@python components: Documentation messages: 395305 nosy: docs@python, eyadams priority: normal severity: normal status: open title: Documentation for pow() should include the possibility of complex numbers as a return type type: enhancement versions: Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue44344> _______________________________________

7 15