All jobs

Replace flake8 and pycodestyle With Ruff Without Reformatting Your Code

Yes. An agent maps your flake8 and pycodestyle settings to an equivalent Ruff config, replaces them in tox and CI, and opens a pull request that changes no source.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

The agent finds every place the linters run, because in an older library the settings are rarely in one file. In un33k/python-slugify there is no [flake8] section at all: the options live on command lines. tox.ini has a flake8 environment that runs with --ignore=E501,F403,F401,E241,E225,E128 and a pycodestyle environment with --ignore=E128,E261,E225,E501,W605, both excluding legacy_reference.py. .github/workflows/ci.yml and dev.yml install and run the two tools again with their own arguments, main.yml runs tox, and format.sh calls pycodestyle on slugify test.py setup.py. dev.requirements.txt lists pycodestyle and not flake8.

It runs each of those commands as written to get a baseline. With flake8 7.5.0 and pycodestyle 2.15.0, the versions current when this page was written, both tox commands exit 0. format.sh exits 1 with E902 FileNotFoundError: test.py, because the tests moved into tests/ and the script was not updated. Then it finds out what the ignore lists are hiding. With no ignores, pycodestyle reports 232 E501 and 3 E128 and nothing else, so E261, E225, E241 and W605 match no line in the code today.

The mapping to Ruff is not one to one, and the agent shows where. Ruff 0.17.3 has no E128: passing it to --ignore fails with Unknown rule selector. E225 and E241 exist only behind --preview. With --select E,W,F --ignore E501,F401,F403 Ruff is clean, with and without preview. With nothing ignored it reports 138 E501 at its default line length of 88, where pycodestyle counted 232 at 79, plus 8 F401 and 2 F403, all ten in slugify/__init__.py, which re-exports with from .special import *. So the config it writes in pyproject.toml selects E, W and F, ignores E501, puts F401 and F403 in per-file-ignores for __init__.py only, and excludes tools/legacy_reference.py. The dead ignore codes are dropped, and the three continuation-indent findings that E128 was hiding stay hidden because Ruff has no rule for them.

What the agent refuses to do is as important. Run with no configuration, Ruff reports 71 findings from its default rules, 32 of them UP025 in slugify/special.py, and ruff format --check says 14 of the 16 files would be reformatted. Both lists include slugify/_legacy.py and tests/test_legacy.py, which this repository's AGENTS.md declares frozen. So it runs neither --fix nor the formatter, leaves every .py file untouched, and replaces the two tox environments with one ruff environment, the lint steps in ci.yml and dev.yml with ruff check, and the broken format.sh with the same command. The pytest suite, 133 passed and 5 skipped at the time of writing, is run before and after as a check that nothing but configuration moved.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Replace flake8 and pycodestyle with Ruff in this Python library, without changing any Python source. Start by reading AGENTS.md and following it. Then read tox.ini, pyproject.toml, format.sh, dev.requirements.txt and every workflow under .github/workflows, and list each place a linter runs with its exact arguments. Run every one of those commands as written and record the exit code. Run pycodestyle and flake8 again with no ignore list to see which ignored codes still match something. For each code in the old ignore lists, say whether Ruff has the rule, whether it is stable or preview only, and whether it matches any line here. Write a [tool.ruff] section in pyproject.toml that reproduces the old pass or fail result: select the pycodestyle and Pyflakes families, carry over only the ignores that are needed, prefer per-file-ignores to global ones, and keep the same exclusions. Do not enable Ruff's formatter, do not run --fix, and do not enable rule families the old tools never checked; report what those would find as a list for a later change. Replace the flake8 and pycodestyle environments in tox.ini with one ruff environment, update the workflows and format.sh, update dev.requirements.txt, and run tox for the lint environment and pytest. Open a pull request with the output of every command.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
  1. Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
  2. Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
  3. Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

What comes back

A pull request that changes pyproject.toml, tox.ini, format.sh, dev.requirements.txt and two workflow files, and no file under slugify, tests or tools. The description has a table with one row per old ignore code: where it was set, whether Ruff has it, and what it matched. It shows the old commands passing, ruff check passing with the new config, and the pytest summary. A second section lists what was left out on purpose, with counts: the default-rule findings by code and the files the formatter would rewrite.

A reviewer reads the table more than the diff. They confirm that the two star imports are excused only in __init__.py and that F401 is now enforced everywhere else, which is stricter than before and intended. They decide whether the line-length rule should come back at some limit, since E501 was ignored by both old tools and stays ignored. And they check the Ruff version: rule sets move between releases, so the tox environment and the workflows pin the one the agent tested, and Dependabot or a later run can raise it.

Run it on every Python repository still on flake8

The swap is a one-time job per repository. For an org with many Python packages, send this body to POST /o/{org}/sessions once for each repository that still lists flake8 or pycodestyle, with the repository in resources. Add a request_id that is a UUID v5 of the repository name so the batch can be repeated without starting a second run for the same one.

The instruction not to touch source is what makes a batch reviewable: every pull request is configuration only, and a reviewer can approve ten in a sitting. Formatting and the wider rule families are a second pass, per repository, started from the list each first run leaves behind. If the key has a webhook_url, each run posts its result there when it ends.

The use case this job follows, with its automation and trigger: Hand off a long task.

Why run it on Rush?

A faithful linter migration needs the old tools and the new one installed side by side, run with and without each ignore, on the real tree. That is a few dozen commands whose outputs have to be compared, and the agent does it in a sandbox with a fresh virtual environment, where no editor plugin or global config changes what a linter reports. Every command and its output is kept with the run, so each row of the mapping table can be checked against the command that produced it.

The restraint matters as much as the measurements. Ruff makes it easy to fix and format a whole repository in one command, and on a laptop that is the tempting path. An agent given an explicit boundary, here the project's own rule that two files are frozen, reports what the wider change would touch and stops. The result is a pull request small enough to merge the day it arrives.

Frequently asked questions

Can Ruff reproduce my flake8 ignore list exactly?

Usually not code for code. Some pycodestyle checks have no Ruff rule, such as E128, and some are available only in preview, such as E225. The agent tests each code and builds a config that gives the same pass or fail result on your code, then lists the codes that had no equivalent.

Will this reformat my code?

No. The prompt forbids the formatter and --fix, and the pull request contains no Python file. The agent does run ruff format --check to count what formatting would change, and reports that number so you can plan it as a separate change.

Why are F401 and F403 ignored only for __init__.py?

Because that is the only place they occur. The package's __init__.py re-exports names with star imports and unused-looking imports on purpose. The old command lines ignored both codes everywhere; scoping them to one file keeps the re-exports quiet and lets Ruff catch a real unused import anywhere else.

Do I still need pycodestyle if I have Ruff?

Not for the checks Ruff implements, which cover the E and W codes this project had active apart from line length and continuation indent. What you give up are the pycodestyle rules Ruff does not have. Here those matched three lines, all already ignored.

The same job on other stacks

More jobs like this: Hand off a long task

Keep reading