What the agent does
The error arrives without a code change. A script that worked for years is installed on a new machine, pip resolves an unpinned PyPDF2 to 3.0.1, and the first line that touches a PDF raises PyPDF2.errors.DeprecationError: PdfFileReader is deprecated and was removed in PyPDF2 3.0.0. Use PdfReader instead. The agent reads how the dependency is declared before it reads the code. In a tool like yourcelf/signpdf, which stamps a signature image onto one page of a PDF, requirements.txt lists pypdf2 and reportlab with no versions and setup.py repeats both in install_requires, so every fresh install gets the release that removed the old names.
PyPDF2 3.0.1, published at the end of 2022, is the last release under that name; the project continued as pypdf. Renaming to the 3.x API alone would stop the error and leave the script on a package that receives no fixes, so the agent moves to pypdf in the same change. signpdf.py uses eight old names: PdfFileReader, PdfFileWriter, getNumPages, getPage, cropBox, mediaBox, mergePage and addPage. They become PdfReader, PdfWriter, len(reader.pages), reader.pages[i], cropbox, mediabox, merge_page and add_page. The agent does not take that mapping from memory. It installs PyPDF2 2.12.1, the last line that still runs the old names, and runs the script with warnings enabled: each deprecated call prints its own replacement, and those messages are the list it works from.
The repository has no tests, so the agent builds the evidence. It generates a three-page PDF and a small PNG, then runs the unchanged script under PyPDF2 1.26.0 and the ported script under pypdf, with the same --coords argument. It opens both outputs and compares them page by page: the page count, the text extracted from each page, the media box, and the presence of exactly one image form on the signed page and none on the others. On signpdf those match. It does not compare bytes, because the two libraries write objects in a different order and the files differ in size by a few bytes without differing in content.
Then it writes that comparison down as a test, with pytest and the two generated fixtures, so the next library upgrade has something to run. It updates requirements.txt and install_requires to pypdf, and adds python_requires to match the Python versions the chosen pypdf release supports, since setup.py declares none. It leaves alone what it noticed and was not asked to change, such as the helper that returns a temporary file's name after the file has been closed, and mentions it in the pull request.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "This project fails with 'PdfFileReader is deprecated and was removed in PyPDF2 3.0.0'. Migrate it from PyPDF2 to pypdf. Read every file that declares dependencies (requirements files, setup.py, setup.cfg, pyproject.toml, lock files) and report how PyPDF2 is specified and which version a fresh install resolves to today. List every PyPDF2 name the code uses: classes, methods, properties and exception classes. To get the replacement for each, install the last PyPDF2 2.x release in a scratch environment, run the code with warnings shown, and use the deprecation messages; quote them. Port the code to pypdf, changing imports, class names, method names and property names, and nothing else. If the project has tests, run them before and after. If it has none, generate small input files, run the old code under an old PyPDF2 release that still works and the new code under pypdf, and compare the outputs by content: page count, extracted text per page, page boxes, and whatever the code adds or removes. Do not compare raw bytes. Save both output files as artifacts of this run so a reviewer can open them. Turn that comparison into a pytest test and commit it with its fixtures. Replace PyPDF2 with pypdf in every dependency file, keep the project's pinning style, and set the minimum Python version to what the pypdf release requires if the project declares none or a lower one. List anything else you noticed but did not change. Open a pull request.",
"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 changes the import and ten other lines in signpdf.py, the dependency name in requirements.txt and setup.py, and adds a test file with two small fixtures. The description begins with the original traceback and the version a fresh install resolved to, then a table of old name, new name and the deprecation message that justified each. Below that is the output comparison: one row per page with the values from the old and the new run.
A reviewer looks first for names that were renamed by guess. A property such as cropBox fails only when its line runs, so a call the comparison never reached is unproven, and the description says which lines the generated inputs exercised. They check that both dependency files changed, because pip install signpdf reads setup.py and not requirements.txt. They can open the two output PDFs, which come back as artifacts on the session, and look at the signature placement themselves.
Run it on every script you find while working in your editor
PyPDF2 imports hide in one-file tools across many repositories, and you tend to meet them one at a time while doing something else. Rush's API is also an MCP server at https://api.phoenix.so/mcp. Add it to your MCP client with an API key and the agent in your editor can hand the job over the moment it sees the import: it calls create_session with this prompt and the repository, gets the session back at once, and goes on with what you asked it for.
When you want the result, the same client calls wait_for_sessions, which waits up to 50 seconds per call for a session to settle, and get_session returns the answer and the pull request. A run started this way with an API key is a developer run: it uses Rush's models, billed per token to the member who created the key.
The use case this job follows, with its automation and trigger: Upgrade dependencies weekly.
Why run it on Rush?
Three versions of one library have to be installed side by side to do this properly: the old release that still runs the code, the last 2.x release for its deprecation messages, and pypdf. The run creates those environments in its own sandbox and nothing on your machine changes. Every command and its output is kept in the session transcript, including the warnings the name mapping came from.
The comparison of output files is the proof, and it is the step people skip. Renaming methods until the traceback goes away shows only that the script no longer crashes on the path you tried. Generating inputs, producing a PDF with both libraries and checking them page by page shows the tool still does its job, and the resulting test stays in the repository.
Frequently asked questions
Can I just pin PyPDF2 below 3.0 instead?
It stops the error and is a reasonable stopgap for one deploy. PyPDF2 2.x still runs the old names and prints a warning for each. But no PyPDF2 release has been published since 3.0.1, so a pin keeps you on code that gets no bug or security fixes. The port is mostly renames, and doing it once ends the problem.
Is pypdf a drop-in replacement for PyPDF2 3.x?
For code already using the 3.x names, changing import PyPDF2 to import pypdf covers most of it, since pypdf continued from that codebase. Later pypdf releases removed more deprecated names and raised the minimum Python version, so run your tests after switching. Code still on PdfFileReader needs the renames first.
What replaces getPage, getNumPages and addPage?
reader.pages[i] replaces reader.getPage(i), len(reader.pages) replaces reader.getNumPages() and writer.add_page(page) replaces writer.addPage(page). Page properties moved to lower case, for example mediaBox to mediabox, and mergePage became merge_page. extractText became extract_text.
Will the output PDF be byte-identical?
No, and it does not need to be. Different library versions number and order the objects in the file differently, so sizes and hashes change. What should match is the content: the same pages, text, boxes and added elements. That is what the agent's comparison checks.
What about PyPDF3 or PyPDF4?
Those are separate forks made while PyPDF2 was inactive. The maintained line today is pypdf, which is where the PyPDF2 project itself moved. If a project imports PyPDF3 or PyPDF4, the agent treats it the same way: find the names in use, map them, and compare outputs.
More jobs like this: Upgrade dependencies weekly
- Migrate From python-jose to PyJWT in a FastAPI App (python-jose)
- Migrate From raven to sentry-sdk in a Django App (raven)
- Migrate From React Query v3 to TanStack Query v5 (React Query)
- Migrate a React App From Redux to Redux Toolkit (Redux)
- Replace the Deprecated request Package With Native fetch (request)
- Replace rimraf and mkdirp With fs.rm and fs.mkdir in a Node.js Package (rimraf)