Project Configuration

Relevant source files

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

• rope/base/prefs.py
• rope/base/project.py
• rope/base/libutils.py
• ropetest/projecttest.py
• pyproject.toml
• README.rst

The Project Configuration system in Rope manages how the library interacts with a user's Python project. It defines preferences for refactoring behavior, resource filtering, and environmental settings. Configuration is primarily handled through a Project object, which encapsulates the project root, preferences, and data storage locations.

Rope supports multi-layered configuration, allowing settings to be defined in a dedicated .ropeproject folder, within a pyproject.toml file, or passed directly during project initialization. This system ensures that refactoring operations remain consistent across different development environments while allowing for project-specific overrides.

Sources: rope/base/project.py:164-188, rope/base/prefs.py:316-326

Core Configuration Components

The Project Class

The Project class is the central authority for configuration. It initializes the file system commands, preferences, and resource matchers. When a project is opened, it loads configurations from available sources and initializes internal components like pycore for code analysis.

Sources: rope/base/project.py:164-210

Preferences (Prefs)

Preferences are stored in a Prefs dataclass. This structure defines a wide array of options ranging from ignored resources to specific refactoring styles.

The following table summarizes key configuration categories within Prefs:

Category	Options	Default Value	Description
Resources	ignored_resources	['*.pyc', '*~', '.ropeproject', ...]	Patterns for files/folders to ignore.
Analysis	automatic_soa	True	Whether to perform Static Object Analysis on save.
Refactor	indent_size	4	Number of spaces for indentation.
History	max_history_items	32	Number of undo operations to retain.
Imports	preferred_import_style	"default"	Controls insertion style (e.g., normal vs from-module).

Sources: rope/base/prefs.py:65-188, rope/base/prefs.py:270-282

Configuration Loading Logic

Rope employs a hierarchical loading strategy via the pytoolconfig library. It looks for configuration in several locations, prioritizing them to allow local overrides.

1. Direct Constructor Arguments: Preferences passed to Project(..., **prefs).
2. Legacy Config: The .ropeproject/config.py file.
3. Modern Config: The tool.rope section in pyproject.toml.
4. Global Config: System-wide defaults.

The diagram shows the sequence of loading configuration sources, ending with the merge of file-based settings and runtime overrides.
Sources: rope/base/project.py:212-221, rope/base/prefs.py:316-326

Resource Filtering

Rope uses ignored_resources to filter out files and directories from its internal representation. This is crucial for performance and for excluding environments like .venv or version control metadata like .git.

• Pattern Matching: Patterns like *.pyc match files in any directory, while build//*.o matches recursively within the build directory.
• Resource Matcher: The _ResourceMatcher class (referenced in Project) uses these patterns to determine if a resource is "ignored".

Sources: rope/base/prefs.py:68-87, rope/base/project.py:186-189

Special Configuration Modules

Import Preferences

Rope provides granular control over how imports are organized and inserted through the ImportPrefs and AutoimportPrefs dataclasses.

@dataclass
class ImportPrefs:
    preferred_import_style: str = field(
        default="default",
        description='''Controls how rope inserts new import statements.'''
    )

Sources: rope/base/prefs.py:53-62

Configuration via config.py

For complex setups, users can provide a set_prefs(prefs) function within .ropeproject/config.py. This allows for programmatic configuration, such as setting callbacks or dynamically adjusting paths based on the environment.

Sources: rope/base/prefs.py:293-313, ropetest/projecttest.py:756-764

Summary

The project configuration system provides a robust foundation for the Rope library. By separating project logic from user preferences and supporting multiple configuration formats (TOML, Python, and runtime arguments), Rope allows developers to tailor the refactoring engine to their specific project structures and coding standards. The integration with pytoolconfig ensures that Rope follows modern Python standards for tool configuration while maintaining backward compatibility for legacy .ropeproject directories.