All jobs

Migrate From Flask-RESTPlus to Flask-RESTX

Yes. An agent renames the imports, fixes the settings Flask-RESTX silently ignores, calls every endpoint to prove validation still works, and opens a pull request.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

Flask-RESTPlus is no longer maintained, and Flask-RESTX is the fork that kept its API. The import rename is the part everyone expects. The agent starts earlier, by finding out whether the project still installs at all. In an API like postrational/rest_api_demo, requirements.txt pins flask-restplus==0.9.2, Flask-SQLAlchemy==2.1 and Werkzeug==0.16.1, the last one being the usual workaround for Flask-RESTPlus failing to import on Werkzeug 1.0. On Python 3.11 those pins resolve to Flask 1.1 and Jinja2 2.11 with an unpinned MarkupSafe, and importing the app stops with ImportError: cannot import name 'soft_unicode' from 'markupsafe'. So there is no working baseline to compare against, and the agent says so instead of pretending one exists.

It then changes flask_restplus to flask_restx in the five files that import it (api/restplus.py, the two endpoint modules, serializers.py and parsers.py), replaces the three pins with flask-restx and a current Flask-SQLAlchemy, and updates install_requires in setup.py to match. Api, Resource, fields, reqparse, api.model, api.inherit, @api.expect and @api.marshal_with keep their names, so the app imports and /api/swagger.json answers 200. A migration that stops here looks finished.

The repository has no tests, so the agent writes a short script with Flask's test client that creates a category and a post and then calls each route, including the failure cases. Two things show up. Listing posts returns 500, because posts.py calls posts_query.paginate(page, per_page, error_out=False) in two places and Flask-SQLAlchemy 3 accepts those arguments by keyword only. And a POST to /api/blog/posts/ with no title is no longer rejected: app.py sets RESTPLUS_VALIDATE and RESTPLUS_MASK_SWAGGER, Flask-RESTX reads RESTX_VALIDATE and RESTX_MASK_SWAGGER, and an unknown config key raises nothing. The invalid body reaches create_blog_post and fails later with a 404 from the NoResultFound handler.

The agent renames both keys, moves ERROR_404_HELP to RESTX_ERROR_404_HELP (the old name still works but warns), and passes page= and per_page= by keyword. It reruns the script and checks that the missing-title request now answers 400 with 'title' is a required property. It leaves the module name api/restplus.py and the RESTPLUS_ names in settings.py alone unless asked, since those are the project's own identifiers, and lists them in the pull request as optional cleanup.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Migrate this project from Flask-RESTPlus to Flask-RESTX. First try a fresh install of the current pinned requirements on the Python version the project targets and import the app; report whether it still works, with the exact error if not. Then replace flask_restplus imports with flask_restx, replace the flask-restplus pin with flask-restx in every manifest (requirements files, setup.py, pyproject.toml), and remove pins that existed only to keep Flask-RESTPlus importable, such as an old Werkzeug. Search the code and config for every RESTPLUS_ setting and for ERROR_404_HELP, and rename each to the key Flask-RESTX reads (RESTX_VALIDATE, RESTX_MASK_SWAGGER, RESTX_MASK_HEADER, RESTX_JSON, RESTX_ERROR_404_HELP); list any setting you could not map. If upgrading pulled in newer majors of Flask, Werkzeug or Flask-SQLAlchemy, fix what they break and name each fix separately. Run the test suite if there is one. If there is none, write a script using the Flask test client that calls every route once with valid input and once with invalid input, and confirm that request validation still rejects a body missing a required field, that marshalled responses keep their fields, and that swagger.json is served. Do not rename the project's own modules or constants. Open a pull request that lists the renamed settings, the fixes caused by other upgraded packages, and the output of the route checks.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
  1. 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.
  2. 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.
  3. 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 small diff and a description that carries the weight. For rest_api_demo the code change is five import lines, three config keys in app.py, two paginate calls, and the pins in requirements.txt and setup.py. The description separates three kinds of change: the rename, the settings Flask-RESTX would have ignored, and the fixes that belong to Flask-SQLAlchemy 3 and not to this migration at all.

It also includes the route check as a table: each route, the input, the status before the settings fix and after. The row a reviewer should read first is the invalid POST, because it is the one that a rename-only migration gets wrong without any error. If the project had no working baseline, the description states that the comparison is against the documented behaviour, not against a run of the old code.

Before merging, the reviewer decides whether to keep the unpinned versions the agent chose or pin them, and whether the new check script should stay in the repository as a first test.

Run it on every GitHub issue labelled flask-restx

Teams with several small Flask services usually move them one at a time. Open a tracking issue in each repository, then add an automation to that repository's Project with a github trigger on issues.labeled and the labels filter set to flask-restx, and save the prompt above. Only a label applied by an owner, member or collaborator of the repository fires the trigger. The issue text is placed after the saved prompt as event data, so it can carry notes the prompt cannot know, such as which clients depend on the exact shape of validation errors.

If you would rather start the batch from a script, send one POST /o/{org}/sessions per repository with the body above and a request_id that is a UUID v5 of the repository name, so running the script twice starts nothing twice.

The use case this job follows, with its automation and trigger: Upgrade dependencies weekly.

Why run it on Rush?

The dangerous part of this migration produces no error. A config key that the new library does not read is still a valid config key, the app starts, the Swagger page renders, and request validation is off. Finding that takes sending a bad request and looking at the answer, which is a step people skip when the diff is five import lines. The agent sends it, in a sandbox with a fresh install of current packages, and the request and response are kept in the session transcript.

A fresh install is also the honest environment for this job. A developer's virtualenv for an old Flask-RESTPlus project often still works only because it was created years ago. The sandbox starts empty, so the pull request describes what a new clone or a rebuilt image will meet, including the unrelated breakages from Flask-SQLAlchemy that arrive with the same upgrade.

Frequently asked questions

Is Flask-RESTX a drop-in replacement for Flask-RESTPlus?

For the Python API, nearly: the classes and decorators keep their names, so changing flask_restplus to flask_restx is usually enough to import. The configuration is not drop-in. Settings prefixed RESTPLUS_ are ignored, so validation and field masks can change behaviour with no error.

Which settings do I have to rename?

RESTPLUS_VALIDATE, RESTPLUS_MASK_SWAGGER, RESTPLUS_MASK_HEADER and RESTPLUS_JSON become the same names with a RESTX_ prefix. ERROR_404_HELP becomes RESTX_ERROR_404_HELP; the old name is still read, with a deprecation warning. SWAGGER_UI_DOC_EXPANSION is unchanged.

Why does my old project fail with an ImportError before I change anything?

Old Flask-RESTPlus releases only run on old Flask and Werkzeug, and those in turn depend on packages they did not pin. A fresh install picks a current MarkupSafe that no longer has soft_unicode, or a Werkzeug without cached_property at the top level. Moving to Flask-RESTX lets you drop the old pins instead of adding more.

Will my Swagger documentation change?

The generated swagger.json keeps the same paths, models and namespaces. The agent fetches it after the migration and reports differences if the project had a working baseline to compare with. The mask header parameter appears or disappears depending on RESTX_MASK_SWAGGER, which is one more reason to rename that key.

Does the agent upgrade Flask and SQLAlchemy too?

Only as far as the new pins require. Removing an old Werkzeug pin usually brings in current Flask and Flask-SQLAlchemy, and the agent fixes what breaks, such as positional arguments to paginate. Each of those fixes is listed apart from the Flask-RESTX changes so you can see which upgrade caused it.

More jobs like this: Upgrade dependencies weekly

Keep reading