PYTHON-3247 Mitigate user issues caused by change in directConnection defaults in 4.x

doc/changelog.rst

@@ -89,6 +89,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`

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

pymongo/mongo_client.py

@@ -137,6 +137,11 @@ def __init__(
     ) -> 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