What the agent does
WTForms 3.0.0, released in November 2021, removed TextField, an alias of StringField that had been deprecated since the 2.x line. from wtforms import TextField then raises ImportError: cannot import name 'TextField' from 'wtforms', and the whole module that holds the form fails to import, so a Flask app dies at startup rather than on one page. StringField has existed through all of 2.x and 3.x with the same label, validators and data attribute, so the fix is a rename and nothing else.
Tishka17/codephoto, a small Flask service that renders a snippet of code as a photo of a screen, is a clear case. Its requirements.txt lists pygments, pillow, gunicorn, flask, boto3, Flask-WTF and python-telegram-bot with no versions, and its Procfile runs gunicorn app:app. Line 10 of app.py is from wtforms import StringField, TextField, and the form a few lines down is MyForm(FlaskForm) with language = StringField('language') and code = TextField("code", validators=[DataRequired()]). A clean install on Python 3.11 today resolves WTForms 3.3.2, Flask 3.1.3 and Flask-WTF 1.3.0, and python app.py stops at line 10 with the ImportError above, before Flask is even configured.
The agent reproduces that first, then searches the whole repository for the removed names, TextField and the other pre-3.0 aliases, and replaces each with the field it aliased. Here that is two tokens in one file: the import and the code field. The form keeps its validators, and the view that reads form.code.data and form.language.data needs no change because StringField exposes the same attribute. The agent does not pin WTForms<3 to avoid the rename: 2.3.3, the last 2.x release, is from July 2020.
Then it starts the app again, and that is where the page earns its keep. With TextField fixed, python app.py fails on the next line that imports something removed: bot.py line 7, from telegram.ext import Updater, Filters, MessageHandler, CallbackContext, CommandHandler, Dispatcher, raises ImportError: cannot import name 'Filters' from 'telegram.ext' on the python-telegram-bot 22.8 a fresh install resolves. That is a different library and a larger change, so the agent reports it as the next break with the file and line, keeps it out of this pull request, and says so in the description.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "This Flask app fails at startup with \"ImportError: cannot import name 'TextField' from 'wtforms'\" after WTForms was installed fresh. Read the dependency files and report how wtforms and flask-wtf are pinned, then create a clean virtual environment on a current Python, install the dependencies as a new user would, and report the versions that were resolved. Start the app the way the Procfile or README does and save the traceback. Search every .py file for the field aliases WTForms 3 removed (TextField, and any other name that fails to import from wtforms) and list each use with its file and line. Replace each with the current field class (StringField for TextField) and keep the labels and validators as they are. Do not pin wtforms below 3. Start the app again: if it now fails on a different library's removed API, report that traceback with its file and line as a separate finding and do not fix it in this change. If it starts, request the form page with an HTTP client and submit the form once. Open a pull request with the resolved versions, the list of changed fields, and the startup result.",
"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 renames each removed alias to its current field, two tokens in app.py in the fixture above, with a description that lists the WTForms, Flask and Flask-WTF versions a clean install resolved, the traceback before the change, and every TextField found in the repository with its file and line.
What a reviewer checks is that each rename kept the field's label and validators and that nothing else was touched. StringField and TextField share the data attribute the views read, so no view changes, and the description points at the lines that read form.code.data to show it looked.
The description also says how far the app got afterwards. In codephoto's case it reaches bot.py and stops on python-telegram-bot's removed Filters, so the pull request names that file and line as the next change rather than claiming the app starts. A reviewer merges the one-library fix knowing exactly what remains.
Run it on every Monday morning
A requirements file with no versions breaks on an install day, not a commit day. Give the Project an automation with a schedule trigger, for example the cron expression 0 7 * * 1 in your timezone, and a prompt that tells the agent to install the dependencies fresh, import the app the way the Procfile does, and open a pull request only when it fails on a name a new release removed. On a week when nothing broke, the run ends with a one-line answer and no pull request.
For a set of small Flask tools kept by one team, start the request above once per repository from a script with an API key, and read each session's pr_url when its run.completed webhook arrives. Runs past the key's max_concurrent limit are accepted and wait as queued, so the script needs no retry loop.
The use case this job follows, with its automation and trigger: Fix a bug from an alert.
Why run it on Rush?
The rename takes a minute. What takes longer is learning how many more removals stand between a fresh install and a running app, and the only honest way to find out is to install fresh and start it. An agent in a sandbox does that, fixes the one library the report names, and leaves the next traceback in the session and in the pull request, so the team sees the whole distance rather than one step of it.
It also starts from the state a new contributor is in. A laptop that has carried WTForms 2.2 since the app was written never shows this error; a sandbox resolves what pip install Flask-WTF gives today, which is the environment the next person to clone the repository will have.
Frequently asked questions
Is StringField the same as TextField?
Yes. TextField was an alias kept from WTForms 1.x and removed in 3.0.0; StringField takes the same label, validators and keyword arguments and exposes the same data. The rename changes no behaviour.
Can I pin WTForms below 3 instead?
2.3.3, the last 2.x release, still installs and still has TextField, so a pin works for now. It also keeps a form library from 2020 under an app whose other dependencies are current, to avoid a rename. The request above tells the agent not to pin.
Why did the app fail again after the fix?
Because an unpinned requirements file moves every dependency at once. In the fixture the next failure is python-telegram-bot, whose 22.x removed Filters, Updater arguments and Dispatcher that bot.py imports. The agent reports that as a separate finding with the file and line, because it is a different library and a larger change.
Does Flask-WTF itself need a change?
Not for this error. FlaskForm is still the base class on Flask-WTF 1.3.0, and CSRFProtect still works the same way. Only the field names imported from wtforms moved.
Will the agent also rename fields in Jinja templates?
Templates refer to form attributes by name, form.code for instance, not by field class, so they do not change. The agent checks the templates anyway and lists them as read.
More jobs like this: Fix a bug from an alert
- Fix "ImportError: cannot import name 'triu' from 'scipy.linalg'" in Gensim (Gensim)
- Fix "ImportError: cannot import name '_unicodefun' from 'click'" in Black (Black)
- 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)