From: kobarity <kobarity@gmail.com>
Date: Sun, 2 Mar 2025 08:37:36 +0000 (+0900)
Subject: Improve docstrings of python.el import management
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=1bbeb8e7e6d7d4052d23e32c23c0fe2028eddb6b;p=emacs.git

Improve docstrings of python.el import management

Added notes that when adding import statements for a file that
does not belong to a project, it may take some time to find
candidate import statements in the default directory.

* lisp/progmodes/python.el (python-add-import)
(python-fix-imports): Improve docstring.  (Bug#74894)

(cherry picked from commit cf03c2b6093d3b555f758f033610a6015378de57)
---

diff --git a/lisp/progmodes/python.el b/lisp/progmodes/python.el
index a0a84fac0c3..8ff43d0720b 100644
--- a/lisp/progmodes/python.el
+++ b/lisp/progmodes/python.el
@@ -6889,6 +6889,12 @@ argument, restrict the suggestions to imports defining the symbol
 at point.  If there is only one such suggestion, act without
 asking.
 
+If the buffer does not belong to a project, the import statement is
+searched under the buffer's default directory.  For example, if the file
+is located directly under the home directory, all files under the home
+directory will be searched.  Please note that this can take a long time
+and may appear to hang.
+
 When calling from Lisp, use a non-nil NAME to restrict the
 suggestions to imports defining NAME."
   (interactive (list (when current-prefix-arg (thing-at-point 'symbol))))
@@ -6933,7 +6939,17 @@ asking."
 
 ;;;###autoload
 (defun python-fix-imports ()
-  "Add missing imports and remove unused ones from the current buffer."
+  "Add missing imports and remove unused ones from the current buffer.
+
+If there are missing imports, ask for an import statement using all
+imports found in the current project as suggestions.  If there is only
+one such suggestion, act without asking.
+
+If the buffer does not belong to a project, the import statement is
+searched under the buffer's default directory.  For example, if the file
+is located directly under the home directory, all files under the home
+directory will be searched.  Please note that this can take a long time
+and may appear to hang."
   (interactive)
   (let ((buffer (current-buffer))
         undefined unused add remove)