编写Python包时如何避免重复导入及依赖污染用户命名空间？

现象说明 #

你遇到的是Python模块导入的默认正常行为：Python没有严格的私有成员限制，默认情况下模块顶层的所有导入对象、定义的变量/类/函数都会作为模块的公开属性暴露，可通过dir()检索到，也支持外部直接访问。

推荐解决方案 #

1. 使用__all__声明公开接口（最常用，符合Python社区规范） #

在每个模块的顶层添加__all__变量，显式列出所有对外开放的成员，未被列入的内容均属于内部实现：

• apis.py添加内容：

import pandas as pd

# 仅声明DBInterface为公开接口
__all__ = ["DBInterface"]

class DBInterface:
    def __init__():
        pass

• MyClass.py添加内容：

__all__ = ["MyClass"]

class MyClass:
    def __init__():
        pass

• 顶层__init__.py也可以补充：

from MyThing.MyClass import MyClass
from MyThing.apis import DBInterface

__all__ = ["MyClass", "DBInterface"]

这个方案的优势：

• 符合Python社区约定，所有文档生成工具、静态检查工具都会自动将__all__外的内容识别为内部实现，不会展示给用户
• 用户执行from MyThing import *时只会导入__all__中声明的成员，不会导入内部依赖
• 不需要修改原有内部代码的调用逻辑

2. 内部依赖导入添加下划线私有标记 #

如果希望用户通过dir()查看模块内容时，内部依赖不会和公开接口混排，可以将导入的依赖改名为下划线开头的形式，符合Python「下划线开头为私有成员」的约定：

# apis.py修改导入方式
import pandas as _pd

class DBInterface:
    def query(self):
        # 内部调用时用_pd即可
        return _pd.DataFrame()

下划线开头的成员默认不会被from module import *导入，也不会被大多数文档工具收录，普通用户通常不会主动访问这类私有成员。

3. 局部导入依赖（仅适合少量场景使用） #

如果完全不想让依赖出现在模块顶层属性中，可以将导入语句放到需要用到依赖的方法/函数内部：

class DBInterface:
    def query(self):
        import pandas as pd
        return pd.DataFrame()

Python的模块导入是全局缓存的，多次调用方法不会重复加载模块，性能开销极小。但这个方案写起来繁琐，不适合绝大多数文件都要用到pandas的场景。

额外说明 #

Python的设计理念是「大家都是成年人」，不需要强制禁止用户访问内部成员，只要明确公开接口和内部实现的边界即可。即使用户硬要访问mt.apis.pd这类非公开成员，也属于用户主动使用内部实现，你不需要为这类使用方式的兼容性负责，也不属于「污染用户命名空间」的范畴。

另外注意你给出的用户使用示例中调用了mt.MyThing()，但当前你暴露的类是mt.MyClass，如果要对齐示例用法，可以修改顶层__init__.py的导入逻辑：

from MyThing.MyClass import MyClass as MyThing
from MyThing.apis import DBInterface
__all__ = ["MyThing", "DBInterface"]

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