Docs 菜单

Docs 主页 → 开发应用程序 → Python 驱动程序 → pymongo

升级 PyMongo 版本

在此页面上

  • 概述
  • 显示弃用警告
  • 重大更改

概述

本页介绍升级到新版本的 PyMongo 时必须对应用程序进行的更改。

重要

本指南仅包含对 v 4.0之后的 PyMongo 版本的重大更改。 如果您要从 PyMongo v2 或 v3 升级，请参阅 PyMongo4 迁移指南。

升级前，请执行以下操作：

  • 确保新的 PyMongo 版本与应用程序连接到的 MongoDB Server 版本以及应用程序运行所在的 Python 版本兼容。有关版本兼容性信息，请参阅PyMongo 兼容性页面。

  • 在“重大更改”部分中，解决应用程序正在使用的驱动程序版本与计划升级版本之间发生的任何重大更改。

提示

为了最大限度地减少应用程序将来升级驱动程序版本时所需的更改数量，请使用Stable API。

显示弃用警告

当您使用已弃用的 PyMongo 功能时，驱动程序会引发 DeprecationWarning 。 默认情况下，Python 解释器不会显示这些警告。 要将它们打印到stderr ，请使用-Wd选项启动 Python。

以下示例运行insert.py ，这是一个调用已弃用方法的 Python 应用程序。 解释器会显示DeprecationWarning ，因为 Python 是使用-Wd选项启动的。

$ python3 -Wd insert.py
insert.py:4: DeprecationWarning: insert is deprecated. Use insert_one or insert_many instead.
  client.test.test.insert({})

要将DeprecationWarning消息视为例外，请使用-We选项启动 Python，如以下示例所示：

$ python3 -We insert.py
Traceback (most recent call last):
  File "insert.py", line 4, in <module>
    client.test.test.insert({})
  File "/home/durin/work/mongo-python-driver/pymongo/collection.py", line 2906, in insert
    "instead.", DeprecationWarning, stacklevel=2)
DeprecationWarning: insert is deprecated. Use insert_one or insert_many instead.

提示

有关解释器警告和-W选项的更多信息，请参阅以下 Python 文档：

重大更改

重大更改是对从特定版本的驱动程序开始的约定或行为的更改。 如果在升级驱动程序之前未解决，此类更改可能会导致应用程序无法正常工作。

本部分中的破坏性变更 (breaking change) 按引入它们的驱动程序版本进行分类。升级驱动程序版本时，请解决当前版本和升级版本之间的所有破坏性变更 (breaking change)。

例子

从版本4.0升级

如果您要将 PyMongo 从 v 4.0升级到 v 4.7 ，请解决为版本4.1到4.7列出的所有重大更改（如果有）。

版本 4.7 重大更改

  • 所有内部类和命令中出现的所有SON集合类型均已更改为dict 。

  • options.pool_options.metadata属性现在的类型为dict ，而不是SON 。 以下代码示例显示了这些格式存储数据方式上的差异：

# Before (SON)
>>> from pymongo import MongoClient
>>> client = MongoClient()
>>> client.options.pool_options.metadata
SON([('driver', SON([('name', 'PyMongo'), ('version', '4.7.0.dev0')])), ('os', SON([('type', 'Darwin'), ('name', 'Darwin'), ('architecture', 'arm64'), ('version', '14.3')])), ('platform', 'CPython 3.11.6.final.0')])
# After (dict)
>>> client.options.pool_options.metadata
{'driver': {'name': 'PyMongo', 'version': '4.7.0.dev0'}, 'os': {'type': 'Darwin', 'name': 'Darwin', 'architecture': 'arm64', 'version': '14.3'}, 'platform': 'CPython 3.11.6.final.0'}

要将单层dict对象转换为SON对象，请将dict对象传递给SON构造函数，如以下示例所示：

>>> data_as_dict = client.options.pool_options.metadata
>>> SON(data_as_dict)
SON([('driver', {'name': 'PyMongo', 'version': '4.7.0.dev0'}), ('os', {'type': 'Darwin', 'name': 'Darwin', 'architecture': 'arm64', 'version': '14.3'}), ('platform', 'CPython 3.11.6.final.0')])

如果dict对象有多个层，则必须逐层转换值，如以下示例所示：

>>> def dict_to_SON(data_as_dict: dict[Any, Any]):
...     data_as_SON = SON()
...     for key, value in data_as_dict.items():
...         data_as_SON[key] = dict_to_SON(value) if isinstance(value, dict) else value
...     return data_as_SON
>>>
>>> dict_to_SON(data_as_dict)
SON([('driver', SON([('name', 'PyMongo'), ('version', '4.7.0.dev0')])), ('os', SON([('type', 'Darwin'), ('name', 'Darwin'), ('architecture', 'arm64'), ('version', '14.3')])), ('platform', 'CPython 3.11.6.final.0')])

版本 4.2 破坏性更改

  • 改进对 Pyright 的支持 工具后，ClientSession 类不再使用泛型类型。

  • 客户端字段级加密 (CSFLE) 需要 pymongocrypt v 1.3.0或更高版本。

  • BSON 、 PyMongo和 gridfs 包现在使用 __all__ 变量来声明其公共 API。 如果您的应用程序包含from bson import *语句，请确保它仍然导入必要的 API。

  • estimated_document_count()方法始终使用计数命令。 此命令在 MongoDB 5.0.0版本的 Stable API 中不可用 到5.0.8 。 如果将estimated_document_count()方法与 Stable API 结合使用，则必须升级到 MongoDB Server v 5.0 。 9或更高版本，或将pymongo.server_api.ServerApi.strict选项设置为False 。

← 新增功能
以前版本 →

在此页面上