Mailman 3 September 2021 - Docs-bugs

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

04 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 05 Dec '21

05 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 杨青 13 Nov '21

13 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 05 Nov '21

05 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

[issue45125] Improve tests and docs of how `pickle` works with `SharedMemory` obejcts
by Nikita Sobolev 22 Oct '21

22 Oct '21

New submission from Nikita Sobolev <mail(a)sobolevn.me>: As we've discussed in https://bugs.python.org/msg401146 we need to improve how `SharedMemory` is documented and tested. Right now docs do not cover `pickle` at all (https://github.com/python/cpython/blob/main/Doc/library/multiprocessing.sha…). And this is an important aspect in multiprocessing. `SharedMemory` and `pickle` in `test_shared_memory_basics` (https://github.com/python/cpython/blob/a5c6bcf24479934fe9c5b859dd1cf72685a0…): ``` sms.buf[0:6] = b'pickle' pickled_sms = pickle.dumps(sms) sms2 = pickle.loads(pickled_sms) self.assertEqual(sms.name, sms2.name) self.assertEqual(bytes(sms.buf[0:6]), bytes(sms2.buf[0:6]), b'pickle') ``` `ShareableList` has better coverage in this regard (https://github.com/python/cpython/blob/a5c6bcf24479934fe9c5b859dd1cf72685a0…): ``` def test_shared_memory_ShareableList_pickling(self): sl = shared_memory.ShareableList(range(10)) self.addCleanup(sl.shm.unlink) serialized_sl = pickle.dumps(sl) deserialized_sl = pickle.loads(serialized_sl) self.assertTrue( isinstance(deserialized_sl, shared_memory.ShareableList) ) self.assertTrue(deserialized_sl[-1], 9) self.assertFalse(sl is deserialized_sl) deserialized_sl[4] = "changed" self.assertEqual(sl[4], "changed") # Verify data is not being put into the pickled representation. name = 'a' * len(sl.shm.name) larger_sl = shared_memory.ShareableList(range(400)) self.addCleanup(larger_sl.shm.unlink) serialized_larger_sl = pickle.dumps(larger_sl) self.assertTrue(len(serialized_sl) == len(serialized_larger_sl)) larger_sl.shm.close() deserialized_sl.shm.close() sl.shm.close() ``` So, my plan is: 1. Improve testing of `SharedMemory` after pickling/unpickling. I will create a separate test with all the `pickle`-related stuff there 2. Improve docs: user must understand what will have when `SharedMemory` / `SharableList` is pickled and unpickled. For example, the fact that it will still be shared can be a surprise to many. I am going to send a PR with both thing somewhere this week. I will glad to head any feedback before / after :) ---------- assignee: docs@python components: Documentation, Tests messages: 401219 nosy: docs@python, sobolevn priority: normal severity: normal status: open title: Improve tests and docs of how `pickle` works with `SharedMemory` obejcts type: behavior versions: Python 3.10, Python 3.11, Python 3.8, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue45125> _______________________________________

3 6

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

22 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

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

22 Oct '21

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 15 Oct '21

15 Oct '21

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

[issue45277] typo in codecs documentation
by HugoThiolliere 05 Oct '21

05 Oct '21

New submission from HugoThiolliere <hugo.thiolliere(a)hotmail.fr>: There is a typo in https://docs.python.org/3/library/codecs.html#encodings-and-unicode The first sentence in the last paragraph before the table reads : "There’s another encoding that is able to encoding the full range of Unicode characters" When it should read "There’s another encoding that is able to encode the full range of Unicode characters" ---------- assignee: docs@python components: Documentation messages: 402545 nosy: Gronahak, docs@python priority: normal severity: normal status: open title: typo in codecs documentation type: enhancement versions: Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue45277> _______________________________________

4 9