Mypy

作者 bobmatnyc718070a7d622MIT77 個星標收錄於 2026年10月8日更新於 2026年10月8日儲存庫2 個月前更新

mypy - Static type checker for Python with gradual typing, strict mode, Protocol support, and framework integration

僅含說明Software Development
AI 產生的概覽

使用 Python 靜態型別檢查器 mypy 的參考指南，涵蓋型別提示、設定與框架整合。

功能
這個技能是 mypy（Python 靜態型別檢查器）的使用參考。它說明型別標註基礎（變數、函式、集合、類別）、進階型別用法（Literal、TypeVar、泛型、Protocol、Callable），以及如何透過 mypy.ini、pyproject.toml 與嚴格模式設定 mypy。它也介紹漸進式導入策略、第三方套件的型別存根，以及 FastAPI 與 Django 的型別化寫法。它產出的是指引與程式碼範例，本身並不執行檢查。
適用情境
適用於為 Python 專案加入型別提示或型別安全，或逐步在既有程式庫中導入 mypy 的情境。也適合設定嚴格檢查、處理缺少的型別存根，或為 FastAPI 與 Django 程式碼加上型別。
執行需求
需要透過 pip 安裝 mypy，可選安裝型別存根套件（例如 types-requests、types-PyYAML、types-redis 或 django-stubs），整合範例還涉及 pydantic、django-stubs 等框架套件。不含指令稿，僅為說明性內容。

mypy - Static Type Checking for Python

Overview

mypy is the standard static type checker for Python, enabling gradual typing with type hints (PEP 484) and comprehensive type safety. It catches type errors before runtime, improves code documentation, and enhances IDE support while maintaining Python's dynamic nature through incremental adoption.

Key Features:

  • Gradual typing: Add types incrementally to existing code
  • Strict mode: Maximum type safety with --strict flag
  • Type inference: Automatically infer types from context
  • Protocol support: Structural typing (duck typing with types)
  • Generic types: TypeVar, Generic, and advanced type patterns
  • Framework integration: FastAPI, Django, Pydantic compatibility
  • Plugin system: Extend type checking for libraries
  • Incremental checking: Fast type checking on large codebases

Installation:

bash
# Basic mypypip install mypy
# With common type stubspip install mypy types-requests types-PyYAML types-redis
# For FastAPI projectspip install mypy pydantic
# For Django projectspip install mypy django-stubs
# Development setuppip install mypy pre-commit

Type Annotation Basics

1. Variable Type Hints

python
# Basic typesname: str = "Alice"age: int = 30height: float = 5.9is_active: bool = True
# Type inference (mypy infers types)count = 10  # mypy infers: intmessage = "Hello"  # mypy infers: str
# Multiple types with Unionfrom typing import Union
user_id: Union[int, str] = 123  # Can be int OR strresult: Union[int, None] = None  # Nullable int
# Optional (shorthand for Union[T, None])from typing import Optional
user_email: Optional[str] = None  # Can be str or None

2. Function Type Hints

python
# Basic function typingdef greet(name: str) -> str:    return f"Hello, {name}"
# Multiple parametersdef add(a: int, b: int) -> int:    return a + b
# Optional parameters with defaultsdef create_user(name: str, age: int = 18) -> dict:    return {"name": name, "age": age}
# No return valuedef log_message(message: str) -> None:    print(message)
# Functions that never returnfrom typing import NoReturn
def raise_error() -> NoReturn:    raise ValueError("Always raises")

3. Collection Type Hints

python
from typing import List, Dict, Set, Tuple
# List with element typenumbers: List[int] = [1, 2, 3, 4]names: List[str] = ["Alice", "Bob", "Charlie"]
# Dict with key and value typesuser_ages: Dict[str, int] = {"Alice": 30, "Bob": 25}config: Dict[str, Union[str, int]] = {"host": "localhost", "port": 8000}
# Set with element typeunique_ids: Set[int] = {1, 2, 3}
# Tuple with fixed typescoordinate: Tuple[float, float] = (10.5, 20.3)user_record: Tuple[int, str, bool] = (1, "Alice", True)
# Variable-length tuplenumbers: Tuple[int, ...] = (1, 2, 3, 4, 5)
# Modern syntax (Python 3.9+)numbers: list[int] = [1, 2, 3]user_ages: dict[str, int] = {"Alice": 30}

4. Class Type Hints

