文档菜单
文档首页
/
语言
/
Python
/
PyMongo

升级PyMongo版本

在本页

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

概述

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

重要

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

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

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

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

提示

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

显示弃用警告

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

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

$ 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文档

破坏性更改

破坏性更改是指在特定版本的驱动程序中开始的行为或约定的更改。如果在上传驱动程序之前未解决此类更改，则可能会阻止应用程序正常工作。

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

示例

从版本4.0升级

如果您正在将PyMongo从v4.0升级到v4.7，请解决4.1到4.7版本中列出的所有破坏性更改（如果有）。

4.9版本破坏性更改

版本 4.8 破坏性变更

  • 由于 PyMongo v4.8 使用 hatch 作为其后端构建系统，您不能再使用 setup.py 文件来构建驱动程序。相反，您必须使用 pip 安装 PyMongo。对于可编辑安装，您必须使用 pip v21.3 或更高版本。

版本 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 v1.3.0或更高版本。

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

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

返回

新增功能

下一页

从Motor迁移