Python类型注解模式指南：现代类型提示与Typing最佳实践

python-typing-patterns by 0xdarkmatter/claude-mods

24 周安装量

16 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/0xdarkmatter/claude-mods --skill python-typing-patterns

🇨🇳中文介绍

Python 类型注解模式

用于安全、文档化 Python 代码的现代类型提示。

基础注解

# Variables
name: str = "Alice"
count: int = 42
items: list[str] = ["a", "b"]
mapping: dict[str, int] = {"key": 1}

# Function signatures
def greet(name: str, times: int = 1) -> str:
    return f"Hello, {name}!" * times

# None handling
def find(id: int) -> str | None:
    return db.get(id)  # May return None

集合类型

from collections.abc import Sequence, Mapping, Iterable

# Use collection ABCs for flexibility
def process(items: Sequence[str]) -> list[str]:
    """接受列表、元组或任何序列。"""
    return [item.upper() for item in items]

def lookup(data: Mapping[str, int], key: str) -> int:
    """接受字典或任何映射。"""
    return data.get(key, 0)

# Nested types
Matrix = list[list[float]]
Config = dict[str, str | int | bool]

可选类型与联合类型

# Modern syntax (3.10+)
def find(id: int) -> User | None:
    pass

def parse(value: str | int | float) -> str:
    pass

# With default None
def fetch(url: str, timeout: float | None = None) -> bytes:
    pass

TypedDict

from typing import TypedDict, Required, NotRequired

class UserDict(TypedDict):
    id: int
    name: str
    email: str | None

class ConfigDict(TypedDict, total=False):  # All optional
    debug: bool
    log_level: str

class APIResponse(TypedDict):
    data: Required[list[dict]]
    error: NotRequired[str]

def process_user(user: UserDict) -> str:
    return user["name"]  # Type-safe key access

🇺🇸English

Python Typing Patterns

Modern type hints for safe, documented Python code.

Basic Annotations

# Variables
name: str = "Alice"
count: int = 42
items: list[str] = ["a", "b"]
mapping: dict[str, int] = {"key": 1}

# Function signatures
def greet(name: str, times: int = 1) -> str:
    return f"Hello, {name}!" * times

# None handling
def find(id: int) -> str | None:
    return db.get(id)  # May return None

Collections

from collections.abc import Sequence, Mapping, Iterable

# Use collection ABCs for flexibility
def process(items: Sequence[str]) -> list[str]:
    """Accepts list, tuple, or any sequence."""
    return [item.upper() for item in items]

def lookup(data: Mapping[str, int], key: str) -> int:
    """Accepts dict or any mapping."""
    return data.get(key, 0)

# Nested types
Matrix = list[list[float]]
Config = dict[str, str | int | bool]

Optional and Union

# Modern syntax (3.10+)
def find(id: int) -> User | None:
    pass

def parse(value: str | int | float) -> str:
    pass

# With default None
def fetch(url: str, timeout: float | None = None) -> bytes:
    pass

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

协议（结构类型）

from typing import Protocol

class Readable(Protocol):
    def read(self, n: int = -1) -> bytes:
        ...

def load(source: Readable) -> dict:
    """接受任何具有 read() 方法的对象。"""
    data = source.read()
    return json.loads(data)

# Works with file, BytesIO, custom classes
load(open("data.json", "rb"))
load(io.BytesIO(b"{}"))

from typing import TypeGuard

def is_string_list(val: list[object]) -> TypeGuard[list[str]]:
    return all(isinstance(x, str) for x in val)

def process(items: list[object]) -> None:
    if is_string_list(items):
        # items is now list[str]
        print(", ".join(items))

from typing import Literal, Final

Mode = Literal["read", "write", "append"]

def open_file(path: str, mode: Mode) -> None:
    pass

# Constants
MAX_SIZE: Final = 1024
API_VERSION: Final[str] = "v2"

类型	使用场景
`X	None`
`list[T]`	同质列表
`dict[K, V]`	字典
`Callable[[Args], Ret]`	函数类型
`TypeVar("T")`	泛型参数
`Protocol`	结构类型
`TypedDict`	固定键的字典
`Literal["a", "b"]`	仅限特定值
`Final`	不可重新赋值

类型检查器命令

# mypy
mypy src/ --strict

# pyright
pyright src/

# In pyproject.toml
[tool.mypy]
strict = true
python_version = "3.11"

./references/generics-advanced.md - TypeVar、ParamSpec、TypeVarTuple
./references/protocols-patterns.md - 结构类型、运行时协议
./references/type-narrowing.md - 守卫、isinstance、assert
./references/mypy-config.md - mypy/pyright 配置
./references/runtime-validation.md - Pydantic v2、typeguard、beartype
./references/overloads.md - @overload 装饰器模式

