rename_symbol¶

Rename a function, class, or method in a file and optionally update all references across the project.

Quick Reference¶

rename_symbol(
    file_path: str,              # Path to file
    target_type: str,            # "function", "class", "method"
    target_name: str,            # Current name
    new_name: str,               # New name
    create_backup: bool = True   # Create backup
) -> RenameResult

User Stories¶

→ See all user stories

Parameters¶

Response Schema¶

{
  "data": {
    "file_path": "string",
    "target_type": "string",
    "old_name": "string",
    "new_name": "string",
    "status": "string",
    "backup_path": "string | null",
    "references_updated": "integer",
    "files_modified": ["string"]
  },
  "error": null,
  "tier_applied": "string",
  "duration_ms": "integer"
}

Examples¶

Rename a Function¶

Rename the function 'calc_total' to 'calculate_total' in utils.py

{
  "file_path": "/project/utils.py",
  "target_type": "function",
  "target_name": "calc_total",
  "new_name": "calculate_total"
}

codescalpel rename-symbol utils.py calc_total calculate_total --function

{
  "data": {
    "file_path": "/project/utils.py",
    "target_type": "function",
    "old_name": "calc_total",
    "new_name": "calculate_total",
    "status": "renamed",
    "backup_path": "/project/utils.py.bak",
    "references_updated": 1,
    "files_modified": ["utils.py"]
  },
  "tier_applied": "community",
  "duration_ms": 35
}

Rename a Class¶

Rename UserManager class to UserService in services/user.py

{
  "file_path": "/project/services/user.py",
  "target_type": "class",
  "target_name": "UserManager",
  "new_name": "UserService"
}

codescalpel rename-symbol services/user.py UserManager UserService --class

{
  "data": {
    "file_path": "/project/services/user.py",
    "old_name": "UserManager",
    "new_name": "UserService",
    "status": "renamed",
    "references_updated": 1,
    "files_modified": ["services/user.py"]
  },
  "tier_applied": "community",
  "duration_ms": 42
}

Rename a Method¶

Rename the 'getData' method to 'get_data' in the DataProcessor class

{
  "file_path": "/project/processor.py",
  "target_type": "method",
  "target_name": "DataProcessor.getData",
  "new_name": "get_data"
}

codescalpel rename-symbol processor.py DataProcessor.getData get_data --method

{
  "data": {
    "file_path": "/project/processor.py",
    "target_type": "method",
    "parent_class": "DataProcessor",
    "old_name": "getData",
    "new_name": "get_data",
    "status": "renamed",
    "references_updated": 1
  },
  "tier_applied": "community",
  "duration_ms": 38
}

Rename Without Backup¶

{
  "file_path": "/project/utils.py",
  "target_type": "function",
  "target_name": "helper",
  "new_name": "helper_function",
  "create_backup": false
}

codescalpel rename-symbol utils.py helper helper_function --function --no-backup

Naming Conventions¶

The tool validates that new names follow Python conventions:

Tier Limits¶

rename_symbol capabilities vary by tier:

Community Tier¶

• ✅ Rename functions, classes, methods in a single file
• ✅ Automatic backup creation
• ✅ Naming convention validation
• ✅ Conflict detection
• ⚠️ Single file only - Won't update references in other files
• ⚠️ No import updates - Imports remain unchanged
• ❌ No project-wide rename capability

Pro Tier¶

• ✅ All Community features
• ✅ Search up to 500 files - Find all references
• ✅ Update up to 200 files - Project-wide rename
• ✅ Auto-update imports - Fix import statements
• ✅ Reference tracking - See what gets updated
• ✅ Preview mode - See changes before applying

Enterprise Tier¶

• ✅ All Pro features
• ✅ Unlimited file search/update - Organization-wide rename
• ✅ Full reference tracking - Complete impact analysis
• ✅ Multi-repository rename - Rename across repos
• ✅ Approval workflows - Require team review
• ✅ Audit trail - Track all renames

Key Difference: Scope of Rename - Community: Single file only - Rename in isolation - Pro: 500 files searched, 200 updated - Project-wide refactoring - Enterprise: Unlimited - Organization-wide rename

→ See tier comparison

Error Handling¶

Symbol Not Found¶

{
  "data": null,
  "error": {
    "code": "SYMBOL_NOT_FOUND",
    "message": "Function 'calc_totl' not found in utils.py",
    "suggestions": ["calc_total", "calculate_total"]
  }
}

Invalid Name¶

{
  "data": null,
  "error": {
    "code": "INVALID_NAME",
    "message": "'123_function' is not a valid Python identifier",
    "suggestion": "Names must start with letter or underscore"
  }
}

Name Conflict¶

{
  "data": null,
  "error": {
    "code": "NAME_CONFLICT",
    "message": "Symbol 'calculate_total' already exists in utils.py",
    "existing_symbol": {
      "type": "function",
      "line": 45
    }
  }
}

Best Practices¶

1. Check references first - Use get_symbol_references before renaming
2. Follow conventions - Use appropriate case for symbol type
3. Keep backups - Easy rollback if issues
4. Update tests - Rename in tests too
5. Update docs - API documentation may reference old name

Workflow¶

graph TD
    A[get_symbol_references] --> B{Many references?}
    B -->|Yes| C[Plan carefully]
    B -->|No| D[rename_symbol]
    C --> D
    D --> E[Run tests]
    E -->|Pass| F[Update docs]
    E -->|Fail| G[Check references]

Related Tools¶

• get_symbol_references - Find all usages first
• update_symbol - Replace code instead
• analyze_code - Find symbols to rename