Upgrade PyMongo Versions

Overview

This page describes the changes you must make to your application when you upgrade to a new version of PyMongo.

Before you upgrade, perform the following actions:

• Ensure the new PyMongo version is compatible with the MongoDB Server versions your application connects to and the Python version your application runs on. For version compatibility information, see the PyMongo Compatibility page.

• Address any breaking changes between the driver version your application is using and your planned upgrade version in the Breaking Changes section.

Show Deprecation Warnings

When you use a deprecated PyMongo feature, the driver raises a DeprecationWarning. By default, the Python interpreter silences these warnings. To print them to stderr, start Python with the -Wd options.

The following example runs insert.py, a Python application that calls a deprecated method. The interpreter shows a DeprecationWarning because Python was started with the -Wd options.

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

To treat DeprecationWarning messages as exceptions, start Python with the -We options instead, as shown in the following example:

$ 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.

Breaking Changes

A breaking change is a change of a convention or a behavior starting in a specific version of the driver. This type of change may prevent your application from working properly if not addressed before upgrading the driver.

The breaking changes in this section are categorized by the driver version that introduced them. When upgrading driver versions, address all the breaking changes between the current and upgrade versions.

# 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'}

>>> 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')])

>>> 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')])