From 987df223bf548a21a50bf40560a764b6265e913b Mon Sep 17 00:00:00 2001 From: AlexWaygood Date: Thu, 14 Dec 2023 17:02:46 +0000 Subject: [PATCH 1/3] gh-101100: Fix Sphinx nitpicks in `library/rlcompleter.rst` --- Doc/library/readline.rst | 2 ++ Doc/library/rlcompleter.rst | 35 +++++++++++++++++------------------ Doc/tools/.nitignore | 1 - 3 files changed, 19 insertions(+), 19 deletions(-) diff --git a/Doc/library/readline.rst b/Doc/library/readline.rst index 2e0f45ced30b9c..1adafcaa02eab9 100644 --- a/Doc/library/readline.rst +++ b/Doc/library/readline.rst @@ -218,6 +218,8 @@ Startup hooks if Python was compiled for a version of the library that supports it. +.. _readline-completion: + Completion ---------- diff --git a/Doc/library/rlcompleter.rst b/Doc/library/rlcompleter.rst index 40b09ce897880e..f439fabb13e9bf 100644 --- a/Doc/library/rlcompleter.rst +++ b/Doc/library/rlcompleter.rst @@ -10,12 +10,13 @@ -------------- -The :mod:`rlcompleter` module defines a completion function suitable for the +The :mod:`!rlcompleter` module defines a completion function suitable for the :mod:`readline` module by completing valid Python identifiers and keywords. When this module is imported on a Unix platform with the :mod:`readline` module available, an instance of the :class:`Completer` class is automatically created -and its :meth:`complete` method is set as the :mod:`readline` completer. +and its :meth:`~Completer.complete` method is set as the +:ref:`readline completer `. Example:: @@ -28,7 +29,7 @@ Example:: readline.__name__ readline.parse_and_bind( >>> readline. -The :mod:`rlcompleter` module is designed for use with Python's +The :mod:`!rlcompleter` module is designed for use with Python's :ref:`interactive mode `. Unless Python is run with the :option:`-S` option, the module is automatically imported and configured (see :ref:`rlcompleter-config`). @@ -39,23 +40,21 @@ this module can still be used for custom purposes. .. _completer-objects: -Completer Objects ------------------ +.. class:: Completer -Completer objects have the following method: + Completer objects have the following method: + .. method:: Completer.complete(text, state) -.. method:: Completer.complete(text, state) + Return the *state*\ th completion for *text*. - Return the *state*\ th completion for *text*. - - If called for *text* that doesn't include a period character (``'.'``), it will - complete from names currently defined in :mod:`__main__`, :mod:`builtins` and - keywords (as defined by the :mod:`keyword` module). - - If called for a dotted name, it will try to evaluate anything without obvious - side-effects (functions will not be evaluated, but it can generate calls to - :meth:`__getattr__`) up to the last part, and find matches for the rest via the - :func:`dir` function. Any exception raised during the evaluation of the - expression is caught, silenced and :const:`None` is returned. + If called for *text* that doesn't include a period character (``'.'``), it will + complete from names currently defined in :mod:`__main__`, :mod:`builtins` and + keywords (as defined by the :mod:`keyword` module). + If called for a dotted name, it will try to evaluate anything without obvious + side-effects (functions will not be evaluated, but it can generate calls to + :meth:`~object.__getattr__`) up to the last part, and find matches for the + rest via the :func:`dir` function. Any exception raised during the + evaluation of the expression is caught, silenced and :const:`None` is + returned. diff --git a/Doc/tools/.nitignore b/Doc/tools/.nitignore index 4d1d31d44fcf75..7ce5693bf26e8a 100644 --- a/Doc/tools/.nitignore +++ b/Doc/tools/.nitignore @@ -81,7 +81,6 @@ Doc/library/pyexpat.rst Doc/library/random.rst Doc/library/readline.rst Doc/library/resource.rst -Doc/library/rlcompleter.rst Doc/library/select.rst Doc/library/signal.rst Doc/library/smtplib.rst From 37a58c140e94d86c54c76f917f585453a93531d6 Mon Sep 17 00:00:00 2001 From: AlexWaygood Date: Thu, 14 Dec 2023 23:13:00 +0000 Subject: [PATCH 2/3] Improvements --- Doc/library/rlcompleter.rst | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/Doc/library/rlcompleter.rst b/Doc/library/rlcompleter.rst index f439fabb13e9bf..b09d3854a9e4a8 100644 --- a/Doc/library/rlcompleter.rst +++ b/Doc/library/rlcompleter.rst @@ -10,13 +10,14 @@ -------------- -The :mod:`!rlcompleter` module defines a completion function suitable for the -:mod:`readline` module by completing valid Python identifiers and keywords. +The :mod:`!rlcompleter` module defines a completion function suitable to be +passed to :func:`set_completer` in the :mod:`readline` module. When this module is imported on a Unix platform with the :mod:`readline` module available, an instance of the :class:`Completer` class is automatically created and its :meth:`~Completer.complete` method is set as the -:ref:`readline completer `. +:ref:`readline completer `. The method provides +completion of valid Python :ref:`identifiers and keywords `. Example:: @@ -46,7 +47,11 @@ this module can still be used for custom purposes. .. method:: Completer.complete(text, state) - Return the *state*\ th completion for *text*. + Return the next possible completion for *text*. + + When called by the :mod:`readline` module, this method is called + successively with ``state == 0, 1, 2, ...`` until the method returns + ``None``. If called for *text* that doesn't include a period character (``'.'``), it will complete from names currently defined in :mod:`__main__`, :mod:`builtins` and From 8f4fa9aeb2f89d28da96b41fd4cb57076376c056 Mon Sep 17 00:00:00 2001 From: Alex Waygood Date: Thu, 14 Dec 2023 23:16:58 +0000 Subject: [PATCH 3/3] . --- Doc/library/rlcompleter.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/rlcompleter.rst b/Doc/library/rlcompleter.rst index b09d3854a9e4a8..8287699c5f013e 100644 --- a/Doc/library/rlcompleter.rst +++ b/Doc/library/rlcompleter.rst @@ -11,7 +11,7 @@ -------------- The :mod:`!rlcompleter` module defines a completion function suitable to be -passed to :func:`set_completer` in the :mod:`readline` module. +passed to :func:`~readline.set_completer` in the :mod:`readline` module. When this module is imported on a Unix platform with the :mod:`readline` module available, an instance of the :class:`Completer` class is automatically created