参考 · 随时回来查

术语表

这门课用到的词,一律按这里的定义。每条都配一个你项目里的真实例子——记不住定义没关系,记得住例子就够了。

基本单位

词是什么你项目里
模块
module
一个 .py 文件。 vision.py、webhook.py、raw_store.py
包
package
一个装着 __init__.py 的目录。 geweapi/(里面 29 个 .py)
__init__.py 包被打开时自动执行的那个文件。你不调用它,Python 替你调用。 geweapi/__init__.py,里面有 16 行 import
隐式执行
implicitly executed
官方文档的用词:你没写这行代码,但它跑了。 导入 inbox_service → __init__.py 被隐式执行

那条规则

导入 parent.one 时,会隐式执行 parent/__init__.py。

— Python 语言参考 · The import system

推论:你导入包里的任何一样东西,都等于先把整个 __init__.py 跑一遍。 那里面 import 了什么,就一并加载什么。

常见报错

报错意思先查什么
ModuleNotFoundError 要加载的模块根本找不到。 库没装(第三方),或路径不对(PYTHONPATH 没设)
ImportError 模块找到了,但要拿的那个名字不在里面。 函数或类改过名、被删了,或两端代码版本不一致

两者的区别值得记住:ModuleNotFoundError 是「文件没找到」,ImportError 是「文件在,东西不在」。第二种往往意味着两台机器的代码不是同一份。

项目里的实数

数字指什么
4收件箱对外提供的操作:列出待取、标记已取、取原文、取回调地址
29geweapi/ 包里的 .py 文件数
33收件箱启动时实际加载进内存的模块数
49整个 src/ 下的 .py 文件数,也就是打包上传的量
16geweapi/__init__.py 里的 import 行数——连锁的源头

这四个数字曾经被混着说过一次,导致「不是只有 4 个吗」的困惑。4 是操作数,不是文件数。

要背下来的那条命令

同步代码到预发布之后,在那台机器上跑:

sudo -u avatar env PYTHONPATH=/srv/digital-avatar/src \
  /usr/local/bin/python3.12 -c "import digital_avatar.geweapi.inbox_service; print('ok')"

它做的正是收件箱启动时做的第一件事——把包整个打开一遍。打出 ok 就说明 33 个模块的依赖都在,可以放心重启。不打 ok 而是抛错,报错类型对照上面那张表。