Mailman 3 October 2021 - Docs-bugs

[issue44213] LIST_TO_TUPLE placed below the sentence "all of the following use their opcodes" in dis library documentaiton.
by glubs9 08 Apr '22

08 Apr '22

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

[issue45210] tp_dealloc docs should mention error indicator may be set
by Edward Yang 06 Apr '22

06 Apr '22

New submission from Edward Yang <ezyang(a)mit.edu>: The fact that the error indicator may be set during tp_dealloc is somewhat well known (https://github.com/posborne/dbus-python/blob/fef4bccfc535c6c2819e3f15384600…) but it's not documented in the official manual. We should document it. A simple suggested patch: diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst index b17fb22b69..e7c9b13646 100644 --- a/Doc/c-api/typeobj.rst +++ b/Doc/c-api/typeobj.rst @@ -668,6 +668,20 @@ and :c:type:`PyType_Type` effectively act as defaults.) :c:func:`PyObject_GC_Del` if the instance was allocated using :c:func:`PyObject_GC_New` or :c:func:`PyObject_GC_NewVar`. + If you may call functions that may set the error indicator, you must + use :c:func:`PyErr_Fetch` and :c:func:`PyErr_Restore` to ensure you + don't clobber a preexisting error indicator (the deallocation could + have occurred while processing a different error): + + .. code-block:: c + + static void foo_dealloc(foo_object *self) { + PyObject *et, *ev, *etb; + PyErr_Fetch(&et, &ev, &etb); + ... + PyErr_Restore(et, ev, etb); + } + Finally, if the type is heap allocated (:const:`Py_TPFLAGS_HEAPTYPE`), the deallocator should decrement the reference count for its type object after calling the type deallocator. In order to avoid dangling pointers, the ---------- assignee: docs@python components: Documentation messages: 401854 nosy: docs@python, ezyang priority: normal severity: normal status: open title: tp_dealloc docs should mention error indicator may be set type: enhancement versions: Python 3.11 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue45210> _______________________________________

3 4

[issue45317] Document the removal the usage of the C stack in Python to Python calls
by Mark Shannon 04 Apr '22

04 Apr '22

New submission from Mark Shannon <mark(a)hotpy.org>: Assuming that issue 45256 is implemented, we will need to document it. I'm opening a separate issue, so this doesn't get lost in the midst of 45256. We need to: Document the changes to gdb. Possibly at https://wiki.python.org/moin/DebuggingWithGdb, or in the main docs. Add a "what's new" entry explaining what the impact of this change is. ---------- assignee: docs@python components: Documentation messages: 402850 nosy: Mark.Shannon, docs@python priority: release blocker severity: normal status: open title: Document the removal the usage of the C stack in Python to Python calls type: enhancement versions: Python 3.11 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue45317> _______________________________________

2 5

[issue45099] asyncio.Task's documentation says that loop arg is removed when it's not
by jack1142 02 Apr '22

02 Apr '22

New submission from jack1142 <kuba.kuczys(a)gmail.com>: The documentation here: https://docs.python.org/3.10/library/asyncio-task.html#asyncio.Task Says that `loop` parameter was removed but it's still part of the signature. It gets even more confusing when the deprecation right below it is saying that *not* passing it when there is no running event loop is deprecated :) I could make a PR removing this information but I'm not sure whether there should be also some information put about it being deprecated in 3.8 but not actually getting removed in 3.10? ---------- assignee: docs@python components: Documentation messages: 401047 nosy: docs@python, jack1142 priority: normal severity: normal status: open title: asyncio.Task's documentation says that loop arg is removed when it's not type: behavior versions: Python 3.10 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue45099> _______________________________________

4 10

[issue45584] Clarifying truncating in documentation
by Arthur Milchior 02 Apr '22

02 Apr '22

New submission from Arthur Milchior <arthur(a)milchior.fr>: While floor/ceil 's documentation are very precise, `truncate` was not explained. I actually had to search online to understand the difference between `truncate` and `floor` (admittedly, once I remembered that numbers are signed, and that floating numbers actually uses a bit for negation symbol instead of two complement, it became obvious) I assume that I won't be the only user having this trouble, especially for people whose mother tongue is not English. So I suggest adding a clarification to help make what should be obvious to most actually explicit ---------- assignee: docs@python components: Documentation messages: 404850 nosy: ArthurMilchior, docs@python priority: normal severity: normal status: open title: Clarifying truncating in documentation 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/issue45584> _______________________________________

5 11

[issue45114] bad example for os.stat
by Harri 02 Apr '22

02 Apr '22

New submission from Harri <harri(a)afaics.de>: The example on https://docs.python.org/3/library/stat.html should be improved to avoid endless recursion, if there is a symlink loop. I would suggest to use os.lstat instead of os.stat. ---------- assignee: docs@python components: Documentation messages: 401133 nosy: docs@python, harridu priority: normal severity: normal status: open title: bad example for os.stat versions: Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue45114> _______________________________________

4 7

[issue44740] Lowercase "Internet" and "web" in docs
by Mariusz Felisiak 31 Mar '22

31 Mar '22

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

[issue45618] Documentation builds fail with Sphinx 3.2.1
by Maciej Olko 28 Mar '22

28 Mar '22

New submission from Maciej Olko <maciej.olko(a)gmail.com>: Since the release of Docutils 0.18 today building Python documentation fails. In CPython repository we have Sphinx pinned to 3.2.1, which has too loose requirement for Docutils version in install_requires – docutils>=0.12. Example of failing build: https://github.com/python/python-docs-pl/runs/4009459257. My suggestion is to pin down docutils in docs requirements. ---------- assignee: docs@python components: Documentation messages: 405060 nosy: Maciej Olko, docs@python priority: normal severity: normal status: open title: Documentation builds fail with Sphinx 3.2.1 type: crash 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/issue45618> _______________________________________

7 35

[issue45336] Issue with xml.tree.ElementTree.write
by ed wolf 21 Mar '22

21 Mar '22

New submission from ed wolf <bq824(a)cummins.com>: When executing the following command after modifiy an xml file an error is prodcued. import xml.etree.ElementTree as ET rtexmlFile = 'Fox_CM3550A_SWP1_Rte_ecuc.arxml' rte_ecu_tree = ET.parse(rtexmlFile) root = rte_ecu_tree.getroot() rte_ecu_tree.write(rtexmlFile, encoding="UTF-8", xml_declaration="True", default_namespace="None" method="xml",short_empty_elements="True" ) ValueError: cannot use non-qualified names with default_namespace option The documentation for the ElementTree.write function indicates the following format for this command but this format does not seem to wrok The write command does not also take into account when having standalone in the xml defintion. For ex, <?xml version="1.0" encoding="UTF-8" standalone="no"?> ElementTree.write will not add standalone back to the xml file Is this a bug in version 3.7? write(file, encoding="us-ascii", xml_declaration=None, default_namespace=None, method="xml", *, short_empty_elements=True) Writes the element tree to a file, as XML. file is a file name, or a file object opened for writing. encoding 1 is the output encoding (default is US-ASCII). xml_declaration controls if an XML declaration should be added to the file. Use False for never, True for always, None for only if not US-ASCII or UTF-8 or Unicode (default is None). default_namespace sets the default XML namespace (for “xmlns”). method is either "xml", "html" or "text" (default is "xml"). The keyword-only short_empty_elements parameter controls the formatting of elements that contain no content. If True (the default), they are emitted as a single self-closed tag, otherwise they are emitted as a pair of start/end tags. The output is either a string (str) or binary (bytes). This is controlled by the encoding argument. If encoding is "unicode", the output is a string; otherwise, it’s binary. Note that this may conflict with the type of file if it’s an open file object; make sure you do not try to write a string to a binary stream and vice versa. ---------- assignee: docs@python components: Documentation messages: 402981 nosy: docs@python, twowolfs priority: normal severity: normal status: open title: Issue with xml.tree.ElementTree.write type: performance versions: Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue45336> _______________________________________

4 13

[issue44544] Add full list of possible args to textwrap: wrap, fill, shorten
by Andrei Kulakov 19 Mar '22

19 Mar '22

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