跳转至

模块、包与类型标注

一个 .py 文件是模块。模块将函数、类和常量放在可导入的命名空间中：

# math_tools.py
def add(left: int, right: int) -> int:
    return left + right

# main.py
from math_tools import add
print(add(1, 2))

包是由多个模块组成的命名空间，通常对应一个目录。导入时 Python 会按模块搜索路径查找；项目应避免把文件命名为 json.py、typing.py 等标准库名称，以免遮蔽真实模块。

类型标注的边界

def find_user(user_id: int) -> dict[str, str] | None:
    ...

标注表达了函数的输入与输出约定，可由 IDE、静态检查工具和读者使用。Python 解释器默认不在运行时强制执行它们，因此仍需要数据校验和测试。

公开函数应有清晰的参数、返回值和异常约定；不要为了标注而把简单代码写得难读。复杂类型可用 TypedDict、Protocol 等工具，但应在实际需要时引入。

参考

评论