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

[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

[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

[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