./scripts/check-types.sh - 使用常用选项运行类型检查器

./assets/pyproject-typing.toml - 推荐的 mypy/pyright 配置

这是一个基础技能，没有先决条件。

python-pytest-patterns - 类型安全的夹具和模拟

基于此技能的进阶:

python-async-patterns - 异步类型注解
python-fastapi-patterns - Pydantic 模型和验证
python-database-patterns - SQLAlchemy 类型注解

from typing import TypedDict, Required, NotRequired

class UserDict(TypedDict):
    id: int
    name: str
    email: str | None

class ConfigDict(TypedDict, total=False):  # All optional
    debug: bool
    log_level: str

class APIResponse(TypedDict):
    data: Required[list[dict]]
    error: NotRequired[str]

def process_user(user: UserDict) -> str:
    return user["name"]  # Type-safe key access

from collections.abc import Callable

# Function type
Handler = Callable[[str, int], bool]

def register(callback: Callable[[str], None]) -> None:
    pass

# With keyword args (use Protocol instead)
from typing import Protocol

class Processor(Protocol):
    def __call__(self, data: str, *, verbose: bool = False) -> int:
        ...

from typing import TypeVar

T = TypeVar("T")

def first(items: list[T]) -> T | None:
    return items[0] if items else None

# Bounded TypeVar
from typing import SupportsFloat

N = TypeVar("N", bound=SupportsFloat)

def average(values: list[N]) -> float:
    return sum(float(v) for v in values) / len(values)

Protocol (Structural Typing)

from typing import Protocol

class Readable(Protocol):
    def read(self, n: int = -1) -> bytes:
        ...

def load(source: Readable) -> dict:
    """Accepts any object with read() method."""
    data = source.read()
    return json.loads(data)

# Works with file, BytesIO, custom classes
load(open("data.json", "rb"))
load(io.BytesIO(b"{}"))

from typing import TypeGuard

def is_string_list(val: list[object]) -> TypeGuard[list[str]]:
    return all(isinstance(x, str) for x in val)

def process(items: list[object]) -> None:
    if is_string_list(items):
        # items is now list[str]
        print(", ".join(items))

from typing import Literal, Final

Mode = Literal["read", "write", "append"]

def open_file(path: str, mode: Mode) -> None:
    pass

# Constants
MAX_SIZE: Final = 1024
API_VERSION: Final[str] = "v2"

Type	Use Case
`X	None`
`list[T]`	Homogeneous list
`dict[K, V]`	Dictionary
`Callable[[Args], Ret]`	Function type
`TypeVar("T")`	Generic parameter
`Protocol`	Structural typing
`TypedDict`	Dict with fixed keys
`Literal["a", "b"]`	Specific values only
`Final`	Cannot be reassigned

Type Checker Commands

# mypy
mypy src/ --strict

# pyright
pyright src/

# In pyproject.toml
[tool.mypy]
strict = true
python_version = "3.11"

Additional Resources

./references/generics-advanced.md - TypeVar, ParamSpec, TypeVarTuple
./references/protocols-patterns.md - Structural typing, runtime protocols
./references/type-narrowing.md - Guards, isinstance, assert
./references/mypy-config.md - mypy/pyright configuration
./references/runtime-validation.md - Pydantic v2, typeguard, beartype
./references/overloads.md - @overload decorator patterns

./scripts/check-types.sh - Run type checkers with common options

./assets/pyproject-typing.toml - Recommended mypy/pyright config

This is a foundation skill with no prerequisites.

python-pytest-patterns - Type-safe fixtures and mocking

Build on this skill:

python-async-patterns - Async type annotations
python-fastapi-patterns - Pydantic models and validation
python-database-patterns - SQLAlchemy type annotations

SEO与AEO最佳实践指南：优化内容适配传统搜索与AI答案引擎

Python类型注解模式指南：现代类型提示与Typing最佳实践

🇨🇳中文介绍

Python 类型注解模式

基础注解

集合类型

可选类型与联合类型

TypedDict

🇺🇸English

Python Typing Patterns

Basic Annotations

Collections

Optional and Union

相关 Skills

最新 Skills

可调用类型

泛型

协议（结构类型）

类型守卫

字面量与常量

快速参考

类型检查器命令

额外资源

脚本

资源文件

另请参阅

TypedDict

Callable

Generics

Protocol (Structural Typing)

Type Guards

Literal and Final

Quick Reference

Type Checker Commands

Additional Resources

Scripts

Assets

See Also