Skip to content

Commit f93ad6d

Browse files
mongoKartmongoKart
authored
DOCSP-37363 - What's New (#33)
1 parent 92ccf09 commit f93ad6d

File tree

2 files changed

+80
-57
lines changed

2 files changed

+80
-57
lines changed

‎source/upgrade.txt

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -78,6 +78,65 @@ deprecated PyMongo features.
7878
`the warnings module <https://docs.python.org/3/library/warnings.html>`__
7979
and `the -W command line option <https://docs.python.org/3/using/cmdline.html#cmdoption-W>`__.
8080

81+
82+
Breaking Changes
83+
----------------
84+
85+
A breaking change is a modification of a convention or a behavior starting in a specific
86+
version of the driver. This type of change may prevent your application from working
87+
properly if not addressed before upgrading the driver.
88+
89+
The breaking changes in this section are categorized by the driver version that introduced
90+
them. When upgrading driver versions, address all the breaking changes between the current
91+
and upgrade versions. For example, if you're upgrading {+driver-short+} from v4.0 to v4.7,
92+
address all breaking changes from the version after v4.0, including any listed under v4.7.
93+
94+
.. _version-4.7-breaking-changes:
95+
96+
Version 4.7 Breaking Changes
97+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
98+
99+
- All occurrences of the ``SON`` collection type on all internal classes and
100+
commands have been changed to ``dict``.
101+
- The ``options.pool_options.metadata`` property is now of type ``dict``, not
102+
``SON``. The following code example shows the differences in how these formats
103+
store data:
104+
105+
.. code-block:: python
106+
107+
# Before
108+
>>> from pymongo import MongoClient
109+
>>> client = MongoClient()
110+
>>> client.options.pool_options.metadata
111+
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')])
112+
113+
# After
114+
>>> client.options.pool_options.metadata
115+
{'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'}
116+
117+
To convert a single-layer ``dict`` object to a ``SON`` object, pass the ``dict`` object to
118+
the ``SON`` constructor, as shown in the following example:
119+
120+
.. code-block:: python
121+
122+
>>> data_as_dict = client.options.pool_options.metadata
123+
>>> SON(data_as_dict)
124+
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')])
125+
126+
If the ``dict`` object has multiple layers, you must convert the values one at a time,
127+
as shown in the following example:
128+
129+
.. code-block:: python
130+
131+
>>> def dict_to_SON(data_as_dict: dict[Any, Any]):
132+
... data_as_SON = SON()
133+
... for key, value in data_as_dict.items():
134+
... data_as_SON[key] = dict_to_SON(value) if isinstance(value, dict) else value
135+
... return data_as_SON
136+
>>>
137+
>>> dict_to_SON(data_as_dict)
138+
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')])
139+
81140
.. _pymongo4-migration-guide:
82141

83142
PyMongo 4 Migration Guide

‎source/whats-new.txt

Lines changed: 21 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,3 @@
1-
.. uses changelog.rst
2-
31
.. _pymongo-whats-new:
42

53
==========
@@ -12,7 +10,6 @@ What's New
1210
:depth: 1
1311
:class: singlecol
1412

15-
1613
.. facet::
1714
:name: genre
1815
:values: reference
@@ -31,71 +28,38 @@ Learn what's new in:
3128
What's New in 4.7
3229
-----------------
3330

31+
.. warning:: Breaking Changes
32+
33+
{+driver-short+} v4.7 contains breaking changes. For more information, see
34+
:ref:`version-4.7-breaking-changes`.
35+
3436
The {+driver-short+} v4.7 release includes the following new features:
3537