python
class User:    # Class attributes    name: str    age: int    email: Optional[str]
    def __init__(self, name: str, age: int, email: Optional[str] = None) -> None:        self.name = name        self.age = age        self.email = email
    def get_info(self) -> Dict[str, Union[str, int]]:        return {            "name": self.name,            "age": self.age,            "email": self.email or "N/A"        }
    @classmethod    def from_dict(cls, data: Dict[str, any]) -> "User":        return cls(            name=data["name"],            age=data["age"],            email=data.get("email")        )

Advanced Type Hints

1. Literal Types

python
from typing import Literal
# Restrict to specific valuesdef set_log_level(level: Literal["debug", "info", "warning", "error"]) -> None:    print(f"Log level: {level}")
# Validset_log_level("debug")set_log_level("error")
# Type error: Argument 1 has incompatible type "verbose"set_log_level("verbose")
# Multiple literalsStatus = Literal["pending", "approved", "rejected"]
def update_status(status: Status) -> None:    pass

2. Type Aliases

python
from typing import Dict, List, Union
# Simple aliasUserId = intUserName = str
def get_user(user_id: UserId) -> UserName:    return f"User {user_id}"
# Complex aliasesJSON = Union[Dict[str, "JSON"], List["JSON"], str, int, float, bool, None]Headers = Dict[str, str]QueryParams = Dict[str, Union[str, int, List[str]]]
def make_request(    url: str,    headers: Headers,    params: QueryParams) -> JSON:    pass
# NewType for distinct typesfrom typing import NewType
UserId = NewType("UserId", int)ProductId = NewType("ProductId", int)
def get_user(user_id: UserId) -> str:    return f"User {user_id}"
user = UserId(123)  # Validproduct = ProductId(456)
get_user(user)  # Validget_user(product)  # Type error: ProductId not compatible with UserId

3. Generics and TypeVar

python
from typing import TypeVar, Generic, List
# TypeVar for generic functionsT = TypeVar("T")
def first_element(items: List[T]) -> T:    return items[0]
# Type inferencenum = first_element([1, 2, 3])  # mypy infers: intname = first_element(["Alice", "Bob"])  # mypy infers: str
# Bounded TypeVarfrom typing import Union
NumericType = TypeVar("NumericType", int, float)
def add_numbers(a: NumericType, b: NumericType) -> NumericType:    return a + b
# Generic classesclass Stack(Generic[T]):    def __init__(self) -> None:        self._items: List[T] = []
    def push(self, item: T) -> None:        self._items.append(item)
    def pop(self) -> T:        return self._items.pop()
    def is_empty(self) -> bool:        return len(self._items) == 0
# Usage with type inferenceint_stack: Stack[int] = Stack()int_stack.push(42)int_stack.push("hello")  # Type error: Expected int, got str
str_stack: Stack[str] = Stack()str_stack.push("hello")  # Valid

4. Protocol (Structural Typing)

python
from typing import Protocol
# Define protocol (interface)class Drawable(Protocol):    def draw(self) -> str:        ...
# Any class with draw() method matchesclass Circle:    def draw(self) -> str:        return "Drawing circle"
class Square:    def draw(self) -> str:        return "Drawing square"
# Function accepts any Drawabledef render(obj: Drawable) -> str:    return obj.draw()
# Both work (duck typing with types)circle = Circle()square = Square()render(circle)  # Validrender(square)  # Valid
# Runtime checkable protocolsfrom typing import runtime_checkable
@runtime_checkableclass Closeable(Protocol):    def close(self) -> None:        ...
class File:    def close(self) -> None:        pass
# Runtime checkf = File()isinstance(f, Closeable)  # True

5. Callable Types

python
from typing import Callable
# Function that takes another functiondef apply_twice(func: Callable[[int], int], value: int) -> int:    return func(func(value))
def double(x: int) -> int:    return x * 2
result = apply_twice(double, 5)  # Returns 20
# Generic callablefrom typing import TypeVar
T = TypeVar("T")R = TypeVar("R")
def map_values(    func: Callable[[T], R],    values: List[T]) -> List[R]:    return [func(v) for v in values]
# Callable with multiple argumentsValidator = Callable[[str, int], bool]
def validate_user(name: str, age: int) -> bool:    return len(name) > 0 and age >= 0
validator: Validator = validate_user

mypy Configuration

1. mypy.ini Configuration

ini
# mypy.ini[mypy]# Python versionpython_version = 3.11
# Import discoveryfiles = src,testsexclude = build,dist,venv
# Type checking strictnessdisallow_untyped_defs = Truedisallow_any_unimported = Falseno_implicit_optional = Truewarn_return_any = Truewarn_unused_ignores = Truewarn_redundant_casts = True
# Error reportingshow_error_codes = Trueshow_column_numbers = Truepretty = True
# Incremental type checkingincremental = Truecache_dir = .mypy_cache
# Per-module configuration[mypy-tests.*]disallow_untyped_defs = False
[mypy-migrations.*]ignore_errors = True
# Third-party libraries without stubs[mypy-redis.*]ignore_missing_imports = True
[mypy-celery.*]ignore_missing_imports = True

2. pyproject.toml Configuration

toml
# pyproject.toml[tool.mypy]python_version = "3.11"files = ["src", "tests"]exclude = ["build", "dist", "venv"]
# Strictnessdisallow_untyped_defs = truedisallow_any_unimported = falseno_implicit_optional = truewarn_return_any = truewarn_unused_ignores = truewarn_redundant_casts = truestrict_equality = truestrict_concatenate = true
# Error reportingshow_error_codes = trueshow_column_numbers = truepretty = truecolor_output = true
# Incrementalincremental = truecache_dir = ".mypy_cache"
# Per-module overrides[[tool.mypy.overrides]]module = "tests.*"disallow_untyped_defs = false
[[tool.mypy.overrides]]module = ["redis.*", "celery.*"]ignore_missing_imports = true

3. Strict Mode

bash
# Enable all strict checksmypy --strict src/
# Strict mode equivalent flagsmypy \  --disallow-any-unimported \  --disallow-any-expr \  --disallow-any-decorated \  --disallow-any-explicit \  --disallow-any-generics \  --disallow-subclassing-any \  --disallow-untyped-calls \  --disallow-untyped-defs \  --disallow-incomplete-defs \  --check-untyped-defs \  --disallow-untyped-decorators \  --no-implicit-optional \  --warn-redundant-casts \  --warn-unused-ignores \  --warn-return-any \  --warn-unreachable \  --strict-equality \  src/
ini
# mypy.ini strict configuration[mypy]strict = True
# Relax specific checks if neededdisallow_any_expr = False  # Too strict for most projectsdisallow_any_explicit = False  # Allow explicit Any

Incremental Adoption Strategies

1. Start with Entry Points

python
# Start typing from main.py (top-level)# main.pyfrom typing import Optionalfrom app.services import UserService
def main(config_path: Optional[str] = None) -> None:    """Application entry point."""    service = UserService()    service.run()
if __name__ == "__main__":    main()
bash
# Check only main.py initiallymypy main.py
# Gradually expand scopemypy main.py app/services.pymypy src/

2. Per-Module Strict Mode

ini
# mypy.ini - Gradually enable strict checking[mypy]# Lenient global defaultsignore_missing_imports = Truedisallow_untyped_defs = False
# Strict for new modules[mypy-app.services.user_service]disallow_untyped_defs = Truewarn_return_any = True
[mypy-app.api.*]disallow_untyped_defs = Trueno_implicit_optional = True
# Still lenient for legacy code[mypy-app.legacy.*]ignore_errors = True

3. Use # type: ignore Strategically

python
# Suppress specific errors during migrationimport legacy_module  # type: ignore[import]
def process_data(data):  # type: ignore[no-untyped-def]    # TODO: Add type hints    return data.transform()
# Ignore specific error codesuser_dict = get_user_dict()user_id = user_dict["id"]  # type: ignore[index]
# Ignore entire line (use sparingly)result = external_api.call()  # type: ignore

4. Reveal Types During Development

python
from typing import reveal_type
def process_user(user_id: int):    user = get_user(user_id)    reveal_type(user)  # mypy will show inferred type
    name = user.name    reveal_type(name)  # mypy will show: str

FastAPI Integration

1. FastAPI with Type Hints

