Mailman 3 July 2021 - Docs-bugs

[issue44213] LIST_TO_TUPLE placed below the sentence "all of the following use their opcodes" in dis library documentaiton.
by glubs9 April 8, 2022

April 8, 2022

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 March 31, 2022

March 31, 2022

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 March 19, 2022

March 19, 2022

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

[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

[issue44257] typo and verbous grammar in the grammar spec
by ShinWonho Nov. 4, 2021

Nov. 4, 2021

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 Oct. 31, 2021

Oct. 31, 2021

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 Oct. 21, 2021

Oct. 21, 2021

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

[issue44174] Unclear meaning of _Private__names in enum docs.
by Gregory P. Smith Oct. 21, 2021

Oct. 21, 2021

New submission from Gregory P. Smith <greg(a)krypto.org>: https://docs.python.org/3/library/enum.html#private-names """ _Private__names Private names will be normal attributes in Python 3.10 instead of either an error or a member (depending on if the name ends with an underscore). Using these names in 3.9 will issue a DeprecationWarning. """ It isn't clear from this documentation what is meant by "private names". Please expand on this to be explicit about what name pattern is being described. ---------- assignee: docs@python components: Documentation messages: 393919 nosy: docs@python, gregory.p.smith priority: normal severity: normal stage: needs patch status: open title: Unclear meaning of _Private__names in enum docs. versions: Python 3.10, Python 3.11, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue44174> _______________________________________

4 11

[issue44113] [C API] Deprecate legacy API for configure Python initialization
by STINNER Victor Oct. 15, 2021

Oct. 15, 2021

New submission from STINNER Victor <vstinner(a)python.org>: The https://docs.python.org/dev/c-api/init.html documentation lists many functions which is the legacy way to configure the Python initialization. These functions are kept for backward compatibility but have flaws and are less reliable than the new PyConfig API (PEP 587) documented at https://docs.python.org/dev/c-api/init_config.html I propose to deprecate the legacy functions to configure the Python initialization. Examples: * Py_SetPath() * Py_SetProgramName() * Py_SetPythonHome() * Py_SetStandardStreamEncoding() * PySys_AddWarnOption() * PySys_AddWarnOptionUnicode() * PySys_AddXOption() I don't propose to schedule the removal of these functions, only mark them as deprecated in the *documentation*. Related issue: bpo-43956 "C-API: Incorrect default value for Py_SetProgramName" and PR 24876. ---------- assignee: docs@python components: C API, Documentation messages: 393499 nosy: docs@python, vstinner priority: normal severity: normal status: open title: [C API] Deprecate legacy API for configure Python initialization versions: Python 3.11 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue44113> _______________________________________

3 13