如何让基于asyncio的Python库同时支持CLI命令行与Jupyter Notebook调用？

这个问题我之前也踩过坑！核心矛盾就是CLI环境需要主动启动新的asyncio事件循环，而Jupyter/IPython本身已经在运行一个持久的循环，直接用asyncio.run就会冲突报错。下面给你两个实用的解决方案，看你更倾向哪种：

方案一：自动适配环境，让用户调用方式完全统一 #

这个方案的目标是不管用户在CLI还是Jupyter里，都只需要调用main()就能正常运行，不需要改任何调用代码。

步骤1：写一个环境适配的工具函数 #

我们可以写一个小函数，自动检测当前是否有正在运行的事件循环，然后动态选择正确的运行方式：

import asyncio
from typing import Coroutine

def run_async(coro: Coroutine) -> None:
    try:
        # 尝试获取当前已启动的事件循环
        loop = asyncio.get_running_loop()
        if loop.is_running():
            # Jupyter环境：循环已经在运行，用nest_asyncio允许嵌套运行
            import nest_asyncio
            nest_asyncio.apply()
            # 等待异步逻辑执行完成
            loop.run_until_complete(coro)
    except RuntimeError:
        # CLI环境：没有运行中的循环，直接用asyncio.run启动
        asyncio.run(coro)

步骤2：改造你的handle和main函数 #

把原来直接调用asyncio.run(async_handle())的地方，换成调用这个工具函数：

# 保持你的异步逻辑不变
async def async_handle():
    # 你的异步任务代码
    pass

def regular_handle():
    # 你的同步逻辑不变
    pass

def handle(args):
    if args["async_mode"]:
        # 用我们的适配函数运行异步逻辑
        run_async(async_handle())
    else:
        regular_handle()

def main():
    # 假设你这里有解析args的逻辑，保持不变
    args = parse_args()
    handle(args)

注意事项 #

• 需要提前安装nest_asyncio，你可以把它加到库的可选依赖里（比如在setup.py里加extras_require={"jupyter": ["nest_asyncio"]}），或者告诉Jupyter用户手动安装pip install nest_asyncio。
• 这个方案对用户最友好，不管是CLI执行python -m my_library.main，还是Jupyter里from my_library.main import main; main()，都能直接跑。

方案二：拆分同步/异步入口，更符合asyncio设计规范 #

如果你不想引入额外依赖，这个方案更轻量，只是需要用户在Jupyter里稍微改一下调用方式。

步骤1：把main改成异步函数 #

先把核心逻辑改成异步的，同时保留CLI的同步入口：

async def async_main():
    args = parse_args()
    if args["async_mode"]:
        await async_handle()
    else:
        regular_handle()

def main():
    # CLI环境下直接启动异步逻辑
    asyncio.run(async_main())

# 当作为主模块运行时（CLI调用），自动触发main
if __name__ == "__main__":
    main()

步骤2：Jupyter里的调用方式 #

用户在Jupyter里只需要改成用await调用异步版本的main：

from my_library.main import async_main
await async_main()

如果用户还是想保持main()的调用方式，也可以给异步入口加个同步包装，复用方案一里的run_async函数，这样又能回到统一调用的体验。

额外小技巧：避免命令行参数干扰 #

如果你的parse_args()是用argparse写的，在Jupyter里调用时可能会解析到Notebook的命令行参数，导致出错。可以在解析时判断场景：

def parse_args():
    parser = argparse.ArgumentParser()
    # 你的参数定义
    # 只有当作为主模块运行时（CLI）才解析命令行参数，否则返回默认值
    if __name__ == "__main__":
        return parser.parse_args()
    else:
        # 返回适合Notebook的默认参数
        return parser.parse_args(args=[])

这样在Jupyter里导入调用时，就不会被无关参数干扰了。

内容来源于stack exchange