Python importlib.metadata.entry_points 怎样按组选择插件入口

使用 importlib.metadata.entry_points(group="组名") 就能选择当前 Python 环境中属于该组的插件入口。若已经取得入口集合，也可以调用 entries.select(group="组名")。筛选结果是入口元数据，只有显式执行某个入口的 load() 才会解析并导入它指向的对象。

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

本文使用 Python 3.12+ 标准库的可选择入口集合接口，场景是报告工具按配置选择一个渲染插件。选择策略由宿主负责，不因入口在同一组里就自动认为它们接口兼容。下列代码为原创示例，未在本文制作过程中安装或执行，不附虚构运行结果。

先约定分组和插件接口

先把需求限定为“根据名称选择一个报告渲染函数”。宿主约定组名为 orchard_report.renderers，插件名称为 plain，目标对象为 orchard_plain:render。函数接收报告字典并返回字符串。组名与接口是示例中的原创约定，不是 Python 内置插件标准。

根据 PyPA 入口规范，跨分发包的同名冲突需要消费者自己处理。这里采用“一个名字只能对应一个入口”的策略；若宿主要同时加载多个插件，应该另定排序与组合协议，而不是沿用本例的唯一性要求。

按组发现并只列出元数据

from importlib.metadata import entry_points

GROUP = "orchard_report.renderers"

# 只选择该组的入口元数据，不在列出候选时导入插件模块。
entries = entry_points(group=GROUP)
for ep in sorted(entries, key=lambda item: (item.name, item.value)):
    print(ep.group, ep.name, ep.value)

# 已取得集合时，select 可继续按属性精确筛选。
plain_entries = entries.select(name="plain")
print("plain 候选数：", len(plain_entries))

直接传 group 与先取得集合再 select 是两种组织代码的方式，不需要为了筛选先导入所有目标模块。select(name="plain") 是精确属性匹配，不是前缀查询或正则查找。标准库入口文档 说明了这种属性选择与 EntryPoints 返回类型。

列表为空是一个有效的发现结果，不等同于某个插件导入报错。打印元数据可帮助读者看清有哪些声明；它不能证明目标模块一定存在，也不能证明插件函数能处理当前报告。

显式选中唯一入口再加载

from importlib.metadata import entry_points

GROUP = "orchard_report.renderers"

def load_renderer(name):
    # 显式保存全部匹配项，避免重名时悄悄使用第一项。
    candidates = list(entry_points(group=GROUP, name=name))
    if not candidates:
        raise LookupError(f"未找到渲染器：{name}")
    if len(candidates) != 1:
        values = [ep.value for ep in candidates]
        raise RuntimeError(f"渲染器重名：{name}，候选：{values}")
    ep = candidates[0]
    try:
        renderer = ep.load()  # 此处才解析目标并导入插件模块。
    except Exception as exc:
        # 保留原始异常链，区分“未发现入口”和“入口加载失败”。
        raise RuntimeError(f"无法加载入口：{ep.name} = {ep.value}") from exc
    if not callable(renderer):
        raise TypeError(f"渲染器不是可调用对象：{ep.name}")
    return renderer

if __name__ == "__main__":
    render = load_renderer("plain")
    # 参数与返回值协议由宿主约定；callable 不能证明签名正确。
    result = render({"title": "本周仓储摘要", "count": 7})
    if not isinstance(result, str):
        raise TypeError("渲染器必须返回字符串")
    print(result)

不直接取 candidates[0]，是为了避免环境装入第二个同名插件后行为无声变化。唯一性属于应用决策，Python 不替宿主选择优先级。本例在加载前拒绝空集合和重名，加载后要求对象可调用，实际调用之后再限定返回类型。

这仍是一份简化的接口约定：callable 为真不代表参数签名匹配，渲染函数本身也可能抛出异常。该错误应由业务层作为渲染失败记录，不应被统一改写成“未安装插件”。需要隔离不同租户或不可信插件时，也不能把 group 当作权限或进程隔离机制；load 进入的是普通 Python 导入路径。

把入口声明放进安装元数据

插件项目可以用下面的相关配置表达入口。这里只展示与问题有关的项目元数据片段，构建后端和模块打包配置还需按项目补齐，参见 pyproject.toml 入口声明规范。

# 以下为插件项目 pyproject.toml 中的相关配置；项目还需配置构建后端。
[project]
name = "orchard-plain-renderer"
version = "0.1.0"
requires-python = ">=3.12"

# 带点的组名用引号包成完整键，避免被 TOML 拆成多级表。
[project.entry-points."orchard_report.renderers"]
plain = "orchard_plain:render"

# orchard_plain.py，必须被构建后端包含进插件分发包。
def render(report):
    # 宿主协议要求接收一个字典并返回字符串。
    return f"{report['title']}：共 {report['count']} 项"

分发包名 orchard-plain-renderer、导入模块名 orchard_plain 和入口组名并非同一个标识。声明写在源码文件夹里并不代表当前解释器已经能发现：它需要通过项目的构建安装机制成为可发现的分发元数据。普通自定义组也不会仅凭这段配置自动变成命令行命令。

排查空组和选择策略

先确认执行宿主的解释器环境与安装插件的环境一致，再看入口声明的组名是否逐字一致、构建产物是否包含该声明。不要因为模块可以 import，就推定对应 entry point 一定已经注册。仅把一个源码目录加入导入路径，也不等价于生成安装元数据。

在代码层面，避免把新式 entry_points() 当成按组索引的字典；本文统一使用关键字参数或 select。入口对象则使用 name、group、value 属性，不依赖旧式元组解包。若应用真正要求按某个分发包选择入口，可从该分发包的 entry_points 集合筛选，而不是把分发包对象直接塞进本例的 group 条件。

落地时应明确三个决策：组由哪个宿主定义，重名时是报错还是配置指定来源，以及什么时候允许加载。对于此处按名称选择一个渲染器的任务，延后加载、显式报重名能让行为较容易解释；并不需要额外引入服务发现中心或云部署组件。

常见问题

load 会自动调用 render 吗？

不会替宿主执行 render 的业务调用。它解析目标对象，但模块导入本身可能执行顶层代码；因此“列元数据”和“加载对象”仍应分开。

同一个组能提供类或者模块吗？

入口规范支持对象引用，具体允许什么由宿主协议决定。本例要求的是可调用渲染器；换成类或模块时，应同步修改宿主的适配规则，不能只改 value。

console_scripts 可以拿来当自己的插件组吗？

该组具有安装器创建命令包装器的特定含义。普通应用扩展采用自定义组更容易表达协议，避免把 CLI 入口与报告渲染接口混在一起。