Upgrade PyMongo Versions (original) (raw)

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

Important

This guide includes breaking changes to only PyMongo versions after v4.0. If you're upgrading from PyMongo v2 or v3, see thePyMongo 4 Migration Guide.

Before you upgrade, perform the following actions:

Tip

To minimize the number of changes your application requires when upgrading driver versions in the future, use theStable API.

When you use a deprecated PyMongo feature, the driver raises aDeprecationWarning. 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.

Tip

For more information about interpreter warnings and the -W option, see the following Python documentation:

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.

Example

Upgrading from Version 4.0

If you're upgrading PyMongo from v4.0 to v4.7, address all breaking changes listed for versions 4.1 to 4.7, if any.


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

To convert a single-layer dict object to a SON object, pass the dict object to the SON constructor, as shown in the following example:


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

If the dict object has multiple layers, you must convert the values one at a time, as shown in the following example:


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