迁移到PyMongo Async

Overview

PyMongo Async API是PyMongo和Motor库的统一。在本指南中，您可以了解将应用程序从PyMongo或Motor迁移到PyMongo Async API时必须进行的更改。

动机

PyMongo Async API旨在替代Motor库。Motor旨在为 Tornado 提供支持，后来添加了 asyncio支持。因此， Motor提供了完整的 asyncio 和 Tornado支持，但仍然依赖线程池来执行网络操作。在某些情况下，这可能会导致使用Motor库时性能下降。为了解决此问题， PyMongo Async API直接在PyMongo中实现了 asyncio支持。在大多数情况下， PyMongo Async API的性能优于Motor。要查看性能基准，请参阅性能基准部分。

同步与异步

要确定是迁移到PyMongo Async API还是继续使用同步PyMongo，请考虑本节中的信息。

如果您的应用程序或使用案例符合以下条件，则首选同步PyMongo ：

您的应用程序执行起来很简单，或者您希望避免在代码中使用异步调用
您的应用程序依赖于串行工作负载或响应时间非常快的工作负载
调试应用程序时，您更喜欢简单的同步逻辑

如果您的应用程序或使用案例符合以下条件，请考虑迁移到PyMongo Async API ：

您的应用程序实施大型、高度并发的工作负载（大约数千个并发操作）
您的应用程序依赖于花费很长时间等待响应或写入数据的工作负载
您的应用程序依赖于其他异步库或框架，例如 FastAPI

性能基准测试

下表显示了使用PyMongo Async API和Motor库执行不同任务的性能基准。每项任务均使用 1000 个文档的 10 次迭代执行。在大多数情况下， PyMongo Async API的性能优于Motor。

操作	Motor性能	PyMongo异步性能
`TestFindManyAndEmptyCursor`	74.074 MB/s	112.490 MB/s
`TestFindManyAndEmptyCursor80Tasks`	37.181 MB/s	89.521 MB/s
`TestFindManyAndEmptyCursor8Tasks`	63.145 MB/s	97.165 MB/s
`TestFindOneByID`	3.121 MB/s	2.922 MB/s
`TestFindOneByID80Tasks`	3.789 MB/s	4.071 MB/s
`TestFindOneByID8Tasks`	3.697 MB/s	3.445 MB/s
`TestFindOneByIDUnlimitedTasks`	3.866 MB/s	4.171 MB/s
`TestGridFsDownload`	573.770 MB/s	603.578 MB/s
`TestGridFsUpload`	430.870 MB/s	444.445 MB/s
`TestLargeDocBulkInsert`	82.631 MB/s	102.105 MB/s
`TestLargeDocClientBulkInsert`	75.057 MB/s	90.345 MB/s
`TestLargeDocCollectionBulkInsert`	85.810 MB/s	101.838 MB/s
`TestLargeDocInsertOne`	84.832 MB/s	101.934 MB/s
`TestLargeDocInsertOneUnlimitedTasks`	120.389 MB/s	163.553 MB/s
`TestRunCommand`	0.036 MB/s	0.034 MB/s
`TestRunCommand80Tasks`	0.042 MB/s	0.043 MB/s
`TestRunCommand8Tasks`	0.039 MB/s	0.041 MB/s
`TestRunCommandUnlimitedTasks`	0.043 MB/s	0.042 MB/s
`TestSmallDocBulkInsert`	35.071 MB/s	38.213 MB/s
`TestSmallDocBulkMixedOps`	0.729 MB/s	0.446 MB/s
`TestSmallDocClientBulkInsert`	25.032 MB/s	25.727 MB/s
`TestSmallDocClientBulkMixedOps`	1.746 MB/s	1.723 MB/s
`TestSmallDocCollectionBulkInsert`	34.144 MB/s	37.666 MB/s
`TestSmallDocInsertOne`	0.539 MB/s	0.572 MB/s
`TestSmallDocInsertOneUnlimitedTasks`	0.740 MB/s	0.786 MB/s

从Motor迁移

警告

Motor弃用

Motor将于 5 月 142026 被弃用。我们强烈建议Motor用户在Motor仍受支持的情况下迁移到PyMongo Async API 。

PyMongo Async API 的功能与Motor库类似，但由于直接使用Python asyncio 而不是将工作委托给线程池，因此可以改善延迟和吞吐量。在大多数情况下，您可以使用 AsyncMongoClient 代替 MotorClient，并将应用程序的导入语句更改为从 pymongo 导入，从而将现有Motor应用程序直接迁移到PyMongo Async。

以下示例显示了在Motor中与PyMongo Async 中使用客户端进行写入操作的导入差异：

# Motor client import
from motor.motor_asyncio import AsyncIOMotorClient
# PyMongo Async client import
from pymongo import AsyncMongoClient

要查看PyMongo Async API中可用的异步方法列表，请参阅异步方法部分。要学习；了解与PyMongo对应的Motor版本，请参阅兼容性指南的 Motor兼容性部分。

以下部分介绍了从Motor迁移到PyMongo Async API时必须在应用程序中实现的方法签名更改。

方法签名更改

以下Motor方法签名在PyMongo Async API中的行为有所不同：

AsyncMongoClient.__init__() 不接受 io_loop 参数。
AsyncCursor.each() 不存在于PyMongo Async API中。
MotorGridOut.stream_to_handler() 不存在于PyMongo Async API中。
AsyncCursor.to_list(0) 在PyMongo Async API中无效。请改用 to_list(None)。
MongoClient 是线程安全的，可由多个线程使用，但是，AsyncMongoClient 不是线程安全的，只能由单个事件循环使用。

警告

Motor用户在切换到PyMongo Async API时可能会遇到性能下降的情况。这是由于PyMongo Async API使用原生asyncio 任务而不是基于线程的执行程序。基于线程的执行程序具有与同步驾驶员类似的性能特征，但速度较慢。这意味着它们对于不符合上述PyMongo Async API标准的工作负载具有更好的性能。

如果您遇到性能下降的情况，请确定您的使用案例是否需要PyMongo Async API 。如果您确定同步PyMongo更适合您的使用案例，请考虑使用带有 asyncio.loop.run_in_executor() 的同步驾驶员以实现异步兼容性。要学习；了解更多信息，请参阅事件循环API文档。

从PyMongo迁移

PyMongo Async API 的行为与PyMongo类似，但所有执行网络操作的方法都是协程，必须等待。要从PyMongo迁移到PyMongo Async，您必须通过以下方式更新代码：

将所有使用的 MongoClient 替换为 AsyncMongoClient。
为所有异步方法调用添加 await 关键字。
如果在函数内调用异步方法，请将该函数标记为 async。

从同步PyMongo迁移到PyMongo Async API时，请记住以下几点：

要将 AsyncCursor 转换为列表，必须使用异步 cursor.to_list() 方法。
PyMongo Async API中的 AsyncCollection.find() 方法是同步的，但会返回 AsyncCursor。要遍历游标，必须使用 async for 循环。
AsyncMongoClient对象不支持connect 关键字参数。
不能跨线程或事件循环股票AsyncMongoClient 对象。
要访问权限异步调用返回结果的属性或方法，必须将该调用正确括在括号中，如以下示例所示：
```
id = (await posts.insert_one(doc)).inserted_id
```

异步方法

有关PyMongo Async API中可用异步方法的完整列表，请参阅API文档。

注意

上述API文档中未列出的任何方法都是同步的。