From 6020a5393da4371156e0e5f877b148a2b25f3533 Mon Sep 17 00:00:00 2001 From: Neil Schemenauer Date: Tue, 8 Oct 2024 10:44:59 -0700 Subject: [PATCH 1/3] gh-125142: add REPL help text for keyboard shortcuts --- Lib/pydoc.py | 70 ++++++++++++++----- ...-10-08-10-44-14.gh-issue-125142.HVlHrs.rst | 2 + 2 files changed, 55 insertions(+), 17 deletions(-) create mode 100644 Misc/NEWS.d/next/Documentation/2024-10-08-10-44-14.gh-issue-125142.HVlHrs.rst diff --git a/Lib/pydoc.py b/Lib/pydoc.py index eec7b0770f56ca..4e04723f6f4aa8 100644 --- a/Lib/pydoc.py +++ b/Lib/pydoc.py @@ -1797,6 +1797,55 @@ def writedocs(dir, pkgpath='', done=None): writedoc(modname) return + +def _intro_basic(): + # Intro text if basic REPL is used. + ver = '%d.%d' % sys.version_info[:2] + return f'''\ +Welcome to Python {ver}'s help utility! If this is your first time using +Python, you should definitely check out the tutorial at +https://docs.python.org/{ver}/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". +''' + + +def _intro_pyrepl(): + # Intro text if enhanced (non-basic) REPL is used. + ver = '%d.%d' % sys.version_info[:2] + return f''' +Welcome to Python {ver}'s help utility! If this is your first time using +Python, you should definitely check out the tutorial at +https://docs.python.org/{ver}/tutorial/. + +You can use the following keyboard shortcuts at the main interpreter prompt. +F1: enter interactive help, F2: enter history browsing mode, F3: enter paste +mode (press again to exit). + +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". +''' + + class Helper: # These dictionaries map a topic name to either an alias, or a tuple @@ -2063,23 +2112,10 @@ def help(self, request, is_cli=False): self.output.write('\n') def intro(self): - self.output.write('''\ -Welcome to Python {0}'s help utility! If this is your first time using -Python, you should definitely check out the tutorial at -https://docs.python.org/{0}/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". -'''.format('%d.%d' % sys.version_info[:2])) + if os.environ.get('PYTHON_BASIC_REPL'): + self.output.write(_intro_basic()) + else: + self.output.write(_intro_pyrepl()) def list(self, items, columns=4, width=80): items = list(sorted(items)) diff --git a/Misc/NEWS.d/next/Documentation/2024-10-08-10-44-14.gh-issue-125142.HVlHrs.rst b/Misc/NEWS.d/next/Documentation/2024-10-08-10-44-14.gh-issue-125142.HVlHrs.rst new file mode 100644 index 00000000000000..2340013f5de492 --- /dev/null +++ b/Misc/NEWS.d/next/Documentation/2024-10-08-10-44-14.gh-issue-125142.HVlHrs.rst @@ -0,0 +1,2 @@ +As part of the builtin help intro text, show the keyboard shortcuts for the +new, non-basic REPL (F1, F2, and F3). From 16ebb4c95b937fb3c9cb0c775305adad8226c383 Mon Sep 17 00:00:00 2001 From: Neil Schemenauer Date: Tue, 7 Jan 2025 11:58:50 -0800 Subject: [PATCH 2/3] Refactor code, reduce duplicate text. --- Lib/pydoc.py | 53 ++++++++++++++++++++++++++++------------------------ 1 file changed, 29 insertions(+), 24 deletions(-) diff --git a/Lib/pydoc.py b/Lib/pydoc.py index 4e04723f6f4aa8..8d071f786c5b2d 100644 --- a/Lib/pydoc.py +++ b/Lib/pydoc.py @@ -1798,30 +1798,38 @@ def writedocs(dir, pkgpath='', done=None): return -def _intro_basic(): - # Intro text if basic REPL is used. +def _introdoc(): + import textwrap ver = '%d.%d' % sys.version_info[:2] - return f'''\ -Welcome to Python {ver}'s help utility! If this is your first time using -Python, you should definitely check out the tutorial at -https://docs.python.org/{ver}/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". -''' + if os.environ.get('PYTHON_BASIC_REPL'): + pyrepl_keys = '' + else: + # Additional help for keyboard shortcuts if enhanced (non-basic) REPL is used. + pyrepl_keys = ''' + You can use the following keyboard shortcuts at the main interpreter prompt. + F1: enter interactive help, F2: enter history browsing mode, F3: enter paste + mode (press again to exit). + ''' + return textwrap.dedent(f'''\ + Welcome to Python {ver}'s help utility! If this is your first time using + Python, you should definitely check out the tutorial at + https://docs.python.org/{ver}/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". + {pyrepl_keys} + 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". + ''') def _intro_pyrepl(): - # Intro text if enhanced (non-basic) REPL is used. ver = '%d.%d' % sys.version_info[:2] return f''' Welcome to Python {ver}'s help utility! If this is your first time using @@ -2112,10 +2120,7 @@ def help(self, request, is_cli=False): self.output.write('\n') def intro(self): - if os.environ.get('PYTHON_BASIC_REPL'): - self.output.write(_intro_basic()) - else: - self.output.write(_intro_pyrepl()) + self.output.write(_introdoc()) def list(self, items, columns=4, width=80): items = list(sorted(items)) From cb6e3dc63b24a6d1033269bce9f143403cf865da Mon Sep 17 00:00:00 2001 From: Neil Schemenauer Date: Mon, 28 Apr 2025 13:48:07 -0700 Subject: [PATCH 3/3] Remove unused code. --- Lib/pydoc.py | 31 +++---------------------------- 1 file changed, 3 insertions(+), 28 deletions(-) diff --git a/Lib/pydoc.py b/Lib/pydoc.py index c1cf5242785359..def76d076a2989 100644 --- a/Lib/pydoc.py +++ b/Lib/pydoc.py @@ -68,6 +68,7 @@ class or function within a module or module in a package. If the import re import sys import sysconfig +import textwrap import time import tokenize import urllib.parse @@ -1816,7 +1817,7 @@ def _introdoc(): if os.environ.get('PYTHON_BASIC_REPL'): pyrepl_keys = '' else: - # Additional help for keyboard shortcuts if enhanced (non-basic) REPL is used. + # Additional help for keyboard shortcuts if enhanced REPL is used. pyrepl_keys = ''' You can use the following keyboard shortcuts at the main interpreter prompt. F1: enter interactive help, F2: enter history browsing mode, F3: enter paste @@ -1838,33 +1839,7 @@ def _introdoc(): To quit this help utility and return to the interpreter, enter "q", "quit" or "exit". - ''') - - -def _intro_pyrepl(): - ver = '%d.%d' % sys.version_info[:2] - return f''' -Welcome to Python {ver}'s help utility! If this is your first time using -Python, you should definitely check out the tutorial at -https://docs.python.org/{ver}/tutorial/. - -You can use the following keyboard shortcuts at the main interpreter prompt. -F1: enter interactive help, F2: enter history browsing mode, F3: enter paste -mode (press again to exit). - -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". -''' - + ''') class Helper: