Python中如何获取类对象的规范公共导入路径？

核心结论 #

Python没有官方内置的规范机制直接获取类的「公共API路径」。因为公共导出是包作者通过__all__、显式导入等方式约定的设计规则，属于代码组织层面的约定，而非语言本身强制绑定的元信息。

问题背景回顾 #

给定如下包结构：

|-- my_package
|   |-- __init__.py
|   |-- _my_module.py

my_package/_my_module.py内容：

class MyObject: ...

my_package/__init__.py内容：

from ._my_module import MyObject

__all__ = [
    "MyObject"
]

这里MyObject的内部实现路径是my_package._my_module.MyObject，但对外暴露的公共API路径是my_package.MyObject，我们需要可靠地获取后者。

现有方案的问题 #

你提供的过滤模块名私有前缀的函数存在明显缺陷：

• 逻辑过于简单，无法处理多层嵌套的包结构（比如my_package._sub._module.MyObject）
• 无法区分「私有模块中被显式导出的对象」和「真正的私有内部对象」
• 若包作者用非下划线前缀的内部模块（比如internal_module），函数会直接失效

可行的替代方案 #

1. 手动为类标记公共路径 #

最可靠的方式是在类定义时显式添加元信息，直接声明其公共API路径：
修改_my_module.py：

class MyObject:
    __public_path__ = "my_package.MyObject"

之后直接通过MyObject.__public_path__获取，完全符合包作者的设计意图，没有歧义。

2. 基于包导出关系的改进函数 #

如果无法修改包的代码，可以实现一个基于__all__和模块导入关系的检查函数，比原始方案更可靠：

from typing import Any, Type
import importlib

def get_public_path(obj: Type[Any]) -> str:
    # 从对象所在模块向上遍历，查找第一个将其作为公共API导出的模块
    module_parts = obj.__module__.split(".")
    for i in range(len(module_parts), 0, -1):
        current_module_name = ".".join(module_parts[:i])
        try:
            current_module = importlib.import_module(current_module_name)
            module_short_name = current_module_name.split(".")[-1]
            # 跳过私有模块（以下划线开头）
            if module_short_name.startswith("_"):
                continue
            # 检查对象是否在模块的__all__中
            if hasattr(current_module, "__all__") and obj.__name__ in current_module.__all__:
                return f"{current_module_name}.{obj.__name__}"
            # 若没有__all__，检查对象是否直接属于该模块（显式导出）
            elif getattr(current_module, obj.__name__, None) is obj:
                return f"{current_module_name}.{obj.__name__}"
        except ImportError:
            continue
    # 找不到公共路径时返回原始路径
    return f"{obj.__module__}.{obj.__name__}"

# 测试
if __name__ == '__main__':
    from my_package import MyObject
    print(get_public_path(MyObject))  # 输出 my_package.MyObject

这个函数会从对象的模块向上遍历，找到第一个将其作为公共API导出的模块。

最佳实践 #

• 包作者视角：如果需要让外部获取对象的公共路径，优先选择手动标记元信息的方式，这是最清晰且无歧义的方案。
• 使用者视角：如果无法修改包的代码，使用改进后的遍历函数，但需注意这种方式依赖包的导出约定，若包作者调整了导出结构，函数可能需要同步修改。

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