__init__.py 是否写逻辑取决于是否暴露公共 api：纯组织用途应留空；需简化导入则仅放显式导入；严禁初始化操作。子包循环导入应通过抽取共享模块或接口解耦。tests 不应放入包内。拆包需满足独立演进、安装、维护等实际需求。
包结构里 __init__.py 到底要不要写逻辑
写了容易隐式耦合，不写又可能破坏导入体验——关键看是否暴露公共 API。
- 纯组织用途（如仅用于分层）：
__init__.py留空最安全，避免意外执行副作用 - 需要简化上层导入（如
from mypkg import Client）：只放from .submod import Client这类显式导入，别调用函数、读配置、初始化全局状态 - 常见错误：在
__init__.py里调用logging.basicConfig()或连接数据库——模块一导入就触发，测试难 mock，多进程易冲突
子包之间循环导入怎么破
不是靠“加 try/except”或“延迟 import”，而是从依赖方向上切断。
- 典型症状：
ImportError: cannot import name 'X' from partially initialized module 'mypkg.a' - 优先把共享数据/类型抽到独立的
types.py或core.py包级模块，让 a 和 b 都单向依赖它 - 若必须跨子包调用行为，用协议（
typing.Protocol）或抽象基类定义接口，实现放在具体子包，调用方只依赖接口 - 避免在
__init__.py中跨子包导入——这会放大循环风险
tests 目录该不该放进包里
不该。测试代码不是生产依赖，放进包会导致安装时冗余、误导用户、污染命名空间。
- 正确布局：
mypkg/（包目录）和同级tests/（测试目录），pyproject.toml中用packages = [{include = "mypkg"}]明确限定 - 常见错误：把
tests/放进mypkg/下，并加__init__.py——用户pip install后会多出mypkg.tests可导入模块，且 pytest 可能误发现并运行已安装包里的测试 - 测试中要导入被测模块？用
-m pytest在项目根目录运行，或确保python -c "import mypkg"能通，pytest 自动识别源码路径
什么时候该拆新包，而不是加子包
当某个功能模块具备独立演进、可单独安装、有不同维护者或版本节奏时，才值得拆。
立即学习“Python免费学习笔记（深入）”；
- 信号包括：该模块已有外部用户直接依赖；它用不同 license；CI 流水线需独立触发；文档/README 独立成体系
- 反例：为“看起来更清晰”把
utils/拆成mypkg-utils——只会增加发布负担、版本对齐成本、import 路径断裂 - 拆包后，原包内保留兼容性 shim 是可行的（如
from mypkg_utils import helper），但得标注Deprecated并设弃用周期
真正的复杂点不在目录怎么排，而在于每次新增模块时，你有没有下意识问一句：“这个东西，未来半年会不会被另一个团队拿去改而不通知我？”——答案如果是“会”，那结构就该为它留出隔离边界。
