What the agent does
The error comes from setuptools 58, which removed the use_2to3 option. A package that set it was written in Python 2 syntax and relied on setuptools to run the 2to3 translator over its source during every install on Python 3. With the option gone, pip install stops with error in <name> setup command: use_2to3 is invalid. before a single file is copied. The agent reads setup.py first. In a client library like embedly/embedly-python, setup() carries use_2to3=True next to test_suite="embedly.tests", a tests_require list that adds unittest2 and mock on old interpreters, and classifiers that stop at Python 3.3. tox.ini lists py26,py27,py32,py33, and .travis.yml runs python setup.py test on the same four.
It reproduces the failure with a current setuptools in a clean virtualenv, then deletes the use_2to3 line. Now the package installs and fails on first import, ImportError: cannot import name 'quote' from 'urllib', raised by from urllib import quote, urlencode at line 11 of embedly/client.py. This is the real job. The translation that used to happen at install time has to be written into the source once, permanently.
To find every such place the agent does not guess. It runs the 2to3 tool that ships with older Python 3 releases over a copy of the tree in report mode and reads the diff. For this package the tool proposes exactly two changes to library code: the import becomes from urllib.parse import quote, urlencode, and the map(lambda url, data: Url(data, method, url), url_or_urls, data) that builds the result list in _get() gets wrapped in list(), because map returns an iterator on Python 3 and callers index the result. The agent applies both, writing the second as a list comprehension. The UserDict import the tool cannot translate is already handled by a try and except in embedly/py3_utils.py. The tool's remaining suggestions delete from __future__ lines and wrap .keys() calls in the tests, and the agent leaves those lines as they are since they run correctly on Python 3 unchanged.
Then it runs the suite, python embedly/tests.py, and sorts the result instead of reporting a bare count. Of 19 tests, 11 pass. The other 8 depend on the live Embedly service: seven call its API with the placeholder key internal, which the API answers with 403, and one asserts that a particular provider is still in the live services list. The agent shows the 403 response and states that those tests cannot pass in any environment without a real key, so they are not evidence for or against the change. It does not mock them into passing.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Installing this package fails with: error in setup command: use_2to3 is invalid. Fix it so the package installs and works on current Python 3 without pinning setuptools below 58. Read setup.py, setup.cfg, pyproject.toml, tox.ini and the CI config and report every Python version they claim. Reproduce the error in a clean virtualenv with the newest setuptools. Remove use_2to3, use_2to3_fixers and use_2to3_exclude_fixers. Then find what the translator used to change: run the 2to3 tool from a Python version that still ships lib2to3 over a copy of the source in report mode, and list each proposed change, separated into library code and tests. Apply by hand the changes the library needs to run on Python 3 and say which proposals you skipped and why. Do not add six or a compatibility layer, and do not keep Python 2 support unless the repository still tests on it; if you drop it, set python_requires and update classifiers to match. Install the package with pip, import every module, and run the test suite. For each failing test, determine whether it fails because of the port or because it needs network access or credentials, and show the evidence; do not mock or delete tests to make the suite pass. Leave test_suite, tests_require and the tox and CI matrices alone except to note that they are out of date. Open a pull request with the install error before, the 2to3 report, and the test results after.",
"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 that changes setup.py and embedly/client.py: the use_2to3 line removed, a python_requires line added with classifiers to match, the urllib.parse import, and the list built eagerly in _get(). The description opens with the install error, includes the 2to3 report as a collapsed block, and lists which of its proposals were applied.
The test section is a table with one row per failing test and the reason: seven that receive a 403 from the API, one that looks for a provider the service list no longer contains. Next to it is the count that passes. A reviewer with a real Embedly key can run the remaining eight by replacing the placeholder and will learn more than the agent could.
The description ends with what is stale and untouched: the tox.ini environment list, the Travis matrix, and test_suite and tests_require, which current setuptools reports as unknown options and ignores. Cleaning those up is a packaging modernisation of its own, and the agent offers it as a follow-up instead of folding it into a fix for an install error.
Run it on every failed workflow run
For a package you maintain, this error first appears as a red CI run when the runner image picks up a newer setuptools. An automation with a github trigger on workflow_run.failure starts a run when that happens, and the event text that follows the saved prompt gives the agent the workflow and commit. The trigger fires only for work by an owner, member or collaborator, and never for runs from forks. Because the prompt is specific to one error, add a line telling the agent to stop without changes when the failed log does not contain use_2to3.
For a dependency you only consume, there is no workflow to watch. Start a run through the API on your fork of the package with the body above, and install from the fork until the fix is released upstream.
The use case this job follows, with its automation and trigger: Fix a bug from an alert.
Why run it on Rush?
The common advice is to pin setuptools<58, which works until some other package in the same environment needs a newer setuptools, and it has to be applied by everyone who installs the package. The durable fix is to do the translation once in the source. That needs two interpreters: a current one to reproduce the error and an older one that still ships 2to3. A sandbox can install both in minutes without disturbing anything, and the agent leaves the report from the tool in the record so the hand edits can be compared with it line for line.
The honest handling of the test suite matters as much as the port. Old client libraries often test against a live service that has changed or now requires credentials. An agent that reports "8 failures" tells the reviewer little, and one that mocks them away tells them something false. The run shows the HTTP response behind each failure, so the pull request can say precisely what was verified.
Frequently asked questions
Can I just pin setuptools below 58?
As a stopgap for installing someone else's package, yes: pip install "setuptools<58" first and build without isolation. For your own package it only moves the problem to your users. The agent is told not to pin and to port the source instead.
Why did this start failing without any change to the package?
pip builds each source distribution with the newest setuptools unless the project says otherwise. When setuptools 58 removed use_2to3, every package still declaring it began to fail at install time on fresh environments, while machines with an old wheel cached kept working.
Will the package still work on Python 2 afterwards?
Only if the port is written to run on both, which usually means a compatibility layer. The prompt has the agent drop Python 2 unless your CI still tests it, and declare that with python_requires so pip on Python 2 keeps resolving to the last compatible release.
How does the agent know it found everything 2to3 used to change?
It runs the same translator over the source and reads its report, so the list of changes comes from the tool that used to make them. It then imports every module and runs the tests. Anything the tool cannot see, such as bytes and text mixed at runtime, shows up there or is listed as untested.