Skip to main content

​
General

Refactron is an intelligent Python code refactoring tool that analyzes your code for issues and suggests automated improvements with safety guarantees.
Yes! Refactron is open source and free to use. Some advanced features require an API key for authentication.
Refactron supports Python 3.8 and above.
Absolutely! Refactron is designed for CI/CD integration. Use refactron ci to generate configuration templates.

​
Installation & Setup

Install via pip:
pip install refactron
Then login to authenticate:
refactron login
Refactron works out of the box with sensible defaults. For customization, run:
refactron init
This creates a .refactron.yaml configuration file.
Refactron automatically installs all required dependencies via pip. For AI features, you’ll need a Groq API key (free tier available).

​
Usage

Run:
refactron analyze myproject/
This will scan your code and report issues by severity.
Refactron includes multiple safety features:
  • Preview mode - See changes before applying
  • Risk scores - Each suggestion has a risk rating
  • Automatic backups - All changes are backed up
  • Rollback - Easily undo changes
Yes! Use the --type flag:
refactron refactor myfile.py --type extract_constant
Or configure in .refactron.yaml:
enabled_refactorers:
  - extract_constant
  - add_docstring
First, set your Groq API key:
export GROQ_API_KEY='your-key'
Then index your codebase:
refactron rag index
Now use AI-powered refactoring:
refactron refactor myfile.py --ai

​
AI & RAG

By default, Refactron uses Groq (Llama 3). You can also configure custom LLM providers.
When using AI features with cloud LLM providers (like Groq), code snippets are sent for analysis. The RAG indexing happens locally. You can use local LLM providers for complete privacy.
Re-index after significant code changes:
refactron rag index --update
For complete re-indexing:
refactron rag index --force

​
Pattern Learning

Refactron learns from your feedback on refactoring suggestions. When you accept or reject suggestions, it adapts to your project’s style and preferences.
Yes, in .refactron.yaml:
enable_pattern_learning: false
By default in .refactron/patterns/ in your project root. You can customize this:
pattern_storage_dir: /custom/path

​
Troubleshooting

Run refactron login to authenticate. Check your authentication status:
refactron auth status
Enable performance optimizations:
enable_ast_cache: true
enable_parallel_processing: true
max_parallel_workers: 4
You can:
  1. Provide feedback to pattern learning
  2. Ignore specific issues with inline comments: 
    x = 42  # refactron: ignore magic-number
  3. Exclude files in .refactron.yaml: 
    exclude_patterns:
  - "*/tests/*"
List available rollback sessions:
refactron rollback --list
Rollback specific session:
refactron rollback --session <id>
Create the index first:
refactron rag index

​
Advanced

Yes! Extend the BaseAnalyzer class:
from refactron.analyzers.base_analyzer import BaseAnalyzer

class MyAnalyzer(BaseAnalyzer):
    def analyze_file(self, file_path, ast_tree):
        # Your analysis logic
        return issues
Yes! Refactron integrates well with:
  • Black - Code formatting
  • isort - Import sorting
  • pytest - Testing
  • pre-commit - Git hooks
  • Prometheus - Monitoring
Check out our GitHub repository and see the CONTRIBUTING.md guide!

​
Support

Can’t find your answer? Open an issue on GitHub or check the full documentation.