What the agent does
Python 3.12 removed smtpd together with asyncore and asynchat, the modules it was built on. The agent begins by finding out whether the server worked before the removal, because the answer changes the size of the job. billzhong/inbox.py is a 64-line module that wraps the standard library's server so an application can write @inbox.collate above a function and receive mail. Line 3 is import smtpd, line 4 is import asyncore, the class on line 14 subclasses smtpd.SMTPServer, and serve() ends in asyncore.loop(). The agent writes a short driver that starts the inbox on a local port, sends one message with smtplib, and prints what the handler got. It runs that driver on every interpreter it tests.
On Python 3.11 the import succeeds with three deprecation warnings, one per module, and the first of them names the successor: Please see aiosmtpd. Then the message arrives and nothing reaches the handler. The server logs process_message() got an unexpected keyword argument 'mail_options', the channel closes, and the client sees SMTPServerDisconnected. The method on line 21 has the Python 2 signature. On 3.12 and 3.13 the module does not import at all. So the title's error is the newest of three problems, and a fix that only restores the import would hand back a server that accepts connections and drops mail.
The agent tests that claim instead of asserting it. Keeping the old design is possible: ThiefMaster/maildump does it with a copy of CPython 3.11's file under maildump/vendor/smtpd.py and pyasyncore and pyasynchat in its setup.cfg. Tried on the fixture with Python 3.13, a verbatim copy first raises RuntimeError: 'smtpd' was slated for removal after Python 3.12 alpha, from a guard line in the file that the maildump copy has removed. With the guard gone, the mail_options error returns. With **kwargs added to the signature, line 23 fails next, initial_value must be str or None, not bytes, because Parser().parsestr(data) is now handed bytes. Three edits deep, the vendored route still needs the same Python 3 work, plus an unmaintained copy to carry.
So it ports to aiosmtpd, which is about the same amount of code. The InboxServer class becomes a handler object with an async def handle_DATA(self, server, session, envelope) that reads envelope.mail_from, envelope.rcpt_tos and envelope.content, parses the subject, and calls the collator with the same four keyword arguments as before. serve() starts a Controller and blocks until interrupted, so callers and the dispatch() command line behave as they did. The driver on Python 3.13 then prints the recipient list, the sender, the subject hello and a 71-byte body. Three behaviours are stated in the pull request: body is bytes unless the controller is created with decode_data=True, in which case it is a string; a handler that returns 550 no thanks makes the client see that reply as an SMTPDataError; and the collator now runs on the controller's own thread, not the one that called serve().
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "This project fails with \"ModuleNotFoundError: No module named 'smtpd'\" on Python 3.12 and later. Before changing anything, write a driver script that starts the project's SMTP server on a localhost port in a background thread, sends one message with smtplib (From, To, Subject and a one-line body), and prints exactly what the project's message handler received and what the client saw. Run it on Python 3.11, where smtpd still exists, and on 3.12 or newer, and save both outputs including warnings; report whether the server actually delivered the message to the handler on 3.11. Then evaluate two options and show the driver's output for each on the newest Python: keeping the old design with a vendored copy of the standard library's smtpd plus the pyasyncore and pyasynchat packages, and porting to aiosmtpd. Choose the one that leaves the least unmaintained code. Keep the project's public interface unchanged: the same decorator or callback, the same keyword arguments to it, the same blocking serve call and command line. In the pull request state the type of the message body the handler now receives and how to get a string instead, how a handler rejects a message and what the client then sees, and which thread the handler runs on compared with before. Add the driver as a test that binds to an unused port. Update the dependency list and the Python version classifiers to what you ran. Do not open any connection to a real mail server.",
"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 rewrites inbox.py around aiosmtpd's Controller, adds aiosmtpd to requirements.txt and to install_requires in setup.py, removes argparse from that list since it has been in the standard library for a long time, and replaces the Python 2.6 and 2.7 classifiers with the versions the driver ran on. The driver becomes a test. The description has four driver outputs: 3.11 before, showing the dropped message; 3.12 before, showing the import error; the vendored attempt with its three successive errors; and the port on the newest Python with the delivered message.
A reviewer reads the three behaviour notes first, because they are the ways a caller could notice the change: the body's type, the rejection path and the thread. A handler that touched shared state without a lock was safe under the single asyncore loop and may not be now. They also check that the test binds to a free local port and talks to nothing else. If the port cannot keep the public interface intact, the pull request says which part changed and why, and the session is left for review.
Run it on every failed job on a new Python
This error appears the day a base image or a CI matrix moves to Python 3.12. If the tests run in GitHub Actions, give an automation a github trigger on workflow_run.failure, and it starts a run when a workflow fails; the failure event is placed after the saved prompt. Word the prompt so the agent first checks that the failure is the missing module and stops with a short note when it is something else.
For a mail-receiving service already in production, the import error arrives from the process supervisor or an error tracker instead. A handler on your server can forward events whose message contains No module named 'smtpd' to a webhook trigger's URL with the trigger's secret as Authorization: Bearer. Every restart attempt raises the same error, so cap the automation's max runs per hour at a small number.
The use case this job follows, with its automation and trigger: Fix a bug from an alert.
Why run it on Rush?
The question that matters here is whether mail gets through, and answering it takes several interpreters and a server and client talking over a real socket. A Rush run has a sandbox where it can install Python 3.11 and 3.13 side by side, bind local ports, and send the same message through each variant. The printed handler output for every combination is kept with the session, which is how the pull request can show that the old code was already dropping messages on 3.11.
It also keeps a tempting shortcut honest. Vendoring the removed module looks like a five-minute fix and is recommended in many answers to this error. In the sandbox that route is tried for real and its three successive failures are recorded, so the choice of aiosmtpd is argued from what happened and a reviewer who prefers vendoring can see exactly what it would take.
Frequently asked questions
What replaces smtpd in Python 3.12?
The standard library has no replacement. Python 3.11's deprecation warning points to aiosmtpd, an asyncio-based package with a Controller that runs the server and a handler object with a handle_DATA coroutine in place of process_message.
Can I just install a backport and keep my code?
Partly. pyasyncore and pyasynchat bring back the two helper modules, and you can copy smtpd.py from CPython 3.11 after deleting the line that raises on newer versions. Your subclass still has to accept the keyword arguments and bytes payloads that Python 3 passes. You then own a copy of code nobody maintains.
I only used smtpd as a debugging server. Is there a one-liner?
python -m aiosmtpd -n is the usual stand-in for the old python -m smtpd debugging command; by default it prints the messages it receives. The agent changes scripts, Makefiles and documentation that call the old command and checks the new one starts in the sandbox.
Will my handler receive the same arguments?
The port keeps the names your callback already takes. The body's type is the difference to plan for: bytes by default, a string when the controller is created with decode_data=True. The pull request states which one it chose and shows the driver's output.
More jobs like this: Fix a bug from an alert
- Fix "ModuleNotFoundError: No module named 'telnetlib'" on Python 3.13 (telnetlib)
- Fix "Node.js 20 actions are deprecated" Annotations in GitHub Actions Workflows (GitHub Actions)
- Fix "Node Sass does not yet support your current environment" on a current Node release (node-sass)
- Fix "ValueError: 'not' is not a valid parameter name" in a FastAPI App on Python 3.11 or Later (Pydantic)
- Fix "np.alltrue was removed in the NumPy 2.0 release" (NumPy)
- Fix "ValueError: numpy.dtype size changed, may indicate binary incompatibility. Expected 96 from C header, got 88 from PyObject" (NumPy)