| Name | autorefine JSON |
| Version |
0.0.1
JSON |
| download |
| home_page | https://github.com/bswck/autorefine |
| Summary | Mechanize the refactoring process to operate on a large scale. |
| upload_time | 2023-12-06 23:24:13 |
| maintainer | |
| docs_url | None |
| author | bswck |
| requires_python | >=3.8,<4.0 |
| license | GPL-3.0 |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# autorefine [](https://pypi.org/project/autorefine/) [](https://pypi.org/project/autorefine/)
[](https://github.com/bswck/autorefine/actions/workflows/test.yml)
[](https://coverage-badge.samuelcolvin.workers.dev/redirect/bswck/autorefine)
[](https://python-poetry.org/)
[](https://github.com/astral-sh/ruff)
[](https://github.com/psf/black)
[](https://github.com/bswck/autorefine/blob/HEAD/LICENSE)
[](https://github.com/pre-commit/pre-commit)
Mechanize the refactoring process to operate on a large scale.
The project is aimed to provide a framework for the process of refactoring Python projects
from the very beginning to the very end:
- `autorefine analyze` → **analyze the project** with linters and type checkers,
- `autorefine roadmap` → **create a refactoring roadmap** (like https://github.com/CERT-Polska/malduck/issues/110, but with more details available as a specialized document),
- `autorefine plan` → **create a delivery plan** (like in the issue above) to split the refactoring process into **a sequence of iterations**,
- `autorefine autopilot` → **apply automatic fixes** and commit them in reviewable and git-bisectable chunks with meaningful descriptions,
- `autorefine audit` → typically **run tests** and other tools that determine whether the project runs safe,
- `autorefine troubleshoot` → using the configured **auditing task**, `git bisect` to **find out what fix went wrong**, describe the problem,
- leave the rest for manual work,
- `autorefine finalize` → **create a PR** (like https://github.com/CERT-Polska/malduck/issues/111) to finalize the current iteration of refactoring with a detailed description of the changes and a link to the roadmap, delivery plan and all commits.
Created to accomplish https://github.com/jaraco/skeleton/issues/98 and for personal use to raise awareness of best practices across the Python community globally.
# Planned tooling
The project is planned to be a wrapper around the following well-tested & recognized tools:
- [MonkeyType](https://github.com/Instagram/MonkeyType#readme) for automatic type annotations generation,
- [Fixit](https://github.com/Instagram/Fixit#readme) for automatic fixes that require static analysis and scope analysis and planning of manual refactoring steps,
- [Ruff](https://github.com/astral-sh/ruff#readme) for automatic fixes and planning of manual refactoring steps,
- Static type checking:
- [mypy](https://github.com/python/mypy#readme),
- [pyre](https://github.com/facebook/pyre-check#readme),
- [pytype](https://github.com/google/pytype#readme),
- [diff-cover](https://github.com/Bachmann1234/diff_cover#readme) for [coverage](https://github.com/nedbat/coverage#readme) reports on fixes,
- [smokeshow](https://github.com/samuelcolvin/smokeshow#readme) for hosting detailed refactoring roadmaps and delivery plans,
- [pandas](https://github.com/pandas-dev/pandas) for collecting tasks and creating markdown tables,
- [GitHub CLI](https://cli.github.com/) for creating tickets.
# Refactoring workflow
`autorefine` will be a CLI tool that will help you refactor a project in a few simple steps:
1. Fork a repository you want to refactor.
1. Create a new branch for refactoring.
1. Run `autorefine configure` to run a wizard that will help you configure `autorefine`, configure audits (`autorefine` will typically detect doctest, pytest and other tools that determine whether the project runs safe) and refactor the project for a specific choice of linting tools.
1. Run `autorefine analyze` to analyze the project with linters and type checkers. `autorefine` now knows what needs to be fixed in the current HEAD.
1. Run `autorefine roadmap` to create a refactoring roadmap. You will have a checklist of all the things that need to be fixed in the project automatically and manually.
2. Run `autorefine plan` to create a delivery plan and set up iterations of the refactoring process. For example, you can start off by a PR that aims to modernize the codebase and does not change the implementation (fixes in the roadmap will be grouped and you will be able to select which ones you want to apply in this iteration), that would be the first iteration, and then apply some implementation-changing autofixes, such as replacing `f"'{x}'"` with `f"{x!r}"`—that could be the second iteration. Having a delivery plan will make `autorefine` create a PR for each iteration, so that you can review the changes and merge them separately.
3. Run `autorefine autopilot` to apply automatic fixes and commit them in reviewable and git-bisectable chunks with meaningful descriptions.
4. Run `autorefine audit` to prevent future regressions.
5. Run `autorefine troubleshoot` to repeatedly call `autorefine audit` within `git bisect` to find out what fix went wrong, and get a detailed description of the problem and suggestions on how to fix it.
6. Manually fix the problems that cannot be fixed automatically. You will find them in the roadmap (`autorefine roadmap`).
7. Run `autorefine finalize` to finalize the current iteration and create a PR with a detailed description of the changes and a link to the roadmap, delivery plan and all commits of the current refactor iteration.
# Non-MVP ideas
- `autorefine ci` to create a dedicated CI pipeline (which will, by default, run `autorefine analyze` and `autorefine audit` on every PR) for your Git hosting provider (GitHub, GitLab, Bitbucket, etc.),
- `autorefine template [TEMPLATE_NAME]` to configure Quality Assurance and CI/CD tooling (Ruff, tox, towncrier, Sphinx, etc.) by smart copying what is seen a specified repository (e.g. `autorefine template jaraco/skeleton`+[jaraco.develop](https://github.com/jaraco/jaraco.develop) could be used to copy tox.ini, GitHub Actions etc.)—feature for projects that don't intend to use a skeleton.
- `autorefine breakdown` to create separate tickets for each fix in the roadmap in your workflow management tool (GitHub Projects, Jira, ClickUp, Asana, Trello, etc.).
# Get inspired
- https://instagram-engineering.com/static-analysis-at-scale-an-instagram-story-8f498ab71a0c
# Installation
If you want to…
## …use this tool in your project 💻
You might simply install it with [pipx](https://github.com/pypa/pipx#readme):
```shell
pipx install autorefine
```
## …contribute to [autorefine](https://github.com/bswck/autorefine) 🚀
> [!Note]
> If you use Windows, it is highly recommended to complete the installation in the way presented below through [WSL2](https://learn.microsoft.com/en-us/windows/wsl/install).
1. Fork the [autorefine repository](https://github.com/bswck/autorefine) on GitHub.
1. [Install Poetry](https://python-poetry.org/docs/#installation).<br/>
Poetry is an amazing tool for managing dependencies & virtual environments, building packages and publishing them.
You might use [pipx](https://github.com/pypa/pipx#readme) to install it globally (recommended):
```shell
pipx install poetry
```
<sub>If you encounter any problems, refer to [the official documentation](https://python-poetry.org/docs/#installation) for the most up-to-date installation instructions.</sub>
If you want to use pipx to install dev dependencies as well, install the [poetry apps](https://github.com/bswck/poetry-apps#readme) plugin:
```shell
pipx inject poetry poetry-apps
```
Be sure to have Python 3.8 installed—if you use [pyenv](https://github.com/pyenv/pyenv#readme), simply run:
```shell
pyenv install 3.8
```
1. Clone your fork locally and install dependencies.
```shell
git clone https://github.com/your-username/autorefine path/to/autorefine
cd path/to/autorefine
poetry env use $(cat .python-version)
poetry install
```
Next up, simply activate the virtual environment and install pre-commit hooks:
```shell
poetry shell
pre-commit install --hook-type pre-commit --hook-type pre-push
```
For more information on how to contribute, check out [CONTRIBUTING.md](https://github.com/bswck/autorefine/blob/HEAD/CONTRIBUTING.md).<br/>
Always happy to accept contributions! ❤️
# Legal info
© Copyright by Bartosz Sławecki ([@bswck](https://github.com/bswck)).
<br />This software is licensed under the terms of [GPL-3.0 License](https://github.com/bswck/autorefine/blob/HEAD/LICENSE).
Raw data
{
"_id": null,
"home_page": "https://github.com/bswck/autorefine",
"name": "autorefine",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8,<4.0",
"maintainer_email": "",
"keywords": "",
"author": "bswck",
"author_email": "bswck.dev@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/22/8f/69af6f6df917e7d999c3249d8041452d1c2c6b2aeedaa9b20c2f0abfcc86/autorefine-0.0.1.tar.gz",
"platform": null,
"description": "\n# autorefine [](https://pypi.org/project/autorefine/) [](https://pypi.org/project/autorefine/)\n[](https://github.com/bswck/autorefine/actions/workflows/test.yml)\n[](https://coverage-badge.samuelcolvin.workers.dev/redirect/bswck/autorefine)\n[](https://python-poetry.org/)\n[](https://github.com/astral-sh/ruff)\n[](https://github.com/psf/black)\n[](https://github.com/bswck/autorefine/blob/HEAD/LICENSE)\n[](https://github.com/pre-commit/pre-commit)\n\nMechanize the refactoring process to operate on a large scale.\n\nThe project is aimed to provide a framework for the process of refactoring Python projects\nfrom the very beginning to the very end:\n- `autorefine analyze` \u2192 **analyze the project** with linters and type checkers,\n- `autorefine roadmap` \u2192 **create a refactoring roadmap** (like https://github.com/CERT-Polska/malduck/issues/110, but with more details available as a specialized document),\n- `autorefine plan` \u2192 **create a delivery plan** (like in the issue above) to split the refactoring process into **a sequence of iterations**,\n- `autorefine autopilot` \u2192 **apply automatic fixes** and commit them in reviewable and git-bisectable chunks with meaningful descriptions,\n- `autorefine audit` \u2192 typically **run tests** and other tools that determine whether the project runs safe,\n- `autorefine troubleshoot` \u2192 using the configured **auditing task**, `git bisect` to **find out what fix went wrong**, describe the problem,\n- leave the rest for manual work,\n- `autorefine finalize` \u2192 **create a PR** (like https://github.com/CERT-Polska/malduck/issues/111) to finalize the current iteration of refactoring with a detailed description of the changes and a link to the roadmap, delivery plan and all commits.\n\nCreated to accomplish https://github.com/jaraco/skeleton/issues/98 and for personal use to raise awareness of best practices across the Python community globally.\n\n# Planned tooling\nThe project is planned to be a wrapper around the following well-tested & recognized tools:\n- [MonkeyType](https://github.com/Instagram/MonkeyType#readme) for automatic type annotations generation,\n- [Fixit](https://github.com/Instagram/Fixit#readme) for automatic fixes that require static analysis and scope analysis and planning of manual refactoring steps,\n- [Ruff](https://github.com/astral-sh/ruff#readme) for automatic fixes and planning of manual refactoring steps,\n- Static type checking:\n - [mypy](https://github.com/python/mypy#readme),\n - [pyre](https://github.com/facebook/pyre-check#readme),\n - [pytype](https://github.com/google/pytype#readme),\n- [diff-cover](https://github.com/Bachmann1234/diff_cover#readme) for [coverage](https://github.com/nedbat/coverage#readme) reports on fixes,\n- [smokeshow](https://github.com/samuelcolvin/smokeshow#readme) for hosting detailed refactoring roadmaps and delivery plans,\n- [pandas](https://github.com/pandas-dev/pandas) for collecting tasks and creating markdown tables,\n- [GitHub CLI](https://cli.github.com/) for creating tickets.\n\n# Refactoring workflow\n`autorefine` will be a CLI tool that will help you refactor a project in a few simple steps:\n\n1. Fork a repository you want to refactor.\n\n1. Create a new branch for refactoring.\n\n1. Run `autorefine configure` to run a wizard that will help you configure `autorefine`, configure audits (`autorefine` will typically detect doctest, pytest and other tools that determine whether the project runs safe) and refactor the project for a specific choice of linting tools.\n\n1. Run `autorefine analyze` to analyze the project with linters and type checkers. `autorefine` now knows what needs to be fixed in the current HEAD.\n\n1. Run `autorefine roadmap` to create a refactoring roadmap. You will have a checklist of all the things that need to be fixed in the project automatically and manually.\n\n2. Run `autorefine plan` to create a delivery plan and set up iterations of the refactoring process. For example, you can start off by a PR that aims to modernize the codebase and does not change the implementation (fixes in the roadmap will be grouped and you will be able to select which ones you want to apply in this iteration), that would be the first iteration, and then apply some implementation-changing autofixes, such as replacing `f\"'{x}'\"` with `f\"{x!r}\"`\u2014that could be the second iteration. Having a delivery plan will make `autorefine` create a PR for each iteration, so that you can review the changes and merge them separately.\n\n3. Run `autorefine autopilot` to apply automatic fixes and commit them in reviewable and git-bisectable chunks with meaningful descriptions.\n\n4. Run `autorefine audit` to prevent future regressions.\n\n5. Run `autorefine troubleshoot` to repeatedly call `autorefine audit` within `git bisect` to find out what fix went wrong, and get a detailed description of the problem and suggestions on how to fix it.\n\n6. Manually fix the problems that cannot be fixed automatically. You will find them in the roadmap (`autorefine roadmap`).\n\n7. Run `autorefine finalize` to finalize the current iteration and create a PR with a detailed description of the changes and a link to the roadmap, delivery plan and all commits of the current refactor iteration.\n\n# Non-MVP ideas\n- `autorefine ci` to create a dedicated CI pipeline (which will, by default, run `autorefine analyze` and `autorefine audit` on every PR) for your Git hosting provider (GitHub, GitLab, Bitbucket, etc.),\n- `autorefine template [TEMPLATE_NAME]` to configure Quality Assurance and CI/CD tooling (Ruff, tox, towncrier, Sphinx, etc.) by smart copying what is seen a specified repository (e.g. `autorefine template jaraco/skeleton`+[jaraco.develop](https://github.com/jaraco/jaraco.develop) could be used to copy tox.ini, GitHub Actions etc.)\u2014feature for projects that don't intend to use a skeleton.\n- `autorefine breakdown` to create separate tickets for each fix in the roadmap in your workflow management tool (GitHub Projects, Jira, ClickUp, Asana, Trello, etc.).\n\n# Get inspired\n- https://instagram-engineering.com/static-analysis-at-scale-an-instagram-story-8f498ab71a0c\n\n# Installation\nIf you want to\u2026\n\n\n\n## \u2026use this tool in your project \ud83d\udcbb\nYou might simply install it with [pipx](https://github.com/pypa/pipx#readme):\n\n```shell\npipx install autorefine\n```\n\n## \u2026contribute to [autorefine](https://github.com/bswck/autorefine) \ud83d\ude80\n\n\n> [!Note]\n> If you use Windows, it is highly recommended to complete the installation in the way presented below through [WSL2](https://learn.microsoft.com/en-us/windows/wsl/install).\n\n\n\n1. Fork the [autorefine repository](https://github.com/bswck/autorefine) on GitHub.\n\n1. [Install Poetry](https://python-poetry.org/docs/#installation).<br/>\n Poetry is an amazing tool for managing dependencies & virtual environments, building packages and publishing them.\n You might use [pipx](https://github.com/pypa/pipx#readme) to install it globally (recommended):\n\n ```shell\n pipx install poetry\n ```\n\n <sub>If you encounter any problems, refer to [the official documentation](https://python-poetry.org/docs/#installation) for the most up-to-date installation instructions.</sub>\n\n If you want to use pipx to install dev dependencies as well, install the [poetry apps](https://github.com/bswck/poetry-apps#readme) plugin:\n ```shell\n pipx inject poetry poetry-apps\n ```\n\n Be sure to have Python 3.8 installed\u2014if you use [pyenv](https://github.com/pyenv/pyenv#readme), simply run:\n\n ```shell\n pyenv install 3.8\n ```\n\n1. Clone your fork locally and install dependencies.\n\n ```shell\n git clone https://github.com/your-username/autorefine path/to/autorefine\n cd path/to/autorefine\n poetry env use $(cat .python-version)\n poetry install\n ```\n\n Next up, simply activate the virtual environment and install pre-commit hooks:\n\n ```shell\n poetry shell\n pre-commit install --hook-type pre-commit --hook-type pre-push\n ```\n\nFor more information on how to contribute, check out [CONTRIBUTING.md](https://github.com/bswck/autorefine/blob/HEAD/CONTRIBUTING.md).<br/>\nAlways happy to accept contributions! \u2764\ufe0f\n\n\n# Legal info\n\u00a9 Copyright by Bartosz S\u0142awecki ([@bswck](https://github.com/bswck)).\n<br />This software is licensed under the terms of [GPL-3.0 License](https://github.com/bswck/autorefine/blob/HEAD/LICENSE).\n\n",
"bugtrack_url": null,
"license": "GPL-3.0",
"summary": "Mechanize the refactoring process to operate on a large scale.",
"version": "0.0.1",
"project_urls": {
"Coverage": "https://coverage-badge.samuelcolvin.workers.dev/redirect/bswck/autorefine",
"Distribution": "https://pypi.org/project/autorefine/",
"Documentation": "https://autorefine.readthedocs.io/en/latest/",
"Homepage": "https://github.com/bswck/autorefine",
"Issues": "https://github.com/bswck/autorefine/issues"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c76614b109c7cbc9af19e0c4aa63aa85ed891de355725870a9ed292955e2edff",
"md5": "8d324acf579ab603f7efda7b18e8bfe4",
"sha256": "7b9a3677fde76d549b78bb4fa0e1263ec77c5dc3740b5d9db995ec1ba6899d70"
},
"downloads": -1,
"filename": "autorefine-0.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8d324acf579ab603f7efda7b18e8bfe4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8,<4.0",
"size": 21587,
"upload_time": "2023-12-06T23:24:12",
"upload_time_iso_8601": "2023-12-06T23:24:12.300487Z",
"url": "https://files.pythonhosted.org/packages/c7/66/14b109c7cbc9af19e0c4aa63aa85ed891de355725870a9ed292955e2edff/autorefine-0.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "228f69af6f6df917e7d999c3249d8041452d1c2c6b2aeedaa9b20c2f0abfcc86",
"md5": "214c45469ff0a0baefb29ee69f4cba86",
"sha256": "754fa74014a49bbddc0faaeea07497c0a34b179282d63871699db469f604aeaf"
},
"downloads": -1,
"filename": "autorefine-0.0.1.tar.gz",
"has_sig": false,
"md5_digest": "214c45469ff0a0baefb29ee69f4cba86",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8,<4.0",
"size": 21953,
"upload_time": "2023-12-06T23:24:13",
"upload_time_iso_8601": "2023-12-06T23:24:13.824789Z",
"url": "https://files.pythonhosted.org/packages/22/8f/69af6f6df917e7d999c3249d8041452d1c2c6b2aeedaa9b20c2f0abfcc86/autorefine-0.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-06 23:24:13",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "bswck",
"github_project": "autorefine",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "autorefine"
}
