gh-103066: Add links and help in site.py constants
#103777
Conversation
|
All commit authors signed the Contributor License Agreement. |
|
@terryjreedy as a participant of the parent issue. |
There was a problem hiding this comment.
help() is already documented in functions.rst. Instead of documenting it again as a "constant", it may be better either to mention it explicitly when referring to the added builtins:
and add :func:`help` and :ref:`few other builtins <site-consts>`or add a reference to it in the description of the added constants:
adds the :func:`help` function and several constants to the built-in namespace.| @@ -79,6 +79,8 @@ A small number of constants live in the built-in namespace. They are: | |||
| :exc:`SyntaxError`), so they can be considered "true" constants. | |||
|
|
|||
|
|
|||
| .. _site-consts: | |||
There was a problem hiding this comment.
The objects above are all non-callable singleton or doubleton instances of their class. (debug is one of False or True). All of the below are callable singleton or doubleton instances of custom classes in _sitebuiltins. I would prefer that 'constants' be replaced by 'objects'/'callables'/'functions'/???, but this is secondary to the issue.
There was a problem hiding this comment.
I agree with your observation, they are not exactly constants. As the title of this section is "Built-in Constants", I won't make any changes, I feel it's a bit out of scope.
There was a problem hiding this comment.
I would take the opportunity to improve this to say that the site module adds several globals to the built-in namespace
|
A Python core developer has requested some changes be made to your pull request before we can consider merging it. If you could please address their requests along with any other requests in other reviews from core developers that would be appreciated. Once you have made the requested changes, please leave a comment on this pull request containing the phrase |
|
Hi @davidcaron , thank you for the contribution.
|
Co-authored-by: Terry Jan Reedy <tjreedy@udel.edu>
| @@ -79,6 +79,8 @@ A small number of constants live in the built-in namespace. They are: | |||
| :exc:`SyntaxError`), so they can be considered "true" constants. | |||
|
|
|||
|
|
|||
| .. _site-consts: | |||
There was a problem hiding this comment.
I agree with your observation, they are not exactly constants. As the title of this section is "Built-in Constants", I won't make any changes, I feel it's a bit out of scope.
|
I have made the requested changes; please review again. |
|
Thanks for making the requested changes! @terryjreedy: please review the changes made to this pull request. |
|
@serhiy-storchaka The only docs failure reason I could find in the raw log, |
|
Does this still apply to the new REPL? https://docs.python.org/3.13/whatsnew/3.13.html#a-better-interactive-interpreter |
|
I don’t see any difference for |
|
There's a difference with ❯ python3.12 -S
Python 3.12.5 (v3.12.5:ff3bc82f7c9, Aug 7 2024, 05:32:06) [Clang 13.0.0 (clang-1300.0.29.30)] on darwin
>>> help(dir)
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
NameError: name 'help' is not defined
>>> help
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
NameError: name 'help' is not defined
>>> ^D❯ python3.13 -S
Python 3.13.0rc1 (v3.13.0rc1:e4a3e786a5e, Jul 31 2024, 19:49:53) [Clang 15.0.0 (clang-1500.3.9.4)] on darwin
>>> help(dir)
Traceback (most recent call last):
File "<python-input-0>", line 1, in <module>
help(dir)
^^^^
NameError: name 'help' is not defined
>>> help
>>> Welcome to Python 3.13's help utility! If this is your first time using
Python, you should definitely check out the tutorial at
https://docs.python.org/3.13/tutorial/.
Enter the name of any module, keyword, or topic to get help on writing
Python programs and using Python modules. To get a list of available
modules, keywords, symbols, or topics, enter "modules", "keywords",
"symbols", or "topics".
Each module also comes with a one-line summary of what it does; to list
the modules whose name or summary contain a given string such as "spam",
enter "modules spam".
To quit this help utility and return to the interpreter,
enter "q", "quit" or "exit".
help>So this text may be technically correct, in that the
Maybe it's confusing that the Is this a bug in the new REPL? |
|
This is not a bug. When -S prevents site.py from running, the visible effect is fewer imported modules and fewer entries in globals. That's the intended goal. While that means that the old-style help() and exit() callables are gone in this scenario, making the functionality itself unavailable was not the goal. Therefore, it's perfectly fine that the new-style commands (that do not require entries in globals) continue to work. |
|
Thanks @davidcaron for the PR, and @hugovk for merging it 🌮🎉.. I'm working now to backport this PR to: 3.13. |
|
Thanks @davidcaron for the PR, and @hugovk for merging it 🌮🎉.. I'm working now to backport this PR to: 3.12. |
…103777) (cherry picked from commit 67957ea) Co-authored-by: David Caron <dcaron05@gmail.com> Co-authored-by: Terry Jan Reedy <tjreedy@udel.edu> Co-authored-by: Łukasz Langa <lukasz@langa.pl> Co-authored-by: Serhiy Storchaka <storchaka@gmail.com> Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>
…103777) (cherry picked from commit 67957ea) Co-authored-by: David Caron <dcaron05@gmail.com> Co-authored-by: Terry Jan Reedy <tjreedy@udel.edu> Co-authored-by: Łukasz Langa <lukasz@langa.pl> Co-authored-by: Serhiy Storchaka <storchaka@gmail.com> Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>
|
GH-123762 is a backport of this pull request to the 3.13 branch. |
|
GH-123763 is a backport of this pull request to the 3.12 branch. |
… (#123762) Co-authored-by: David Caron <dcaron05@gmail.com> Co-authored-by: Terry Jan Reedy <tjreedy@udel.edu> Co-authored-by: Łukasz Langa <lukasz@langa.pl> Co-authored-by: Serhiy Storchaka <storchaka@gmail.com> Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>
… (#123763) Co-authored-by: David Caron <dcaron05@gmail.com> Co-authored-by: Terry Jan Reedy <tjreedy@udel.edu> Co-authored-by: Łukasz Langa <lukasz@langa.pl> Co-authored-by: Serhiy Storchaka <storchaka@gmail.com> Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>
Fixes issue: #103066
The issue mentioned that the
site.pydocumentation didn't have a list of objects it adds to builtins.I found this list exists somewhere else in the documentation (built-in constants), so I figured linking to it was simpler.
Also the
helpspecial constant wasn't mentioned in this list of site-added constants, so I added it with a link to the built-in functions section where it's documented more extensively.