Mailman 3 December 2021 - Docs-bugs

[issue46066] Docs: TypedDict alternative definition syntax with keyword args is confusing
by 97littleleaf11 Feb. 4, 2022

Feb. 4, 2022

New submission from 97littleleaf11 <97littleleaf11(a)gmail.com>: According to the docs: https://docs.python.org/3/library/typing.html?#typing.TypedDict, there are two additional equivalent syntax for TypedDict definition. Point2D = TypedDict('Point2D', x=int, y=int, label=str) Point2D = TypedDict('Point2D', {'x': int, 'y': int, 'label': str}) However, the former one is quite confusing since we have the `total` keyword arg for TypedDict. In addition, PEP589(https://www.python.org/dev/peps/pep-0589/#id19) doesn't have this. I think we could discard the definition syntax using keyword args in the doc. ---------- assignee: docs@python components: Documentation messages: 408458 nosy: 97littleleaf11, docs@python priority: normal severity: normal status: open title: Docs: TypedDict alternative definition syntax with keyword args is confusing versions: Python 3.10, Python 3.8, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue46066> _______________________________________

3 8

[issue45380] help() appears confused about the module of typing.Annotated
by Alex Waygood Feb. 3, 2022

Feb. 3, 2022

New submission from Alex Waygood <Alex.Waygood(a)Gmail.com>: `help()` appears confused about the module of `typing.Annotated`. If you call `help()` on a parameterised "instance" of `typing.Annotated`, it will claim that `Annotated` belongs to whatever module the annotated type is from. Additionally, `help()` appears not to know about the `__metadata__` attribute of `typing.Annotated`. ``` >>> from typing import Annotated, Callable >>> t = Annotated[int | str, "Some metadata"] >>> help(t) Help on _AnnotatedAlias in module types: Annotated = int | str >>> u = Annotated[Callable[[int], str], "Some metadata"] >>> help(u) Help on _AnnotatedAlias in module typing: Annotated = typing.Callable[[int], str] >>> s = Annotated[int, "Some metadata"] Help on _AnnotatedAlias in module builtins: Annotated = class int(object) | int([x]) -> integer | int(x, base=10) -> integer # (etc., giving the entire output of help() for `int`) ``` ---------- assignee: docs@python components: Documentation, Library (Lib) messages: 403258 nosy: AlexWaygood, docs@python priority: normal severity: normal status: open title: help() appears confused about the module of typing.Annotated type: behavior versions: Python 3.10, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue45380> _______________________________________

3 4

[issue46005] [doc] replace 'distutils' examples with 'setuptools'
by Elmir Feb. 2, 2022

Feb. 2, 2022

New submission from Elmir <elmir.jagudin(a)maxiv.lu.se>: As the distutils have been deprecated, the documentation on building C/C++ extension modules should be updated to use more future proof tool. I guess the section: 'Building C and C++ Extensions with distutils' should be replaced with: 'Building C and C++ Extensions with setuptools' Here is link to the section that needs to be updated/replaced: https://docs.python.org/3/extending/building.html#building-c-and-c-extensio… ---------- assignee: docs@python components: Documentation messages: 407896 nosy: docs@python, elmjag priority: normal severity: normal status: open title: [doc] replace 'distutils' examples with 'setuptools' type: enhancement versions: Python 3.10, Python 3.11 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue46005> _______________________________________

4 6

[issue45990] Exception notes need more documentation
by Ram Rachum Jan. 30, 2022

Jan. 30, 2022

New submission from Ram Rachum <ram(a)rachum.com>: The new __note__ feature for exception could be useful, but the documentation (and the section in "What's new") aren't good enough: "__note__: A mutable field which is :const:`None` by default and can be set to a string. If it is not :const:`None`, it is included in the traceback. This field can be used to enrich exceptions after they have been caught." This is more of a definition than an explanation. If this is solving a problem, there should be an explanation that starts from the problem being solved, hopefully with 2-3 examples where this is useful. If people start using this feature without some guidance, they might put things in the note that should have been in the message. ---------- assignee: docs@python components: Documentation messages: 407722 nosy: cool-RR, docs@python, iritkatriel priority: normal severity: normal status: open title: Exception notes need more documentation versions: Python 3.11 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue45990> _______________________________________

2 1

[issue46157] Typo in JSON documentation
by Jordan Bonecutter Jan. 24, 2022

Jan. 24, 2022

New submission from Jordan Bonecutter <jordanbonecutter(a)gmail.com>: In this doc: https://docs.python.org/3/library/json.html#json.dump The section on check_circular has a typo: ...a circular reference will result in an RecursionError => a RecursionError ---------- assignee: docs@python components: Documentation messages: 409051 nosy: docs@python, jordan-bonecutter priority: normal severity: normal status: open title: Typo in JSON documentation type: enhancement _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue46157> _______________________________________

