{"id":44470262,"url":"https://github.com/tboy1337/pyrefactor","last_synced_at":"2026-06-27T09:00:15.645Z","repository":{"id":321093711,"uuid":"1078206219","full_name":"tboy1337/PyRefactor","owner":"tboy1337","description":"A Python refactoring and optimization linter that uses AST analysis to identify performance issues, complexity problems, and code improvements.","archived":false,"fork":false,"pushed_at":"2026-06-24T20:46:39.000Z","size":487,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-06-24T21:19:08.285Z","etag":null,"topics":["ast","code-analysis","code-quality","code-review","lint","linter","linting","optimization","optimize","python","python-linter","refactoring","static-analysis"],"latest_commit_sha":null,"homepage":"https://tboy1337.github.io/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tboy1337.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["tboy1337"],"patreon":"tboy1337","open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"lfx_crowdfunding":null,"polar":null,"buy_me_a_coffee":"tboy1337","thanks_dev":null,"custom":null}},"created_at":"2025-10-17T11:18:28.000Z","updated_at":"2026-06-24T20:44:33.000Z","dependencies_parsed_at":null,"dependency_job_id":"a0f99728-b434-4fca-b056-e18e194a8552","html_url":"https://github.com/tboy1337/PyRefactor","commit_stats":null,"previous_names":["tboy1337/pyrefactor"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/tboy1337/PyRefactor","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tboy1337%2FPyRefactor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tboy1337%2FPyRefactor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tboy1337%2FPyRefactor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tboy1337%2FPyRefactor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tboy1337","download_url":"https://codeload.github.com/tboy1337/PyRefactor/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tboy1337%2FPyRefactor/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34847287,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-27T02:00:06.362Z","response_time":126,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ast","code-analysis","code-quality","code-review","lint","linter","linting","optimization","optimize","python","python-linter","refactoring","static-analysis"],"created_at":"2026-02-12T21:15:26.000Z","updated_at":"2026-06-27T09:00:15.612Z","avatar_url":"https://github.com/tboy1337.png","language":"Python","funding_links":["https://github.com/sponsors/tboy1337","https://patreon.com/tboy1337","https://buymeacoffee.com/tboy1337"],"categories":[],"sub_categories":[],"readme":"# PyRefactor\r\n\r\nA Python refactoring and optimization linter that uses AST analysis to identify performance issues, complexity problems, and code improvements.\r\n\r\n[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)\r\n\r\n## Features\r\n\r\n- **Multi-threaded Analysis**: Fast parallel file processing\r\n- **Configurable Detectors**: Enable/disable specific detectors\r\n- **Severity Levels**: Issues categorized as INFO, LOW, MEDIUM, or HIGH\r\n- **Flexible Output**: Group by file or severity\r\n- **Cross-platform**: Works on Windows, macOS, and Linux\r\n\r\n## Detectors\r\n\r\n- **Complexity**: High cyclomatic complexity functions\r\n- **Performance**: String concatenation in loops (thresholded), repeated uncached calls in loops, inefficient operations\r\n- **Boolean Logic**: Overcomplicated boolean expressions\r\n- **Loops**: Index patterns, nested loops with lookups, loop-invariant calls\r\n- **Duplication**: Duplicate code blocks\r\n- **Context Manager**: Missing `with` statements for resource operations\r\n- **Control Flow**: Unnecessary `else` after `return`/`raise`/`break`/`continue`\r\n- **Dictionary Operations**: Non-idiomatic dict patterns, missing `.get()`, unnecessary `.keys()`, dict comprehensions (R010)\r\n- **Comparisons**: Chained comparisons, singleton checks, `type()` vs `isinstance()`\r\n\r\nSee [docs/RULES.md](docs/RULES.md) for the full rule catalog (C001–C006, P001–P007, B001/B004–B007, L001–L004, D001, R001–R016).\r\n\r\n## Installation\r\n\r\n### Recommended: Via pip\r\n\r\n```bash\r\npip install pyrefactor\r\n```\r\n\r\n### Standalone Executable\r\n\r\nDownload the latest release from the [Releases](https://github.com/tboy1337/PyRefactor/releases/latest) section. No Python installation required.\r\n\r\n### From Source\r\n\r\n```bash\r\ngit clone https://github.com/tboy1337/PyRefactor.git\r\ncd PyRefactor\r\npip install -e .\r\n```\r\n\r\n**Requirements**: Python 3.12+\r\n\r\n**Status**: PyRefactor is **Production/Stable** (see PyPI classifiers).\r\n\r\n**License**: This project uses the [Commercial Restricted License (CRL)](LICENSE.md). Personal and non-commercial use is permitted; commercial use requires permission from the copyright holder.\r\n\r\nSee [docs/CONFIGURATION.md](docs/CONFIGURATION.md) for full configuration reference (TOML and INI formats).\r\n\r\n## Usage\r\n\r\n```bash\r\n# Analyze a file or directory\r\npyrefactor myfile.py\r\npyrefactor src/\r\n\r\n# Show only medium/high severity issues\r\npyrefactor --min-severity medium src/\r\n\r\n# Group by severity level\r\npyrefactor --group-by severity src/\r\n\r\n# Machine-readable JSON output for CI and tooling\r\npyrefactor --format json src/\r\n\r\n# Use more workers for faster analysis\r\npyrefactor --jobs 8 src/\r\n\r\n# Custom configuration file\r\npyrefactor --config custom.toml src/\r\n```\r\n\r\n### Options\r\n\r\n- `-c, --config`: Configuration file path; when omitted, auto-discover `pyproject.toml` (`[tool.pyrefactor]`), then `pyrefactor.ini`, then built-in defaults\r\n- `-g, --group-by`: Group text output by `file` or `severity` (default: `file`)\r\n- `--format`: Output format: `text` (default) or `json`\r\n- `--min-severity`: Minimum severity to report: `info`, `low`, `medium`, `high` (default: `info`). Also filters which issues count toward the exit code.\r\n- `-j, --jobs`: Number of parallel workers (default: 4)\r\n- `-v, --verbose`: Enable verbose logging\r\n- `--fail-on-parse-errors`: Exit with code 1 when any file has a syntax or parse error\r\n- `--version`: Show version\r\n\r\n### Exit Codes\r\n\r\nExit codes are computed **after** applying `--min-severity`. For example, `--min-severity high` exits `0` when only MEDIUM issues exist, because those issues are filtered out before the exit code is determined.\r\n\r\n- `0` - No issues remain at or above `--min-severity`. Per-file syntax or parse errors are reported in output but do not change the exit code unless `--fail-on-parse-errors` is set.\r\n- `1` - One or more issues remain at or above `--min-severity`, or parse errors when `--fail-on-parse-errors` is used\r\n- `2` - Configuration, path, or orchestration error (invalid paths, missing config, no Python files to analyze, or all files excluded by patterns)\r\n\r\n### Analysis Limits\r\n\r\nFiles larger than **10 MB** are skipped with a parse-style error message. This limit is fixed and not configurable.\r\n\r\n## Configuration\r\n\r\nConfigure via TOML file (e.g., `pyproject.toml`):\r\n\r\n```toml\r\n[tool.pyrefactor]\r\nexclude_patterns = [\"__pycache__\", \".venv\", \"build\", \"dist\"]\r\n\r\n[tool.pyrefactor.complexity]\r\nenabled = true\r\nmax_cyclomatic_complexity = 10\r\nmax_branches = 10\r\nmax_nesting_depth = 3\r\nmax_function_lines = 50\r\nmax_arguments = 5\r\nmax_local_variables = 15\r\n\r\n[tool.pyrefactor.performance]\r\nenabled = true\r\nmin_concatenations = 3\r\nmin_duplicate_calls = 3\r\n\r\n[tool.pyrefactor.boolean_logic]\r\nenabled = true\r\nmax_boolean_operators = 3\r\n\r\n[tool.pyrefactor.loops]\r\nenabled = true\r\n\r\n[tool.pyrefactor.duplication]\r\nenabled = true\r\nmin_duplicate_lines = 5\r\nsimilarity_threshold = 0.85\r\n\r\n[tool.pyrefactor.context_manager]\r\nenabled = true\r\n\r\n[tool.pyrefactor.control_flow]\r\nenabled = true\r\n\r\n[tool.pyrefactor.dict_operations]\r\nenabled = true\r\n\r\n[tool.pyrefactor.comparisons]\r\nenabled = true\r\n```\r\n\r\nConfiguration is searched in: `--config` → `pyproject.toml` → `pyrefactor.ini` → defaults\r\n\r\n### INI configuration (`pyrefactor.ini`)\r\n\r\nSee the repository's [`pyrefactor.ini`](pyrefactor.ini) for a full annotated example with every detector section. A minimal example:\r\n\r\n```ini\r\n[complexity]\r\nenabled = true\r\nmax_cyclomatic_complexity = 10\r\n\r\n[duplication]\r\nenabled = true\r\nmin_duplicate_lines = 5\r\nsimilarity_threshold = 0.85\r\n\r\n[general]\r\nexclude_patterns = __pycache__, .venv, build, dist\r\n```\r\n\r\nSee [docs/CONFIGURATION.md](docs/CONFIGURATION.md) for the complete configuration reference.\r\n\r\n**Note:** The PyPI package version (`pyproject.toml`) may differ from GitHub release build numbers used for standalone executables.\r\n\r\n## CI/CD Integration\r\n\r\n### Pre-commit Hook\r\n\r\n```yaml\r\nrepos:\r\n  - repo: local\r\n    hooks:\r\n      - id: pyrefactor\r\n        name: PyRefactor\r\n        entry: pyrefactor\r\n        language: system\r\n        types: [python]\r\n        args: [--min-severity=medium]\r\n```\r\n\r\n### GitHub Actions\r\n\r\nThis repository's [Build-Release-PYPI](.github/workflows/Build-Release-PYPI.yml) workflow builds and publishes releases only; it does not run the test suite. Run `python scripts/verify.py` locally before release.\r\n\r\nExample workflow for consumers (not maintained in this repository):\r\n\r\n```yaml\r\nname: Code Quality\r\non: [push, pull_request]\r\n\r\njobs:\r\n  pyrefactor:\r\n    runs-on: ubuntu-latest\r\n    steps:\r\n      - uses: actions/checkout@v4\r\n      - uses: actions/setup-python@v5\r\n        with:\r\n          python-version: '3.12'\r\n      - run: pip install pyrefactor\r\n      - run: pyrefactor --min-severity medium --fail-on-parse-errors src/\r\n```\r\n\r\n## Contributing\r\n\r\nContributions are welcome! This project is under a Commercial Restricted License (CRL). For commercial use, contact the copyright holder.\r\n\r\n### Development\r\n\r\nInstall the package with development dependencies:\r\n\r\n```bash\r\npip install -e \".[dev]\"\r\n```\r\n\r\nAlternatively:\r\n\r\n```bash\r\npip install -e .\r\npip install -r requirements-dev.txt\r\n```\r\n\r\nRun the local verification script (formatting, type checks, lint, security scan, self-lint, and pytest with coverage):\r\n\r\n```bash\r\npython scripts/verify.py\r\n```\r\n\r\nOn Windows you can also use `py scripts/verify.py`. The script uses `sys.executable` and absolute paths so it behaves the same on Windows, macOS, and Linux.\r\n\r\nRun tests directly (same suite as verify, without formatting or lint steps):\r\n\r\n```bash\r\npytest\r\n```\r\n\r\n1. Follow existing code style (Black, isort)\r\n2. Add tests for new features (\u003e90% coverage)\r\n3. Run type checking and linting\r\n\r\n## License\r\n\r\nLicensed under the CRL license - see [LICENSE.md](LICENSE.md) for details.\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftboy1337%2Fpyrefactor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftboy1337%2Fpyrefactor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftboy1337%2Fpyrefactor/lists"}