PYTHON-2993 Deprecate MongoClient read only config option helpers and add client.options (#1095)

Author: blink1073

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

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

doc/api/pymongo/mongo_client.rst

@@ -14,23 +14,17 @@
 
          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:: max_bson_size
       .. autoattribute:: max_message_size
       .. autoattribute:: max_write_batch_size
-      .. autoattribute:: local_threshold_ms
-      .. autoattribute:: server_selection_timeout
       .. autoattribute:: codec_options
       .. autoattribute:: read_preference
       .. autoattribute:: write_concern
@@ -50,3 +44,9 @@
       .. autoattribute:: is_locked
       .. automethod:: fsync
       .. automethod:: unlock
+      .. autoattribute:: event_listeners
+      .. autoattribute:: max_pool_size
+      .. autoattribute:: min_pool_size
+      .. autoattribute:: max_idle_time_ms
+      .. autoattribute:: local_threshold_ms
+      .. autoattribute:: server_selection_timeout

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

@@ -4,6 +4,12 @@ Changelog
 Changes in Version 3.13.0
 -------------------------
 
+Notable improvements
+....................
+- Added :attr:`pymongo.mongo_client.MongoClient.options` for read-only access
+  to a client's configuration options.
+
+
 Issues Resolved
 ...............
 
@@ -19,10 +25,23 @@ Bug fixes
 
 Deprecations
 ............
-
 - Deprecated :meth:`~pymongo.collection.Collection.map_reduce` and
   :meth:`~pymongo.collection.Collection.inline_map_reduce`.
   Use :meth:`~pymongo.collection.Collection.aggregate` instead.
+- Deprecated :attr:`pymongo.mongo_client.MongoClient.event_listeners`.
+  Use :attr:`~pymongo.mongo_client.options.event_listeners` instead.
+- Deprecated :attr:`pymongo.mongo_client.MongoClient.max_pool_size`.
+  Use :attr:`~pymongo.mongo_client.options.pool_options.max_pool_size` instead.
+- Deprecated :attr:`pymongo.mongo_client.MongoClient.max_idle_time_ms`.
+  Use :attr:`~pymongo.mongo_client.options.pool_options.max_idle_time_seconds` instead.
+- Deprecated :attr:`pymongo.mongo_client.MongoClient.local_threshold_ms`.
+  Use :attr:`~pymongo.mongo_client.options.local_threshold_ms` instead.
+- Deprecated :attr:`pymongo.mongo_client.MongoClient.server_selection_timeout`.
+  Use :attr:`~pymongo.mongo_client.options.server_selection_timeout` instead.
+- Deprecated :attr:`pymongo.mongo_client.MongoClient.retry_writes`.
+  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.
 
 See the `PyMongo 3.13.0 release notes in JIRA`_ for the list of resolved issues
 in this release.

pymongo/client_options.py

@@ -149,8 +149,11 @@ def _parse_pool_options(options):
 
 
 class ClientOptions(object):
-
-    """ClientOptions"""
+    """Read only configuration options for a MongoClient.
+    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
@@ -193,7 +196,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
 
@@ -265,3 +268,11 @@ 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

@@ -269,7 +269,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

@@ -735,7 +735,7 @@ def __init__(
         self.__cursor_manager = None
         self.__kill_cursors_queue = []
 
-        self._event_listeners = options.pool_options.event_listeners
+        self._event_listeners = options.pool_options._event_listeners
 
         # Cache of existing indexes used by ensure_index ops.
         self.__index_cache = {}
@@ -749,7 +749,7 @@ def __init__(
         )
 
         self.__all_credentials = {}
-        creds = options.credentials
+        creds = options._credentials
         if creds:
             self._cache_credentials(creds.source, creds)
 
@@ -1017,10 +1017,14 @@ def watch(
 
     @property
     def event_listeners(self):
-        """The event listeners registered for this client.
+        """**DEPRECATED**: The event listeners registered for this client.
 
         See :mod:`~pymongo.monitoring` for details.
+
+        .. versionchanged:: 3.13
+           Deprecated.  Use ``client.options.event_listeners`` instead.
         """
+        warnings.warn("event_listeners is deprecated.  Use ``client.options.event_listeners`` instead.", DeprecationWarning, stacklevel=2)
         return self._event_listeners.event_listeners
 
     @property
@@ -1132,7 +1136,7 @@ def is_mongos(self):
 
     @property
     def max_pool_size(self):
-        """The maximum allowable number of concurrent connections to each
+        """**DEPRECATED**: 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. Cannot be 0.
@@ -1142,22 +1146,33 @@ def max_pool_size(self):
         ``waitQueueTimeoutMS`` is set, a blocked operation will raise
         :exc:`~pymongo.errors.ConnectionFailure` after a timeout.
         By default ``waitQueueTimeoutMS`` is not set.
+
+        .. versionchanged:: 3.13
+           Deprecated.  Use ``client.options.pool_options.max_pool_size`` instead.
         """
+        warnings.warn("max_pool_size is deprecated.  Use ``client.options.pool_options.max_pool_size`` instead.", DeprecationWarning, stacklevel=2)
         return self.__options.pool_options.max_pool_size
 
     @property
     def min_pool_size(self):
-        """The minimum required number of concurrent connections that the pool
+        """**DEPRECATED**: The minimum required number of concurrent connections that the pool
         will maintain to each connected server. Default is 0.
+        .. versionchanged:: 3.13
+           Deprecated.
         """
+        warnings.warn("min_pool_size is deprecated.  Use ``client.options.pool_options.min_pool_size`` instead.", DeprecationWarning, stacklevel=2)
         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
+        """**DEPRECATED**: The maximum number of milliseconds that a connection can remain
         idle in the pool before being removed and replaced. Defaults to
         `None` (no limit).
+
+        .. versionchanged:: 3.13
+           Deprecated.  Use ``client.options.pool_options.max_idle_time_seconds`` instead.
         """
+        warnings.warn("max_idle_time_ms is deprecated. Use ``client.options.pool_options.max_idle_time_seconds`` instead.", DeprecationWarning, stacklevel=2)
         seconds = self.__options.pool_options.max_idle_time_seconds
         if seconds is None:
             return None
@@ -1177,6 +1192,17 @@ def nodes(self):
         description = self._topology.description
         return frozenset(s.address for s in description.known_servers)
 
+    @property
+    def options(self):
+        """The configuration options for this client.
+
+        :Returns:
+          An instance of :class:`~pymongo.client_options.ClientOptions`.
+
+        .. versionadded:: 3.13
+        """
+        return self.__options
+
     @property
     def max_bson_size(self):
         """The largest BSON object the connected server accepts in bytes.
@@ -1212,22 +1238,42 @@ def max_write_batch_size(self):
 
     @property
     def local_threshold_ms(self):
-        """The local threshold for this instance."""
+        """**DEPRECATED**: The local threshold for this instance.
+
+        .. versionchanged:: 3.13
+           Deprecated.  Use ``client.options.local_threshold_ms`` instead.
+        """
+        warnings.warn("local_threshold_ms is deprecated.  Use ``client.options.local_threshold_ms`` instead.", DeprecationWarning, stacklevel=2)
         return self.__options.local_threshold_ms
 
     @property
     def server_selection_timeout(self):
-        """The server selection timeout for this instance in seconds."""
+        """**DEPRECATED**: The server selection timeout for this instance in seconds.
+
+        .. versionchanged:: 3.13
+           Deprecated.  Use ``client.options.server_selection_timeout`` instead.
+        """
+        warnings.warn("server_selection_timeout is deprecated.  Use ``client.options.server_selection_timeout`` instead.", DeprecationWarning, stacklevel=2)
         return self.__options.server_selection_timeout
 
     @property
     def retry_writes(self):
-        """If this instance should retry supported write operations."""
+        """**DEPRECATED**: If this instance should retry supported write operations.
+
+        .. versionchanged:: 3.13
+           Deprecated.  Use ``client.options.retry_writes`` instead.
+        """
+        warnings.warn("retry_writes is deprecated.  Use ``client.options.retry_writes`` instead.", DeprecationWarning, stacklevel=2)
         return self.__options.retry_writes
 
     @property
     def retry_reads(self):
-        """If this instance should retry supported write operations."""
+        """**DEPRECATED**: If this instance should retry supported write operations.
+
+        .. versionchanged:: 3.13
+           Deprecated.  Use ``client.options.retry_reads`` instead.
+        """
+        warnings.warn("retry_reads is deprecated.  Use ``client.options.retry_reads`` instead.", DeprecationWarning, stacklevel=2)
         return self.__options.retry_reads
 
     def _is_writable(self):
@@ -1469,7 +1515,7 @@ def _retry_with_session(self, retryable, func, session, bulk):
 
         Re-raises any exception thrown by func().
         """
-        retryable = retryable and self.retry_writes and session and not session.in_transaction
+        retryable = retryable and self.options.retry_writes and session and not session.in_transaction
         return self._retry_internal(retryable, func, session, bulk)
 
     def _retry_internal(self, retryable, func, session, bulk):
@@ -1538,7 +1584,7 @@ def _retryable_read(self, func, read_pref, session, address=None, retryable=True
 
         Re-raises any exception thrown by func().
         """
-        retryable = retryable and self.retry_reads and not (session and session.in_transaction)
+        retryable = retryable and self.options.retry_reads and not (session and session.in_transaction)
         last_error = None
         retrying = False
 

pymongo/monitor.py

@@ -117,7 +117,7 @@ def __init__(self, server_description, topology, pool, topology_settings):
         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

pymongo/monitoring.py

@@ -1381,10 +1381,10 @@ def enabled_for_cmap(self):
     def event_listeners(self):
         """List of registered event listeners."""
         return (
-            self.__command_listeners[:],
-            self.__server_heartbeat_listeners[:],
-            self.__server_listeners[:],
-            self.__topology_listeners[:],
+            self.__command_listeners +
+            self.__server_heartbeat_listeners +
+            self.__server_listeners +
+            self.__topology_listeners
         )
 
     def publish_command_start(