Skip to content

Conversation

@veeceey
Copy link

@veeceey veeceey commented Feb 8, 2026

Summary

This PR improves the googleability of mypy documentation by including actual error messages in the examples. When users encounter mypy errors, they can now more easily find relevant documentation by searching for the exact error message text.

Changes

Made improvements to docs/source/common_issues.rst:

  1. List invariance example (line 309): Changed from "mypy will complain about this, because List is invariant" to the actual error message
  2. Incompatible function argument (line 332): Changed from "# Fails" to the actual error message
  3. Incompatible method override examples (lines 729 and 739): Changed from "# Error" to actual full error messages

Before and After

Before

lst = new_lst  # mypy will complain about this, because List is invariant

After

lst = new_lst  # error: Incompatible types in assignment (expression has type "list[B]", variable has type "list[A]")

Benefits

  1. Better searchability: Users can search for exact error messages and find relevant documentation
  2. Clearer expectations: Users understand what error mypy will actually produce
  3. Easier comparison: Users can compare their errors with documented examples

Rationale

As mentioned in #2393, including actual error messages makes it much easier to Google for common mypy errors and find the relevant documentation. This is especially helpful for new users who may not know which section of the documentation addresses their specific error.

Fixes #2393

This change improves the googleability of mypy documentation by including
actual error messages in the examples. When users encounter mypy errors,
they can now more easily find relevant documentation by searching for the
exact error message text.

Changes made to docs/source/common_issues.rst:
- Added actual error message for list invariance example (line 309)
- Added actual error message for incompatible function argument example (line 332)
- Added actual error message for incompatible method override examples (lines 729 and 739)

Before: Comments like "# Error" or "mypy will complain about this"
After: Full error messages like "# error: Incompatible types in assignment (expression has type ...)"

This makes it easier for users to:
1. Search for error messages and find relevant documentation
2. Understand what error mypy will actually produce
3. Compare their errors with documented examples

Fixes python#2393
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.

Improve googleability by using real error messages in documentation

1 participant