Skip to content

PYTHON-2388 Begin PyMongo 4.0 migration guide #540

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Jan 12, 2021
Merged

PYTHON-2388 Begin PyMongo 4.0 migration guide #540

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
27c2c70
PYTHON-2388 Begin PyMongo 4.0 migration guide
ShaneHarvey Jan 11, 2021
a99915e
PYTHON-2388 Make Python version changes more clear
ShaneHarvey Jan 12, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 8 additions & 1 deletion doc/changelog.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,15 @@ Changelog
Changes in Version 4.0
----------------------

PyMongo 4.0 brings a number of improvements as well as some backward breaking
changes. For example, all APIs deprecated in PyMongo 3.X have been removed.
Be sure to read the changes listed below and the :doc:`migrate-to-pymongo4`
before upgrading from PyMongo 3.x.

.. warning:: PyMongo 4.0 drops support for Python 2.7, 3.4, and 3.5.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: can we move this to the top of the section?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done.


Breaking Changes in 4.0
```````````````````````
.......................

- Removed :mod:`~pymongo.thread_util`.

Expand Down
4 changes: 4 additions & 0 deletions doc/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,9 @@ everything you need to know to use **PyMongo**.
:doc:`faq`
Some questions that come up often.

:doc:`migrate-to-pymongo4`
A PyMongo 3.x to 4.x migration guide.

:doc:`migrate-to-pymongo3`
A PyMongo 2.x to 3.x migration guide.

Expand Down Expand Up @@ -119,5 +122,6 @@ Indices and tables
contributors
changelog
python3
migrate-to-pymongo4
migrate-to-pymongo3
developer/index
46 changes: 46 additions & 0 deletions doc/migrate-to-pymongo4.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
PyMongo 4 Migration Guide
=========================

.. contents::

.. testsetup::

from pymongo import MongoClient, ReadPreference
client = MongoClient()
collection = client.my_database.my_collection

PyMongo 4.0 brings a number of improvements as well as some backward breaking
changes. This guide provides a roadmap for migrating an existing application
from PyMongo 3.x to 4.x or writing libraries that will work with both
PyMongo 3.x and 4.x.

PyMongo 3
---------

The first step in any successful migration involves upgrading to, or
requiring, at least that latest version of PyMongo 3.x. If your project has a
requirements.txt file, add the line "pymongo >= 3.12, < 4.0" until you have
completely migrated to PyMongo 4. Most of the key new methods and options from
PyMongo 4.0 are backported in PyMongo 3.12 making migration much easier.

.. note:: Users of PyMongo 2.X who wish to upgrade to 4.x must first upgrade
to PyMongo 3.x by following the :doc:`migrate-to-pymongo3`.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we add a similar note to the one above to address the unsupported interpreter versions? E.g.

.. note:: Python 2.7, 3.4, and 3.5 users who wish to upgrade to PyMongo 4.x must first upgrade to Python 3.6+. See [add link to resource] for information on upgrading Python versions.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done.

Enable Deprecation Warnings
---------------------------

:exc:`DeprecationWarning` is raised by most methods removed in PyMongo 4.0.
Make sure you enable runtime warnings to see where deprecated functions and
methods are being used in your application::

python -Wd <your application>

Warnings can also be changed to errors::

python -Wd -Werror <your application>

.. note:: Not all deprecated features raise :exc:`DeprecationWarning` when
used. See `Removed features with no migration path`_.

Removed features with no migration path
---------------------------------------