0
# Project Management
1
2
Core functionality for managing Python projects, resources, and configuration. The project management system provides the foundation for all rope operations with file system abstraction and project state management.
3
4
## Capabilities
5
6
### Project Creation and Management
7
8
The Project class is the central entry point for all rope operations, managing project state, resources, and configuration.
9
10
```python { .api }
11
class Project:
12
"""
13
Main project class for managing Python projects.
14
15
Parameters:
16
- projectroot (str): Path to project root directory
17
- fscommands (FSCommands, optional): File system operations interface
18
- ropefolder (str): Name of rope project folder (default: ".ropeproject")
19
- prefs: Additional project preferences and configuration options
20
"""
21
def __init__(self, projectroot, fscommands=None, ropefolder=".ropeproject", **prefs): ...
22
23
def get_resource(self, resource_name):
24
"""
25
Get a resource by its path relative to project root.
26
27
Parameters:
28
- resource_name (str): Path relative to project root
29
30
Returns:
31
Resource: File or Folder resource
32
33
Raises:
34
ResourceNotFoundError: If resource does not exist
35
"""
36
37
def get_file(self, path):
38
"""Get a File resource, creating if it doesn't exist."""
39
40
def get_folder(self, path):
41
"""Get a Folder resource, creating if it doesn't exist."""
42
43
def get_module(self, name, folder=None):
44
"""
45
Get a Python module by name.
46
47
Parameters:
48
- name (str): Module name to find
49
- folder (Resource, optional): Starting folder for search
50
51
Returns:
52
PyObject: Python module object
53
54
Raises:
55
ModuleNotFoundError: If module cannot be found
56
"""
57
58
def find_module(self, modname, folder=None):
59
"""Find module resource by name, returns None if not found."""
60
61
def get_python_files(self):
62
"""Get all Python files in the project."""
63
64
def get_files(self):
65
"""Get all files in the project."""
66
67
def get_source_folders(self):
68
"""Get project source folders containing Python packages."""
69
70
def get_python_path_folders(self):
71
"""Get folders from Python path configuration."""
72
73
def get_pycore(self):
74
"""Get PyCore instance for advanced analysis."""
75
76
def get_pymodule(self, resource, force_errors=False):
77
"""
78
Get PyModule object for a resource.
79
80
Parameters:
81
- resource (Resource): Python file resource
82
- force_errors (bool): Whether to force error reporting
83
84
Returns:
85
PyModule: Python module analysis object
86
"""
87
88
def get_prefs(self):
89
"""Get project preferences configuration."""
90
91
def is_ignored(self, resource):
92
"""Check if a resource should be ignored by rope."""
93
94
def validate(self, folder):
95
"""Validate files and folders in the given folder."""
96
97
def sync(self):
98
"""Synchronize project state with file system."""
99
100
def do(self, changes, task_handle=None):
101
"""
102
Execute a set of changes.
103
104
Parameters:
105
- changes (Change or ChangeSet): Changes to apply
106
- task_handle (TaskHandle, optional): Handle for monitoring progress
107
"""
108
109
def close(self):
110
"""Close the project and release resources."""
111
```
112
113
### Project-less Operations
114
115
For operations that don't require a persistent project, rope provides a singleton NoProject instance.
116
117
```python { .api }
118
def get_no_project():
119
"""
120
Get a NoProject singleton for operations without persistent state.
121
122
Returns:
123
NoProject: Singleton instance for project-less operations
124
"""
125
126
class NoProject:
127
"""
128
Project-like interface for operations without persistent project state.
129
Supports the same interface as Project but without file system persistence.
130
"""
131
```
132
133
### Resource Management
134
135
Resources represent files and folders within a project, providing a consistent interface for file system operations.
136
137
```python { .api }
138
class Resource:
139
"""
140
Base class for project resources implementing os.PathLike.
141
142
Attributes:
143
- path (str): Absolute path to the resource
144
- name (str): Resource name (filename or folder name)
145
- parent (Resource): Parent folder resource
146
- project (Project): Project containing this resource
147
"""
148
149
def move(self, new_location):
150
"""
151
Move resource to new location.
152
153
Parameters:
154
- new_location (str): New path relative to project root
155
"""
156
157
def remove(self):
158
"""Remove the resource from file system."""
159
160
def create(self):
161
"""Create the resource if it doesn't exist."""
162
163
def exists(self):
164
"""Check if resource exists on file system."""
165
166
class File(Resource):
167
"""
168
File resource with content operations.
169
"""
170
171
def read(self):
172
"""
173
Read file contents.
174
175
Returns:
176
str: File contents as string
177
"""
178
179
def write(self, contents):
180
"""
181
Write contents to file.
182
183
Parameters:
184
- contents (str): Content to write to file
185
"""
186
187
class Folder(Resource):
188
"""
189
Folder resource with child management operations.
190
"""
191
192
def get_children(self):
193
"""
194
Get all child resources.
195
196
Returns:
197
list[Resource]: List of child files and folders
198
"""
199
200
def get_child(self, name):
201
"""
202
Get specific child resource by name.
203
204
Parameters:
205
- name (str): Child resource name
206
207
Returns:
208
Resource: Child resource
209
210
Raises:
211
ResourceNotFoundError: If child doesn't exist
212
"""
213
214
def create_file(self, name):
215
"""
216
Create a new file in this folder.
217
218
Parameters:
219
- name (str): File name
220
221
Returns:
222
File: Created file resource
223
"""
224
225
def create_folder(self, name):
226
"""
227
Create a new folder in this folder.
228
229
Parameters:
230
- name (str): Folder name
231
232
Returns:
233
Folder: Created folder resource
234
"""
235
```
236
237
### Library Utilities
238
239
Helper functions for common project operations and resource management.
240
241
```python { .api }
242
def path_to_resource(project, path, type=None):
243
"""
244
Convert file system path to project resource.
245
246
Parameters:
247
- project (Project): Project instance
248
- path (str): File system path
249
- type (str, optional): Resource type hint ('file' or 'folder')
250
251
Returns:
252
Resource: Corresponding project resource
253
"""
254
255
def path_relative_to_project_root(project, path):
256
"""
257
Get path relative to project root.
258
259
Parameters:
260
- project (Project): Project instance
261
- path (str): Absolute or relative path
262
263
Returns:
264
str: Path relative to project root
265
"""
266
267
def is_python_file(project, resource):
268
"""
269
Check if resource is a Python file.
270
271
Parameters:
272
- project (Project): Project instance
273
- resource (Resource): Resource to check
274
275
Returns:
276
bool: True if resource is a Python file
277
"""
278
279
def modname(resource):
280
"""
281
Get module name from resource.
282
283
Parameters:
284
- resource (Resource): Python file resource
285
286
Returns:
287
str: Module name (dotted notation)
288
"""
289
290
def analyze_module(project, resource):
291
"""
292
Perform static analysis on a module.
293
294
Parameters:
295
- project (Project): Project instance
296
- resource (Resource): Python file to analyze
297
"""
298
299
def analyze_modules(project, task_handle=None):
300
"""
301
Analyze all modules in the project.
302
303
Parameters:
304
- project (Project): Project instance
305
- task_handle (TaskHandle, optional): Progress monitoring handle
306
"""
307
```
308
309
### Observer Pattern
310
311
Projects support observers for monitoring changes and validation.
312
313
```python { .api }
314
class Project:
315
def add_observer(self, observer):
316
"""
317
Add an observer for project changes.
318
319
Parameters:
320
- observer: Observer object with validate() method
321
"""
322
323
def remove_observer(self, observer):
324
"""
325
Remove a project observer.
326
327
Parameters:
328
- observer: Observer to remove
329
"""
330
```
331
332
## Usage Examples
333
334
### Basic Project Operations
335
336
```python
337
from rope.base.project import Project
338
339
# Create a new project
340
project = Project('/path/to/project')
341
342
try:
343
# Get a Python file
344
myfile = project.get_resource('src/mymodule.py')
345
346
# Read file contents
347
if myfile.exists():
348
content = myfile.read()
349
print(f"File contains {len(content)} characters")
350
351
# Get all Python files
352
python_files = project.get_python_files()
353
print(f"Project has {len(python_files)} Python files")
354
355
# Create a new file
356
newfile = project.get_file('src/newmodule.py')
357
newfile.write('# New Python module\n')
358
359
finally:
360
project.close()
361
```
362
363
### Working Without a Project
364
365
```python
366
from rope.base.project import get_no_project
367
368
# Get singleton NoProject instance
369
project = get_no_project()
370
371
# Use same interface but without persistence
372
try:
373
# Analyze a single file
374
resource = project.get_resource('/path/to/standalone.py')
375
module = project.get_pymodule(resource)
376
377
finally:
378
# No need to close NoProject
379
pass
380
```