From 791abcdb33434e5aa4b98442d77026dcdc92f3b2 Mon Sep 17 00:00:00 2001 From: William Zhou Date: Mon, 22 Mar 2021 14:43:20 -0700 Subject: [PATCH 1/8] add topology description getter --- pymongo/mongo_client.py | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/pymongo/mongo_client.py b/pymongo/mongo_client.py index 21e6d66bb5..c0aad1a112 100644 --- a/pymongo/mongo_client.py +++ b/pymongo/mongo_client.py @@ -891,6 +891,14 @@ def event_listeners(self): """ return self._event_listeners.event_listeners + @property + def topology_description(self): + """(id, topology_type, servers, etc.) of current topology + + .. versionadded:: 3.12 + """ + return self._topology.description + @property def address(self): """(host, port) of the current standalone, primary, or mongos, or None. From 1db39cf6c624c6160eedaa6bb0ddbd56b4e7668e Mon Sep 17 00:00:00 2001 From: William Zhou Date: Mon, 22 Mar 2021 16:39:36 -0700 Subject: [PATCH 2/8] add test --- test/test_client.py | 3 +++ 1 file changed, 3 insertions(+) diff --git a/test/test_client.py b/test/test_client.py index 31850f701e..dd5e37392a 100644 --- a/test/test_client.py +++ b/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. From 2bfc5d46418c9d51c2926023faa57be303ae265c Mon Sep 17 00:00:00 2001 From: William Zhou Date: Tue, 23 Mar 2021 12:38:39 -0700 Subject: [PATCH 3/8] added docs --- doc/api/pymongo/mongo_client.rst | 1 + doc/api/pymongo/server_description.rst | 6 +----- doc/api/pymongo/topology_description.rst | 6 +----- doc/changelog.rst | 2 ++ pymongo/mongo_client.py | 4 +++- 5 files changed, 8 insertions(+), 11 deletions(-) diff --git a/doc/api/pymongo/mongo_client.rst b/doc/api/pymongo/mongo_client.rst index 73a79bb9b2..e48af01ad2 100644 --- a/doc/api/pymongo/mongo_client.rst +++ b/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 diff --git a/doc/api/pymongo/server_description.rst b/doc/api/pymongo/server_description.rst index 2d354fca6f..fc6b55ec74 100644 --- a/doc/api/pymongo/server_description.rst +++ b/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: diff --git a/doc/api/pymongo/topology_description.rst b/doc/api/pymongo/topology_description.rst index b14f1bf2c2..8141507df7 100644 --- a/doc/api/pymongo/topology_description.rst +++ b/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 diff --git a/doc/changelog.rst b/doc/changelog.rst index 62f46f275c..dc08ae724d 100644 --- a/doc/changelog.rst +++ b/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 ....................... diff --git a/pymongo/mongo_client.py b/pymongo/mongo_client.py index c0aad1a112..9d4ab3c5e1 100644 --- a/pymongo/mongo_client.py +++ b/pymongo/mongo_client.py @@ -893,7 +893,9 @@ def event_listeners(self): @property def topology_description(self): - """(id, topology_type, servers, etc.) of current topology + """Returns the current :class:`~pymongo.topology_description.TopologyDescription`. + The returned object is immutable, and should be called periodically/as needed + to avoid using stale information. .. versionadded:: 3.12 """ From f7198fc00d0e5a6390c900316c40dfb862e2ce6e Mon Sep 17 00:00:00 2001 From: William Zhou Date: Tue, 23 Mar 2021 12:38:44 -0700 Subject: [PATCH 4/8] added docs --- doc/api/pymongo/index.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/api/pymongo/index.rst b/doc/api/pymongo/index.rst index 1a54a5b42d..1dca326c21 100644 --- a/doc/api/pymongo/index.rst +++ b/doc/api/pymongo/index.rst @@ -48,6 +48,7 @@ Sub-modules: read_preferences results server_api + topology_description uri_parser write_concern event_loggers From deb30b6d19102633277677b40064d0266ac0dea2 Mon Sep 17 00:00:00 2001 From: William Zhou Date: Tue, 23 Mar 2021 12:45:57 -0700 Subject: [PATCH 5/8] update to 4.0 --- pymongo/mongo_client.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pymongo/mongo_client.py b/pymongo/mongo_client.py index 9d4ab3c5e1..8ecb9186e1 100644 --- a/pymongo/mongo_client.py +++ b/pymongo/mongo_client.py @@ -897,7 +897,7 @@ def topology_description(self): The returned object is immutable, and should be called periodically/as needed to avoid using stale information. - .. versionadded:: 3.12 + .. versionadded:: 4.0 """ return self._topology.description From b24c8e8b2f737e7e6f026e3a390736a8d4a9770f Mon Sep 17 00:00:00 2001 From: William Zhou Date: Tue, 23 Mar 2021 15:44:58 -0700 Subject: [PATCH 6/8] added server description to index --- doc/api/pymongo/index.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/api/pymongo/index.rst b/doc/api/pymongo/index.rst index 1dca326c21..5770145936 100644 --- a/doc/api/pymongo/index.rst +++ b/doc/api/pymongo/index.rst @@ -48,6 +48,7 @@ Sub-modules: read_preferences results server_api + server_description topology_description uri_parser write_concern From 8110535da9547553e12f539517f130baa2026ef8 Mon Sep 17 00:00:00 2001 From: William Zhou Date: Tue, 23 Mar 2021 15:47:26 -0700 Subject: [PATCH 7/8] nits --- doc/changelog.rst | 2 +- pymongo/mongo_client.py | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/changelog.rst b/doc/changelog.rst index dc08ae724d..e0cc3a6913 100644 --- a/doc/changelog.rst +++ b/doc/changelog.rst @@ -11,7 +11,7 @@ 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` +- Added :attr:`pymongo.mongo_client.MongoClient.topology_description`. Breaking Changes in 4.0 ....................... diff --git a/pymongo/mongo_client.py b/pymongo/mongo_client.py index 8ecb9186e1..7c6a15e945 100644 --- a/pymongo/mongo_client.py +++ b/pymongo/mongo_client.py @@ -894,8 +894,8 @@ def event_listeners(self): @property def topology_description(self): """Returns the current :class:`~pymongo.topology_description.TopologyDescription`. - The returned object is immutable, and should be called periodically/as needed - to avoid using stale information. + The returned object is immutable, and should be accessed periodically/as needed + to avoid seeing stale topology information. .. versionadded:: 4.0 """ From 408ace85a7652e560da6662d0fd2f76a80317c73 Mon Sep 17 00:00:00 2001 From: William Zhou Date: Wed, 24 Mar 2021 01:17:10 -0700 Subject: [PATCH 8/8] update documentation --- pymongo/mongo_client.py | 18 +++++++++++++++--- 1 file changed, 15 insertions(+), 3 deletions(-) diff --git a/pymongo/mongo_client.py b/pymongo/mongo_client.py index 7c6a15e945..5dda8efd81 100644 --- a/pymongo/mongo_client.py +++ b/pymongo/mongo_client.py @@ -893,9 +893,21 @@ def event_listeners(self): @property def topology_description(self): - """Returns the current :class:`~pymongo.topology_description.TopologyDescription`. - The returned object is immutable, and should be accessed periodically/as needed - to avoid seeing stale topology information. + """The description of the connected MongoDB deployment. + + >>> client.topology_description + , , ]> + >>> 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 """