PYTHON-2480: Add MongoClient helper to access the current TopologyDescription (#583)

Author: guanlinzhou

doc/api/pymongo/index.rst

@@ -48,6 +48,8 @@ Sub-modules:
    read_preferences
    results
    server_api
+   server_description
+   topology_description
    uri_parser
    write_concern
    event_loggers

doc/api/pymongo/mongo_client.rst

@@ -15,6 +15,7 @@
          Raises :class:`~pymongo.errors.InvalidName` if an invalid database name is used.
 
       .. autoattribute:: event_listeners
+      .. autoattribute:: topology_description
       .. autoattribute:: address
       .. autoattribute:: primary
       .. autoattribute:: secondaries

doc/api/pymongo/server_description.rst

@@ -6,8 +6,4 @@
 .. automodule:: pymongo.server_description
 
    .. autoclass:: pymongo.server_description.ServerDescription()
-
-      .. autoattribute:: address
-      .. autoattribute:: all_hosts
-      .. autoattribute:: server_type
-      .. autoattribute:: server_type_name
+      :members:

doc/api/pymongo/topology_description.rst

@@ -6,9 +6,5 @@
 .. automodule:: pymongo.topology_description
 
    .. autoclass:: pymongo.topology_description.TopologyDescription()
+      :members:
 
-      .. automethod:: has_readable_server(read_preference=ReadPreference.PRIMARY)
-      .. automethod:: has_writable_server
-      .. automethod:: server_descriptions
-      .. autoattribute:: topology_type
-      .. autoattribute:: topology_type_name

doc/changelog.rst

@@ -11,6 +11,8 @@ 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.
 
+- Added :attr:`pymongo.mongo_client.MongoClient.topology_description`.
+
 Breaking Changes in 4.0
 .......................
 

pymongo/mongo_client.py

@@ -891,6 +891,28 @@ def event_listeners(self):
         """
         return self._event_listeners.event_listeners
 
+    @property
+    def topology_description(self):
+        """The description of the connected MongoDB deployment.
+
+        >>> client.topology_description
+        <TopologyDescription id: 605a7b04e76489833a7c6113, topology_type: ReplicaSetWithPrimary, servers: [<ServerDescription ('localhost', 27017) server_type: RSPrimary, rtt: 0.0007973677999995488>, <ServerDescription ('localhost', 27018) server_type: RSSecondary, rtt: 0.0005540556000003249>, <ServerDescription ('localhost', 27019) server_type: RSSecondary, rtt: 0.0010367483999999649>]>
+        >>> client.topology_description.topology_type_name
+        'ReplicaSetWithPrimary'
+
+        Note that the description is periodically updated in the background
+        but the returned object itself is immutable. Access this property again
+        to get a more recent
+        :class:`~pymongo.topology_description.TopologyDescription`.
+
+        :Returns:
+          An instance of
+          :class:`~pymongo.topology_description.TopologyDescription`.
+
+        .. versionadded:: 4.0
+        """
+        return self._topology.description
+
     @property
     def address(self):
         """(host, port) of the current standalone, primary, or mongos, or None.

test/test_client.py

@@ -62,6 +62,7 @@
 from pymongo.server_type import SERVER_TYPE
 from pymongo.settings import TOPOLOGY_TYPE
 from pymongo.topology import _ErrorContext
+from pymongo.topology_description import TopologyDescription
 from pymongo.srv_resolver import _HAVE_DNSPYTHON
 from pymongo.write_concern import WriteConcern
 from test import (client_context,
@@ -597,6 +598,8 @@ def test_init_disconnected(self):
         self.assertFalse(c.secondaries)
         c = rs_or_single_client(connect=False)
         self.assertIsInstance(c.max_write_batch_size, int)
+        self.assertIsInstance(c.topology_description, TopologyDescription)
+        self.assertEqual(c.topology_description, c._topology._description)
 
         if client_context.is_rs:
             # The primary's host and port are from the replica set config.