Python: Add reasons to runtime typing suppressions #9629

Maintainer-owned issue. Community contributors: please do not pick up or start implementing this issue.

Category

Repository maintenance

Problem

Runtime source contains many type-checker suppressions without a brief reason explaining the valid runtime contract or checker limitation. Broad ignores make it difficult to distinguish intentional dynamic behavior from hidden type defects.

Evidence

The audit found hundreds of suppression-related matches, with notable concentrations in Core observability, middleware, agents, security, and serialization, plus provider package private-usage suppressions. python/CODING_STANDARD.md now permits targeted # type: ignore[...] in internal code when it is clearer, but requires an inline reason.

Desired Outcome

Add concise reasons to retained suppressions, replace broad ignores with rule-specific forms, and improve annotations, overloads, or Protocols where that removes the suppression without runtime complexity. Prioritize runtime source before tests and samples.

Language

Python

Acknowledgements

• I searched existing issues and did not find a duplicate.
• I will wait for explicit maintainer agreement before starting implementation of a non-trivial change.

Ownership: Core maintainers only; not available for community pickup.