Python 教程 / 包结构、__main__ 与程序执行入口
包将相关 Python 模块组织成层级。把程序动作放进 main 函数,再通过明确的执行入口调用,可以让其他代码导入模块而不自动运行整个程序;包目录中的 __main__.py 则提供 python -m 包名的入口。
建立普通包并确定执行目录
本例创建包含 __init__.py 的普通包。命名空间包可以没有这个文件,但入门时先使用明确的普通包结构。以下文件夹名和文件名要保持一致:
project/
expense_app/
__init__.py
math_tools.py
__main__.py
创建 project 目录,在里面建立 expense_app 子目录,再创建三份文件。终端应位于 project,不是 expense_app 内部。使用已选定的项目 Python 解释器,不需要安装第三方依赖。模块拆分的基本规则见模块、import 与查找路径。
这里的“包”首先指可以导入的源码层级。能否通过 pip 安装,还涉及分发项目的配置、构建与安装验证;仅创建这些目录并不等于发布了一个可安装发行包。
保存全部文件并使用 -m 运行
expense_app/__init__.py的完整内容如下。英语文档字符串表示“支出计算包”,不影响本例计算:
"""Expense calculation package."""
expense_app/math_tools.py的完整内容:
def total(amounts):
return sum(amounts)
expense_app/__main__.py的完整内容:
from .math_tools import total
def main():
print(total([3500, 8000, 2500]))
if __name__ == "__main__":
main()
以 UTF-8 保存后,在 project 目录执行:
python -m expense_app
预期输出 14000。如果核对过的解释器命令为 python3,可相应执行 python3 -m expense_app。-m按模块查找规则定位目标,并为执行提供包上下文;执行包名时会运行其 __main__.py。
开头 from .math_tools import total中的点表示当前包。不要把上述命令等同于 python expense_app/__main__.py:直接按路径运行这个内部文件时,相对导入缺少已知父包,可能报 ImportError。保持代码不变,对比两种命令,确认错误来自执行方式后恢复 -m 命令。
用 __name__ 区分运行与导入
作为顶层入口执行时,模块的 __name__ 是 __main__;作为普通模块导入时,它具有包和模块名称。本例导入 expense_app.__main__ 后,名称为 expense_app.__main__,因此条件不成立,不会调用 main。
main 只是约定俗成的函数名称,定义它不会自动运行。示例的条件判断才决定何时调用它。函数中的计算与输出会等到调用时发生;但导入语句、函数定义时求值的表达式,以及其他顶层语句仍可能执行,不能把这个条件理解为禁止一切导入副作用。
官方文档也展示了保持 __main__.py 简短、从其他模块导入入口函数的组织方式;不必给每个包入口机械添加同一套结构。本例保留条件判断,是为了单独验证这个入口模块的导入行为。相关区别见Python 官方 __main__ 与包入口说明。
模块查找与数据文件查找不是一回事。-m不意味着所有相对数据路径自动以包目录为基准;普通相对文件路径仍受当前工作目录影响。发布程序时可以接收明确路径参数,或按实际需要使用包资源机制,不要假定用户总在源码目录启动。
分别验证执行、导入与错误恢复
仍在 project 目录,执行以下命令:
python -c "import expense_app.__main__; print('imported')"
预期只输出 imported,不应输出合计。若出现 14000,检查是否有未放入函数或判断块的打印与计算,或 main 是否在顶层被无条件调用。测试“能运行”和“能安静地导入”是两种不同检查。
- 将 __main__.py 中 8000 暂时改成 9000,使用 -m 运行,应得到 15000;导入检查仍只应输出 imported。
- 恢复 8000,再次运行,应回到 14000。之后只改变命令为直接文件路径,观察相对导入错误;不要为修复该错误随意修改系统路径。
- 回到 project 并恢复 -m 命令。如果仍提示找不到包,检查 expense_app 的拼写、目录层级和当前解释器;若自己改过包名,还要同步调整导入路径与运行命令。
通常从包外的项目根目录使用 python -m 包名.模块名来保留包上下文。以后移动数据位置或安装为分发项目时,应重新验证启动目录、资源访问和安装后的导入,不能只依赖源码目录中的一次成功运行。




