PYTHON-2988 Deprecate MongoClient max_bson_size/max_message_size/max_write_batch_size (#1096)

Author: blink1073

doc/api/pymongo/mongo_client.rst

@@ -22,9 +22,6 @@
       .. autoattribute:: is_primary
       .. autoattribute:: is_mongos
       .. autoattribute:: nodes
-      .. autoattribute:: max_bson_size
-      .. autoattribute:: max_message_size
-      .. autoattribute:: max_write_batch_size
       .. autoattribute:: codec_options
       .. autoattribute:: read_preference
       .. autoattribute:: write_concern
@@ -50,3 +47,6 @@
       .. autoattribute:: max_idle_time_ms
       .. autoattribute:: local_threshold_ms
       .. autoattribute:: server_selection_timeout
+      .. autoattribute:: max_bson_size
+      .. autoattribute:: max_message_size
+      .. autoattribute:: max_write_batch_size

doc/changelog.rst

@@ -42,6 +42,25 @@ Deprecations
   Use :attr:`~pymongo.mongo_client.options.retry_writes` instead.
 - Deprecated :attr:`pymongo.mongo_client.MongoClient.retry_reads`.
   Use :attr:`~pymongo.mongo_client.options.retry_reads` instead.
+- Deprecated :attr:`pymongo.mongo_client.MongoClient.max_bson_size`,
+:attr:`pymongo.mongo_client.MongoClient.max_message_size`, and
+:attr:`pymongo.mongo_client.MongoClient.max_write_batch_size`. These helpers
+were incorrect when in ``loadBalanced=true mode`` and ambiguous in clusters
+with mixed versions. Use the `hello command`_ to get the authoritative
+value from the remote server instead. Code like this::
+
+    max_bson_size = client.max_bson_size
+    max_message_size = client.max_message_size
+    max_write_batch_size = client.max_write_batch_size
+
+can be changed to this::
+
+    doc = client.admin.command('hello')
+    max_bson_size = doc['maxBsonObjectSize']
+    max_message_size = doc['maxMessageSizeBytes']
+    max_write_batch_size = doc['maxWriteBatchSize']
+
+.. _hello command: https://docs.mongodb.com/manual/reference/command/hello/
 
 See the `PyMongo 3.13.0 release notes in JIRA`_ for the list of resolved issues
 in this release.

pymongo/mongo_client.py

@@ -1205,35 +1205,47 @@ def options(self):
 
     @property
     def max_bson_size(self):
-        """The largest BSON object the connected server accepts in bytes.
+        """**DEPRECATED**: The largest BSON object the connected server accepts in bytes.
 
         If the client is not connected, this will block until a connection is
         established or raise ServerSelectionTimeoutError if no server is
         available.
+
+        .. versionchanged:: 3.13
+           Deprecated.
         """
+        warnings.warn("max_bson_size is Deprecated", DeprecationWarning, stacklevel=2)
         return self._server_property("max_bson_size")
 
     @property
     def max_message_size(self):
-        """The largest message the connected server accepts in bytes.
+        """**DEPRECATED**: The largest message the connected server accepts in bytes.
 
         If the client is not connected, this will block until a connection is
         established or raise ServerSelectionTimeoutError if no server is
         available.
+
+        .. versionchanged:: 3.13
+           Deprecated.
         """
+        warnings.warn("max_message_size is Deprecated", DeprecationWarning, stacklevel=2)
         return self._server_property("max_message_size")
 
     @property
     def max_write_batch_size(self):
-        """The maxWriteBatchSize reported by the server.
+        """**DEPRECATED**: The maxWriteBatchSize reported by the server.
 
         If the client is not connected, this will block until a connection is
         established or raise ServerSelectionTimeoutError if no server is
         available.
 
         Returns a default value when connected to server versions prior to
         MongoDB 2.6.
+
+        .. versionchanged:: 3.13
+           Deprecated.
         """
+        warnings.warn("max_write_batch_size is Deprecated", DeprecationWarning, stacklevel=2)
         return self._server_property("max_write_batch_size")
 
     @property