Mailman 3 March 2022 - 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

[issue47138] Bump Sphinx to fix docs build
by Hugo van Kemenade April 8, 2022

April 8, 2022

New submission from Hugo van Kemenade <hugovk+python(a)gmail.com>: The docs build on GitHub Actions is passing on `main` but has started failing for the `3.7` - `3.10` branches: ``` Missing the required blurb or sphinx-build tools. Please run 'make venv' to install local copies. make[1]: *** [Makefile:50: build] Error 1 ``` https://github.com/python/cpython/actions/workflows/doc.yml https://github.com/python/cpython/runs/5714593700?check_suite_focus=true This is because the `PATH=./venv/bin:$PATH sphinx-build --version` check is failing: ``` /home/runner/work/cpython/cpython/Doc/venv/lib/python3.10/site-packages/sphinx/util/docutils.py:45: DeprecationWarning: distutils Version classes are deprecated. Use packaging.version instead. __version_info__ = tuple(LooseVersion(docutils.__version__).version) Traceback (most recent call last): File "/home/runner/work/cpython/cpython/Doc/./venv/bin/sphinx-build", line 5, in <module> from sphinx.cmd.build import main File "/home/runner/work/cpython/cpython/Doc/venv/lib/python3.10/site-packages/sphinx/cmd/build.py", line 25, in <module> from sphinx.application import Sphinx File "/home/runner/work/cpython/cpython/Doc/venv/lib/python3.10/site-packages/sphinx/application.py", line 42, in <module> from sphinx.registry import SphinxComponentRegistry File "/home/runner/work/cpython/cpython/Doc/venv/lib/python3.10/site-packages/sphinx/registry.py", line 24, in <module> from sphinx.builders import Builder File "/home/runner/work/cpython/cpython/Doc/venv/lib/python3.10/site-packages/sphinx/builders/__init__.py", line 26, in <module> from sphinx.util import import_object, logging, rst, progress_message, status_iterator File "/home/runner/work/cpython/cpython/Doc/venv/lib/python3.10/site-packages/sphinx/util/rst.py", line 22, in <module> from jinja2 import environmentfilter ImportError: cannot import name 'environmentfilter' from 'jinja2' (/home/runner/work/cpython/cpython/Doc/venv/lib/python3.10/site-packages/jinja2/__init__.py) ``` This is because `3.10` and `3.9` are still using old versions of Sphinx (3.2.1 and 2.4.4 respectively) which is incompatible with the newest Jinja2: https://github.com/pallets/jinja/issues/1630 `main` is using a newer Sphinx (4.2.0), so it passes. Bumping to Sphinx 4.5.0 will fix both `3.9` and `3.10`. `3.7` and `3.8` are affected too. We can bump `main` to use `4.5.0` as well. ---------- assignee: docs@python components: Documentation messages: 416149 nosy: docs@python, hugovk priority: normal severity: normal status: open title: Bump Sphinx to fix docs build 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/issue47138> _______________________________________

6 24

[issue46769] Improve documentation for `typing.TypeVar`
by Alex Waygood April 6, 2022

April 6, 2022

