All jobs

Migrate a Python Library from Pydantic v1 to v2

Yes. The agent runs bump-pydantic, finishes the validators and custom types it leaves as TODOs, and checks model behaviour the test suite never covered.

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

What the agent does

The agent begins with an inventory of how the code uses Pydantic, since the codemod handles some patterns and gives up on others. In a client library like vangorra/python_withings_api everything is in withings_api/common.py: 20 models that inherit from one ConfiguredBaseModel, whose inner class Config sets allow_mutation to false; two custom field types, TimeZone and ArrowType, that hook in through __get_validators__; and 19 @validator methods, five of which read earlier fields through a values argument to convert timestamps to the response's timezone. pyproject.toml pins pydantic = "^1.7.2" and python = "^3.6 || ^3.7". When this page was written Pydantic 2.14 required Python 3.10, so the Python range has to move too, and the agent takes its baseline on Python 3.10 with the last 1.x release: 32 tests pass.

It then installs Pydantic 2 with the code untouched, to see what the compatibility layer already carries. The result is 17 failed and 15 passed, and all 17 share a cause: TypeError: ArrowType.validate() takes 2 positional arguments but 3 were given, or the same for TimeZone. Version 2 still calls the old hook but passes it one more argument. Next comes bump-pydantic, which rewrites one file. It turns 14 validators into @field_validator(..., mode="before"), adds = None to 39 Optional fields that relied on the old implicit default, and leaves seven TODO[pydantic] comments: one on each custom type and one on each of the five validators that take values. The suite still reads 17 failed, since the codemod did not touch what was failing.

The seven are hand work. Each custom type gets a __get_pydantic_core_schema__ that wraps its existing validate method in a plain validator function, so the parsing logic is not rewritten. Each of the five validators takes info: ValidationInfo and reads info.data["timezone"], which works for the same reason values did: timezone is declared above the fields that use it. After that, 32 tests pass under -W error, with no deprecation warning left.

A green suite is where a careless migration stops, and here it would ship a regression. The codemod replaced the Config class with model_config = ConfigDict(), empty, and the setting that made every model immutable is gone. No test assigns to a field, so nothing fails. The agent diffs behaviour directly: on version 1 an assignment raises TypeError saying the model is immutable; after the codemod it succeeds. It restores the rule with ConfigDict(frozen=True), adds a test for it, and reports that the exception a caller sees is now a ValidationError. The other two keys in the old Config, ignore_extra and allow_extra, are not settings Pydantic 1 reads; extra fields were ignored before and still are.

Start it with one API call

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

{
  "agent": "claude",
  "input": "Migrate this repository from Pydantic v1 to v2. First inventory the usage: every BaseModel subclass and its Config, custom types that define __get_validators__ or __modify_schema__, every @validator and @root_validator and whether it uses values, pre or always, and every call to .dict(), .json(), .parse_obj(), .copy(), .construct() and __fields__, noting which .json() calls belong to other libraries such as requests. Read the dependency manifest, lockfile and CI config, and read Requires-Python of the newest Pydantic 2; if the project's Python range excludes it, say what must change. Take a baseline on the last Pydantic 1 release and record the test totals. Before changing code, write a short behaviour script for one model that records: whether assigning a field is allowed and which exception it raises, whether an unknown field is accepted, what a missing Optional field becomes, and the output of .dict() and .json(); save its output on v1. Install Pydantic 2 with the code unchanged and record the failures by cause. Run bump-pydantic and list what it changed and every TODO it left. Finish each TODO by hand: custom types through __get_pydantic_core_schema__ reusing the existing parsing function, validators that read other fields through ValidationInfo.data, keeping field order in mind. Compare the Config class before and after the codemod line by line and restore any setting it dropped. Run the behaviour script on v2 and report every difference, including changed exception types; add a test for each behaviour the suite did not cover. The tests must pass under -W error. Update the Pydantic and Python constraints and the CI matrix to match. Open a pull request with the inventory, the three test totals, the behaviour comparison and the list of public behaviour changes.",
  "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 in which the code change is confined to the module that defines the models, plus a new test or two, the dependency constraints and the CI matrix. The description starts with the inventory in numbers, such as 20 models, 19 validators and 2 custom types, and says which the codemod converted and which were finished by hand, so the reviewer knows where a person, or in this case the agent, made choices.

Three test totals follow: Pydantic 1 baseline, Pydantic 2 before any change, and Pydantic 2 after. Then the behaviour comparison, which is the section a maintainer of a published library reads most closely. For a library like the one above it has one row that changed: assigning to a field was a TypeError and is now a ValidationError. Anything that catches the old exception downstream will need to know, and the description says so under a heading for public behaviour changes.

Before merging, the reviewer checks the model_config line against the old Config class, reads the two core-schema methods, and decides how to release it. Requiring Pydantic 2 and a newer Python drops users on the old ones, so the agent proposes a major version bump and leaves the version number alone.

Run it on every library still on Pydantic v1

This migration is done once per repository, when a dependency that needs Pydantic 2 forces it. A developer sends this body to POST /o/{org}/sessions from a terminal or an MCP client with a request_id that is a UUID made for the job. The pull request is on the session when the run completes. If the maintainer wants the old exception type kept, a follow-up to POST /o/{org}/sessions/{id}/messages wakes the same sandbox, with both Pydantic versions still installed.

A team with several services on version 1 sends the body once per repository from a script, each with a request_id that is a UUID v5 of the repository's full name. The key queues what it cannot run at once, and its webhook_url receives run.completed for each run it started. The inventories that come back rank the repositories by hand work: a count of validators that use values and of custom types predicts the effort better than lines of code.

The use case this job follows, with its automation and trigger: Hand off a long task.

Why run it on Rush?

What makes this migration risky is behaviour no test asserts, and finding it means running the same script against two major versions of a library that cannot be installed together. In its own sandbox the agent keeps two environments, runs the script and the suite in each, and compares. Every command and its output is in the transcript at GET /o/{org}/sessions/{id}/messages, so a reviewer can see the assignment succeed after the codemod and fail again after the fix.

It is also a job with a long mechanical middle. Converting validators one at a time, running the suite after each, and reading deprecation warnings until none remain takes a person an afternoon of attention. A run does it without one, and returns the two things that needed judgment, the dropped setting and the changed exception, as written findings.

Frequently asked questions

Does bump-pydantic do the whole migration?

No. It converts the patterns it can prove safe and marks the others with TODO[pydantic] comments. In vangorra/python_withings_api it converted 14 of 19 validators and left the five that use values and both custom types. It also emptied a Config class it could not fully translate, without a comment, which is why the agent compares config before and after.

How do validators read other fields in v2?

Through the second argument, a ValidationInfo, whose data holds the fields validated so far. It replaces the values dictionary from version 1. Order still matters: a field can only see fields declared above it, so the agent checks declaration order for every validator that uses it.

What replaces __get_validators__ on a custom type?

A __get_pydantic_core_schema__ class method that returns a core schema. For a type that already has a parsing function, the smallest change is to wrap that function with core_schema.no_info_plain_validator_function. The parsing code and its error messages stay as they were.

Can the library support both Pydantic versions?

It is possible through the pydantic.v1 namespace that version 2 ships, but then the models stay version 1 models and gain nothing. The agent migrates fully by default and reports the Python and Pydantic floor that results. Ask for the dual-support path in the prompt if your users need it.

More Pydantic jobs

More jobs like this: Hand off a long task

Keep reading