0
# Rope
1

2
Rope is the world's most advanced open source Python refactoring library, providing comprehensive code analysis and transformation capabilities. It supports most Python syntax up to Python 3.10 and offers powerful refactoring operations while maintaining code safety through careful static analysis.
3

4
## Package Information
5

6
- **Package Name**: rope
7
- **Language**: Python
8
- **Installation**: `pip install rope`
9
- **License**: LGPL-3.0-or-later
10

11
## Core Imports
12

13
```python
14
import rope.base.project
15
from rope.base.project import Project
16
```
17

18
For refactoring operations:
19

20
```python
21
from rope.refactor.rename import Rename
22
from rope.refactor.move import MoveMethod, MoveModule
23
from rope.refactor.extract import ExtractMethod, ExtractVariable
24
```
25

26
For code assistance:
27

28
```python
29
from rope.contrib.codeassist import code_assist, get_definition_location
30
from rope.contrib.findit import find_occurrences
31
```
32

33
## Basic Usage
34

35
```python
36
from rope.base.project import Project
37
from rope.refactor.rename import Rename
38

39
# Create or open a project
40
project = Project('/path/to/your/project')
41

42
try:
43
    # Get a Python file
44
    mymodule = project.get_resource('mymodule.py')
45
    
46
    # Perform a rename refactoring
47
    # Rename variable at offset 150 to 'new_name'
48
    renamer = Rename(project, mymodule, 150)
49
    changes = renamer.get_changes('new_name')
50
    
51
    # Apply the changes
52
    project.do(changes)
53
    
54
finally:
55
    # Always close the project
56
    project.close()
57
```
58

59
## Architecture
60

61
Rope follows a layered architecture designed for safety and extensibility:
62

63
- **Project Layer**: Manages Python projects, resources, and configuration
64
- **PyCore Layer**: Provides Python code analysis and object model
65
- **Refactoring Layer**: Implements safe code transformations with change management
66
- **Contrib Layer**: Offers IDE integration tools and code assistance features
67

68
The design emphasizes safety through static analysis, avoiding runtime execution of analyzed code, making it suitable for IDE integration and automated refactoring tools.
69

70
## Capabilities
71

72
### Project Management
73

74
Core functionality for managing Python projects, resources, and configuration. Provides the foundation for all rope operations with file system abstraction and project state management.
75

76
```python { .api }
77
class Project:
78
    def __init__(self, root_folder, **prefs): ...
79
    def get_resource(self, resource_name): ...
80
    def get_module(self, name, folder=None): ...
81
    def close(self): ...
82

83
def get_no_project(): ...
84
```
85

86
[Project Management](./project-management.md)
87

88
### Refactoring Operations
89

90
Comprehensive refactoring capabilities including rename, move, extract, inline, and restructure operations. All refactorings follow the standard pattern of construction, information gathering, change generation, and execution.
91

92
```python { .api }
93
class Rename:
94
    def __init__(self, project, resource, offset): ...
95
    def get_old_name(self): ...
96
    def get_changes(self, new_name, **kwargs): ...
97

98
class ExtractMethod:
99
    def __init__(self, project, resource, start_offset, end_offset): ...
100
    def get_changes(self, method_name, **kwargs): ...
101
```
102

103
[Refactoring Operations](./refactoring-operations.md)
104

105
### Code Assistance
106

107
IDE integration tools providing code completion, documentation lookup, definition finding, and occurrence detection. Designed for real-time assistance in development environments.
108

109
```python { .api }
110
def code_assist(project, source_code, offset, resource=None, **kwargs): ...
111
def get_definition_location(project, source_code, offset, **kwargs): ...
112
def find_occurrences(project, resource, offset, **kwargs): ...
113
```
114

115
[Code Assistance](./code-assistance.md)
116

117
### Change Management
118

119
System for representing, combining, and applying code changes safely. Enables previewing modifications before applying them and supports undo operations through project history.
120

121
```python { .api }
122
class Change:
123
    def do(self): ...
124
    def get_description(self): ...
125

126
class ChangeSet:
127
    def add_change(self, change): ...
128
    def do(self): ...
129
```
130

131
[Change Management](./change-management.md)
132

133
### Error Handling
134

135
Exception hierarchy for handling various error conditions during code analysis and refactoring operations.
136

137
```python { .api }
138
class RopeError(Exception): ...
139
class RefactoringError(RopeError): ...
140
class ResourceNotFoundError(RopeError): ...
141
class ModuleNotFoundError(RopeError): ...
142
```
143

144
[Error Handling](./error-handling.md)
145

146
## Types
147

148
```python { .api }
149
class Resource:
150
    """Base class for project resources (files and folders)."""
151
    path: str
152
    name: str
153
    parent: Resource
154
    project: Project
155
    
156
    def move(self, new_location): ...
157
    def remove(self): ...
158
    def exists(self): ...
159

160
class File(Resource):
161
    """File resource with content operations."""
162
    def read(self): ...
163
    def write(self, contents): ...
164

165
class Folder(Resource):
166
    """Folder resource with child management."""
167
    def get_children(self): ...
168
    def get_child(self, name): ...
169
    def create_file(self, name): ...
170
    def create_folder(self, name): ...
171
```