不能直接 await 第三方同步 SDK 函数，因其返回非 awaitable 对象，会触发 TypeError；且同步执行会阻塞事件循环，导致其他协程卡住；应使用 loop.run_in_executor 将其提交至线程池执行，确保异步不阻塞。

python中如何将第三方同步sdk包装为非阻塞异步调用

为什么不能直接 await 第三方同步 SDK 的函数

因为同步函数没有返回 awaitable 对象，Python 解释器会直接报错：TypeError: object XXX is not awaitable。这不是语法问题，而是语义层面的不兼容——同步函数在执行时会独占当前事件循环线程，强行 await 它只会让协程挂起在“等它跑完”，但事件循环本身被阻塞，其他任务全卡住。

用 `loop.run_in_executor` 包一层最稳妥

这是标准库给出的官方解法，把同步调用丢进线程池执行，避免阻塞事件循环主线程。关键不是“变快”，而是“不卡住”。

实操建议：

默认使用 concurrent.futures.ThreadPoolExecutor（不要用 ProcessPoolExecutor，除非该 SDK 明确是 CPU 密集且 GIL 无影响）
显式传入 loop，避免在非主线程中调用 asyncio.get_running_loop() 报 RuntimeError
如果 SDK 初始化耗时（如加载证书、连接池），也得在 executor 里做，不能放在 async def 函数体顶层
错误不会自动传播：executor 中抛出的异常会在 await 时原样 raise，但堆栈可能丢失原始位置，建议加 try/except 并手动补日志上下文

示例：

import asyncio
from concurrent.futures import ThreadPoolExecutor
<h1>假设这是某个同步 SDK 的客户端</h1><p>class SyncSDKClient:
def <strong>init</strong>(self):</p><h1>可能含网络连接、配置加载等同步初始化</h1><pre class="brush:php;toolbar:false;">    pass

def do_something(self, data: str) -> str:
    return f"result for {data}"

async def async_do_something(client: SyncSDKClient, data: str) -> str: loop = asyncio.get_running_loop()

注意：client 实例必须是线程安全的，或每个 executor 调用都新建

return await loop.run_in_executor(None, client.do_something, data)

python-flask-vue-creator

创建 Flask + Vue.js 全栈项目，采用单端口架构、uv 依赖管理、结构化日志和生产级前端设计。当用户要求以下操作时触发：创建新的 Flask+Vue 项目、搭建 Web 应用、构建全栈 Python+Vue 应用、初始化 Flask Web 项目、设置单端口 Flask 前后端项目。触发词：新建项目、创建项目、搭建项目、Flask项目、Vue项目。

下载

什么时候不该用 `run_in_executor`

不是所有同步 SDK 都适合这么包。容易踩的坑有：

threading.local 或依赖线程局部状态的 SDK（比如某些数据库驱动的 session 绑定），在线程池中行为不可控
SDK 内部用了信号（signal）、os.fork 或全局锁（threading.Lock 共享于多个 executor 线程），可能引发死锁或崩溃
高频小请求场景下，线程切换开销可能反超收益；此时应优先查 SDK 是否有官方异步版本（如 aiohttp 替代 requests，aiomysql 替代 pymysql）
若 SDK 是纯计算型且可释放 GIL（如 numpy 数组运算），用 ProcessPoolExecutor 可能更优，但进程间序列化成本高，需实测