python
# main.pyfrom fastapi import FastAPI, HTTPExceptionfrom pydantic import BaseModelfrom typing import List, Optional
app = FastAPI()
# Pydantic models (auto-validated)class User(BaseModel):    id: int    name: str    email: str    age: Optional[int] = None
class UserCreate(BaseModel):    name: str    email: str    age: Optional[int] = None
# Type-safe endpoints@app.get("/")def read_root() -> dict[str, str]:    return {"message": "Hello World"}
@app.get("/users/{user_id}")def read_user(user_id: int) -> User:    if user_id == 0:        raise HTTPException(status_code=404, detail="User not found")    return User(id=user_id, name=f"User {user_id}", email="[email protected]")
@app.get("/users")def list_users(skip: int = 0, limit: int = 10) -> List[User]:    users = [        User(id=i, name=f"User {i}", email=f"user{i}@example.com")        for i in range(skip, skip + limit)    ]    return users
@app.post("/users")def create_user(user: UserCreate) -> User:    # Pydantic ensures type safety    return User(id=1, name=user.name, email=user.email, age=user.age)

2. Async FastAPI Type Checking

python
from typing import List, Optionalfrom fastapi import FastAPI, Dependsfrom sqlalchemy.ext.asyncio import AsyncSession
app = FastAPI()
# Async dependencyasync def get_db() -> AsyncSession:    async with AsyncSessionLocal() as session:        yield session
# Async endpoints with types@app.get("/users/{user_id}")async def read_user(    user_id: int,    db: AsyncSession = Depends(get_db)) -> User:    user = await db.get(User, user_id)    if user is None:        raise HTTPException(status_code=404, detail="User not found")    return user
@app.get("/users")async def list_users(    skip: int = 0,    limit: int = 10,    db: AsyncSession = Depends(get_db)) -> List[User]:    result = await db.execute(        select(User).offset(skip).limit(limit)    )    return result.scalars().all()

3. FastAPI Dependency Injection Types

python
from typing import Annotated, Optionalfrom fastapi import FastAPI, Depends, Header, HTTPException
app = FastAPI()
# Typed dependenciesasync def get_current_user(    authorization: Annotated[Optional[str], Header()] = None) -> User:    if authorization is None:        raise HTTPException(status_code=401, detail="Not authenticated")    # Verify token and return user    return User(id=1, name="Current User", email="[email protected]")
# Use dependency with type annotation@app.get("/me")async def read_current_user(    current_user: Annotated[User, Depends(get_current_user)]) -> User:    return current_user
# Complex dependency chainclass UserService:    def __init__(self, db: AsyncSession) -> None:        self.db = db
    async def get_user(self, user_id: int) -> Optional[User]:        return await self.db.get(User, user_id)
def get_user_service(    db: Annotated[AsyncSession, Depends(get_db)]) -> UserService:    return UserService(db)
@app.get("/users/{user_id}")async def get_user_endpoint(    user_id: int,    service: Annotated[UserService, Depends(get_user_service)]) -> User:    user = await service.get_user(user_id)    if user is None:        raise HTTPException(status_code=404, detail="User not found")    return user

Django Integration

1. Django with django-stubs

bash
# Install django-stubspip install django-stubs mypy
# Generate mypy configurationpython -m mypy --install-types
ini
# mypy.ini[mypy]plugins = mypy_django_plugin.main
[mypy.plugins.django-stubs]django_settings_module = "myproject.settings"

2. Django Models with Type Hints

python
# models.pyfrom django.db import modelsfrom typing import Optional
class User(models.Model):    email: models.EmailField = models.EmailField(unique=True)    name: models.CharField = models.CharField(max_length=100)    age: models.IntegerField = models.IntegerField(null=True, blank=True)    is_active: models.BooleanField = models.BooleanField(default=True)    created_at: models.DateTimeField = models.DateTimeField(auto_now_add=True)
    def get_display_name(self) -> str:        return self.name or self.email
    @classmethod    def get_active_users(cls) -> models.QuerySet["User"]:        return cls.objects.filter(is_active=True)

3. Django Views with Type Hints

python
# views.pyfrom django.http import HttpRequest, HttpResponse, JsonResponsefrom django.shortcuts import get_object_or_404from typing import Dict, Anyfrom .models import User
def user_detail(request: HttpRequest, user_id: int) -> JsonResponse:    user: User = get_object_or_404(User, pk=user_id)    data: Dict[str, Any] = {        "id": user.id,        "name": user.name,        "email": user.email,    }    return JsonResponse(data)
def user_list(request: HttpRequest) -> JsonResponse:    users = User.get_active_users()    data = {        "users": list(users.values("id", "name", "email"))    }    return JsonResponse(data)

Type Stubs and Third-Party Libraries

1. Installing Type Stubs