36-
- Added the ``~pymongo.hello.Hello.server_connection_id``,
37-
``pymongo.monitoring.CommandStartedEvent.server_connection_id``,
38-
``pymongo.monitoring.CommandSucceededEvent.server_connection_id``, and
39-
``pymongo.monitoring.CommandFailedEvent.server_connection_id`` properties.
40-
- Added support for named Key Management Service (KMS) providers for Client-Side Field
41-
Level Encryption (CSFLE).
42-
Previously supported KMS providers were only: aws, azure, gcp, kmip, and local.
43-
The KMS provider is now expanded to support name suffixes (e.g. local:myname).
44-
Named KMS providers enables more than one of each KMS provider type to be configured.
45-
See the docstring for ``~pymongo.encryption_options.AutoEncryptionOpts``.
46-
Note that named KMS providers requires pymongocrypt >=1.9 and libmongocrypt >=1.9.
38+
- Added the ``Hello.connection_id``,
39+
`CommandStartedEvent.server_connection_id <https://pymongo.readthedocs.io/en/latest/api/pymongo/monitoring.html#pymongo.monitoring.CommandStartedEvent.server_connection_id>`__,
40+
`CommandSucceededEvent.server_connection_id <https://pymongo.readthedocs.io/en/latest/api/pymongo/monitoring.html#pymongo.monitoring.CommandSucceededEvent.server_connection_id>`__,
41+
and `CommandFailedEvent.server_connection_id <https://pymongo.readthedocs.io/en/latest/api/pymongo/monitoring.html#pymongo.monitoring.CommandFailedEvent.server_connection_id>`__
42+
properties.
43+
- Added support for name suffixes for Key Management Service (KMS) providers for Client-Side Field
44+
Level Encryption (CSFLE). This feature requires ``pymongocrypt`` v1.9+ and
45+
``libmongocrypt`` v1.9+. For more information, see the API documentation for the
46+
`AutoEncryptionOpts <https://pymongo.readthedocs.io/en/latest/api/pymongo/encryption_options.html#pymongo.encryption_options.AutoEncryptionOpts>`__
47+
class.
4748
- Improved the performance of encoding BSON documents to JSON.
48-
- The ``~pymongo.encryption.ClientEncryption.encrypt`` method and
49-
the ``~pymongo.encryption.ClientEncryption.encrypt_expression`` method now allow ``key_id``
50-
to be passed in as a ``uuid.UUID``.
51-
- Fixed a bug where inflating a ``~bson.raw_bson.RawBSONDocument`` containing a
52-
``~bson.code.Code`` would cause an error.
49+
- The ``ClientEncryption.encrypt()`` and ``ClientEncryption.encrypt_expression()`` methods
50+
now allow the ``key_id`` argument to be passed in as a ``UUID`` Object.
51+
- Inflating a ``RawBSONDocument`` object containing a ``Code`` value no longer causes an
52+
error.
5353
- Fixed a bug in Python 3.12 where the error message
5454
``RuntimeError: can't create new thread at interpreter shutdown``
5555
could be written to ``stderr`` when a ``MongoClient`` thread starts as the Python
5656
interpreter is shutting down.
57-
- Fixed a bug where ``~bson.int64.Int64`` instances could not always be encoded by
57+
- Fixed a bug where ``Int64`` instances could not always be encoded by
5858
`orjson <https://github.com/ijl/orjson>`__. Code like the following example now
59-
run correctly:
59+
runs correctly:
6060

6161
.. code-block:: python
6262

6363
>>> import orjson
6464
>>> from bson import json_util
6565
>>> orjson.dumps({'a': Int64(1)}, default=json_util.default, option=orjson.OPT_PASSTHROUGH_SUBCLASS)
66-
67-
68-
Breaking Changes
69-
````````````````
70-
71-
- Replaced usage of ``bson.son.SON`` on all internal classes and commands to dict,
72-
``options.pool_options.metadata`` is now of type ``dict`` as opposed to ``bson.son.SON``.
73-
Here's some examples of how this changes expected output as well as how to convert from ``dict`` to ``bson.son.SON``:
74-
75-
.. code-block:: python
76-
77-
# Before
78-
>>> from pymongo import MongoClient
79-
>>> client = MongoClient()
80-
>>> client.options.pool_options.metadata
81-
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')])
82-
83-
# After
84-
>>> client.options.pool_options.metadata
85-
{'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'}
86-
87-
# To convert from dict to SON
88-
# This will only convert the first layer of the dictionary
89-
>>> data_as_dict = client.options.pool_options.metadata
90-
>>> SON(data_as_dict)
91-
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')])
92-
93-
# To convert from dict to SON on a nested dictionary
94-
>>> def dict_to_SON(data_as_dict: dict[Any, Any]):
95-
... data_as_SON = SON()
96-
... for key, value in data_as_dict.items():
97-
... data_as_SON[key] = dict_to_SON(value) if isinstance(value, dict) else value
98-
... return data_as_SON
99-
>>>
100-
>>> dict_to_SON(data_as_dict)
101-
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')])

0 commit comments

Comments
 (0)