Python函数类型注解用于IDE和mypy等工具静态检查，非运行时强制；语法为参数名: 类型、函数末尾-> 返回类型，如def greet(name: str, age: int) -> str:；需用真实类型而非字符串字面量，容器类型须带泛型（如list[str]），可选值用str | None（Py3.10+）或Optional[str]。
Python 函数加类型注解不是为了运行时检查，而是让 IDE、mypy、VS Code 能提前发现参数传错、返回值误用等问题——不加注解，str 和 int 混传可能到运行才报错；加了，写代码时就标红提醒。
怎么给普通函数写基础类型注解
语法很简单：参数名后跟 : 类型，函数末尾用 -> 返回类型。Python 3.5+ 原生支持，不需要额外安装库（但 typing 模块在复杂场景仍需导入）。
常见错误是把字符串字面量当类型写，比如写成 def f(x: "int") -> "str" —— 这不会被静态检查工具识别，必须用真实类型或 from __future__ import annotations（Py3.7+ 推荐）延迟求值。
def greet(name: str, age: int) -> str:
return f"Hello {name}, you are {age} years old"
-
name: str表示只接受str实例，传None或list会被 mypy 标出 -
-> str表示调用者可安全当作str使用，比如直接调.upper() - 如果函数可能返回
None，必须显式写成-> str | None（Py3.10+）或-> Optional[str]（旧版）
处理可选值、联合类型和空值
现实函数常有“可能没结果”的情况，比如查字典、读配置、API 调用失败。不能默认假设返回非空，否则 AttributeError 会悄悄潜伏。
Py3.10+ 推荐用 | 操作符；旧版本必须从 typing 导入 Optional、Union。
让 macOS 自动化像说话一样简单 —— 用代码控制你的 Mac，无需学习 AppleScript 系统要求 macOS 14+ (Sonoma) Python 3.9+ 需要开启：辅助功能 + 屏幕录制权限
from typing import Optional, Union <p>def find_user(user_id: int) -> Optional[str]: # 等价于 str | None return "alice" if user_id == 1 else None</p><p>def parse_input(data: str) -> Union[int, float, bool]: # Py3.10+ 可写为 int | float | bool if data.isdigit(): return int(data) elif "." in data: return float(data) else: return data.lower() == "true" </p>
-
Optional[T]就是Union[T, None]的简写，别手写Union[str, None] - 避免用
Any—— 它等于放弃类型检查，IDE 提示全失效 -
Union成员超过 3 个时，考虑封装为TypedDict或新类型（NewType），提升可读性
标注容器类型（list/dict/Callable）要带泛型参数
只写 list 或 dict 是无效的——它们等价于 list[Any] 和 dict[Any, Any]，起不到约束作用。必须说明里面装什么。
常见坑：用 list 当类型提示，结果传了个 tuple 也能过（因为 tuple 不是 list 子类，但类型检查器看到裸 list 就不校验具体内容）。
from typing import List, Dict, Callable, Tuple
<p>def process_users(users: List[str]) -> Dict[str, int]:
return {u: len(u) for u in users}</p><p>def apply_func(fn: Callable[[int, str], bool], x: int, y: str) -> bool:
return fn(x, y)</p><p>def get_coords() -> Tuple[float, float, float]:
return (1.0, 2.0, 3.0)
</p>
-
List[str]表示“元素全为str的列表”，传[1, "a"]会被 mypy 拒绝 -
Dict[str, int]要求 key 是str、value 是int，{"a": "1"}不合法 -
Callable[[int, str], bool]中双括号是固定语法：外层是函数签名，内层是参数类型列表
为什么有时候写了注解 IDE 还不提示？
最常见原因是没启用类型检查工具，或者 Python 解释器路径/环境没配对。VS Code 默认只靠语言服务器（Pylance）做轻量推断，不依赖注解；要真正生效，得配合 mypy 或开启 Pylance 的 typeCheckingMode: basic。
- 确认已安装
mypy：pip install mypy，然后命令行跑mypy your_script.py - VS Code 中检查设置里是否启用了
"python.typeChecking.enabled": true - 如果用了
from __future__ import annotations，确保项目 Python 版本 ≥ 3.7，且 mypy 配置中python_version = "3.7"或更高 - 第三方库没注解？加
types-xxx包（如types-requests），或用# type: ignore临时跳过（不推荐长期用）
类型注解本身不改变运行行为，但它把隐含契约显性化。最容易被忽略的是：函数边界处的类型声明，比函数内部怎么实现重要得多——哪怕 body 里全是 pass，只要签名清晰，调用方就能安全使用。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