5 14

[issue45298] SIGSEGV when access a fork Event in a spawn Process
by Keming Jan. 23, 2022

Jan. 23, 2022

New submission from Keming <kemingy94(a)gmail.com>: Code to trigger this problem: ```python import multiprocessing as mp from time import sleep def wait_for_event(event): while not event.is_set(): sleep(0.1) def trigger_segment_fault(): event = mp.get_context("fork").Event() p = mp.get_context("spawn").Process(target=wait_for_event, args=(event,)) p.start() # this will show the exitcode=-SIGSEGV sleep(1) print(p) event.set() p.terminate() if __name__ == "__main__": trigger_segment_fault() ``` Accessing this forked event in a spawned process will result in a segment fault. I have found a related report: https://bugs.python.org/issue43832. But I think it's not well documented in the Python 3 multiprocessing doc. Will it be better to explicit indicate that the event is related to the start method context in the documentation? ---------- assignee: docs@python components: Documentation messages: 402687 nosy: docs@python, kemingy priority: normal severity: normal status: open title: SIGSEGV when access a fork Event in a spawn Process type: crash _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue45298> _______________________________________

2 1

[issue45877] Inconsistency in minimal supported version of Microsoft Visual Studio
by Oleg Iarygin Jan. 21, 2022

Jan. 21, 2022

New submission from Oleg Iarygin <oleg(a)arhadthedev.net>: According to PCbuild/readme.txt: > Using this directory requires an installation of > Microsoft Visual Studio 2017 (MSVC 14.1) of any edition. However, Doc/using/windows.rst states that Visual Studio 2017 is not required and 2015 may be used instead: > The source tree contains a build solution and project files for Microsoft > Visual Studio 2015, which is the compiler used to build the official Python > releases. VS 2017 mention was introduced in GH-3418. So either PCbuild readme needs to relax its requirements back or windows.rst needs to be updated. ---------- assignee: docs@python components: Build, Documentation messages: 406826 nosy: arhadthedev, docs@python, steve.dower priority: normal severity: normal status: open title: Inconsistency in minimal supported version of Microsoft Visual Studio type: behavior 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/issue45877> _______________________________________

2 2

[issue45554] multiprocessing exitcode is insufficiently documented
by John Marshall Jan. 18, 2022

Jan. 18, 2022

New submission from John Marshall <jmarshall(a)hey.com>: <https://docs.python.org/3.11/library/multiprocessing.html#multiprocessing.P…> describes exitcode as "The child’s exit code. This will be None if the process has not yet terminated. A negative value -N indicates that the child was terminated by signal N." and similarly in earlier documentation versions. This does not describe what the exit code will be under normal circumstances, or if the child abends by raising a Python exception. By examination of BaseProcess._bootstrap() it can be determined that the current behaviour appears to be: * even if your subclass overrides the run() method, whatever this method returns is ignored (and in particular the return value has no effect on the child's exit code); * if the run() method returns normally, the child's exit code will be 0; * if the run() method raises SystemExit (or, I guess, calls sys.exit()) with an integer exit status, that exit status will be propagated to the child's exit code; * if the run() method raises any other exception, the exception traceback will be printed to stderr and the child's exit code will be 1. However I did not see a way to figure these details out from the documentation, and it is unclear whether all these details are supported behaviours. ---------- assignee: docs@python components: Documentation messages: 404597 nosy: docs@python, jmarshall priority: normal severity: normal status: open title: multiprocessing exitcode is insufficiently documented type: behavior _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue45554> _______________________________________

5 11

[issue37800] Clean up the documentation on module attributes
by miss-islington Jan. 16, 2022

Jan. 16, 2022

New submission from miss-islington <mariatta.wijaya+miss-islington(a)gmail.com>: New changeset d7e210070f915d8df5fa863ecba8628304ee1ded by Géry Ogam in branch 'main': bpo-37800: Clean up importlib documentation for some module attributes (GH-10016) https://github.com/python/cpython/commit/d7e210070f915d8df5fa863ecba8628304… ---------- nosy: +miss-islington _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue37800> _______________________________________

2 1

[issue46017] Tutorial incorrectly refers to skits rather than sketches.
by Ben Ricketts Jan. 14, 2022

Jan. 14, 2022

New submission from Ben Ricketts <benricketts77(a)gmail.com>: https://docs.python.org/3/tutorial/appetite.html 4th paragraph from bottom refers to "skits" where as Monty Python in fact perform sketch comedy.It is a minor but important differentiation. ---------- assignee: docs@python components: Documentation messages: 408049 nosy: benricketts77, docs@python priority: normal severity: normal status: open title: Tutorial incorrectly refers to skits rather than sketches. 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/issue46017> _______________________________________

3 2