bash
# Install stubs for popular librariespip install types-requestspip install types-PyYAMLpip install types-redispip install types-boto3
# Search for available stubspip search types-
# Auto-install missing stubsmypy --install-types

2. Creating Custom Stubs

python
# stubs/external_lib.pyifrom typing import Optional, List
class Client:    def __init__(self, api_key: str) -> None: ...
    def get_user(self, user_id: int) -> Optional[dict]: ...
    def list_users(self, limit: int = 10) -> List[dict]: ...
def connect(host: str, port: int) -> Client: ...
ini
# mypy.ini[mypy]mypy_path = stubs

3. Ignoring Missing Imports

ini
# mypy.ini[mypy-external_lib.*]ignore_missing_imports = True
# For multiple libraries[mypy-celery.*,redis.*,boto3.*]ignore_missing_imports = True

CI/CD Integration

1. GitHub Actions

yaml
# .github/workflows/type-check.ymlname: Type Check
on: [push, pull_request]
jobs:  mypy:    runs-on: ubuntu-latest    steps:      - uses: actions/checkout@v3
      - name: Set up Python        uses: actions/setup-python@v4        with:          python-version: '3.11'
      - name: Install dependencies        run: |          pip install mypy          pip install -r requirements.txt          pip install types-requests types-PyYAML
      - name: Run mypy        run: mypy src/
      - name: Run mypy strict on new code        run: mypy --strict src/api/

2. Pre-commit Hook

yaml
# .pre-commit-config.yamlrepos:  - repo: https://github.com/pre-commit/mirrors-mypy    rev: v1.8.0    hooks:      - id: mypy        args: [--strict, --ignore-missing-imports]        additional_dependencies:          - types-requests          - types-PyYAML
bash
# Install pre-commitpip install pre-commitpre-commit install
# Run manuallypre-commit run mypy --all-files

3. Make Target

makefile
# Makefile.PHONY: typechecktypecheck:	mypy src/
.PHONY: typecheck-stricttypecheck-strict:	mypy --strict src/
.PHONY: typecheck-reporttypecheck-report:	mypy src/ --html-report mypy-report	@echo "Report: mypy-report/index.html"
.PHONY: cici: typecheck test lint

Common Patterns and Idioms

1. Overload for Multiple Signatures

python
from typing import overload, Union
@overloaddef process(data: str) -> str: ...
@overloaddef process(data: int) -> int: ...
@overloaddef process(data: list) -> list: ...
def process(data: Union[str, int, list]) -> Union[str, int, list]:    """Process different data types."""    if isinstance(data, str):        return data.upper()    elif isinstance(data, int):        return data * 2    else:        return [x * 2 for x in data]
# mypy knows return typesresult1: str = process("hello")  # Validresult2: int = process(42)  # Validresult3: str = process(42)  # Type error

2. TypedDict for Structured Dicts

python
from typing import TypedDict, Optional
class UserDict(TypedDict):    id: int    name: str    email: str    age: Optional[int]
# Type-safe dict usagedef create_user(data: UserDict) -> UserDict:    return {        "id": 1,        "name": data["name"],        "email": data["email"],        "age": data.get("age"),    }
user: UserDict = {    "id": 1,    "name": "Alice",    "email": "[email protected]",    "age": 30}
# Type error: Missing required key "email"invalid_user: UserDict = {    "id": 1,    "name": "Bob",}

3. Final and Constant Values

python
from typing import Final
# Constants that should never changeAPI_VERSION: Final = "v1"MAX_RETRIES: Final[int] = 3
# Type error: Cannot assign to final nameAPI_VERSION = "v2"
# Final class (cannot be subclassed)from typing import final
@finalclass BaseConfig:    pass
# Type error: Cannot inherit from final classclass AppConfig(BaseConfig):  # Error!    pass

4. Self Type for Method Chaining

python
from typing import Self  # Python 3.11+
class Builder:    def __init__(self) -> None:        self._value = 0
    def add(self, value: int) -> Self:        self._value += value        return self
    def multiply(self, value: int) -> Self:        self._value *= value        return self
    def build(self) -> int:        return self._value
# Type-safe method chainingresult = Builder().add(5).multiply(2).add(3).build()

mypy vs pyright Comparison

Feature Comparison

