# 🤖 Refactron
**The Intelligent Code Refactoring Transformer**
Refactron is a powerful Python library designed to eliminate technical debt, modernize legacy code, and automate code refactoring with intelligence and safety.
[](https://github.com/Refactron-ai/Refactron_lib/actions)
[]()
[]()
[]()
[]()
[]()
[](https://pypi.org/project/refactron/)
[](https://pypi.org/project/refactron/)
[](https://opensource.org/licenses/MIT)
[](https://github.com/Refactron-ai/Refactron_lib)
[](https://pepy.tech/project/refactron)
## ✨ Features
### 🔍 **Comprehensive Analysis**
- **Security Scanning** - Detect `eval()`, `exec()`, SQL injection, shell injection, hardcoded secrets
- **Code Smells** - Find magic numbers, long functions, too many parameters, deep nesting
- **Complexity Metrics** - Cyclomatic complexity, maintainability index
- **Type Hints** - Identify missing or incomplete type annotations
- **Dead Code** - Detect unused functions, variables, and unreachable code
- **Dependencies** - Find circular imports, wildcard imports, deprecated modules
### 🔧 **Intelligent Refactoring**
- **Extract Constants** - Replace magic numbers with named constants
- **Reduce Parameters** - Convert parameter lists into configuration objects
- **Simplify Conditionals** - Transform nested `if` statements into guard clauses
- **Add Docstrings** - Generate contextual documentation automatically
- **Before/After Previews** - See exactly what will change
- **Risk Scoring** - Know how safe each refactoring is (0.0 = perfectly safe, 1.0 = high risk)
### 📊 **Rich Reporting**
- Multiple formats: Text, JSON, HTML
- Detailed issue categorization
- Technical debt quantification
- Export for CI/CD integration
## 🚀 Quick Start
### Installation
```bash
pip install refactron
```
### Basic Usage
```python
from refactron import Refactron
# Initialize Refactron
refactron = Refactron()
# Analyze your code
analysis = refactron.analyze("path/to/your/code.py")
print(analysis.report())
# Apply refactoring
result = refactron.refactor("path/to/your/code.py", preview=True)
result.show_diff()
result.apply()
```
### CLI Usage
```bash
# Initialize configuration
refactron init
# Analyze a file or directory
refactron analyze myproject/ --detailed
# Generate a report
refactron report myproject/ --format json -o report.json
# Preview refactoring suggestions
refactron refactor myfile.py --preview
# Filter specific refactoring types
refactron refactor myfile.py --preview -t extract_constant -t add_docstring
```
**Example Output:**
```
🔍 Refactron Analysis
Analysis Summary
┏━━━━━━━━━━━━━━━━┳━━━━━━━┓
┃ Metric ┃ Value ┃
┡━━━━━━━━━━━━━━━━╇━━━━━━━┩
│ Files Analyzed │ 3 │
│ Total Issues │ 50 │
│ 🔴 Critical │ 3 │
│ ❌ Errors │ 0 │
│ ⚡ Warnings │ 8 │
│ ℹ️ Info │ 39 │
└────────────────┴───────┘
⚠️ Found 3 critical issue(s) that need immediate attention!
```
## 🎯 What Makes Refactron Different?
Unlike traditional linters and formatters, Refactron:
- **Holistic Approach**: Combines analysis, refactoring, and optimization in one tool
- **Context-Aware**: Understands code semantics, not just syntax
- **Safe by Default**: Preview changes, risk scoring, and rollback support
- **Intelligent**: Learn from patterns and suggest contextual improvements
- **Business-Focused**: Quantify technical debt in actionable metrics
## 💡 Real-World Examples
We've included practical examples in the `examples/` directory:
- **`flask_api_example.py`** - Common Flask API issues (security, code smells)
- **`data_science_example.py`** - Data science workflow improvements
- **`cli_tool_example.py`** - CLI application best practices
Try them out:
```bash
# Analyze the Flask example
refactron analyze examples/flask_api_example.py --detailed
# Get refactoring suggestions
refactron refactor examples/flask_api_example.py --preview
```
See `examples/DEMO_USAGE.md` for detailed walkthroughs!
## 📚 Documentation
- [Getting Started (Dev)](GETTING_STARTED_DEV.md) - Development setup
- [Architecture](ARCHITECTURE.md) - Technical design
- [Case Study](CASE_STUDY.md) - Real-world testing results
- [Project Status](PROJECT_STATUS.md) - Complete feature matrix
## 🛠️ Development Status
> **⚠️ Beta Release**: Refactron v0.1.0-beta is production-ready but still evolving. We welcome feedback and contributions!
**Current Metrics:**
- ✅ **98 tests passing** (100% success rate)
- ✅ **90% code coverage**
- ✅ **0 critical issues** in production code
- ✅ Real-world validated on 5,800+ lines
### Roadmap
**Phase 1: Foundation** ✅ **COMPLETE**
- [x] Core architecture & CLI
- [x] Configuration system
- [x] Basic analyzers (complexity, code smells)
- [x] Refactoring suggestions with risk scoring
- [x] Before/after code previews
**Phase 2: Advanced Analysis** ✅ **COMPLETE**
- [x] Security vulnerability scanning
- [x] Dependency analysis
- [x] Dead code detection
- [x] Type hint analysis
- [x] Comprehensive test suite (87 tests, 89% coverage)
**Phase 3: Intelligence & Automation** 🚧 **NEXT**
- [ ] AI-powered pattern recognition
- [ ] Auto-fix capabilities
- [ ] Multi-file refactoring
- [ ] Custom rule engine
- [ ] Performance profiling
**Phase 4: Integration & Scale** 📋 **PLANNED**
- [ ] IDE plugins (VS Code, PyCharm)
- [ ] CI/CD integration (GitHub Actions, GitLab CI)
- [ ] Team collaboration features
- [ ] Historical trend analysis
## 🤝 Contributing
We welcome contributions! Please see:
- [Contributing Guide](CONTRIBUTING.md) - How to contribute
- [Code of Conduct](CODE_OF_CONDUCT.md) - Community guidelines
- [Getting Started (Dev)](GETTING_STARTED_DEV.md) - Development setup
## 🧪 CI/CD Status
Refactron uses GitHub Actions for continuous integration and deployment:
- ✅ Automated testing on Python 3.8, 3.9, 3.10, 3.11, 3.12
- ✅ Code quality checks (Black, isort, flake8)
- ✅ Security scanning with Bandit
- ✅ Automated dependency updates via Dependabot
- ✅ 90% test coverage maintained
Check our [Actions page](https://github.com/Refactron-ai/Refactron_lib/actions) for live build status!
## 📄 License
MIT License - see [LICENSE](LICENSE) file for details.
---
**Star ⭐ this repo if you find it helpful!**
Raw data
{
"_id": null,
"home_page": null,
"name": "refactron",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "refactoring, code-quality, static-analysis, code-optimization, technical-debt, code-review, security-analysis",
"author": null,
"author_email": "Om Sherikar <omsherikar@example.com>",
"download_url": "https://files.pythonhosted.org/packages/e6/f7/4acd74b33efa2a0bf5c4d36fcf0be6e434594d88f7c9a1f66c010fa5a6d2/refactron-1.0.0.tar.gz",
"platform": null,
"description": "# \ud83e\udd16 Refactron\n\n**The Intelligent Code Refactoring Transformer**\n\nRefactron is a powerful Python library designed to eliminate technical debt, modernize legacy code, and automate code refactoring with intelligence and safety.\n\n[](https://github.com/Refactron-ai/Refactron_lib/actions)\n[]()\n[]()\n[]()\n[]()\n[]()\n[](https://pypi.org/project/refactron/)\n[](https://pypi.org/project/refactron/)\n[](https://opensource.org/licenses/MIT)\n[](https://github.com/Refactron-ai/Refactron_lib)\n[](https://pepy.tech/project/refactron)\n\n## \u2728 Features\n\n### \ud83d\udd0d **Comprehensive Analysis**\n- **Security Scanning** - Detect `eval()`, `exec()`, SQL injection, shell injection, hardcoded secrets\n- **Code Smells** - Find magic numbers, long functions, too many parameters, deep nesting\n- **Complexity Metrics** - Cyclomatic complexity, maintainability index\n- **Type Hints** - Identify missing or incomplete type annotations\n- **Dead Code** - Detect unused functions, variables, and unreachable code\n- **Dependencies** - Find circular imports, wildcard imports, deprecated modules\n\n### \ud83d\udd27 **Intelligent Refactoring**\n- **Extract Constants** - Replace magic numbers with named constants\n- **Reduce Parameters** - Convert parameter lists into configuration objects\n- **Simplify Conditionals** - Transform nested `if` statements into guard clauses\n- **Add Docstrings** - Generate contextual documentation automatically\n- **Before/After Previews** - See exactly what will change\n- **Risk Scoring** - Know how safe each refactoring is (0.0 = perfectly safe, 1.0 = high risk)\n\n### \ud83d\udcca **Rich Reporting**\n- Multiple formats: Text, JSON, HTML\n- Detailed issue categorization\n- Technical debt quantification\n- Export for CI/CD integration\n\n## \ud83d\ude80 Quick Start\n\n### Installation\n\n```bash\npip install refactron\n```\n\n### Basic Usage\n\n```python\nfrom refactron import Refactron\n\n# Initialize Refactron\nrefactron = Refactron()\n\n# Analyze your code\nanalysis = refactron.analyze(\"path/to/your/code.py\")\nprint(analysis.report())\n\n# Apply refactoring\nresult = refactron.refactor(\"path/to/your/code.py\", preview=True)\nresult.show_diff()\nresult.apply()\n```\n\n### CLI Usage\n\n```bash\n# Initialize configuration\nrefactron init\n\n# Analyze a file or directory\nrefactron analyze myproject/ --detailed\n\n# Generate a report\nrefactron report myproject/ --format json -o report.json\n\n# Preview refactoring suggestions\nrefactron refactor myfile.py --preview\n\n# Filter specific refactoring types\nrefactron refactor myfile.py --preview -t extract_constant -t add_docstring\n```\n\n**Example Output:**\n```\n\ud83d\udd0d Refactron Analysis\n\n Analysis Summary \n\u250f\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2533\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2513\n\u2503 Metric \u2503 Value \u2503\n\u2521\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2547\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2529\n\u2502 Files Analyzed \u2502 3 \u2502\n\u2502 Total Issues \u2502 50 \u2502\n\u2502 \ud83d\udd34 Critical \u2502 3 \u2502\n\u2502 \u274c Errors \u2502 0 \u2502\n\u2502 \u26a1 Warnings \u2502 8 \u2502\n\u2502 \u2139\ufe0f Info \u2502 39 \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n\n\u26a0\ufe0f Found 3 critical issue(s) that need immediate attention!\n```\n\n## \ud83c\udfaf What Makes Refactron Different?\n\nUnlike traditional linters and formatters, Refactron:\n\n- **Holistic Approach**: Combines analysis, refactoring, and optimization in one tool\n- **Context-Aware**: Understands code semantics, not just syntax\n- **Safe by Default**: Preview changes, risk scoring, and rollback support\n- **Intelligent**: Learn from patterns and suggest contextual improvements\n- **Business-Focused**: Quantify technical debt in actionable metrics\n\n## \ud83d\udca1 Real-World Examples\n\nWe've included practical examples in the `examples/` directory:\n\n- **`flask_api_example.py`** - Common Flask API issues (security, code smells)\n- **`data_science_example.py`** - Data science workflow improvements\n- **`cli_tool_example.py`** - CLI application best practices\n\nTry them out:\n```bash\n# Analyze the Flask example\nrefactron analyze examples/flask_api_example.py --detailed\n\n# Get refactoring suggestions\nrefactron refactor examples/flask_api_example.py --preview\n```\n\nSee `examples/DEMO_USAGE.md` for detailed walkthroughs!\n\n## \ud83d\udcda Documentation\n\n- [Getting Started (Dev)](GETTING_STARTED_DEV.md) - Development setup\n- [Architecture](ARCHITECTURE.md) - Technical design\n- [Case Study](CASE_STUDY.md) - Real-world testing results\n- [Project Status](PROJECT_STATUS.md) - Complete feature matrix\n\n## \ud83d\udee0\ufe0f Development Status\n\n> **\u26a0\ufe0f Beta Release**: Refactron v0.1.0-beta is production-ready but still evolving. We welcome feedback and contributions!\n\n**Current Metrics:**\n- \u2705 **98 tests passing** (100% success rate)\n- \u2705 **90% code coverage**\n- \u2705 **0 critical issues** in production code\n- \u2705 Real-world validated on 5,800+ lines\n\n### Roadmap\n\n**Phase 1: Foundation** \u2705 **COMPLETE**\n- [x] Core architecture & CLI\n- [x] Configuration system\n- [x] Basic analyzers (complexity, code smells)\n- [x] Refactoring suggestions with risk scoring\n- [x] Before/after code previews\n\n**Phase 2: Advanced Analysis** \u2705 **COMPLETE**\n- [x] Security vulnerability scanning\n- [x] Dependency analysis\n- [x] Dead code detection\n- [x] Type hint analysis\n- [x] Comprehensive test suite (87 tests, 89% coverage)\n\n**Phase 3: Intelligence & Automation** \ud83d\udea7 **NEXT**\n- [ ] AI-powered pattern recognition\n- [ ] Auto-fix capabilities\n- [ ] Multi-file refactoring\n- [ ] Custom rule engine\n- [ ] Performance profiling\n\n**Phase 4: Integration & Scale** \ud83d\udccb **PLANNED**\n- [ ] IDE plugins (VS Code, PyCharm)\n- [ ] CI/CD integration (GitHub Actions, GitLab CI)\n- [ ] Team collaboration features\n- [ ] Historical trend analysis\n\n## \ud83e\udd1d Contributing\n\nWe welcome contributions! Please see:\n- [Contributing Guide](CONTRIBUTING.md) - How to contribute\n- [Code of Conduct](CODE_OF_CONDUCT.md) - Community guidelines\n- [Getting Started (Dev)](GETTING_STARTED_DEV.md) - Development setup\n\n\n\n## \ud83e\uddea CI/CD Status\n\nRefactron uses GitHub Actions for continuous integration and deployment:\n- \u2705 Automated testing on Python 3.8, 3.9, 3.10, 3.11, 3.12\n- \u2705 Code quality checks (Black, isort, flake8)\n- \u2705 Security scanning with Bandit\n- \u2705 Automated dependency updates via Dependabot\n- \u2705 90% test coverage maintained\n\nCheck our [Actions page](https://github.com/Refactron-ai/Refactron_lib/actions) for live build status!\n\n## \ud83d\udcc4 License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n\n---\n\n**Star \u2b50 this repo if you find it helpful!**\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "The Intelligent Code Refactoring Transformer - Analyze, refactor, and optimize Python code with AI-powered suggestions",
"version": "1.0.0",
"project_urls": null,
"split_keywords": [
"refactoring",
" code-quality",
" static-analysis",
" code-optimization",
" technical-debt",
" code-review",
" security-analysis"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "87d2a085599f755f70b9450f4ebf5153b1aafaa31bbab8733440b654263bcea5",
"md5": "6c12467f356e6ad8c68240e9948b25ae",
"sha256": "3fc14aff49ed71deb931e14c96e390d0fbaa372e2f9e47ade4c0d175d4b0394e"
},
"downloads": -1,
"filename": "refactron-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6c12467f356e6ad8c68240e9948b25ae",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 53270,
"upload_time": "2025-10-26T18:54:21",
"upload_time_iso_8601": "2025-10-26T18:54:21.047879Z",
"url": "https://files.pythonhosted.org/packages/87/d2/a085599f755f70b9450f4ebf5153b1aafaa31bbab8733440b654263bcea5/refactron-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "e6f74acd74b33efa2a0bf5c4d36fcf0be6e434594d88f7c9a1f66c010fa5a6d2",
"md5": "ac63e8ed8cdc96f9c296bfde3afec2d5",
"sha256": "d3fd97f95216855914de6dd9763e0b78538231c5f5e32a90c439b54eff429221"
},
"downloads": -1,
"filename": "refactron-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "ac63e8ed8cdc96f9c296bfde3afec2d5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 64129,
"upload_time": "2025-10-26T18:54:23",
"upload_time_iso_8601": "2025-10-26T18:54:23.175136Z",
"url": "https://files.pythonhosted.org/packages/e6/f7/4acd74b33efa2a0bf5c4d36fcf0be6e434594d88f7c9a1f66c010fa5a6d2/refactron-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-26 18:54:23",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "refactron"
}
JSON