Mailman 3 December 2021 - Docs-bugs

[issue45729] "history and license" link has wrong target
by Jacob Lifshay Jan. 13, 2022

Jan. 13, 2022

New submission from Jacob Lifshay <programmerjake(a)gmail.com>: https://docs.python.org/3.10/library/csv.html at the bottom the "history and license" link just links back to csv.html, rather than the correct target. ---------- assignee: docs@python components: Documentation messages: 405807 nosy: docs@python, programmerjake priority: normal severity: normal status: open title: "history and license" link has wrong target versions: Python 3.10 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue45729> _______________________________________

5 12

[issue44665] asyncio.create_task() documentation should mention user needs to keep reference to the task
by Vincent Bernat Jan. 6, 2022

Jan. 6, 2022

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 Jan. 4, 2022

Jan. 4, 2022

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

[issue46182] `super` and descriptor clarification
by Arthur Milchior Jan. 3, 2022

Jan. 3, 2022

New submission from Arthur Milchior <arthur(a)milchior.fr>: I find super documentation confusing because it uses multiple variables that are never introduced. Once you understand super, the meaning of those variables gets easier to understand, but still, I believe that it would help the documentation to rephrase some sentences. In https://docs.python.org/3/reference/datamodel.html#invoking-descriptors you can read > If a is an instance of super, then the binding super(B, obj).m() searches obj.__class__.__mro__ for the base class A immediately following B and then invokes the descriptor with the call: A.__dict__['m'].__get__(obj, obj.__class__). It took me many reading to understand that `obj` is supposed to be a new variable; and also why `a` only appear once in the line. I believe it'd be better to explicitly state "We consider the case where a = super(B, obj), with `obj` an instance of B." Also, `super(B, obj).m()` seems to indicate that the method `m` is called. While ` A.__dict__['m'].__get__(obj, obj.__class__)` does not seems to call this method. Hence, I believe that the parentheses should be removed after `m` (and either `m` should be renamed to `x`, or we should state explicitly that we are not considered `a.x` anymore, contrary to the previous cases) In https://docs.python.org/3/library/functions.html#super , you can read > If the second argument is omitted, the super object returned is unbound. If the second argument is an object, isinstance(obj, type) must be true. If the second argument is a type, issubclass(type2, type) must be true (this is useful for classmethods). On first reading, I have no idea what it means that a returned object is unbound. I know what "variable binding" mean, but it really does not seems to apply here. My current understanding, and I would love if someone can confirm it, is that the first sentence means that "contrary to the other cases, the returned value do not have to satisfy any bound". In this case, I believe that it would be far better to put the case with no second argument at the end of the paragraph, ensuring that "is unbound" makes sens to the reader since they already will have seen bounds. Also, it may help clarify to write "is an object `obj`" and "is a type `type2`" so that it get clear what `obj` and `type2` means. Any feedback welcome. ---------- assignee: docs@python components: Documentation messages: 409201 nosy: Arthur-Milchior, docs@python priority: normal severity: normal status: open title: `super` and descriptor clarification 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/issue46182> _______________________________________

2 6

[issue46196] documentation for cmd library should include columnize() function
by sharewell Jan. 2, 2022

Jan. 2, 2022

New submission from sharewell <jawed(a)sharewellnow.com>: Cmd.columnize is an extremely useful function in Python, that can be used in many situations. It is part of the Cmd library. Unfortunately, the Cmd documentation does not mention it. It should. I only found out about it via https://stackoverflow.com/a/59627245 Please add to the documentation: https://docs.python.org/3/library/cmd.html ---------- assignee: docs@python components: Documentation messages: 409332 nosy: docs@python, sharewell priority: normal severity: normal status: open title: documentation for cmd library should include columnize() function versions: Python 3.11 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue46196> _______________________________________

3 5

[issue45903] What’s New In Python 3.11: wrong reference to Signature.from_callable
by Jakub Wilk Jan. 2, 2022

Jan. 2, 2022

New submission from Jakub Wilk <jwilk(a)jwilk.net>: <https://docs.python.org/3.11/whatsnew/3.11.html#removed> says: "Removed from the inspect module: […] the undocumented Signature.from_callable and Signature.from_function functions, deprecated since Python 3.5; use the Signature.from_callable() method instead." But Signature.from_callable can't possibly be removed and the suggested replacement at the same time. I think it should say: "… the undocumented Signature.from_builtin and …" ---------- assignee: docs@python components: Documentation messages: 407054 nosy: docs@python, hugovk, jwilk priority: normal severity: normal status: open title: What’s New In Python 3.11: wrong reference to Signature.from_callable versions: Python 3.11 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue45903> _______________________________________

4 5

[issue46095] Warning about iterate/modify has unwarranted detail
by Ture Pålsson Jan. 1, 2022

Jan. 1, 2022

New submission from Ture Pålsson <ture(a)turepalsson.se>: The language reference about the 'for' statement (https://docs.python.org/3/reference/compound_stmts.html#the-for-statement) has a "Note" box that states that the for statement uses an "internal counter" which is "incremented", and goes into detail about what happens when modifications happen before or after the current loop position. Surely this depends on the underlying iterator? For example, with a balanced tree an insert or a delete could completely re-jigger the tree with hard-to-predict results on an iterator. ---------- assignee: docs@python components: Documentation messages: 408680 nosy: docs@python, turepalsson priority: normal severity: normal status: open title: Warning about iterate/modify has unwarranted detail type: enhancement versions: Python 3.10 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue46095> _______________________________________

4 8

[issue46079] Broken URL in tutorial
by Vivek Vashist Jan. 1, 2022

Jan. 1, 2022

New submission from Vivek Vashist <vivekvashist(a)gmail.com>: URL: http://tycho.usno.navy.mil/cgi-bin/timer.pl is broken in the example https://docs.python.org/3/tutorial/stdlib.html#internet-access > curl -v http://tycho.usno.navy.mil/cgi-bin/timer.pl * Could not resolve host: tycho.usno.navy.mil * Closing connection 0 curl: (6) Could not resolve host: tycho.usno.navy.mil ---------- assignee: docs@python components: Documentation messages: 408585 nosy: docs@python, vivekvashist priority: normal severity: normal status: open title: Broken URL in tutorial versions: Python 3.10 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue46079> _______________________________________

4 11

[issue46201] PEP 495 misnames PyDateTime_DATE_GET_FOLD
by Carl Drougge Dec. 30, 2021

Dec. 30, 2021

New submission from Carl Drougge <bugs.python.org(a)s.z42.net>: PEP 495 names one of the accessor macros PyDateTime_GET_FOLD but the code names it PyDateTime_DATE_GET_FOLD. The FOLD macros are also missing from https://docs.python.org/3/c-api/datetime.html (and versions). ---------- assignee: docs@python components: Documentation messages: 409354 nosy: docs@python, drougge priority: normal severity: normal status: open title: PEP 495 misnames PyDateTime_DATE_GET_FOLD type: behavior 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/issue46201> _______________________________________

1 0

[issue43424] Document the `controller.name` field in `webbrowser` module
by Dong-hee Na Dec. 30, 2021

Dec. 30, 2021

Dong-hee Na <donghee.na(a)python.org> added the comment: New changeset d12bec69931503be78cd555cf7bc22ad6f4f2bd5 by Nikita Sobolev in branch 'main': bpo-43424: Deprecate `webbrowser.MacOSXOSAScript._name` attribute (GH-30241) https://github.com/python/cpython/commit/d12bec69931503be78cd555cf7bc22ad6f… ---------- nosy: +corona10 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue43424> _______________________________________

2 1