Featuremypypyright
Type CheckerOfficial Python type checkerMicrosoft's type checker
SpeedSlower on large codebasesFaster, incremental
StrictnessConfigurable strict modeVery strict by default
IDE IntegrationGood (LSP support)Excellent (Pylance in VS Code)
Plugin SystemYes (mypy plugins)Limited
Error MessagesClear, detailedVery detailed, helpful
CommunityLarge, officialGrowing, Microsoft-backed
Type InferenceGoodExcellent
Configurationmypy.ini, pyproject.tomlpyrightconfig.json, pyproject.toml

When to Use mypy

bash
# Use mypy for:# - Official Python type checking standard# - Plugin ecosystem (Django, SQLAlchemy, Pydantic)# - Gradual typing with fine-grained control# - Compatibility with existing mypy configurations# - CI/CD pipelines (industry standard)

When to Use pyright

bash
# Use pyright for:# - VS Code development (Pylance)# - Faster type checking on large codebases# - Stricter type checking by default# - Better type inference# - Real-time IDE feedback

Using Both

toml
# pyproject.toml - Configure both[tool.mypy]strict = truefiles = ["src"]
[tool.pyright]include = ["src"]strict = ["src/api"]reportMissingTypeStubs = false
bash
# Run both in CImypy src/pyright src/

Local mypy Profiles (Your Repos)

Common patterns from your Python projects:

  • Strict default (edgar, kuzu-memory, mcp-browser): disallow_untyped_defs = true, check_untyped_defs = true, no_implicit_optional = true, warn_return_any = true, strict_equality = true.
  • Relaxed profile (mcp-ticketer): strict flags disabled temporarily with a disable_error_code list for patch releases.
  • Incremental adoption (mcp-vector-search): ignore_errors = true while stabilizing types.
  • Missing imports: ignore_missing_imports = true used in mcp-memory and mcp-ticketer.

Reference: see pyproject.toml in edgar, kuzu-memory, mcp-vector-search, and mcp-ticketer.

Best Practices

1. Start with Key Modules

python
# ✅ GOOD: Type critical business logic first# services/user_service.pyfrom typing import Optional
class UserService:    def get_user(self, user_id: int) -> Optional[User]:        """Retrieve user by ID."""        return self.db.query(User).get(user_id)
    def create_user(self, data: UserCreate) -> User:        """Create new user."""        user = User(**data.dict())        self.db.add(user)        self.db.commit()        return user

2. Use Type Aliases for Readability

python
# ✅ GOOD: Clear, reusable type aliasesfrom typing import Dict, List, Union
JSON = Union[Dict[str, "JSON"], List["JSON"], str, int, float, bool, None]Headers = Dict[str, str]UserId = int
def parse_response(data: JSON, headers: Headers) -> UserId:    pass
# ❌ BAD: Complex inline typesdef parse_response(    data: Union[Dict[str, Union[...]], List[...], str, int, float, bool, None],    headers: Dict[str, str]) -> int:    pass

3. Prefer Explicit Over Implicit

python
# ✅ GOOD: Explicit types for public APIsdef get_user(user_id: int) -> Optional[User]:    return db.query(User).get(user_id)
# ❌ ACCEPTABLE: Type inference for internal helpersdef _format_name(first, last):  # mypy infers str -> str    return f"{first} {last}"

4. Use reveal_type for Debugging

python
# During development, check inferred typesfrom typing import reveal_type
def process_data(data):    result = transform(data)    reveal_type(result)  # mypy: Revealed type is "int"    return result * 2

5. Document Type Ignores

python
# ✅ GOOD: Document why type checking is disabledimport legacy_module  # type: ignore[import]  # TODO: Add type stubs
# ❌ BAD: No explanationimport legacy_module  # type: ignore

Common Pitfalls

❌ Anti-Pattern 1: Using Any Everywhere

python
# WRONG: Defeats purpose of type checkingfrom typing import Any
def process(data: Any) -> Any:    return data.transform()

Correct:

python
from typing import Union, Protocol
class Transformable(Protocol):    def transform(self) -> dict: ...
def process(data: Transformable) -> dict:    return data.transform()

❌ Anti-Pattern 2: Ignoring Type Errors Globally

ini
# WRONG: Disables type checking[mypy]ignore_errors = True

Correct:

ini
# Ignore specific modules only[mypy-legacy.*]ignore_errors = True
[mypy]strict = True

❌ Anti-Pattern 3: Not Using Optional

python
# WRONG: Nullable without Optionaldef get_user(user_id: int) -> User:    user = db.get(user_id)  # Can be None!    return user  # Runtime error if None

Correct:

