python-typing-reference

Answers normative Python type system questions using the vendored typing specification.

1|Updated Feb 25, 2026
One-click install
npx skills add https://github.com/cjthompson/claude-code-config --skill python-typing-reference-cjthompson
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: python-typing-reference
Source: https://github.com/cjthompson/claude-code-config/tree/main/plugins/python-development/skills/python-typing-reference
Command: npx skills add https://github.com/cjthompson/claude-code-config --skill python-typing-reference-cjthompson

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Subtle Python typing questions about assignability, variance, protocols, overloads, or TypedDict semantics are easy to answer incorrectly from memory. This Skill grounds answers in the complete vendored typing specification instead of recollection, distinguishing normative rules from individual checker behavior. ## Core Features & Use Cases - Specification-grounded answers: Reads the pinned typing specification files under the vendored typing-spec directory to resolve detailed typing questions. - Topic index navigation: Uses references/topic-index.md to select the smallest relevant specification files covering generics, protocols, narrowing, qualifiers, TypedDict, and more. - Checker-aware reasoning: Distinguishes normative typing rules from a specific checker's implementation or extension, and respects the project's declared Python version. - Use Case: When mypy and pyright disagree on whether a generic protocol is assignable, consult the specification to determine the normative rule and explain which checker deviates. ## Quick Start Ask whether a contravariant generic protocol is assignable to a concrete class under the Python typing specification and cite the relevant rules.

Frequently Asked Questions about python-typing-reference

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I check if a type is assignable in Python's type system?

Assignability rules are defined in the typing specification's concepts and class compatibility sections. Consult the vendored specification files rather than relying on a single checker's behavior, since checkers may implement extensions or deviate from the normative rules.

How does variance work for generic types in Python?

Variance for generics is defined in the generics and class compatibility sections of the typing specification. Type parameters are invariant by default, and covariant or contravariant behavior requires explicit declaration, with protocols following structural variance rules.

Why do mypy and pyright disagree on a typing question?

Checkers can implement extensions, differ in inference strategies, or deviate from the specification. Comparing their behavior against the normative typing specification identifies which checker follows the standard and which applies an implementation-specific rule.

Does the Python typing specification cover TypedDict and protocols?

Yes, the specification includes dedicated sections for TypedDict, protocols, dataclasses, namedtuples, and tuples. Cross-category questions, such as generic protocols, require reading multiple files like generics.rst and protocol.rst together.

When should I consult the typing specification instead of checker docs?

Consult the specification for normative questions about what the type system requires, such as assignability, narrowing, or overload resolution semantics. Checker documentation is appropriate for tool-specific configuration, flags, and implementation extensions.