Extract Method and Variable

Relevant source files

The following files were used as context for generating this wiki page:

• rope/refactor/extract.py
• ropetest/refactor/extracttest.py
• rope/refactor/similarfinder.py
• rope/refactor/usefunction.py
• rope/base/codeanalyze.py

The Extract Method and Extract Variable refactorings are core components of the Rope library designed to improve code readability and reusability. These features allow developers to select a region of code—either a single expression or multiple statements—and transform it into a new function, method, or local variable.

The system handles a wide array of Python-specific syntax, including decorators, global and nonlocal keywords, asynchronous statements, and structural pattern matching. It ensures that the refactored code remains semantically equivalent by automatically calculating necessary parameters, return values, and maintaining proper scope.
Sources: rope/refactor/extract.py:1-40, README.rst:1-40

Architecture and Core Components

The extraction system is structured into specialized classes that separate concerns such as information collection, condition checking, and code generation.

Component Overview

Class	Description
_ExtractRefactoring	The base class for both Method and Variable extraction, handling initialization and offset fixing.
_ExtractInfo	A data container that holds the project context, scope information, and the source code regions being refactored.
_ExtractPerformer	Orchestrates the extraction process by coordinating definition finding and occurrence replacement.
_ExtractCollector	Collects the code patterns and matches needed to perform the actual source code transformation.
_ExceptionalConditionChecker	Validates the selected region to ensure the refactoring is safe and syntactically valid.

Sources: rope/refactor/extract.py:25-45, rope/refactor/extract.py:122-132

Extraction Logic Flow

The following diagram illustrates the sequence of operations when a user initiates an extraction refactoring.

The _ExtractPerformer manages this flow, ensuring that _ExtractMethodParts or _ExtractVariableParts are used based on the refactoring type.
Sources: rope/refactor/extract.py:135-155, rope/refactor/extract.py:228-260

Extract Method Specifics

Extract Method transforms a block of code into a new function or method. It identifies variables that need to be passed as arguments and variables that must be returned to the original scope.

Function Kind Detection

Rope automatically detects the appropriate type of function to create based on the context of the extraction:

• Function: Extracted in a module scope.
• Method: Extracted within a class, receiving self as the first argument.
• Static Method: Identified via the $ prefix or @staticmethod context.
• Class Method: Identified via the @ prefix or @classmethod context.

Sources: rope/refactor/extract.py:75-100, rope/refactor/extract.py:350-380

Variable Analysis logic

The _FunctionInformationCollector (an ast.RopeNodeVisitor) determines how variables are handled:

1. Read Variables: Names read within the region but not written become arguments.
2. Written Variables: Names assigned within the region that are subsequently read outside the region become return values.
3. Global/Nonlocal: The system detects assignments to global or nonlocal names and inserts the appropriate keywords into the new function body.

Similar Occurrence Finding

One of the advanced features of Rope's extraction is the ability to replace similar expressions or statements throughout the scope, not just the selected region. This is handled by the SimilarFinder and RawSimilarFinder classes.

• Search Scope: If similar=True is passed, the system searches the entire module (for global functions) or class (for methods) for matching patterns.
• Code Templates: The system uses CodeTemplate to substitute variable names into the patterns found, ensuring that even if different variable names are used in other locations, they are correctly mapped to the new function's arguments.

Sources: rope/refactor/similarfinder.py:15-60, rope/refactor/extract.py:180-210

Validation and Constraints

The _ExceptionalConditionChecker enforces strict rules to prevent invalid refactorings.

Constraint Category	Rule
Completeness	Selected region must contain complete statements. Partial words or unbalanced blocks (e.g., an if without its body) trigger a RefactoringError.
Control Flow	A break or continue statement cannot be extracted unless its parent loop is also within the selection.
Returns	Multi-line extractions can only contain one return statement, and it must be the last statement.
Syntax	Extract Variable cannot span multiple lines. Extraction of expressions containing the walrus operator (:=) is restricted.

Sources: rope/refactor/extract.py:277-345, rope/refactor/usefunction.py:25-45

Usage Example: Extract Method

If a user selects a + b in the following code:

def example():
    a = 1
    b = 2
    c = a + b
    print(c)

Rope's ExtractMethod will transform it to:

def example():
    a = 1
    b = 2
    c = new_func(a, b)
    print(c)

def new_func(a, b):
    return a + b

The system identifies a and b as required arguments because they are defined before the extraction and used within it.
Sources: ropetest/refactor/extracttest.py:50-80, rope/refactor/extract.py:465-490

Conclusion

The Extract Method and Variable module provides a robust implementation of standard refactoring patterns for Python. By utilizing AST-based analysis and a sophisticated similarity finder, it automates the tedious parts of restructuring code while ensuring that the resulting source is clean, valid, and maintains the original program's logic.