Mailman 3 January 2022 - Docs-bugs

[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

[issue46013] Confusing period in object.__hash__ doc
by JMcB 20 Mar '22

20 Mar '22

New submission from JMcB <joel.mcbride1(a)live.com>: At https://docs.python.org/3/reference/datamodel.html#object.__hash__ It says: Called by built-in function hash() and for operations on members of hashed collections including set, frozenset, and dict. __hash__() should return an integer. How it's rendered there, the kerning made it confusing to me on a first read because dict. [new sentence]__hash__() looked like dict.__hash__(). I think a line break should be added, which I'll open a pr to do. ---------- assignee: docs@python components: Documentation messages: 408014 nosy: JMcB17, docs@python priority: normal severity: normal status: open title: Confusing period in object.__hash__ doc type: enhancement versions: Python 3.10 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue46013> _______________________________________

5 9

[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

[issue46291] [doc] First argument to raise can also be BaseException
by Gregor Titze 15 Mar '22

15 Mar '22

New submission from Gregor Titze <gregor.titze(a)gmail.com>: The Python Tutorial describes the first argument to the raise statement as follows: """ This must be either an exception instance or an exception class (a class that derives from Exception). """ https://docs.python.org/3/tutorial/errors.html#raising-exceptions However, the Python Language Reference states, that exceptions should be a subclass or instance of BaseException. https://docs.python.org/3/reference/simple_stmts.html#grammar-token-python-… I think it would be correct, to adapt the Tutorial to match the Reference. ---------- assignee: docs@python components: Documentation messages: 409961 nosy: docs@python, gtitze priority: normal severity: normal status: open title: [doc] First argument to raise can also be BaseException 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/issue46291> _______________________________________

5 18

[issue45680] Documentation on `GenericAlias` objects could be improved
by Alex Waygood 08 Mar '22

08 Mar '22

New submission from Alex Waygood <Alex.Waygood(a)Gmail.com>: The documentation on `GenericAlias` objects implies at multiple points that only container classes can implement `__class_getitem__`, and goes into very little detail about what it means for a non-container class to be parameterized. ---------- assignee: docs@python components: Documentation messages: 405384 nosy: AlexWaygood, docs@python, gvanrossum, kj, lukasz.langa priority: normal severity: normal status: open title: Documentation on `GenericAlias` objects could be improved type: behavior versions: Python 3.10, Python 3.11, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue45680> _______________________________________

5 39

[issue46494] Mention typing_extensions in the typing documentation
by Jelle Zijlstra 07 Mar '22

07 Mar '22

New submission from Jelle Zijlstra <jelle.zijlstra(a)gmail.com>: I've often seen people say things like "I can't use TypeGuard yet, I'm stuck on 3.9". That's not true, because the typing_extensions package backports all typing features to all supported Python versions. To help make people aware of this option, we should mention typing_extensions in https://docs.python.org/3.10/library/typing.html. Perhaps this can go in the "Relevant PEPs" section, or at the end of the intro section. Suggested wording: "New features have been added to the typing module in each major version of Python. The typing extensions (link to GitHub) package provides backports to all supported versions of Python 3 for almost all of these features." ---------- assignee: docs@python components: Documentation messages: 411434 nosy: AlexWaygood, Jelle Zijlstra, docs@python, gvanrossum, kj, sobolevn, srittau priority: normal severity: normal status: open title: Mention typing_extensions in the typing documentation versions: Python 3.10, Python 3.11, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue46494> _______________________________________

7 13

[issue45492] stdlib inspect documentation on code.co_names is incorrect
by Dutcho 02 Mar '22

02 Mar '22

New submission from Dutcho <dutcho(a)ziggo.nl>: The standard library documentation on module inspect starts with an overview of types and attributes. This overview (in all Python versions) states: code.co_names: tuple of names of local variables code.co_varnames: tuple of names of arguments and local variables That suggests the argument names are set(code.co_varnames) - set(code.co_names), which is incorrect. I think the attribute description should be: code.co_names: tuple of names of used global and built-in variables >>> def f(x): a = 1; print(f, a) >>> assert f.__code__.co_varnames == ('x', 'a') # argument and local, in that order >>> assert set(f.__code__.co_names) == set(('f', 'print')) # global and built-in (don't care order), not local ---------- assignee: docs@python components: Documentation messages: 404068 nosy: Dutcho, docs@python priority: normal severity: normal status: open title: stdlib inspect documentation on code.co_names is incorrect 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/issue45492> _______________________________________

3 6

[issue45991] Improve ambiguous docstrings in pkgutil
by Kevin Hock 28 Feb '22

28 Feb '22

New submission from Kevin Hock <khock(a)pinterest.com>: # Issue If you search for "list of paths" in https://github.com/KevinHock/cpython/blob/main/Lib/pkgutil.py A lot of people mistake this as `PosixPath`. You can see an example here: https://github.com/duo-labs/parliament/pull/207 that references other OSS repositories. # Solution We can - Change the wording. e.g. "list of strings of the paths" or some variation of that. and perhaps additionally - Throw a ValueError similar to: https://github.com/python/cpython/blob/628abe4463ed40cd54ca952a2b4cc2d6e740… ---------- assignee: docs@python components: Documentation messages: 407727 nosy: docs@python, khock priority: normal severity: normal status: open title: Improve ambiguous docstrings in pkgutil 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/issue45991> _______________________________________

4 7

[issue45735] Promise that the long-time truth that `args=list` works
by Tim Peters 25 Feb '22

25 Feb '22

New submission from Tim Peters <tim(a)python.org>: A number of contexts allow specifying a tuple of arguments to be passed later to a function. The Thread constructor is a fine example, and happened to come up (again! for me) here today: https://stackoverflow.com/questions/69858950/why-do-we-have-to-add-comma-in… This often confuses especially newbies, because the function they intend to parallelize often takes only a single argument, and Python's syntax for a 1-element tuple actually _requires_ parentheses in the context of an argument list, with a naked trailing comma: t = threading.Thread(target=access, args=(thread_number,)) It "looks weird" to people. I'm not suggesting to change that, but instead to officially bless the workaround I've seen very often in real code: use a list instead. t = threading.Thread(target=access, args=[thread_number]) Nobody scratches their head over what that means. CPython's implementations typically couldn't care less what kind of sequence is used, and none that I'm aware of verify that it's specifically a tuple. The implementations just go on to do some simple variation of self.target(*self.args) Tuple or list makes no real difference. I'm not really keen to immortalize the "any sequence type whatsoever that just happens to work" implementation behavior, but am keen to promise that a list specifically will work. A lot of code already relies on it. ---------- assignee: docs@python components: Documentation keywords: easy messages: 405846 nosy: docs@python, tim.peters priority: low severity: normal stage: needs patch status: open title: Promise that the long-time truth that `args=list` works type: behavior versions: Python 3.11 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue45735> _______________________________________

5 11