Repository navigation
Readline completion of module names in import statements #69605
Description
Activity
As mentioned in bpo-25209, here is a patch to complete module and attribute names in import statements. This is a rewrite of some personal code I have had kicking around for a few years, but I have added extra features (parsing “import x as alias”, supporting “from .relative import x”).
All the existing completions should continue to work as long as the statement immediately preceding the cursor does not look like an “import” statement. When an import statement is detected, these other completions are disabled.
When alternative completions are displayed, my code appends a dot (.) indicator to package names, but this is not inserted in the input line. Maybe people think this is a good idea or maybe not.
This illustrates what it looks like in action. Text in square brackets was automatically completed:
Python 3.6.0a0 (qbase qtip readline/complete-import.patch tip:65d2b721034a, Oct 16 2015, 10:02:3) [GCC 5.1.0] on linux Type "help", "copyright", "credits" or "license" for more information. >>> import io, h<Tab><Tab> hashlib heapq hmac html. http. >>> import io, htm[l].<Tab><Tab> html.entities html.parser >>> import io, html.e[ntities] >>> from html import e<Tab><Tab> entities escape >>> from html import es[cape]
The code works around bpo-16182 (byte vs code point indexing) in a very simplistic way. It probably won’t give useful completions (if any) for non-ASCII input involving imports.
The patch currently does not complete built-in module names (sys.builtin_module_names). This should not be hard to add, but I need to decide whether the support should be added specially in rlcompleter, or generally in pkgutil.iter_modules() instead.
I also have code to complete the following, which I could try to make patches for if there is interest:
- keyword argument names to function calls, e.g. open("file", enc[oding=]
- attributes on constructor return types, e.g. ValueError("msg").__t[raceback__]
I'm reviewing the patch, but it will take a time.
Wouldn't be simpler to use regular expressions instead of tokenizer?
For now Completer doesn't depends on the readline module, nor other global state. It can be used for completing in other environment, for example to complete words in IDE. Patched Completer retrieves additional information from the readline module. This can break existing code. It would be nice to decouple Completer from readline. In contrary to user .pythonrc.py file, we are free to invent new interfaces. May be add methods to the Completer class that provides needed additional information (nothing by default), and add Completer's subclass ReadlineCompleter that implements these methods using readline?
Found presumable bugs:
"import sy" doesn't suggest completion "sys".
"import os.p" doesn't suggest completion "os.path".
MojoVampire commented
on Oct 16, 2015 MojoVampiremannequinMannequinIs there a reason ipython's import completer couldn't be borrowed in its entirety? At work, I use a lightly adapted version of the code from ipython to do completion when I'm using the plain interactive interpreter (for whatever reason), and it works just fine.
Josh: Thanks for pointing out I Python. I haven’t used it much myself, but it does seem to do a similar thing to my proposal. Looks like the relevant code may be around module_completion() at <https://github.com/ipython/ipython/blob/ab929fe/IPython/core/completerlib.py#L209\>.
The “sys” module is one of the builtin modules that I mentioned above. I plan to discuss changing pkgutil.iter_modules() to include it, in a separate bug report.
The “os.path” case is more awkward. The “os” module is not actually a package. I believe “import os.path” only works because executing the “os” module modifies sys.modules. My code currently avoids importing non-packages, because I thought it would be annoying to accidentally run a script via tab completion (anything not protected by ‘if __name__ == "__main__" ’). On the other hand, I Python happily completes “os.path” (and many more non-submodule names). It also can be tricked into running scripts, e.g. if you do “import idlelib.__main__.” and press Tab. But maybe this is not a real problem, and I should stop being paranoid.
I tend to avoid regular expressions if practical. But Serhiy you may be right that some simple string matching rules would reduce the need for tokenizing. It looks like I Python only has a few simple rules for the entire input line being “import x” and “from x import y”. The disadvantage is less accurate understanding of more complicated syntax, like “from x import y; from z import (a, bb as b, . . .”. It is a tradeoff between simpler code that only supports basic functionality versus complex code that supports more complete functionality.
I hear your points about decoupling from Readline and backwards compatibility. I will consider the overall architecture more in a future update. It would be good to allow this stuff to be used in e.g. Idle (though I wouldn’t know where to wire it in myself).
Added few cursory comments on Rietveld.
"sys" and "os.path" cases are not critical and we can ignore them if it complicates the code. But preserving Completer independence from readline looks more important to me. We can just add methods get_line_buffer(), get_begidx(), get_endidx() and get_completion_type() to Completer, but may be better to add more high level methods.
I moved all the calls targetting the readline module into a ReadlineCompleter subclass. However the logic for parsing “import” statements still exists in the base Completer class in private methods. An overview of the two classes:
class Completer: def complete(self, text, state): self._get_matches(text) def _get_matches(text): # Only completes global and object.attr names, like before def _code_matches(self, code, ...): # Completes import statements, otherwise returns (None, ...) class ReadlineCompleter(Completer): # New public class def complete(self, text, state): # Moved Yury’s Tab insertion logic here return super().complete(...) def _get_matches(text): code = readline.get_line_buffer()[:readline.get_endidx()] self._code_matches(code) super()._get_matches(text) # Fallback to existing behaviour
Perhaps the _code_matches() and related methods could be turned into more general public APIs, e.g. complete_code(code) -> list of modules, attributes, globals, etc. But that would affect global_matches() and attr_matches(), which I have not touched so far.
Other changes:
I changed my mind. I thought it would be easier to implement this with simple regular expressions and string operations, but handling the corner cases makes it difficult. I now think that using the
tokenizemodule is the only correct solution.My apologies, @vadmium. Are you still interesting in continuing this work?
I don’t want to spend much time on this, but I’m happy for other people to build on my code.
I should have some time in the next couple of days so I'd like to look into implementing this :)
- added a commit that references this issue
on Apr 25, 2025 - added a commit that references this issue
on May 4, 2025 22 remaining items
- added 6 commits that reference this issue
on Jan 5, 2026 Nice, I think this issue can be closed again!
Reacted by Tomas R.- added a commit that references this issue
on Apr 5, 2026 - Wouldn't it be cool if from typing completed the import keyword? ImportParser.parse() returns None in such a case, and I don't know if there is precedent for completing after a space, might be a litte bit too magical?
- Yup! I'm already working on that along with general improvements to the parser :)
Hey @tomasr8, is this still on your radar? I'd love to see this land someday, can have a try at it if needed!
- Wouldn't it be cool if from typing completed the import keyword? ImportParser.parse() returns None in such a case, and I don't know if there is precedent for completing after a space, might be a litte bit too magical?
- Yup! I'm already working on that along with general improvements to the parser :)
Hey @tomasr8, is this still on your radar? I'd love to see this land someday, can have a try at it if needed!
Hey @loic-simon I was indeed working on that at some point (I even have a branch for it, but can't find it ATM), but feel free to pick it up! The import parser might also need some refactoring while you're at it :) I'll try to review it in a timely manner 😆
Reacted by Loïc Simon- added a commit that references this issue
on Apr 25, 2026
Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.
Show more details
GitHub fields:
bugs.python.org fields:
Linked PRs