From cd824e62a6ef70a6820ffb6b80be7fda2520bd60 Mon Sep 17 00:00:00 2001 From: David Caron Date: Mon, 24 Apr 2023 13:28:53 -0400 Subject: [PATCH 1/5] add link to constants list in site docs --- Doc/library/constants.rst | 2 ++ Doc/library/site.rst | 2 +- 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/Doc/library/constants.rst b/Doc/library/constants.rst index 38dd552a0363ac..f69766e9b61a25 100644 --- a/Doc/library/constants.rst +++ b/Doc/library/constants.rst @@ -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: + Constants added by the :mod:`site` module ----------------------------------------- diff --git a/Doc/library/site.rst b/Doc/library/site.rst index 4a88013f1d6ed2..67e528c2a8fcee 100644 --- a/Doc/library/site.rst +++ b/Doc/library/site.rst @@ -16,7 +16,7 @@ import can be suppressed using the interpreter's :option:`-S` option. .. index:: triple: module; search; path Importing this module will append site-specific paths to the module search path -and add a few builtins, unless :option:`-S` was used. In that case, this module +and add :ref:`a few builtins `, unless :option:`-S` was used. In that case, this module can be safely imported with no automatic modifications to the module search path or additions to the builtins. To explicitly trigger the usual site-specific additions, call the :func:`site.main` function. From e45577e0b815f3471d1a0777d81e22fa0232d1e5 Mon Sep 17 00:00:00 2001 From: David Caron Date: Mon, 24 Apr 2023 13:30:27 -0400 Subject: [PATCH 2/5] add `help` to constants added by site module --- Doc/library/constants.rst | 6 ++++++ Doc/library/functions.rst | 1 + 2 files changed, 7 insertions(+) diff --git a/Doc/library/constants.rst b/Doc/library/constants.rst index f69766e9b61a25..7bc58cccdf0e64 100644 --- a/Doc/library/constants.rst +++ b/Doc/library/constants.rst @@ -96,6 +96,12 @@ should not be used in programs. (i.e. EOF) to exit", and when called, raise :exc:`SystemExit` with the specified exit code. +.. data:: help + + Object that when printed, prints the message "Type help() for interactive + help, or help(object) for help about object.", and when called, invokes the + built-in :ref:`help ` function. + .. data:: copyright credits diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index 7792e598c1155c..7169a960780d23 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -789,6 +789,7 @@ are always available. They are listed here in alphabetical order. truncates the return value based on the bit width of the host machine. See :meth:`__hash__` for details. +.. _func-help: .. function:: help() help(request) From 13342fd42ae7d95ebea8948a993a83636d6721ba Mon Sep 17 00:00:00 2001 From: David Caron Date: Mon, 24 Apr 2023 14:02:33 -0400 Subject: [PATCH 3/5] add :noindex: and change link for `help` --- Doc/library/constants.rst | 3 ++- Doc/library/functions.rst | 1 - 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/constants.rst b/Doc/library/constants.rst index 7bc58cccdf0e64..57cc84e76207b2 100644 --- a/Doc/library/constants.rst +++ b/Doc/library/constants.rst @@ -97,10 +97,11 @@ should not be used in programs. specified exit code. .. data:: help + :noindex: Object that when printed, prints the message "Type help() for interactive help, or help(object) for help about object.", and when called, invokes the - built-in :ref:`help ` function. + built-in :func:`help` function. .. data:: copyright credits diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index 7169a960780d23..7792e598c1155c 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -789,7 +789,6 @@ are always available. They are listed here in alphabetical order. truncates the return value based on the bit width of the host machine. See :meth:`__hash__` for details. -.. _func-help: .. function:: help() help(request) From ca3b0f8b368dc566d2106e4eb1fc89f73d46dd04 Mon Sep 17 00:00:00 2001 From: David Caron Date: Sun, 26 May 2024 16:39:34 -0400 Subject: [PATCH 4/5] Apply suggestions from code review Co-authored-by: Terry Jan Reedy --- Doc/library/constants.rst | 4 ++-- Doc/library/site.rst | 5 +++-- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/Doc/library/constants.rst b/Doc/library/constants.rst index c2e6a80cfdfb05..0bc897c71f6082 100644 --- a/Doc/library/constants.rst +++ b/Doc/library/constants.rst @@ -100,8 +100,8 @@ should not be used in programs. :noindex: Object that when printed, prints the message "Type help() for interactive - help, or help(object) for help about object.", and when called, invokes the - built-in :func:`help` function. + help, or help(object) for help about object.", and when called, + acts as described :func:`elsewhere `. .. data:: copyright credits diff --git a/Doc/library/site.rst b/Doc/library/site.rst index a6fef7f6fd2e89..8519f310b1d4dd 100644 --- a/Doc/library/site.rst +++ b/Doc/library/site.rst @@ -15,8 +15,9 @@ import can be suppressed using the interpreter's :option:`-S` option. .. index:: triple: module; search; path -Importing this module will append site-specific paths to the module search path -and add :ref:`a few builtins `, unless :option:`-S` was used. In that case, this module +Importing this module normally appends site-specific paths to the module search path +and adds :ref:`callables `, including :func:`help`. to the built-in namespace. +However, Python startup option :option:`-S` blocks this and this module can be safely imported with no automatic modifications to the module search path or additions to the builtins. To explicitly trigger the usual site-specific additions, call the :func:`main` function. From 92a837072d0cac05c7d79649ef11f3586cb30785 Mon Sep 17 00:00:00 2001 From: David Caron Date: Sun, 26 May 2024 16:41:33 -0400 Subject: [PATCH 5/5] line length and remove `.` --- Doc/library/site.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/site.rst b/Doc/library/site.rst index 8519f310b1d4dd..0f9b5d9d654ad1 100644 --- a/Doc/library/site.rst +++ b/Doc/library/site.rst @@ -16,8 +16,8 @@ import can be suppressed using the interpreter's :option:`-S` option. .. index:: triple: module; search; path Importing this module normally appends site-specific paths to the module search path -and adds :ref:`callables `, including :func:`help`. to the built-in namespace. -However, Python startup option :option:`-S` blocks this and this module +and adds :ref:`callables `, including :func:`help` to the built-in +namespace. However, Python startup option :option:`-S` blocks this and this module can be safely imported with no automatic modifications to the module search path or additions to the builtins. To explicitly trigger the usual site-specific additions, call the :func:`main` function.