What the agent does
Python 3.12 removed asyncore and asynchat from the standard library, so any module that imports them at the top now fails before a single line of its own code runs. seb-m/pyinotify is a clear case. Its setup.py (version 0.9.6) picks one of two source trees by interpreter, python2/ or python3/, and ships a single module, pyinotify.py. Line 71 of python3/pyinotify.py is import asyncore. The package installs on 3.12 without complaint, because nothing in the build imports the module, and then import pyinotify raises the error in the title for every user, including the ones who never touch asyncore.
The agent starts by measuring how much of the file depends on the import. In 2,365 lines, one class does: AsyncNotifier, which inherits from asyncore.file_dispatcher and whose __init__ hands the inotify file descriptor to it. The other four notifiers (Notifier, ThreadedNotifier, TornadoAsyncNotifier and AsyncioNotifier) never reference it, and AsyncioNotifier already does the same job on the event loop with loop.add_reader(self._fd, self.handle_read). So the smallest correct change is to wrap the import in try/except ImportError, define AsyncNotifier only when the module is present, and leave everything else alone. On 3.11 and older nothing changes. On 3.12 the module imports again and the one asyncore class is absent.
It then weighs the alternative and writes both down. The pyasyncore package on PyPI restores an importable asyncore on 3.12, and declaring it as a dependency for python_version >= "3.12" keeps AsyncNotifier available to callers who still use asyncore.loop(). That is the right choice when your own code subclasses dispatchers throughout. For a library with one optional adapter and a working asyncio equivalent, the guard is less to carry. The agent picks by counting your call sites, and says which it chose and why.
pyinotify has no tests to lean on: .travis.yml lists Python 2.6 through 3.4 and its script line is /bin/true. So the agent writes a small smoke test before calling anything fixed. It creates a WatchManager, watches a temporary directory for IN_CREATE and IN_DELETE, creates and removes a file, and asserts that both events arrive through a plain Notifier and through AsyncioNotifier. It runs that on an interpreter older than 3.12 and on 3.12, installing whichever one the sandbox lacks, and updates the classifiers in setup.py, which stop at 3.4.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "This project fails on Python 3.12 with \"ModuleNotFoundError: No module named 'asyncore'\" (or 'asynchat'). Reproduce it first: install the package into a clean Python 3.12 environment and import it, and record the traceback. Then list every import of asyncore, asynchat and smtpd in the source, tests, examples and docs, and for each one say what depends on it: which classes inherit from a dispatcher, which code calls asyncore.loop(), and whether that code is core to the package or an optional adapter. Choose the smallest fix that keeps existing users working. If only an optional class needs asyncore, guard the import and define that class only when the module is available. If the package depends on it throughout, either add the pyasyncore backport as a dependency for Python 3.12 and later, or port the code to asyncio, and explain the choice. Do not change behaviour on Python versions that still have the module. If the project has no test that exercises the affected code, write a small one that runs without network access. Run the tests on a Python older than 3.12 and on 3.12, and include both outputs. Update the supported-version metadata to match what you tested. Open a pull request that lists anything a caller can no longer import on 3.12.",
"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 a short diff. In a package shaped like pyinotify it touches one source file, where the import gains a guard and one class moves under a condition, adds one test file, and edits the classifiers in setup.py. The description opens with the traceback from a clean 3.12 environment, so the reviewer sees the failure the change answers, and follows with the smoke test's output on both interpreters.
It also states the cost in plain terms. With the guard, pyinotify.AsyncNotifier does not exist on 3.12, and code that names it gets an AttributeError at the point of use instead of every user getting an import error at startup. The description names AsyncioNotifier as the replacement and shows the few lines that differ for a caller. If the agent chose the backport instead, the description shows the new dependency line and its version marker.
The reviewer checks two things before merging: that the guarded class really is the only user of the module, which the import list in the description makes easy to confirm with a search, and that the new test fails on 3.12 when the guard is reverted. A test that passes either way proves nothing about this bug.
Run it on every failed workflow run
This error tends to arrive overnight, when a CI image or a container base moves to Python 3.12 and a job that passed yesterday stops at an import. Add an automation on the repository's Project with the prompt above and a github trigger on workflow_run.failure. The failed run is added after the prompt as event text, so the agent can see which workflow and branch broke. The prompt remains the only instruction: when the failure is something else, the agent reports what it found and opens no pull request.
If the traceback reaches you through an error tracker instead, use a webhook trigger. Most trackers sign their own deliveries and cannot send the Authorization: Bearer header the trigger requires, so a small handler on your server receives the tracker's webhook, checks its signature and forwards the body to the trigger's URL with the secret. The automation's max runs per hour caps how many runs a burst of identical errors can start.
The use case this job follows, with its automation and trigger: Fix a bug from an alert.
Why run it on Rush?
Reproducing this honestly takes a clean interpreter. A laptop that has carried the same virtual environment across upgrades may already have pyasyncore installed as a dependency of something else, and then the import works locally while it fails for every new user. The sandbox starts with nothing installed, so the import the agent runs is the one a fresh install gets, and the traceback and each later command stay in the session next to the pull request.
The fix also needs two interpreters side by side, one that still has the module and one that does not, with the same test run on each. Setting that up is routine work an agent does without being asked twice, and it is exactly the step that gets skipped when the change looks like three lines. Running it on Rush means the evidence that old versions still behave the same is attached to the result, not asserted in a comment.
Frequently asked questions
Why does the package install on 3.12 but fail on import?
Installing copies files and does not execute your module. In pyinotify, setup.py never imports pyinotify.py, so the build succeeds on any version. The first import pyinotify executes line 71, and that is where the missing module surfaces.
Is installing pyasyncore enough?
It makes the import work, and for an application you control it is a reasonable stopgap. For a library it has to be declared as a dependency with a version marker, or your users hit the same error. The backport is the removed standard-library code published as a package, and it will not gain features, so new code should target asyncio.
Will the agent rewrite my asyncore server in asyncio?
Only when the prompt's conditions call for it and it can test the result. A dispatcher subclass with handle_read and handle_write maps onto an asyncio protocol, but buffering and connection lifetime differ, and a port without tests is a guess. The agent says how much code depends on the module and proposes a port as a follow-up when a guard or the backport fixes today's failure.
Does this also cover asynchat and smtpd?
Yes. All three were removed in the same release, and the prompt asks for every import of each. asynchat is covered by a separate backport package, and smtpd users usually move to aiosmtpd, which the agent notes where it finds one.
More jobs like this: Fix a bug from an alert
- Fix "ModuleNotFoundError: No module named 'audioop'" on Python 3.13 (audioop)
- Fix "ModuleNotFoundError: No module named 'cgi'" on Python 3.13 (Python)
- Fix "ModuleNotFoundError: No module named 'crypt'" on Python 3.13 (crypt)
- Fix "ModuleNotFoundError: No module named 'dash_core_components'" (Dash)
- Fix "ModuleNotFoundError: No module named 'fabric.api'" by Porting a fabfile to Fabric 3 (Fabric)
- Fix "ModuleNotFoundError: No module named 'imghdr'" on Python 3.13 (imghdr)