bpo-23216: IDLE: Add docstrings to search modules (GH-12141)
diff --git a/Lib/idlelib/grep.py b/Lib/idlelib/grep.py
index 873233e..6068d7e 100644
--- a/Lib/idlelib/grep.py
+++ b/Lib/idlelib/grep.py
@@ -14,11 +14,16 @@
from idlelib import searchengine
# Importing OutputWindow here fails due to import loop
-# EditorWindow -> GrepDialop -> OutputWindow -> EditorWindow
+# EditorWindow -> GrepDialog -> OutputWindow -> EditorWindow
def grep(text, io=None, flist=None):
- """Create or find singleton GrepDialog instance.
+ """Open the Find in Files dialog.
+
+ Module-level function to access the singleton GrepDialog
+ instance and open the dialog. If text is selected, it is
+ used as the search phrase; otherwise, the previous entry
+ is used.
Args:
text: Text widget that contains the selected text for
@@ -26,7 +31,6 @@
io: iomenu.IOBinding instance with default path to search.
flist: filelist.FileList instance for OutputWindow parent.
"""
-
root = text._root()
engine = searchengine.get(root)
if not hasattr(engine, "_grepdialog"):
@@ -50,17 +54,29 @@
searchengine instance to prepare the search.
Attributes:
- globvar: Value of Text Entry widget for path to search.
- recvar: Boolean value of Checkbutton widget
- for traversing through subdirectories.
+ flist: filelist.Filelist instance for OutputWindow parent.
+ globvar: String value of Entry widget for path to search.
+ globent: Entry widget for globvar. Created in
+ create_entries().
+ recvar: Boolean value of Checkbutton widget for
+ traversing through subdirectories.
"""
- SearchDialogBase.__init__(self, root, engine)
+ super().__init__(root, engine)
self.flist = flist
self.globvar = StringVar(root)
self.recvar = BooleanVar(root)
def open(self, text, searchphrase, io=None):
- "Make dialog visible on top of others and ready to use."
+ """Make dialog visible on top of others and ready to use.
+
+ Extend the SearchDialogBase open() to set the initial value
+ for globvar.
+
+ Args:
+ text: Multicall object containing the text information.
+ searchphrase: String phrase to search.
+ io: iomenu.IOBinding instance containing file path.
+ """
SearchDialogBase.open(self, text, searchphrase)
if io:
path = io.filename or ""
@@ -85,9 +101,9 @@
btn.pack(side="top", fill="both")
def create_command_buttons(self):
- "Create base command buttons and add button for search."
+ "Create base command buttons and add button for Search Files."
SearchDialogBase.create_command_buttons(self)
- self.make_button("Search Files", self.default_command, 1)
+ self.make_button("Search Files", self.default_command, isdef=True)
def default_command(self, event=None):
"""Grep for search pattern in file path. The default command is bound
@@ -119,6 +135,10 @@
search each line for the matching pattern. If the pattern is
found, write the file and line information to stdout (which
is an OutputWindow).
+
+ Args:
+ prog: The compiled, cooked search pattern.
+ path: String containing the search path.
"""
dir, base = os.path.split(path)
list = self.findfiles(dir, base, self.recvar.get())
@@ -149,7 +169,13 @@
def findfiles(self, dir, base, rec):
"""Return list of files in the dir that match the base pattern.
+ Use the current directory if dir has no value.
If rec is True, recursively iterate through subdirectories.
+
+ Args:
+ dir: Directory path to search.
+ base: File search pattern.
+ rec: Boolean for recursive search through subdirectories.
"""
try:
names = os.listdir(dir or os.curdir)