模块与包

模块通常是一个 .py 文件；包用于组织模块和子包。现代 Python 支持没有 __init__.py 的命名空间包，因此“目录必须包含 __init__.py 才是包”并不准确。常规应用包仍通常保留它，以明确包边界并放置少量包级初始化。

project/
├── pyproject.toml
├── src/
│   └── app/
│       ├── __init__.py
│       ├── __main__.py
│       ├── service.py
│       └── models.py
└── tests/

导入

优先导入模块或明确名称，避免 import *：

import json
from app.models import User

payload = json.dumps({"id": 1})
user = User(id=1)

import * 隐藏名称来源，也可能被 __all__ 改变导入结果。__all__ 只影响星号导入，不限制普通属性访问。

相对导入用于包内部，例如 from .models import User；应用入口和跨包依赖优先使用绝对导入。避免模块顶层执行网络访问、数据库连接或其他明显副作用，因为首次导入会执行模块顶层代码。

入口与可执行包

模块直接运行时，__name__ 为 "__main__"；作为模块导入时，值为其限定模块名。

def main() -> None:
    print("run application")


if __name__ == "__main__":
    main()

包提供 __main__.py 后，可使用 python -m app 执行。使用 -m 有利于按包语义解析导入。

依赖与发布

项目元数据和依赖声明放在 pyproject.toml，锁文件和安装工具按团队选型统一。标准库无需安装；第三方依赖必须声明版本范围，避免仅依赖当前虚拟环境的隐式状态。

[project]
name = "app"
requires-python = ">=3.11"
dependencies = [
  "httpx>=0.27,<1",
]

参考

• Python 模块教程
• Python 包导入系统