Code Assist and Autocomplete
Relevant source files
The following files were used as context for generating this wiki page:
The Code Assist and Autocomplete system in Rope provides a suite of tools for IDE-like functionality, including code completion, call tips, documentation extraction, and definition location finding. It is designed to work even with syntactically incomplete code, which is common during active development.
Core Architecture and Data Flow
The primary entry point for the system is rope.contrib.codeassist.code_assist. When invoked, it utilizes a specialized internal class, _PythonCodeAssist, to analyze the source code at a specific offset. The system relies on Rope's core object model to evaluate expressions and identify available names within different scopes.
Data Flow Diagram
The following diagram illustrates the flow of a code assistance request through the system components.
Syntax Resilience
One of the most critical components of the Code Assist module is its ability to handle syntax errors via the FixSyntax class. When code assist is requested, the code often contains incomplete statements that would normally cause a ModuleSyntaxError.
FixSyntax attempts to "fix" the code by commenting out problematic lines or inserting pass statements to maintain a valid AST for analysis. This is governed by the maxfixes parameter, which determines how many syntax errors the system will attempt to resolve before failing.
Syntax Fixing Logic
- Detection: Attempt to parse the module using
libutils.get_string_module. - Error Handling: If a
ModuleSyntaxErroroccurs, identify the line number. - Commenting: Use the internal
_Commenterclass to replace the failing line or block withpass. - Retry: Re-attempt parsing until the module is valid or
maxfixesis reached.
Sources: rope/contrib/fixsyntax.py:7-40, rope/contrib/codeassist.py:108-115
Completion Proposals
The system returns a list of CompletionProposal objects. These objects encapsulate metadata about the suggested completions, including their name, scope, and type.
Proposal Attributes and Scopes
| Attribute | Description | Possible Values |
|---|---|---|
| Scope | Indicates where the name originated. | global, local, builtin, attribute, keyword, imported, parameter_keyword |
| Type | The approximate type of the object. | instance, class, function, module, None |
Sources: rope/contrib/codeassist.py:195-225
Sorting Mechanism
Proposals are sorted using _ProposalSorter, which applies a ranking based on scope and type preferences. By default, it prioritizes parameter keywords and local variables over builtins and keywords. It also uses an underline count to sort private members lower in the results.
Sources: rope/contrib/codeassist.py:348-380
Key Features
Call Tips and Documentation
The PyDocExtractor class is responsible for generating documentation strings and function signatures.
get_doc: Extracts the docstring for an object at a given offset, handling class headers and superclass methods.get_calltip: Returns a string representation of a function signature. It can optionally remove theselfparameter for method calls.
Sources: rope/contrib/codeassist.py:108-140, rope/contrib/codeassist.py:397-440
Definition Location
The get_definition_location function identifies where a specific name is defined. It returns a tuple containing the Resource (file) and the line number. If the definition is in the current module, the resource returned is None.
Sources: rope/contrib/codeassist.py:143-158, ropetest/contrib/codeassisttest.py:255-270
Canonical Path Analysis
get_canonical_path provides a structured path to a specific object within a project, represented as a list of (name, type) tuples.
# Example Canonical Path Result
# [('/path/to/mod.py', 'MODULE'), ('Foo', 'CLASS'), ('bar', 'FUNCTION'), ('x', 'PARAMETER')]
Sources: rope/contrib/codeassist.py:173-210, ropetest/contrib/codeassisttest.py:650-665
Implementation Details
Word Identification
The worder.Worder class is used extensively to find the "starting expression" and the "starting offset" relative to the cursor. This ensures that the completion logic knows exactly which part of the text the user is attempting to complete (e.g., in my_object.att, the expression is my_object and the starting word is att).
Sources: rope/contrib/codeassist.py:74-90, rope/base/libutils.py:130-145
Sequence Diagram: Code Completion Request
This diagram demonstrates the interaction between modules when a user triggers autocomplete.
Conclusion
The Code Assist and Autocomplete system serves as a bridge between Rope's refactoring engine and developer environments. By leveraging FixSyntax to overcome the transient syntax errors of live coding and PyDocExtractor to provide context, it provides robust static analysis-based assistance. The modular design of CompletionProposal and its sorting logic allows for highly customizable integration into various IDEs.