Python包模块导入最佳实践：如何让新手便捷调用函数？

包结构回顾 #

你的Python包结构如下：

pkg/
├── __init__.py
├── mod.py
├── mod_calc.py
└── mod_plotting.py

一、内部模块的导入优化 #

你在mod.py中使用的import pkg.mod_calc as MC是可行的，但更推荐使用相对导入，这样包名称变更时无需修改内部导入代码，更贴合Python包开发的规范：

# mod.py
from . import mod_calc as MC
from . import mod_plotting as MP

MC.calculate_this()
MP.plot_this()

二、面向新手的友好接口实现（替代from ... import *） #

from ... import *确实会引发命名污染、函数来源模糊等问题，符合Python风格的做法是显式导出指定函数，具体步骤如下：

1. 修改__init__.py，显式暴露目标函数 #

在包的入口文件中，明确列出要让用户直接调用的函数，同时通过__all__规范import *的行为（可选但推荐）：

# __init__.py
# 显式导入并导出目标函数
from .mod import do_this
from .mod_calc import calculate_this
from .mod_plotting import plot_this

# 定义__all__，限制`from pkg import *`时导入的内容
__all__ = ['do_this', 'calculate_this', 'plot_this']

2. 用户脚本的规范调用方式 #

新手用户可以选择两种简洁且安全的调用方式：

方式一：显式导入指定函数（最推荐）

# script:
from pkg import do_this, calculate_this, plot_this

do_this()       # 来自mod.py
calculate_this()# 来自mod_calc.py
plot_this()     # 来自mod_plotting.py

这种方式清晰明了，不会污染命名空间，IDE也能提供准确的自动补全。

方式二：受控的from pkg import *

如果用户偏好极致简洁，由于我们定义了__all__，此时import *只会导入指定的函数，避免了命名冲突：

# script:
from pkg import *

do_this()
calculate_this()
plot_this()

补充说明 #

• 显式导出的方式既满足了新手用户的简洁需求，又遵循了Python的命名空间规范，规避了import *的潜在问题。
• 后续新增可直接调用的函数时，只需在__init__.py中添加对应导入语句，并更新__all__列表即可。

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