Skip to content

docs: document exception hierarchy - #3870

Open
Boulea7 wants to merge 1 commit into
ApeWorX:mainfrom
Boulea7:docs-exception-hierarchy-3442
Open

docs: document exception hierarchy#3870
Boulea7 wants to merge 1 commit into
ApeWorX:mainfrom
Boulea7:docs-exception-hierarchy-3442

Conversation

@Boulea7

@Boulea7 Boulea7 commented Aug 11, 2026

Copy link
Copy Markdown

What was wrong?

The exception hierarchy and JSON-RPC error fallback behavior were only described in migration notes, making it difficult for users to choose the right exception boundary.

Related to Issue #3442
Closes #3442

How was it fixed?

  • Add a focused guide for the Web3Exception hierarchy and common branches.
  • Explain method-specific error formatters, Web3RPCError specialization, and message-based fallback behavior.
  • Link the guide from the documentation table of contents.
  • Add a documentation newsfragment.

Validation

  • make check-docs (HTML build, 205 doctests, newsfragment validation)
  • Strict targeted Sphinx build with nitpicky warnings treated as errors
  • Targeted pre-commit checks, including the repository-wide mypy hook

Todo:

  • Clean up commit history
  • Add or update documentation related to these changes
  • Add entry to the release notes

Cute Animal Picture

A curious cat

@Boulea7
Boulea7 marked this pull request as ready for review August 11, 2026 21:06
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Document web3.py exceptions and hierarchy at a high level

1 participant