Mailman 3 November 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

[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

[issue45840] Improve cross-references in the data model documentation
by Alex Waygood Dec. 13, 2021

Dec. 13, 2021

New submission from Alex Waygood <Alex.Waygood(a)Gmail.com>: The documentation for the data model has a lot of cross-references to other parts of the data model. However, often these cross-references do not have proper hyperlinks online, as :meth:`__iter__` is used (for example), instead of :meth:`~object.__iter__`. The documentation would be much more readable and navigable if this were fixed. ---------- assignee: docs@python components: Documentation messages: 406569 nosy: AlexWaygood, docs@python priority: normal severity: normal status: open title: Improve cross-references in the data model documentation versions: Python 3.10, Python 3.11, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue45840> _______________________________________

2 10

[issue45391] 3.10 objects.inv classifies UnionType as data
by gaborjbernat Dec. 9, 2021

Dec. 9, 2021

New submission from gaborjbernat <gaborjbernat(a)gmail.com>: It's a class though: ❯ sphobjinv suggest ./objects.inv UnionType :py:data:`types.UnionType` defined as: UnionType = type(int | str) ---------- assignee: docs@python components: Documentation messages: 403300 nosy: docs@python, gaborjbernat priority: normal severity: normal status: open title: 3.10 objects.inv classifies UnionType as data versions: Python 3.10 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue45391> _______________________________________

6 13

[issue44534] unittest.mock.Mock.unsafe doc is garbled
by Roy Smith Dec. 4, 2021

Dec. 4, 2021

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

[issue45922] Many method, function, built-in... are not clickable and should be
by Arthur Milchior Dec. 4, 2021

Dec. 4, 2021

New submission from Arthur Milchior <arthur(a)milchior.fr>: I would like to work on this documentation improvement. Before spending time on it, I would like to know whether it would be accepted in principle and whether the way I would intend to improve the documentation would be accepted. # Problem: In a lot of part of the documentation, the text refers to a method, function, built-in, variable, member defined somewhere else in the doc, but does not link to it (I'll call it "the defined thing" in the remaining of this BPO). ## Example As an example, in https://docs.python.org/3.10/library/imp.html#imp.reload , you'll get link to import from, but no link on __name__. Admittedly, it's probably not a big deal by itself, and I would not have opened a bug report only for this one. But I'm convinced that there are sufficiently many missing links that a PR that would solve add a lot of them would improve the day to day use of the documentation in a small way for a lot of users. This example seems interesting to me because it also shows that creating the links can not be 100% automated (even if most of it can). Indeed, __name__ is a property of modules, but it is also a property of class, function, method, descriptor and generator instances. The former is defined in https://docs.python.org/3.10/library/types.html?highlight=__name__#types.Mo… while the latter is defined in https://docs.python.org/3.10/library/stdtypes.html?highlight=__name__#defin… . Hence, a commit dealing with __name__ need to check that the correct reference is used each time. I got the idea from a change requested by Terry J Reedy on another of my documentation PR a few days ago: https://github.com/python/cpython/pull/29183#pullrequestreview-816414072 and I believe this should be more systematic. # How I'll solve this issue ## Ensuring the PR is easy to review For each defined thing, I'll create a commit that simply add links to this refered thing. In the example I gave, it will transform ``__name__`` to :meth:`__name__`. That means that each commit will be very easy to review (even if it will be boring). Even better, any diff tools can show that there are no other difference than the one I claim to make. ### One downside The downside is that it requires that I do not change the place where line break occurs (otherwise, git default diff tool will show a lot of difference). this mean that some lines will grow larger than 80 characters. In this case, I believe that this is a cost worth paying because: * there are already a lot of lines with more than 80 characters in the documentation, * reformating each paragraph will makes the reviewer work extremely hard, for virtually no benefits * if required, a last commit can reformat all paragraphs at the end. ## How I'll find missing references I will NOT find all missing references. I do not believe it is a realistic goal. My goal here is to improve the documentation, I don't care if it is not perfect here. What I do is that I search for lines containing matching the regexp `\`\.{2,}\`\`; they are generally, but not always, code that should be reference. For each missing reference, I'll use search and replace in the documentation codebase to replace the code by the link, I'll compile and check that the link works. ## Future work I believe ideally a linter should warn if a single word betwen `` and `` could potentially be a reference. This seems harder work to be honest, I don't know how I'd start it. And it seems useless while so many missing references are in the codebase. # Conclusion My questions are thus: * If I were to make such a PR, would it be accepted * is there any feedback, improvement one would suggest that may improve the result or save time ---------- assignee: docs@python components: Documentation messages: 407242 nosy: Arthur-Milchior, docs@python priority: normal severity: normal status: open title: Many method, function, built-in... are not clickable and should be 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/issue45922> _______________________________________

4 4

[issue45920] make doctest fails
by Arthur Milchior Dec. 2, 2021

Dec. 2, 2021

New submission from Arthur Milchior <arthur(a)milchior.fr>: On current main, f87ea0350286837e9e96de03f8bfa215176c2928 , ``` cd cpython/Doc make doctest ``` fails. Due to: Document: library/functions --------------------------- Warning, treated as error: ********************************************************************** File "library/functions.rst", line ?, in default Failed example: list(zip(range(3), ['fee', 'fi', 'fo', 'fum'], strict=True)) Expected: Traceback (most recent call last): ... ValueError: zip() argument 2 is longer than argument 1 Got: Traceback (most recent call last): File "/usr/lib/python3.8/doctest.py", line 1336, in __run exec(compile(example.source, filename, "single", File "<doctest default[0]>", line 1, in <module> list(zip(range(3), ['fee', 'fi', 'fo', 'fum'], strict=True)) TypeError: zip() takes no keyword arguments This is not surprising since zip didn't take "Strict" kwarg in 3.8. The issue is that 3.10 doc is tested with Python 3.8. If in Makefile I change Python to "Python3.10" I get a new error, but it still mention "/usr/lib/python3.8/doctest.py" so I guess for some reason it was not using 3.10 everywhere. I don't know make enough to have any idea how to correct this one. By the way, is there a tool to auto-format .rst file? Initially, that was what I was trying to figure out, if I could get automatically warning when a new line is more than 80 chars long for example. ---------- assignee: docs@python components: Documentation messages: 407238 nosy: Arthur-Milchior, docs@python priority: normal severity: normal status: open title: make doctest fails versions: Python 3.10 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue45920> _______________________________________

2 2

[issue45896] Conflicting statements in docs about default support for asyncio subprocesses on Windows
by Rob Dec. 1, 2021

Dec. 1, 2021

New submission from Rob <rob(a)appkingsoftware.com>: Hi, In the docs for the asyncio event loop, it has a note on page: https://docs.python.org/3/library/asyncio-eventloop.html#running-subprocess… "Note The default asyncio event loop on Windows does not support subprocesses. See Subprocess Support on Windows for details." Then following the link in that note to: https://docs.python.org/3/library/asyncio-platforms.html#subprocess-support… Says: "On Windows, the default event loop ProactorEventLoop supports subprocesses, whereas SelectorEventLoop does not." So the issue is, there are conflicting statements about default support for asyncio subprocesses on Windows. It seems the first statement listed above, is wrong or outdated since the default event loop on Windows is the ProactorEventLoop which does support subprocesses. Thank you! ---------- assignee: docs@python components: Documentation messages: 406967 nosy: Rob4226, docs@python priority: normal severity: normal status: open title: Conflicting statements in docs about default support for asyncio subprocesses on Windows versions: Python 3.10 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue45896> _______________________________________

4 10