New submission from Alex Waygood <Alex.Waygood(a)Gmail.com>: There are three variants of `TypeVar`s: (1) TypeVars that are neither constrained nor bound: `T = TypeVar("T")` (2) TypeVars that are bound: `U = TypeVar("U", bound=str)` (3) TypeVars that are constrained: `V = TypeVar("V", str, bytes)` The third variant is important for annotating certain functions, such as those in the `re` module. However, it has a number of issues (see https://github.com/python/typing/discussions/1080 for further discussion): (1) It has somewhat surprising semantics in many situations. (2) It is difficult for type checkers to deal with, leading to a number of bugs in mypy, for example. (3) Many users (especially people relatively inexperienced with Python typing) reach for constrained TypeVars in situations where using bound TypeVars or the @overload decorator would be more appropriate. Both PEP 484 and the documentation for the typing module, however: (1) Give examples for variants (1) and (3), but not for variant (2), which is treated as something of an afterthought. (2) Do not mention that TypeVars can be bound to a union of types, which is an important point: `T = TypeVar("T", str, bytes)` has different semantics to `T = TypeVar("T", bound=str|bytes)`, and often the latter is more appropriate. ---------- assignee: docs@python components: Documentation messages: 413342 nosy: AlexWaygood, Jelle Zijlstra, docs@python, gvanrossum, kj, sobolevn priority: normal severity: normal stage: needs patch status: open title: Improve documentation for `typing.TypeVar` type: behavior versions: Python 3.10, Python 3.11, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue46769> _______________________________________

5 13

[issue47115] Documentation inconsistency with the stable ABI
by Jeremiah Gabriel Pascual April 6, 2022

April 6, 2022

New submission from Jeremiah Gabriel Pascual <nohackingofkrowten(a)gmail.com>: In https://docs.python.org/3/c-api/typeobj.html#static-types, it says that PyTypeObject isn't part of the stable ABI. Yet, in https://docs.python.org/3/c-api/type.html#c.PyTypeObject, it says that PyTypeObject IS part of the stable ABI. Which is true? ---------- assignee: docs@python components: Documentation messages: 415989 nosy: Crowthebird, docs@python priority: normal severity: normal status: open title: Documentation inconsistency with the stable ABI _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue47115> _______________________________________

3 5

[issue45210] tp_dealloc docs should mention error indicator may be set
by Edward Yang April 6, 2022

April 6, 2022

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

[issue47184] multiprocessing.set_start_method force argument is not documented
by John Hagen April 5, 2022

April 5, 2022

New submission from John Hagen <johnthagen(a)gmail.com>: multiprocessing.set_start_method() has a `force` argument that is not documented: https://docs.python.org/3.10/library/multiprocessing.html#multiprocessing.s… ---------- assignee: docs@python components: Documentation messages: 416451 nosy: John Hagen, docs@python priority: normal severity: normal status: open title: multiprocessing.set_start_method force argument is not documented type: enhancement 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/issue47184> _______________________________________

2 2

[issue46168] Incorrect format specified for the "style" key in the configuration file format formatter example
by David Bereza April 5, 2022

April 5, 2022

New submission from David Bereza <bokunogf(a)gmail.com>: Documentation link: https://docs.python.org/3/library/logging.config.html#configuration-file-fo… It seems that the example for the "formatter_form01" formatter section specifies following for the style(please note the single-quotes around the value). style='%' This seems to raise a ValueError with the message "Style must be one of..." when parsing the configuration file. Removing the single quotes seems to fix the issue: style=% ---------- assignee: docs@python components: Documentation messages: 409108 nosy: bokunogf, docs@python priority: normal severity: normal status: open title: Incorrect format specified for the "style" key in the configuration file format formatter example versions: Python 3.8 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue46168> _______________________________________

4 3

[issue45790] Inaccurate phrasing in extending/newtypes_tutorial
by Rodrigo Tobar April 5, 2022

April 5, 2022

New submission from Rodrigo Tobar <rtobarc(a)gmail.com>: In `extending/newtypes_tutorial.rst` the following phrase appears: "[...], containing a pointer to a type object and a reference count (these can be accessed using the macros :c:macro:`Py_REFCNT` and c:macro:`Py_TYPE` respectively)." I believe it should read "using the macros :c:macro:`Py_TYPE` and c:macro:`Py_REFCNT` respectively" to follow the same order in which the fields are described. I'll put forward a patch. It seems this phrase goes way back a few python versions, but I'm tagging 3.11 here only. ---------- assignee: docs@python components: Documentation messages: 406185 nosy: docs@python, rtobar2 priority: normal severity: normal status: open title: Inaccurate phrasing in extending/newtypes_tutorial versions: Python 3.11 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue45790> _______________________________________

4 7

[issue47007] [doc] str docs are inconsistent with special method lookup
by Vanshaj Singhania April 5, 2022

April 5, 2022

New submission from Vanshaj Singhania <svanshaj2001(a)gmail.com>: The documentation for the `str` class[^1] says: > If neither encoding nor errors is given, str(object) returns object.__str__() This led our students[^2] to try the following code: >>> class Test: ... def __str__(self): ... return 'hi' ... >>> test = Test() >>> test.__str__ = lambda self: 'bye' >>> str(test) The expected result was calling `test.__str__()`, but instead the interpreter output was `'hi'`. The docs for special method lookup[^3] do say that instance attributes are ignored: > For custom classes, implicit invocations of special methods are only guaranteed to work correctly if defined on an object’s type, not in the object’s instance dictionary. This makes sense, and explains the observed behavior, but the `str` class docs seem to be inconsistent with this. Perhaps it would be more clear if the `str` documentation mentioned that it called `type(object).__str__()` instead of `object.__str__()`. [^1]: https://docs.python.org/3/library/stdtypes.html#str [^2]: CS 61A at UC Berkeley, https://cs61a.org [^3]: https://docs.python.org/3/reference/datamodel.html#special-method-lookup ---------- assignee: docs@python components: Documentation messages: 415110 nosy: docs@python, itsvs priority: normal severity: normal status: open title: [doc] str docs are inconsistent with special method lookup type: enhancement versions: Python 3.10, Python 3.11, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue47007> _______________________________________

5 9

[issue47097] Document PEP 646
by Jelle Zijlstra April 5, 2022

April 5, 2022

New submission from Jelle Zijlstra <jelle.zijlstra(a)gmail.com>: https://docs.python.org/3.11/library/typing.html doesn't say anything about TypeVarTuple yet. ---------- assignee: docs@python components: Documentation messages: 415850 nosy: AlexWaygood, JelleZijlstra, docs@python, gvanrossum, kj, mrahtz priority: deferred blocker severity: normal stage: needs patch status: open title: Document PEP 646 versions: Python 3.11 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue47097> _______________________________________

3 5