Mailman 3 August 2021 - Docs-bugs

[issue44174] Unclear meaning of _Private__names in enum docs.
by Gregory P. Smith 21 Oct '21

21 Oct '21

New submission from Gregory P. Smith <greg(a)krypto.org>: https://docs.python.org/3/library/enum.html#private-names """ _Private__names Private names will be normal attributes in Python 3.10 instead of either an error or a member (depending on if the name ends with an underscore). Using these names in 3.9 will issue a DeprecationWarning. """ It isn't clear from this documentation what is meant by "private names". Please expand on this to be explicit about what name pattern is being described. ---------- assignee: docs@python components: Documentation messages: 393919 nosy: docs@python, gregory.p.smith priority: normal severity: normal stage: needs patch status: open title: Unclear meaning of _Private__names in enum docs. versions: Python 3.10, Python 3.11, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue44174> _______________________________________

4 11

[issue44113] [C API] Deprecate legacy API for configure Python initialization
by STINNER Victor 15 Oct '21

15 Oct '21

New submission from STINNER Victor <vstinner(a)python.org>: The https://docs.python.org/dev/c-api/init.html documentation lists many functions which is the legacy way to configure the Python initialization. These functions are kept for backward compatibility but have flaws and are less reliable than the new PyConfig API (PEP 587) documented at https://docs.python.org/dev/c-api/init_config.html I propose to deprecate the legacy functions to configure the Python initialization. Examples: * Py_SetPath() * Py_SetProgramName() * Py_SetPythonHome() * Py_SetStandardStreamEncoding() * PySys_AddWarnOption() * PySys_AddWarnOptionUnicode() * PySys_AddXOption() I don't propose to schedule the removal of these functions, only mark them as deprecated in the *documentation*. Related issue: bpo-43956 "C-API: Incorrect default value for Py_SetProgramName" and PR 24876. ---------- assignee: docs@python components: C API, Documentation messages: 393499 nosy: docs@python, vstinner priority: normal severity: normal status: open title: [C API] Deprecate legacy API for configure Python initialization versions: Python 3.11 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue44113> _______________________________________

3 13

[issue44809] Changelog missing removal of StrEnum etc.
by Sebastian Rittau 29 Sep '21

29 Sep '21

New submission from Sebastian Rittau <srittau(a)rittau.biz>: It seems that at some point StrEnum and a few other members were added to Python 3.10. I think they were present in 3.10 beta 2, but it seems they were removed by beta 4. While the Changelog at https://docs.python.org/3.10/whatsnew/changelog.html mentions that they were added, there is no note about their removal again. ---------- assignee: docs@python components: Documentation messages: 398760 nosy: docs@python, srittau priority: normal severity: normal status: open title: Changelog missing removal of StrEnum etc. versions: Python 3.10 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue44809> _______________________________________

4 3

[issue39452] Improve the __main__ module documentation
by Géry 31 Aug '21

31 Aug '21

Géry <gery.ogam(a)gmail.com> added the comment: No worries, it was almost twenty years ago. > But it's probably better to raise a dedicated exception in that case and catch it in main(), rather than just calling sys.exit() deep inside the other code. Yes I agree, and I think you explained very clearly why it is better in the blog post: > Another refinement is to define a Usage() exception, which we catch in an except clause at the end of main(): > […] > This gives the main() function a single exit point, which is preferable over multiple return 2 statements. So I think you made two independent points: - raising a dedicated exception instead of calling `sys.exit` inside nested functions and catching it inside `main` allows a single exit point; - calling `sys.exit` outside of `main` instead of inside prevents exiting the Python interpreter in an interactive session. ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue39452> _______________________________________

1 0

[issue39452] Improve the __main__ module documentation
by Jack DeVries 31 Aug '21

31 Aug '21

