What the agent does
Flask-Script is why many old Flask apps cannot upgrade Flask at all. Its __init__.py runs from flask._compat import text_type, a module Flask removed in 2.0, so import flask_script fails with ModuleNotFoundError: No module named 'flask._compat' on Flask 2.0.0 and on the current 3.1 release alike. The agent starts with manage.py, since that file is the whole surface. In an app like miguelgrinberg/flack it creates Manager(create_app) and registers five commands: a Server subclass named runserver that overrides get_options to offer host, port, debugger and reloader flags and starts the app with socketio.run; a Command subclass that passes its arguments through to celery worker -A flack.celery; and three @manager.command functions, createdb, test and lint. A block at the bottom sets FLACK_CONFIG=testing when the first argument is test or lint.
Recording a baseline comes before the port, and with a repository this old the baseline is the first obstacle. requirements.txt pins 2019 releases, and on a current installer the install stops at anyjson==0.3.3 with error in anyjson setup command: use_2to3 is invalid, on Python 3.11 and on 3.7 alike. The agent builds a Python 3.7 environment with the build tool constrained to setuptools<58, leaves out the gevent, greenlet and uWSGI pins that the management commands do not import, and says so. The rest installs, and it records each command there: createdb creates db.sqlite, runserver --help lists six flags, celery --version prints Celery's version through the passthrough. It also records the oddities, because they are behaviour too. python manage.py with no argument dies with an IndexError at the line that reads sys.argv[1]. lint exits 1 when flake8 is clean and 0 when it reports problems, because the function ends with sys.exit(lint) on a boolean.
The port does not need a newer Flask. Flask 1.1.1, the pinned release, already ships the Click-based CLI, so the agent rewrites manage.py as a Click group built on FlaskGroup and changes no pin. Each command keeps its name. runserver keeps -h, -p, -d, -D, -r and -R. The Celery passthrough becomes a command with ignore_unknown_options and an unprocessed argument list. createdb accepts both --drop-first and the old --drop_first. test and lint are declared with with_appcontext=False and test sets FLACK_CONFIG itself, which replaces the block that inspected sys.argv. One detail is specific to this Flask version. Flask 1.1 hands its ScriptInfo object to a factory that takes exactly one required parameter, and a factory whose first parameter is a config name would then receive an object where a string belongs. This one declares two parameters with defaults, so it is called with none; the agent reads call_factory in the installed Flask to confirm that instead of assuming it.
The check that matters most is not about commands at all. Running any command of the new manage.py logs Flask-SocketIO is Running under Werkzeug, WebSocket is not available. FlaskGroup sets the environment variable FLASK_RUN_FROM_CLI, and Flask-SocketIO 4.2.0 reacts to it by forcing its async mode to threading. Under Flask-Script the same app reports eventlet. A port that stops at matching help text would ship a development server without WebSocket support. The agent sets the async mode explicitly where the SocketIO object is configured, confirms the mode reads eventlet again under the new entry point, and puts both readings in the pull request.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Replace Flask-Script with Flask's built-in Click CLI in this application. Read manage.py, requirements.txt, the application factory, the README and any script that calls manage.py. List every command, its options with short and long names and defaults, and anything manage.py does before or after dispatching (environment variables, monkey patching, exit codes). Install the pinned requirements; if they do not install on a current Python, say which package fails and why, then build the oldest environment that works and say exactly how. Record the output and exit code of every command, of --help for each, and of manage.py with no arguments. Port manage.py to a click group on flask.cli.FlaskGroup without upgrading Flask or any other pin. Keep every command name, option name and exit code, including ones that look wrong; list those instead of fixing them. Check that the application object behaves the same under the new entry point: compare extension state such as the Socket.IO async mode before and after, and fix any difference the CLI introduces. Remove Flask-Script from requirements.txt. Repeat every recorded command on the new manage.py and show both outputs in the pull request. Update README commands only where they changed.",
"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 manage.py, removes the Flask-Script==2.0.5 line from requirements.txt, and adds one argument where the Socket.IO extension is set up. The README keeps its three documented commands, python manage.py createdb, runserver and celery, because they still work as written. The description lists each command with its old and new help text and exit code, the install failure and the environment the agent used instead, and the async mode before and after.
The intended differences are few. Running manage.py with no command now prints the list of five commands and exits 0 instead of raising. Help is Click's format, and -?, which Flask-Script used for help because -h meant host, is gone; --help replaces it. Everything else is meant to be identical.
Two findings are reported and left alone. The inverted exit code of lint is preserved, with a note that any CI job relying on it has been getting the wrong answer. And test fails before and after for a reason outside this job: tests/tests.py still imports a decorator named async from flack.tasks, a name that became a reserved word in Python 3.7 and that the application code has since renamed to async_task. The run shows the same failure on both sides, which is the evidence that the port did not cause it.
Run it on every service whose manage.py imports flask_script
This is a prerequisite job: nothing else about a Flask upgrade can start until it is done, and it is the same in every service that has it. Find the repositories with a search for flask_script and send the body above to POST /o/{org}/sessions once for each, with the repository as the resource and a request_id that is a UUID v5 of its name. Runs beyond the key's max_concurrent are accepted as queued and start when a slot frees.
The use case this job follows, with its automation and trigger: Upgrade dependencies weekly.
Why run it on Rush?
Old Flask apps are hard to work on because their environments no longer build, and that is exactly the part an engineer does not want on a laptop: an end-of-life Python, a pinned build tool, packages that predate wheels. The agent assembles that environment in a sandbox that is discarded with the task, records how it built it, and the same transcript holds every command it ran there.
The Socket.IO finding shows why the run has to execute things. Nothing in the diff of manage.py mentions async modes; the change comes from an environment variable one library sets and another reads. It is found by loading the app both ways and printing a value, which an agent with a working environment does as a matter of course.
Frequently asked questions
Why do I get No module named 'flask._compat'?
Something in your environment imports Flask-Script, and Flask-Script imports a private Flask module that was removed in Flask 2.0. The package's last release still has that import, so pinning a newer Flask-Script does not help. The fix is to stop importing it, which is this migration.
Do I have to upgrade Flask in the same change?
No, and it is better not to. Flask has had a Click command line since long before 2.0, so the port works on the Flask you already pin. The Flask upgrade becomes its own change, now unblocked.
Will python manage.py still work, or do I have to switch to the flask command?
It still works. The agent keeps manage.py as the entry point by ending it with a call to the Click group, so deploy scripts and documentation that call python manage.py createdb do not change.
What happens to custom Command classes with get_options?
Each becomes a function decorated with @click.option for every Option it declared, with the same short and long names and defaults. A command that captured all remaining arguments becomes a Click command that ignores unknown options and takes an unprocessed argument list, so it can still forward flags to another program.
More jobs like this: Upgrade dependencies weekly
- Migrate From garyburd/redigo to gomodule/redigo (Redigo)
- Migrate a Go Test Suite From Ginkgo v1 to Ginkgo v2 (Ginkgo)
- Replace go-bindata With go:embed in a Go Web Server (go-bindata)
- Replace mitchellh/go-homedir With os.UserHomeDir in a Go CLI (go-homedir)
- Replace hashicorp/go-multierror With errors.Join in a Go Project (go-multierror)
- Migrate From go-redis v8 to v9 (github.com/redis/go-redis/v9) (go-redis)