python
from typing import Optional
def get_user(user_id: int) -> Optional[User]:    return db.get(user_id)
# Handle None explicitlyuser = get_user(123)if user is not None:    print(user.name)

Quick Reference

Common Commands

bash
# Basic type checkingmypy main.pymypy src/
# Strict modemypy --strict src/
# Install missing type stubsmypy --install-types
# Generate HTML reportmypy src/ --html-report mypy-report
# Check specific error codesmypy --show-error-codes src/
# Ignore missing importsmypy --ignore-missing-imports src/
# Follow importsmypy --follow-imports=silent src/
# Incremental mode (faster)mypy --incremental src/
# Verbose outputmypy --verbose src/

Error Code Reference

bash
# Common error codes[attr-defined]      # Attribute not defined[arg-type]          # Argument type mismatch[return-value]      # Return type mismatch[assignment]        # Assignment type mismatch[call-overload]     # No matching overload[index]             # Invalid index operation[operator]          # Unsupported operand type[import]            # Cannot find import[misc]              # Miscellaneous type error[no-untyped-def]    # Function missing type annotation[var-annotated]     # Variable needs type annotation

Resources

Related Skills

When using mypy, consider these complementary skills (available in the skill library):

  • pytest: Type-safe testing with mypy - integrates type checking into your test suite for comprehensive type coverage
  • fastapi-local-dev: FastAPI with full type safety - combines FastAPI's runtime validation with mypy's static checking
  • pydantic: Runtime type validation with mypy support - validates data at runtime while mypy validates at compile time

mypy Version Compatibility: This skill covers mypy 1.8+ and reflects current best practices for Python type checking in 2025.

來源與署名

來源：bobmatnyc/claude-mpm-skills位於toolchains/python/tooling/mypy提交718070a

授權條款： MIT

內容歸原作者所有。SourceWeft 從公開儲存庫中收錄這些內容。

檢舉或申請下架

更多來自 bobmatnyc/claude-mpm-skills 的技能

Wordpress Security Validation

bobmatnyc

說明以安全為優先的 WordPress 開發模式，涵蓋 nonce、清理、驗證與輸出轉義。

Security772 個月前更新

Bug Fix

bobmatnyc

提供結構化的缺陷修正流程：重現、找出根本原因、修正、驗證、補上回歸測試並記錄 PR。

Software Development772 個月前更新

Threat Modeling

bobmatnyc

執行輕量級 STRIDE 威脅建模工作坊，並將辨識出的風險轉化為緩解措施、工單與測試。

Security772 個月前更新

Webapp Testing

bobmatnyc

提供 Playwright 模式的參考指南，用於撰寫網頁應用程式測試，涵蓋選擇器、等待、斷言與除錯。

Software Development772 個月前更新

Opentelemetry

bobmatnyc

提供使用 OpenTelemetry 為服務埋點並透過 Collector 匯出 OTLP 遙測的參考指引。

DevOps & Cloud772 個月前更新

Skill Creator

bobmatnyc

指導如何建立、組織並封裝模組化的代理技能，並運用漸進式揭露。

AI & Agents772 個月前更新

更多Software Development技能

Playground

anthropics

精選

建立自成一體的互動式 HTML 遊樂場，包含控制項、即時預覽與可複製的提示詞輸出。

Software Development37K今天更新

M5 Onboard

anthropics

精選

透過 USB 偵測 M5Stack ESP32 開發板，燒錄 UIFlow 2.0 韌體並安裝 MicroPython 應用程式套件。

Software Development37K今天更新

Cardputer Buddy

anthropics

精選

指導迭代 Cardputer-Adv 的 MicroPython 應用程式套件：新增應用程式、透過 USB 序列埠推送檔案、查看日誌並執行 REPL 指令。

Software Development37K今天更新

Web Design Guidelines

vercel-labs

精選

依據從遠端來源取得的 Web Interface Guidelines 審查 UI 程式碼，並以 file:line 形式回報問題。

Software Development32K5 週前更新

Vercel React Native Skills

vercel-labs

精選

React Native 與 Expo 最佳實務規則，涵蓋清單效能、動畫、導覽、UI 模式、狀態與 monorepo 設定。

Software Development32K5 週前更新

Vercel React Best Practices

vercel-labs

精選

Vercel 的 React 與 Next.js 效能指南，以 70 條規則的形式用於撰寫、審查與重構程式碼。

Software Development32K5 週前更新