tessl/pypi-rope
A comprehensive Python refactoring library providing powerful and safe code transformations, analysis, and IDE integration capabilities.
—
Pending
project-management.mddocs/
Project Management
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.
Capabilities
Project Creation and Management
The Project class is the central entry point for all rope operations, managing project state, resources, and configuration.
class Project:
"""
Main project class for managing Python projects.
Parameters:
- projectroot (str): Path to project root directory
- fscommands (FSCommands, optional): File system operations interface
- ropefolder (str): Name of rope project folder (default: ".ropeproject")
- prefs: Additional project preferences and configuration options
"""
def __init__(self, projectroot, fscommands=None, ropefolder=".ropeproject", **prefs): ...
def get_resource(self, resource_name):
"""
Get a resource by its path relative to project root.
Parameters:
- resource_name (str): Path relative to project root
Returns:
Resource: File or Folder resource
Raises:
ResourceNotFoundError: If resource does not exist
"""
def get_file(self, path):
"""Get a File resource, creating if it doesn't exist."""
def get_folder(self, path):
"""Get a Folder resource, creating if it doesn't exist."""
def get_module(self, name, folder=None):
"""
Get a Python module by name.
Parameters:
- name (str): Module name to find
- folder (Resource, optional): Starting folder for search
Returns:
PyObject: Python module object
Raises:
ModuleNotFoundError: If module cannot be found
"""
def find_module(self, modname, folder=None):
"""Find module resource by name, returns None if not found."""
def get_python_files(self):
"""Get all Python files in the project."""
def get_files(self):
"""Get all files in the project."""
def get_source_folders(self):
"""Get project source folders containing Python packages."""
def get_python_path_folders(self):
"""Get folders from Python path configuration."""
def get_pycore(self):
"""Get PyCore instance for advanced analysis."""
def get_pymodule(self, resource, force_errors=False):
"""
Get PyModule object for a resource.
Parameters:
- resource (Resource): Python file resource
- force_errors (bool): Whether to force error reporting
Returns:
PyModule: Python module analysis object
"""
def get_prefs(self):
"""Get project preferences configuration."""
def is_ignored(self, resource):
"""Check if a resource should be ignored by rope."""
def validate(self, folder):
"""Validate files and folders in the given folder."""
def sync(self):
"""Synchronize project state with file system."""
def do(self, changes, task_handle=None):
"""
Execute a set of changes.
Parameters:
- changes (Change or ChangeSet): Changes to apply
- task_handle (TaskHandle, optional): Handle for monitoring progress
"""
def close(self):
"""Close the project and release resources."""Project-less Operations
For operations that don't require a persistent project, rope provides a singleton NoProject instance.
def get_no_project():
"""
Get a NoProject singleton for operations without persistent state.
Returns:
NoProject: Singleton instance for project-less operations
"""
class NoProject:
"""
Project-like interface for operations without persistent project state.
Supports the same interface as Project but without file system persistence.
"""Resource Management
Resources represent files and folders within a project, providing a consistent interface for file system operations.
class Resource:
"""
Base class for project resources implementing os.PathLike.
Attributes:
- path (str): Absolute path to the resource
- name (str): Resource name (filename or folder name)
- parent (Resource): Parent folder resource
- project (Project): Project containing this resource
"""
def move(self, new_location):
"""
Move resource to new location.
Parameters:
- new_location (str): New path relative to project root
"""
def remove(self):
"""Remove the resource from file system."""
def create(self):
"""Create the resource if it doesn't exist."""
def exists(self):
"""Check if resource exists on file system."""
class File(Resource):
"""
File resource with content operations.
"""
def read(self):
"""
Read file contents.
Returns:
str: File contents as string
"""
def write(self, contents):
"""
Write contents to file.
Parameters:
- contents (str): Content to write to file
"""
class Folder(Resource):
"""
Folder resource with child management operations.
"""
def get_children(self):
"""
Get all child resources.
Returns:
list[Resource]: List of child files and folders
"""
def get_child(self, name):
"""
Get specific child resource by name.
Parameters:
- name (str): Child resource name
Returns:
Resource: Child resource
Raises:
ResourceNotFoundError: If child doesn't exist
"""
def create_file(self, name):
"""
Create a new file in this folder.
Parameters:
- name (str): File name
Returns:
File: Created file resource
"""
def create_folder(self, name):
"""
Create a new folder in this folder.
Parameters:
- name (str): Folder name
Returns:
Folder: Created folder resource
"""Library Utilities
Helper functions for common project operations and resource management.
def path_to_resource(project, path, type=None):
"""
Convert file system path to project resource.
Parameters:
- project (Project): Project instance
- path (str): File system path
- type (str, optional): Resource type hint ('file' or 'folder')
Returns:
Resource: Corresponding project resource
"""
def path_relative_to_project_root(project, path):
"""
Get path relative to project root.
Parameters:
- project (Project): Project instance
- path (str): Absolute or relative path
Returns:
str: Path relative to project root
"""
def is_python_file(project, resource):
"""
Check if resource is a Python file.
Parameters:
- project (Project): Project instance
- resource (Resource): Resource to check
Returns:
bool: True if resource is a Python file
"""
def modname(resource):
"""
Get module name from resource.
Parameters:
- resource (Resource): Python file resource
Returns:
str: Module name (dotted notation)
"""
def analyze_module(project, resource):
"""
Perform static analysis on a module.
Parameters:
- project (Project): Project instance
- resource (Resource): Python file to analyze
"""
def analyze_modules(project, task_handle=None):
"""
Analyze all modules in the project.
Parameters:
- project (Project): Project instance
- task_handle (TaskHandle, optional): Progress monitoring handle
"""Observer Pattern
Projects support observers for monitoring changes and validation.
class Project:
def add_observer(self, observer):
"""
Add an observer for project changes.
Parameters:
- observer: Observer object with validate() method
"""
def remove_observer(self, observer):
"""
Remove a project observer.
Parameters:
- observer: Observer to remove
"""Usage Examples
Basic Project Operations
from rope.base.project import Project
# Create a new project
project = Project('/path/to/project')
try:
# Get a Python file
myfile = project.get_resource('src/mymodule.py')
# Read file contents
if myfile.exists():
content = myfile.read()
print(f"File contains {len(content)} characters")
# Get all Python files
python_files = project.get_python_files()
print(f"Project has {len(python_files)} Python files")
# Create a new file
newfile = project.get_file('src/newmodule.py')
newfile.write('# New Python module\n')
finally:
project.close()Working Without a Project
from rope.base.project import get_no_project
# Get singleton NoProject instance
project = get_no_project()
# Use same interface but without persistence
try:
# Analyze a single file
resource = project.get_resource('/path/to/standalone.py')
module = project.get_pymodule(resource)
finally:
# No need to close NoProject
passInstall with Tessl CLI
npx tessl i tessl/pypi-rope