What the agent does
The formatter crashes before it reads a file: ImportError: cannot import name '_unicodefun' from 'click', raised from patch_click in black/__init__.py. Black releases before 22.3.0 import a private module of click, and click 8.1 removed it. Black's own version was pinned, but click's was not, so the pin kept working until the next clean install pulled a newer click. That is why the failure appears in CI and in freshly created pre-commit environments first, while a developer with an older environment sees nothing.
ternaus/retinaface pins the affected release in two places, which is common and matters for the fix. .pre-commit-config.yaml has the https://github.com/psf/black hook at rev: 21.12b0. requirements_dev.txt begins with black==21.12b0 and has no line for click. The workflow .github/workflows/ci.yml runs pip install -r requirements_dev.txt and then black --check . across a matrix of four Python versions. The agent reads all three, plus the [tool.black] table in pyproject.toml, which sets line-length = 119 and target-version to py36 through py38. In a clean environment, pip install black==21.12b0 brings the current click and any black command fails with the import error. So does the pre-commit hook at that rev.
The agent finds the boundary by installing, not from memory. Black 21.12b0 and 22.1.0 both fail against a current click; 22.3.0 runs. Holding click at 8.0.4 also makes 21.12b0 run, and that is the stopgap some projects use through additional_dependencies on the hook. The agent prefers moving Black, and it moves both pins to the same version so that the hook and the CI job cannot disagree about formatting. It does not run pre-commit autoupdate across the file, because that command moves every hook to its newest tag at once and turns a one-line fix into a review of every tool in the file.
A newer Black formats differently, so the bump comes in two commits. The first changes the two version pins. The second is the output of running Black over the repository with the project's own configuration, and nothing else. From 22.1.0 Black's stable style writes a**b for simple power operands where 21.12b0 left a ** b, and that kind of change touches numeric code in many files. While reading the config the agent also checks whether the other hooks can still be installed. Here the flake8 hook's repository is given as https://gitlab.com/pycqa/flake8, an address that no longer answers an anonymous git ls-remote, so pre-commit would stop there next. The agent reports it and proposes the GitHub address as a separate one-line change.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Running black fails with \"ImportError: cannot import name '_unicodefun' from 'click'\". Find every place the Black version is set: the psf/black rev in .pre-commit-config.yaml, requirements and constraints files, pyproject.toml or setup.cfg extras, tox.ini, Makefiles and CI workflows. Note any place click is pinned. In a clean virtual environment, install the project's dev dependencies as CI does and run the project's black command; keep the traceback. Also run the black pre-commit hook from a fresh pre-commit cache and keep its output. Fix it by raising Black to one version, 22.3.0 or later, in every place it is pinned, so the pre-commit hook and CI use the same release; choose the lowest release that works unless the project's supported Python versions require a newer one, and say which you chose. Do not pin click as the fix and do not run pre-commit autoupdate on other hooks. Commit the version change alone. Then run Black with the project's existing configuration and commit any reformatting as a second commit that contains only formatter output; list the number of files changed and show three representative hunks. Do not hand-edit code to avoid a reformat. Check that every other hook repository in the pre-commit config can still be fetched, and that the Python versions in the CI matrix are ones the chosen Black supports; report problems you find without fixing them, except that a hook repository URL that has moved may be corrected in its own commit. Run the remaining linters and the tests. Open a pull request with the failing output, the passing output, and the list of things you found but left alone.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- 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.
- 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.
- 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 with two commits a reviewer can read separately. The first is small: the rev under the Black hook and the black== line in the dev requirements, both at the same version. The second is mechanical and may be large: files rewritten by the new Black, with no human edits mixed in. The description gives the file count and a few sample hunks so the nature of the changes is clear without scrolling the whole diff.
The description also carries the before and after: the import error from a clean environment, then black --check . passing and the pre-commit hook reporting Passed. Other findings are listed apart from the fix. In a repository like the fixture that list would include a hook repository that cannot be cloned and a CI matrix that still names Python versions GitHub's current runners may not provide.
What the reviewer verifies is that the second commit really is formatter output. The quickest way is to check out the first commit, run Black, and compare. If the team would sooner avoid a reformat today, the first commit can be swapped for a click pin on the hook; the description explains that option and why it only postpones the upgrade.
Run it on every failed lint job
Lint jobs fail on this error for every open pull request at once, since none of them changed anything related. Put the trigger in the workflow: a step after the Black step with if: failure() that searches the log for _unicodefun and sends the request above with your API key. Start it from the default branch, not from each feature branch, so one fix lands and the others rebase on it. A request_id that is a UUID v5 of the repository name and the Black version in the pin makes every failing job that day resolve to the same run.
Without a request_id, each failing job would start its own agent and you would receive several identical pull requests. If the key has a webhook_url, the run.completed event arrives when the pull request is open, and a handler can post its link where the team will see it.
The use case this job follows, with its automation and trigger: Fix a bug from an alert.
Why run it on Rush?
The failure exists only in a new environment. Pre-commit keeps each hook's virtualenv in a cache and reuses it for as long as the rev is unchanged, so people who installed the hook before click 8.1 can commit happily while a new teammate, a new laptop and CI all crash. A Rush sandbox has no pre-commit cache, which makes it the right place to see the error and to confirm that it is gone.
Separating the pin from the reformat takes discipline when you are in a hurry to turn the build green. The agent makes the two commits as a matter of course, runs the other linters and the tests after them, and keeps the full output of each command in the session transcript. The reviewer gets a clean history and the evidence behind it.
Frequently asked questions
Which Black version fixes this?
22.3.0 is the first release that runs with a current click; 21.12b0 and 22.1.0 both raise the import error in a clean install. Any later release also works. The agent picks the lowest working version by default so the reformat stays as small as possible.
Can I pin click instead of upgrading Black?
Yes, as a stopgap. Black 21.12b0 runs with click 8.0.4, and on a pre-commit hook the pin goes in additional_dependencies. It keeps the old formatting, and it leaves you on a pre-release of Black that will meet the next incompatibility.
Will upgrading Black reformat my code?
Probably some of it. Black's stable style changed at 22.1.0; one visible example is a ** b becoming a**b for simple operands. The run puts all such changes in their own commit and reports how many files it touched.
It works on my machine. Why does CI fail?
Your environment was created when click 8.0 was current and has not been rebuilt. CI installs fresh each time and gets the newest click. Running pre-commit clean and then the hook, or creating a new virtualenv, reproduces the CI failure locally.
Should I run pre-commit autoupdate?
It fixes this error and changes every other hook in the file to its newest tag in the same step. That is a larger change with its own failures to sort out. The agent moves only Black and lists the hooks that look out of date, so you can update them deliberately.
More Black jobs
More jobs like this: Fix a bug from an alert
- Fix "ImportError: cannot import name 'url_decode' from 'werkzeug.urls'" with Flask-Login 0.6.2 (Flask-Login)
- Fix "cannot load such file -- net/smtp (LoadError)" on Ruby 3.1 and Later (Ruby)
- Fix "Can't load plugin: sqlalchemy.dialects:postgres" in a Flask App (SQLAlchemy)
- Fix "Error: No such option '-A'" when a Celery worker starts after moving to Celery 5 (Celery)
- Fix "Class constructor MongoStore cannot be invoked without 'new'" After Upgrading connect-mongo (connect-mongo)