Jack DeVries <jdevries3133(a)gmail.com> added the comment: > Your docs seem to promote the second, whereas I've usually preferred the > former. Was this a considered choice on your part? First and foremost, stupid GitHub is not letting the permalink load for some reason, but yes; this was discussed in the conversation with @graingert on June 29th – it was his suggestion. Later, @pradyunsg from PyPa added some suggestions about how the document described console script entrypoints, and the documentation around this issue changed a bit again. As far as my perspective, I also never personally use the sys.exit idiom myself. After all, an exception is going to cause a non-zero exit code, and a traceback is always going to have a lot more value than an exit code. I was, however, surprised to learn how pip treats console script entry points in the course of working on this document. Specifically, it generates an executable script that does wrap the function in sys.exit.I definitely think that the way the document communicates this fact while teaching the idiom is a good thing, so I think that whole "Idiomatic Usage" section is good. I do think we can tweak the document slightly to make it less prescriptive, though, because in reality a lot of people _don't_ use this idiom, so presenting it as a de-facto standard is misleading. Plus, it's not Pythonic to dole out prescriptive boilerplate. I attached a diff that steers in that direction. What do you all think? It is a pretty slight change, but I think it better strikes a balance. ---------- Added file: https://bugs.python.org/file50249/less_prescriptive.diff _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue39452> _______________________________________

1 0

[issue39452] Improve the __main__ module documentation
by Guido van Rossum 31 Aug '21

31 Aug '21

Guido van Rossum <guido(a)python.org> added the comment: You're right, I'm being inconsistent. :-( I withdraw my objection. There are cases where sys.exit() is easier than returning an exit code, e.g. when the error is discovered deep inside some other code. But it's probably better to raise a dedicated exception in that case and catch it in main(), rather than just calling sys.exit() deep inside the other code. It's probably too fine a point for a tutorial. Sorry! ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue39452> _______________________________________

1 0

[issue39452] Improve the __main__ module documentation
by Géry 31 Aug '21

31 Aug '21

Géry <gery.ogam(a)gmail.com> added the comment: @jack__d Thanks for the rewrite! This is a great expansion. Unfortunately I didn’t have the time to review it before the merge. If I find something to be improved I will let you know. @gvanrossum > Your docs seem to promote the second, whereas I've usually preferred the former. Are you sure? Yet in your 2003 blog post [*Python main() functions*](https://www.artima.com/weblogs/viewpost.jsp?thread=4829) you promoted the opposite idiom `if __name__ == "__main__": sys.exit(main())` over the idiom `if __name__ == "__main__": main()`: > Now the `sys.exit()` calls are annoying: when `main()` calls `sys.exit()`, your interactive Python interpreter will exit! The remedy is to let `main()`'s return value specify the exit status. I am interested in the rationale if you changed your mind. ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue39452> _______________________________________

1 0

[issue33426] [doc] Behavior of os.path.join does not match documentation
by Zachary Ware 31 Aug '21

31 Aug '21

Change by Zachary Ware <zachary.ware(a)gmail.com>: ---------- nosy: +zach.ware _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue33426> _______________________________________

1 0

[issue44135] issubclass documentation doesn't explain tuple semantic
by João Henrique Pimentel 31 Aug '21

31 Aug '21

New submission from João Henrique Pimentel <joaozinho(a)gmail.com>: The second parameter (classinfo) of the issubclass built-in function can be a Tuple and, starting from 3.10, it can be a Union Type as well. The documentation states that in these cases "every entry in classinfo will be checked", but it doesn't explain if the check is AND (all) or OR (any). In contrast, the documentation of isinstance is clear: "return True if object is an instance of *any* of the types". Here's a possible rewriting that reduces the odds of incorrect interpretations, based on the text of isinstance: ORIGINAL: "in which case every entry in classinfo will be checked" PROPOSAL: "in which case return True if class is a subclass of any entry in classinfo" ---------- assignee: docs@python components: Documentation messages: 393684 nosy: docs@python, joaozinho priority: normal severity: normal status: open title: issubclass documentation doesn't explain tuple semantic 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/issue44135> _______________________________________

5 12

[issue17576] PyNumber_Index() is not int-subclass friendly (or operator.index() docs lie)
by STINNER Victor 31 Aug '21

31 Aug '21

STINNER Victor <vstinner(a)python.org> added the comment: > If we go in this direction we should add a DeprecationWarning for __str__() returning not direct str. I saw str subclass being used for translation. Example: class Message(str): """A Message object is a unicode object that can be translated. Translation of Message is done explicitly using the translate() method. For all non-translation intents and purposes, a Message is simply unicode, and can be treated as such. """ https://github.com/openstack/oslo.i18n/blob/master/oslo_i18n/_message.py There is likely other funny use cases. I don't know if str() is used on Message instances. ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue17576> _______________________________________

1 0