From 252ed1cef67663e125ed07eee92ef8e096cc2ad0 Mon Sep 17 00:00:00 2001
From: Julius Park <Juliusgeo@gmail.com>
Date: Tue, 3 May 2022 14:49:18 -0700
Subject: [PATCH] PYTHON-3247 Mitigate user issues caused by change in
 directConnection defaults in 4.x (#935)

---
 doc/changelog.rst           |  9 +++++++++
 doc/migrate-to-pymongo4.rst | 24 ++++++++++++++++++++++++
 pymongo/mongo_client.py     |  5 +++++
 3 files changed, 38 insertions(+)

diff --git a/doc/changelog.rst b/doc/changelog.rst
index 3d2f7cadc..97795fdfb 100644
--- a/doc/changelog.rst
+++ b/doc/changelog.rst
@@ -120,6 +120,15 @@ Changes in Version 4.0
 
 .. warning:: PyMongo 4.0 drops support for MongoDB 2.6, 3.0, 3.2, and 3.4.
 
+.. warning:: PyMongo 4.0 changes the default value of the ``directConnection`` URI option and
+  keyword argument to :class:`~pymongo.mongo_client.MongoClient`
+  to ``False`` instead of ``None``, allowing for the automatic
+  discovery of replica sets. This means that if you
+  want a direct connection to a single server you must pass
+  ``directConnection=True`` as a URI option or keyword argument.
+  For more details, see the relevant section of the PyMongo 4.x migration
+  guide: :ref:`pymongo4-migration-direct-connection`.
+
 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`
diff --git a/doc/migrate-to-pymongo4.rst b/doc/migrate-to-pymongo4.rst
index 5f75ed176..d70d7b8a2 100644
--- a/doc/migrate-to-pymongo4.rst
+++ b/doc/migrate-to-pymongo4.rst
@@ -65,6 +65,8 @@ get the same behavior.
 MongoClient
 -----------
 
+.. _pymongo4-migration-direct-connection:
+
 ``directConnection`` defaults to False
 ......................................
 
@@ -74,6 +76,28 @@ allowing for the automatic discovery of replica sets. This means that if you
 want a direct connection to a single server you must pass
 ``directConnection=True`` as a URI option or keyword argument.
 
+If you see any :exc:`~pymongo.errors.ServerSelectionTimeoutError`'s after upgrading from PyMongo 3 to 4.x, you likely
+need to add ``directConnection=True`` when creating the client.
+Here are some example errors:
+
+.. code-block::
+
+        pymongo.errors.ServerSelectionTimeoutError: mongo_node2: [Errno 8] nodename nor servname
+        provided, or not known,mongo_node1:27017
+
+.. code-block::
+
+        ServerSelectionTimeoutError: No servers match selector "Primary()", Timeout: 30s,
+        Topology Description: ...
+
+
+Additionally, the "isWritablePrimary" attribute of a hello command sent back by the server will
+always be True if ``directConnection=False``::
+
+   >>> client.admin.command('hello')['isWritablePrimary']
+   True
+
+
 The waitQueueMultiple parameter is removed
 ..........................................
 
diff --git a/pymongo/mongo_client.py b/pymongo/mongo_client.py
index 5c7e7cb17..6601c18ac 100644
--- a/pymongo/mongo_client.py
+++ b/pymongo/mongo_client.py
@@ -137,6 +137,11 @@ class MongoClient(common.BaseObject, Generic[_DocumentType]):
     ) -> None:
         """Client for a MongoDB instance, a replica set, or a set of mongoses.
 
+        .. warning:: Starting in PyMongo 4.0, ``directConnection`` now has a default value of
+          False instead of None.
+          For more details, see the relevant section of the PyMongo 4.x migration guide:
+          :ref:`pymongo4-migration-direct-connection`.
+
         The client object is thread-safe and has connection-pooling built in.
         If an operation fails because of a network error,
         :class:`~pymongo.errors.ConnectionFailure` is raised and the client