PYTHON-2164 Add MongoClient.options, remove redundant properties (#772)

Author: ShaneHarvey

doc/api/pymongo/client_options.rst

@@ -0,0 +1,7 @@
+:mod:`client_options` -- Read only configuration options for a MongoClient.
+===========================================================================
+
+.. automodule:: pymongo.client_options
+
+   .. autoclass:: pymongo.client_options.ClientOptions()
+      :members:

doc/api/pymongo/index.rst

@@ -29,6 +29,7 @@ Sub-modules:
 
    bulk
    change_stream
+   client_options
    client_session
    collation
    collection

doc/api/pymongo/mongo_client.rst

@@ -14,24 +14,19 @@
 
          Raises :class:`~pymongo.errors.InvalidName` if an invalid database name is used.
 
-      .. autoattribute:: event_listeners
       .. autoattribute:: topology_description
       .. autoattribute:: address
       .. autoattribute:: primary
       .. autoattribute:: secondaries
       .. autoattribute:: arbiters
       .. autoattribute:: is_primary
       .. autoattribute:: is_mongos
-      .. autoattribute:: max_pool_size
-      .. autoattribute:: min_pool_size
-      .. autoattribute:: max_idle_time_ms
       .. autoattribute:: nodes
-      .. autoattribute:: local_threshold_ms
-      .. autoattribute:: server_selection_timeout
       .. autoattribute:: codec_options
       .. autoattribute:: read_preference
       .. autoattribute:: write_concern
       .. autoattribute:: read_concern
+      .. autoattribute:: options
       .. automethod:: start_session
       .. automethod:: list_databases
       .. automethod:: list_database_names

doc/api/pymongo/pool.rst

@@ -2,5 +2,6 @@
 ==============================================================
 
 .. automodule:: pymongo.pool
-   :synopsis: Pool module for use with a MongoDB client.
-   :members:
+
+   .. autoclass:: pymongo.pool.PoolOptions()
+      :members:

doc/changelog.rst

@@ -36,6 +36,13 @@ Breaking Changes in 4.0
 - Removed :attr:`pymongo.mongo_client.MongoClient.max_bson_size`.
 - Removed :attr:`pymongo.mongo_client.MongoClient.max_message_size`.
 - Removed :attr:`pymongo.mongo_client.MongoClient.max_write_batch_size`.
+- Removed :attr:`pymongo.mongo_client.MongoClient.event_listeners`.
+- Removed :attr:`pymongo.mongo_client.MongoClient.max_pool_size`.
+- Removed :attr:`pymongo.mongo_client.MongoClient.max_idle_time_ms`.
+- Removed :attr:`pymongo.mongo_client.MongoClient.local_threshold_ms`.
+- Removed :attr:`pymongo.mongo_client.MongoClient.server_selection_timeout`.
+- Removed :attr:`pymongo.mongo_client.MongoClient.retry_writes`.
+- Removed :attr:`pymongo.mongo_client.MongoClient.retry_reads`.
 - Removed :meth:`pymongo.database.Database.eval`,
   :data:`pymongo.database.Database.system_js` and
   :class:`pymongo.database.SystemJS`.
@@ -180,6 +187,8 @@ Notable improvements
   will connect to. More specifically, when a mongodb+srv:// connection string
   resolves to more than `srvMaxHosts` number of hosts, the client will randomly
   choose a `srvMaxHosts` sized subset of hosts.
+- Added :attr:`pymongo.mongo_client.MongoClient.options` for read-only access
+  to a client's configuration options.
 
 Issues Resolved
 ...............
@@ -2121,7 +2130,7 @@ Important new features:
 - The ``max_pool_size`` option for :class:`~pymongo.mongo_client.MongoClient`
   and :class:`~pymongo.mongo_replica_set_client.MongoReplicaSetClient` now
   actually caps the number of sockets the pool will open concurrently.
-  Once the pool has reached :attr:`~pymongo.mongo_client.MongoClient.max_pool_size`
+  Once the pool has reaches max_pool_size
   operations will block waiting for a socket to become available. If
   ``waitQueueTimeoutMS`` is set, an operation that blocks waiting for a socket
   will raise :exc:`~pymongo.errors.ConnectionFailure` after the timeout. By

doc/migrate-to-pymongo4.rst

@@ -196,6 +196,37 @@ can be changed to this::
 
 .. _hello command: https://docs.mongodb.com/manual/reference/command/hello/
 
+MongoClient.event_listeners and other configuration option helpers are removed
+..............................................................................
+
+The following client configuration option helpers are removed:
+- :attr:`pymongo.mongo_client.MongoClient.event_listeners`.
+- :attr:`pymongo.mongo_client.MongoClient.max_pool_size`.
+- :attr:`pymongo.mongo_client.MongoClient.max_idle_time_ms`.
+- :attr:`pymongo.mongo_client.MongoClient.local_threshold_ms`.
+- :attr:`pymongo.mongo_client.MongoClient.server_selection_timeout`.
+- :attr:`pymongo.mongo_client.MongoClient.retry_writes`.
+- :attr:`pymongo.mongo_client.MongoClient.retry_reads`.
+
+These helpers have been replaced by
+:attr:`pymongo.mongo_client.MongoClient.options`. Code like this::
+
+    client.event_listeners
+    client.local_threshold_ms
+    client.server_selection_timeout
+    client.max_pool_size
+    client.min_pool_size
+    client.max_idle_time_ms
+
+can be changed to this::
+
+    client.options.event_listeners
+    client.options.local_threshold_ms
+    client.options.server_selection_timeout
+    client.options.pool_options.max_pool_size
+    client.options.pool_options.min_pool_size
+    client.options.pool_options.max_idle_time_seconds
+
 ``tz_aware`` defaults to ``False``
 ..................................
 

pymongo/client_options.py

@@ -153,8 +153,12 @@ def _parse_pool_options(options):
 
 
 class ClientOptions(object):
+    """Read only configuration options for a MongoClient.
 
-    """ClientOptions"""
+    Should not be instantiated directly by application developers. Access
+    a client's options via :attr:`pymongo.mongo_client.MongoClient.options`
+    instead.
+    """
 
     def __init__(self, username, password, database, options):
         self.__options = options
@@ -200,7 +204,7 @@ def codec_options(self):
         return self.__codec_options
 
     @property
-    def credentials(self):
+    def _credentials(self):
         """A :class:`~pymongo.auth.MongoCredentials` instance or None."""
         return self.__credentials
 
@@ -272,3 +276,13 @@ def auto_encryption_opts(self):
     def load_balanced(self):
         """True if the client was configured to connect to a load balancer."""
         return self.__load_balanced
+
+    @property
+    def event_listeners(self):
+        """The event listeners registered for this client.
+
+        See :mod:`~pymongo.monitoring` for details.
+
+        .. versionadded:: 4.0
+        """
+        return self.__pool_options._event_listeners.event_listeners()

pymongo/encryption.py

@@ -261,7 +261,7 @@ def __init__(self, client, opts):
         self._internal_client = None
 
         def _get_internal_client(encrypter, mongo_client):
-            if mongo_client.max_pool_size is None:
+            if mongo_client.options.pool_options.max_pool_size is None:
                 # Unlimited pool size, use the same client.
                 return mongo_client
             # Else - limited pool size, use an internal client.

pymongo/mongo_client.py

@@ -722,14 +722,14 @@ def __init__(
         self.__lock = threading.Lock()
         self.__kill_cursors_queue = []
 
-        self._event_listeners = options.pool_options.event_listeners
+        self._event_listeners = options.pool_options._event_listeners
         super(MongoClient, self).__init__(options.codec_options,
                                           options.read_preference,
                                           options.write_concern,
                                           options.read_concern)
 
         self.__all_credentials = {}
-        creds = options.credentials
+        creds = options._credentials
         if creds:
             self.__all_credentials[creds.source] = creds
 
@@ -893,14 +893,6 @@ def watch(self, pipeline=None, full_document=None, resume_after=None,
             batch_size, collation, start_at_operation_time, session,
             start_after)
 
-    @property
-    def event_listeners(self):
-        """The event listeners registered for this client.
-
-        See :mod:`~pymongo.monitoring` for details.
-        """
-        return self._event_listeners.event_listeners()
-
     @property
     def topology_description(self):
         """The description of the connected MongoDB deployment.
@@ -1005,40 +997,6 @@ def is_mongos(self):
         """
         return self._server_property('server_type') == SERVER_TYPE.Mongos
 
-    @property
-    def max_pool_size(self):
-        """The maximum allowable number of concurrent connections to each
-        connected server. Requests to a server will block if there are
-        `maxPoolSize` outstanding connections to the requested server.
-        Defaults to 100. Can be either 0 or None, in which case there is no
-        limit on the number of concurrent connections.
-
-        When a server's pool has reached `max_pool_size`, operations for that
-        server block waiting for a socket to be returned to the pool. If
-        ``waitQueueTimeoutMS`` is set, a blocked operation will raise
-        :exc:`~pymongo.errors.ConnectionFailure` after a timeout.
-        By default ``waitQueueTimeoutMS`` is not set.
-        """
-        return self.__options.pool_options.max_pool_size
-
-    @property
-    def min_pool_size(self):
-        """The minimum required number of concurrent connections that the pool
-        will maintain to each connected server. Default is 0.
-        """
-        return self.__options.pool_options.min_pool_size
-
-    @property
-    def max_idle_time_ms(self):
-        """The maximum number of milliseconds that a connection can remain
-        idle in the pool before being removed and replaced. Defaults to
-        `None` (no limit).
-        """
-        seconds = self.__options.pool_options.max_idle_time_seconds
-        if seconds is None:
-            return None
-        return 1000 * seconds
-
     @property
     def nodes(self):
         """Set of all currently connected servers.
@@ -1054,38 +1012,15 @@ def nodes(self):
         return frozenset(s.address for s in description.known_servers)
 
     @property
-    def local_threshold_ms(self):
-        """The local threshold for this instance."""
-        return self.__options.local_threshold_ms
-
-    @property
-    def server_selection_timeout(self):
-        """The server selection timeout for this instance in seconds."""
-        return self.__options.server_selection_timeout
-
-    @property
-    def retry_writes(self):
-        """If this instance should retry supported write operations."""
-        return self.__options.retry_writes
+    def options(self):
+        """The configuration options for this client.
 
-    @property
-    def retry_reads(self):
-        """If this instance should retry supported write operations."""
-        return self.__options.retry_reads
+        :Returns:
+          An instance of :class:`~pymongo.client_options.ClientOptions`.
 
-    def _is_writable(self):
-        """Attempt to connect to a writable server, or return False.
+        .. versionadded:: 4.0
         """
-        topology = self._get_topology()  # Starts monitors if necessary.
-        try:
-            svr = topology.select_server(writable_server_selector)
-
-            # When directly connected to a secondary, arbiter, etc.,
-            # select_server returns it, whatever the selector. Check
-            # again if the server is writable.
-            return svr.description.is_writable
-        except ConnectionFailure:
-            return False
+        return self.__options
 
     def _end_sessions(self, session_ids):
         """Send endSessions command(s) with the given session ids."""
@@ -1282,7 +1217,7 @@ def _retry_with_session(self, retryable, func, session, bulk):
 
         Re-raises any exception thrown by func().
         """
-        retryable = (retryable and self.retry_writes
+        retryable = (retryable and self.options.retry_writes
                      and session and not session.in_transaction)
         return self._retry_internal(retryable, func, session, bulk)
 
@@ -1353,7 +1288,7 @@ def _retryable_read(self, func, read_pref, session, address=None,
         Re-raises any exception thrown by func().
         """
         retryable = (retryable and
-                     self.retry_reads
+                     self.options.retry_reads
                      and not (session and session.in_transaction))
         last_error = None
         retrying = False

pymongo/monitor.py

@@ -123,7 +123,7 @@ def __init__(
         self._server_description = server_description
         self._pool = pool
         self._settings = topology_settings
-        self._listeners = self._settings._pool_options.event_listeners
+        self._listeners = self._settings._pool_options._event_listeners
         pub = self._listeners is not None
         self._publish = pub and self._listeners.enabled_for_server_heartbeat
         self._cancel_context = None