Python importlib.metadata怎样读取已安装包的入口点

做 Python 插件发现时，真正要找的往往不是某个固定模块，而是“当前虚拟环境里安装了哪些分发包、它们声明了哪些入口点”。这时可以使用 importlib.metadata.entry_points()：先按 group 筛选，再按 name 找到目标，最后在真正调用前使用 load() 解析对象。

这套 API 查询的是安装元数据中的入口点，不是扫描所有可导入模块。分发包名、import 包名和入口点名也不一定一一对应，所以插件系统应把分组和命名约定写清楚。

官方地址：https://docs.python.org/3/library/importlib.metadata.html

一、先分清三个名称从哪里来

importlib.metadata 面向的是已安装的 distribution package。常见的 dist-info 或 egg-info 元数据里可以声明入口点；入口点通常由一个组名、一个名称和一个值组成，值常写成 module:attribute。

例如，一个命令行工具可能声明在 console_scripts 组，一个应用插件则可以约定自己的 myapp.plugins 组。读取时先确定组，再处理组内条目，排查范围会比盲目导入模块更稳定。

from importlib.metadata import entry_points

# 先读取当前环境可发现的入口点集合，不把它当成普通模块列表。
all_points = entry_points()

# groups 是入口点集合提供的分组信息，适合先观察环境中有哪些组。
print(sorted(all_points.groups))

这里的输出取决于当前环境安装了哪些包，不能把某台机器上的组列表当成固定结果。排查问题时，先确认运行脚本使用的 Python 和安装依赖是同一个环境。

二、按 group 筛选入口点

Python 3.10 及之后，入口点集合支持 select()，而 entry_points() 也可以把筛选条件直接传进去。读取自定义插件时，建议把组名作为明确的协议边界。

from importlib.metadata import entry_points

PLUGIN_GROUP = "demo.plugins"

# 只筛选插件组，避免把命令行脚本等其他入口点混入发现结果。
plugins = entry_points(group=PLUGIN_GROUP)

for point in plugins:
    # name 用于稳定匹配，value 是待延迟解析的 module:attribute 字符串。
    print(point.name, point.value)

如果需要从已经拿到的集合继续筛选，也可以写成 entry_points().select(group=PLUGIN_GROUP)。当前文档把返回值描述为 EntryPoints 集合，它提供 groups、names 和 select() 等能力。

三、按 name 找到一个入口点

当应用只需要一个指定插件时，不要直接取列表下标。可以同时传入 group 和 name，再显式处理没有找到、找到多个或名称配置错误的情况。

from importlib.metadata import entry_points

def find_plugin(name: str):
    # 同时限制组和名称，避免不同插件组出现同名条目时误选。
    matches = entry_points(group="demo.plugins", name=name)

    if not matches:
        # 未安装、组名写错或插件没有声明入口点时都可能得到空集合。
        raise LookupError(f"未找到插件入口点：{name}")

    # 入口点名称应由插件协议保证唯一，这里保留第一项作为明确约定。
    return matches[0]

point = find_plugin("markdown")
print(point.module, point.attr, point.extras)

EntryPoint 的常用属性包括 name、group、value、module、attr 和 extras。如果你的协议允许同名插件共存，就不要使用第一项策略，而应把分发包名或优先级也纳入选择规则。

四、用 load 延迟解析目标对象

入口点的 value 只是一个描述，例如 demo_plugin.handlers:run。调用 load() 后，Python 才会导入模块并取出属性，因此可以把插件加载放在真正需要执行的路径上。

from importlib.metadata import entry_points

def run_plugin(name: str, payload: dict[str, object]) -> object:
    # 先定位声明，再把真正的导入延迟到调用点。
    matches = entry_points(group="demo.plugins", name=name)
    if len(matches) != 1:
        # 0 个表示未安装，多个表示插件协议没有保持名称唯一。
        raise LookupError(f"插件入口点数量异常：{name} -> {len(matches)}")

    point = matches[0]
    try:
        handler = point.load()
    except (ImportError, AttributeError) as exc:
        # module 或 attr 配置错误时保留入口点信息，便于定位打包问题。
        raise RuntimeError(f"插件加载失败：{point.value}") from exc

    # 由插件协议决定可调用对象的参数约定。
    return handler(payload)

异常应在 load() 附近转换，而不是等到业务调用深处才出现一条难以关联的导入错误。需要注意的是，load() 只负责解析入口点指向的对象；对象是否可调用、参数是否正确，仍然属于你的插件协议。

五、兼容 Python 版本差异

如果项目需要支持较老 Python 版本，入口点 API 的返回形态是最容易踩坑的地方。官方文档说明：Python 3.10 引入可筛选入口点，Python 3.12 起 entry_points() 始终返回 EntryPoints 对象；更早版本曾返回按组组织的字典。

如果要兼容多个版本，建议在项目的兼容层集中处理差异，业务代码只接收一个统一的入口点集合。这样升级 Python 时，变化只会落在适配代码，而不会散落在每个插件调用点。

总结：先筛选，再加载，最后执行

读取已安装包入口点可以按三层理解：用 group 划定插件协议，用 name 选中具体条目，用 load() 在真正需要时解析对象。排查“为什么找不到插件”时，依次检查运行环境、分发包元数据、组名和名称，最后再看 module:attr 是否能被加载。

相关问题

• 入口点和 import 包名一样吗？不一定。入口点来自分发包元数据，分发包、顶层 import 包和入口点名称可以不同。
• 为什么 entry_points() 找不到自定义插件？先确认插件安装在当前 Python 环境，再确认声明的 group 和 name 与查询代码完全一致。
• 什么时候应该调用 load()？通常在确定要执行某个插件后再调用，避免启动阶段导入所有可选依赖。
• 多个入口点同名怎么办？不要静默取第一项，应该把分发包、优先级或配置来源加入唯一性规则。