如何以可维护、易读的方式访问Python同级包？

我太懂这种情况了——一开始两个函数在同一个文件里，调用起来顺手得很，可一旦为了代码整洁拆分到不同文件，不仅要处理导入的问题，还得担心后续维护时别人看不懂依赖关系。结合实际项目经验，给你分享几个能让代码长期保持可维护性的最佳实践：

1. 用__init__.py统一暴露公共API #

把包内各个模块的核心函数都收拢到tools/__init__.py里，不管内部怎么拆分文件，外部（包括包内其他模块）都只需要从tools主包导入，不用关心具体的子模块位置。举个例子：

# tools/__init__.py
# 从子模块导入核心函数，统一对外暴露
from .parse import parse_name
from .split import split_name

这样在parse.py里需要调用split_name时，直接写：

# tools/parse.py
# 要么用相对导入，要么直接从主包导入
from . import split_name
# 或者更清晰的写法：from tools import split_name

后续如果要调整split_name的存放位置，只需要修改__init__.py，不用改动所有调用它的地方，大幅降低模块间的耦合度。

2. 拆分时遵循“高内聚、低耦合”原则 #

拆分模块前先想清楚：哪些函数是同一功能域的？比如parse_name和split_name都是处理名称的逻辑，要么把它们放在同一个子模块（比如tools/name_processing.py），要么在__init__.py里把它们归类暴露，让使用者一眼就能看出它们的关联。尽量避免把逻辑上紧密相关的函数拆得太散，不然后续维护时找依赖会很头疼。

3. 用相对导入但别过度 #

包内模块之间的导入，优先用相对导入（比如from .split import split_name），这样如果哪天包的名称改了，内部导入不用跟着改。但要注意别用太深的相对路径（比如from ..utils import xxx），这种写法会让代码可读性骤降，别人很难快速判断模块的层级关系。

4. 明确区分公共接口和内部实现 #

对于包内仅供内部调用的辅助函数，要么在函数名前加下划线（比如_internal_split_helper()），要么把它们放到专门的内部模块（比如tools/_internal.py）里，并且绝对不要在__init__.py中暴露这些内容。这样其他开发者一看就知道这些是内部细节，不应该直接依赖，后续你修改这些内部逻辑时也不用担心破坏外部代码。

5. 给模块加清晰的文档注释 #

每个模块的开头，都写清楚这个模块的职责，以及它依赖的其他包内模块。比如在parse.py的开头：

"""
负责名称解析的模块，依赖split模块的split_name函数完成前置的名称拆分工作
"""
from .split import split_name

这样后续维护的人不用翻遍代码，看一眼模块注释就知道它的作用和依赖关系。

6. 测试跟着模块同步拆分 #

拆分模块后，对应的测试也要跟着拆分到对应的测试文件里（比如tests/test_parse.py、tests/test_split.py），而且测试时尽量通过包的公共API来调用，不要直接导入子模块。这样既能保证公共API的稳定性，也能及时发现模块拆分后引入的问题。

内容的提问来源于stack exchange，提问作者danijar