文档菜单

文档首页 → 开发应用程序 → Python 驱动程序 → PyMongo

升级 PyMongo 版本

本页内容

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

概述

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

重要

本指南仅包括对 v4.0 之后 PyMongo 版本的重大更改。如果您是从 PyMongo v2 或 v3 升级，请参阅PyMongo 4 迁移指南。

在升级之前，请执行以下操作

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

  • 在重大更改部分解决应用程序使用的驱动程序版本和计划升级版本之间的任何重大更改。

提示

为了在将来升级驱动程序版本时最小化应用程序所需的更改数量，请使用稳定 API。

显示弃用警告

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

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

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

要将 弃用警告 消息视为异常，请使用 -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 文档

重大变更

重大变更是指在驱动程序特定版本中开始的一项约定或行为的变化。如果在使用驱动程序之前不解决此类变更，则可能会阻止您的应用程序正常运行。

本节中的重大变更按引入它们的驱动程序版本进行分类。在升级驱动程序版本时，解决当前和升级版本之间的所有重大变更。

示例

从4.0版本升级

如果您正在将PyMongo从v4.0升级到v4.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 类不再使用泛型类型。

  • Client-Side Field Level Encryption (CSFLE) 需要 pymongocrypt v1.3.0 或更高版本。

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

  • estimated_document_count() 方法始终使用计数命令。此命令在 MongoDB 版本 5.0.0 到 5.0.8 的稳定 API 中不可用。如果您使用稳定 API 的 estimated_document_count() 方法，必须升级到 MongoDB 服务器 v5.0.9 或更高版本，或将 pymongo.server_api.ServerApi.strict 选项设置为 False。

← 最新更新
前一个版本 →

本页内容