Mailman 3 December 2021 - Docs-bugs

[issue45618] Documentation builds fail with Sphinx 3.2.1
by Maciej Olko March 28, 2022

March 28, 2022

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

March 21, 2022

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

March 20, 2022

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

[issue45680] Documentation on `GenericAlias` objects could be improved
by Alex Waygood March 8, 2022

March 8, 2022

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

[issue45492] stdlib inspect documentation on code.co_names is incorrect
by Dutcho March 2, 2022

March 2, 2022

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 Feb. 28, 2022

Feb. 28, 2022

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 Feb. 25, 2022

Feb. 25, 2022

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

[issue46200] Discourage logging f-strings due to security considerations
by Arie Bovenberg Feb. 19, 2022

Feb. 19, 2022

New submission from Arie Bovenberg <a.c.bovenberg(a)gmail.com>: (I've already submitted this issue to security(a)python.org, who directed me to propose a documentation change here) Logging f-strings is quite popular, because the `%` style of logging is often considered ugly. However, logging preformatted strings comes with security risks which should explicitly be mentioned in the logging documentation. The following example illustrates the problem: logger.info('look: %s', untrusted_string) # OK logger.info('look: %(foo)s', {'foo', untrusted_string}) # OK logger.info(f'look: {untrusted_string}') # OK (security-wise) logger.info(f'look: {untrusted_string}', some_dict) # DANGER! The problem is that `untrusted_string` will be interpreted as a string template by the logger. If `untrusted_string` has the value `%(foo)999999999s` (where foo is present in `some_dict`), logging gets stuck trying to add over a gigabyte of whitespace to a string. In other words: a Denial-of-Service attack. Of course, this combination of f-string and logger arguments is unlikely. But it is plausible that: - After a refactoring to f-string, removing the dict argument is forgotten; - A developer adding a variable to a message prefers using f-strings and thus creates a template mixing the two styles (e.g. `{foo} and %(bar)s`); - The string is passed through a logging Filter or other function which adds a dict argument. Open questions: 1. Do we want to simply highlight the risks, or actively discourage logging f-strings? My thoughts: I feel it's important enough to actively discourage logging preformatted strings (i.e. also .format and manual %-formatting). A strong recommendation will allow security linters to flag this. Additionally, there are other advantages to the formatting built into `logging` (e.g. performance). 2. Should we type annotate logger `msg` as `Literal[str]` following PEP675? My thoughts: Annotating `msg` as a literal string will greatly help enforce this best practice. The adoption of typecheckers exceeds that of security linters. 3. Where should this risk be documented? a. In the `logger.debug` function docs b. In the `logging` docs introduction (like xml.etree.elementtree) c. In a new "security" section of the `logging` docs d. An informational PEP on logging security considerations (similar to PEP672) My thoughts: I fear option (a) would not get the attention of most readers. Option (c) or (d) may be useful to also highlight general risks of logging (i.e. log injection) As soon as there is agreement on these questions, I would be happy to submit a PR. ---------- assignee: docs@python components: Documentation messages: 409352 nosy: ariebovenberg, docs@python priority: normal severity: normal status: open title: Discourage logging f-strings due to security considerations type: security versions: Python 3.10, Python 3.11, Python 3.7, Python 3.8, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue46200> _______________________________________

8 16

[issue45393] help() on operator precedence has confusing entries "avait" "x" and "not" "x"
by Max Feb. 10, 2022

Feb. 10, 2022

New submission from Max <mh+bugs.python.org(a)dsi972.fr>: Nobody seems to have noticed this AFAICS: If you type, e.g., help('+') to get help on operator precedence, the fist column gives a lit of operators for each row corresponding to a given precedence. However, the row for "not" (and similar for "await"), has the entry "not" "x" That looks as if there were two operators, "not" and "x". But the letter x is just an argument to the operator, so it should be: "not x" exactly as for "+x" and "-x" and "~x" and "x[index]" and "x.attribute", where also x is not part of the operator but an argument. On the corresponding web page https://docs.python.org/3/reference/expressions.html#operator-summary it is displayed correctly, there are no quotes. ---------- assignee: docs@python components: Documentation messages: 403321 nosy: MFH, docs@python priority: normal severity: normal status: open title: help() on operator precedence has confusing entries "avait" "x" and "not" "x" 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/issue45393> _______________________________________

5 8