Web3.py v7 introduced a migration problem that was much more painful than a normal dependency upgrade. It changed middleware architecture, provider names, exception imports, and namespace usage in ways that can easily break production code if migrated mechanically.

I built Web3.py v7 Zero-BS Migrator to automate that upgrade with a hybrid approach: deterministic AST transforms for statically provable changes, and a tightly scoped AI rewrite layer only for middleware patterns that cannot be translated safely with pure syntax rules.

Project links:

• DoraHacks submission: https://dorahacks.io/buidl/43676
• Demo video: https://youtu.be/f2sC1IJPfpc
• GitHub PR: https://github.com/codemod/useful-codemods/pull/29
• Live app: https://web3py-migrator-web.vercel.app/

The problem

The biggest breaking change in Web3.py v7 was the move from functional middleware to class-based middleware. That means many existing codebases cannot be upgraded with simple search-and-replace logic, because middleware often contains custom logic and project-specific behavior.

The migration also includes changes such as WebsocketProviderV2 to WebSocketProvider, .ws to .socket, and updates around exceptions and AttributeDict. Across a real codebase, those changes are repetitive, easy to miss, and expensive to review manually.

The design

I used a two-layer system.

Layer 1: deterministic AST transforms

The first layer uses Tree-Sitter-based AST transforms to handle migration patterns that can be converted deterministically. This covers provider renames, exception import adjustments, AttributeDict changes, and namespace updates like .ws to .socket.

If a transformation can be proven from syntax alone, it should be done with a deterministic rule rather than AI.

Layer 2: scoped AI for middleware migration

The second layer is reserved only for functional middleware, where deterministic translation is not enough. The tool uses a sandboxed NVIDIA NIM Llama-3-70B rewrite applied only to the relevant function node instead of the whole file.

That keeps the AI component constrained to the one area where it adds real value, while safety controls such as context injection, indentation tracking, retry logic, and deprecation handling keep the rewrite usable in practice.

Results

The evaluation numbers were:

• 120-file test suite.
• 142 total patterns found.
• 130 automated.
• 91.5% automation coverage.
• 0 false positives.
• 98.59 evaluation score.

The key lesson is simple: use deterministic transforms wherever possible, and use AI only where the migration is architectural rather than purely syntactic.intent.

If a migration tool can respect that boundary, it can be both fast and trustworthy. That was the goal of Web3.py v7 Zero-BS Migrator.
In practical terms, this means teams upgrading from Web3.py v6 to v7 can automate the bulk of the migration quickly, while still treating custom middleware as a controlled and reviewable rewrite step.

Demo and links

• DoraHacks submission: https://dorahacks.io/buidl/43676
• Demo video: https://youtu.be/f2sC1IJPfpc
• GitHub PR: https://github.com/codemod/useful-codemods/pull/29
• Live app: https://web3py-migrator-web.vercel.app/

Closing note

The main lesson from building this was that migration tooling works best when it separates deterministic code transformation from architectural judgment. Web3.py v7 is a good example of why that distinction matters: some breaking changes are simple rewrites, while others require a deeper understanding of intent. [page:1]

If a migration tool can respect that boundary, it can be both fast and trustworthy. That was the goal of Web3.py v7 Zero-BS Migrator. [page:1]