PYTHON-1842 Implement Connection Monitoring and Pooling spec

Author: ShaneHarvey

doc/api/pymongo/monitoring.rst

@@ -17,6 +17,10 @@
    .. autoclass:: TopologyListener
       :members:
       :inherited-members:
+   .. autoclass:: ConnectionPoolListener
+      :members:
+      :inherited-members:
+
    .. autoclass:: CommandStartedEvent
       :members:
       :inherited-members:
@@ -53,3 +57,43 @@
    .. autoclass:: ServerHeartbeatFailedEvent
       :members:
       :inherited-members:
+
+   .. autoclass:: PoolCreatedEvent
+      :members:
+      :inherited-members:
+   .. autoclass:: PoolClearedEvent
+      :members:
+      :inherited-members:
+   .. autoclass:: PoolClosedEvent
+      :members:
+      :inherited-members:
+
+   .. autoclass:: ConnectionCreatedEvent
+      :members:
+      :inherited-members:
+   .. autoclass:: ConnectionReadyEvent
+      :members:
+      :inherited-members:
+
+   .. autoclass:: ConnectionClosedReason
+      :members:
+
+   .. autoclass:: ConnectionClosedEvent
+      :members:
+      :inherited-members:
+   .. autoclass:: ConnectionCheckOutStartedEvent
+      :members:
+      :inherited-members:
+
+   .. autoclass:: ConnectionCheckOutFailedReason
+      :members:
+
+   .. autoclass:: ConnectionCheckOutFailedEvent
+      :members:
+      :inherited-members:
+   .. autoclass:: ConnectionCheckedOutEvent
+      :members:
+      :inherited-members:
+   .. autoclass:: ConnectionCheckedInEvent
+      :members:
+      :inherited-members:

doc/changelog.rst

@@ -37,16 +37,18 @@ Version 3.9 adds support for MongoDB 4.2. Highlights include:
   time, with at-most-once semantics.
 - Support for retryable reads and the ``retryReads`` URI option which is
   enabled by default. See the :class:`~pymongo.mongo_client.MongoClient`
-  documentation for details.
+  documentation for details. Now that supported operations are retried
+  automatically and transparently, users should consider adjusting any custom
+  retry logic to prevent an application from inadvertently retrying for too
+  long.
 - Support zstandard for wire protocol compression.
 - Support for periodically polling DNS SRV records to update the mongos proxy
   list without having to change client configuration.
 - New method :meth:`pymongo.database.Database.aggregate` to support running
   database level aggregations.
-
-  Now that supported operations are retried automatically and transparently,
-  users should consider adjusting any custom retry logic to prevent
-  an application from inadvertently retrying for too long.
+- Support for publishing Connection Monitoring and Pooling events via the new
+  :class:`~pymongo.monitoring.ConnectionPoolListener` class. See
+  :mod:`~pymongo.monitoring` for an example.
 
 .. _URI options specification: https://github.com/mongodb/specifications/blob/master/source/uri-options/uri-options.rst
 

pymongo/client_options.py

@@ -110,15 +110,15 @@ def _parse_pool_options(options):
     """Parse connection pool options."""
     max_pool_size = options.get('maxpoolsize', common.MAX_POOL_SIZE)
     min_pool_size = options.get('minpoolsize', common.MIN_POOL_SIZE)
-    default_idle_seconds = common.validate_timeout_or_none(
-        'maxidletimems', common.MAX_IDLE_TIME_MS)
-    max_idle_time_seconds = options.get('maxidletimems', default_idle_seconds)
+    max_idle_time_seconds = options.get(
+        'maxidletimems', common.MAX_IDLE_TIME_SEC)
     if max_pool_size is not None and min_pool_size > max_pool_size:
         raise ValueError("minPoolSize must be smaller or equal to maxPoolSize")
     connect_timeout = options.get('connecttimeoutms', common.CONNECT_TIMEOUT)
     socket_keepalive = options.get('socketkeepalive', True)
     socket_timeout = options.get('sockettimeoutms')
-    wait_queue_timeout = options.get('waitqueuetimeoutms')
+    wait_queue_timeout = options.get(
+        'waitqueuetimeoutms', common.WAIT_QUEUE_TIMEOUT)
     wait_queue_multiple = options.get('waitqueuemultiple')
     event_listeners = options.get('event_listeners')
     appname = options.get('appname')

pymongo/common.py

@@ -88,6 +88,12 @@
 # Default value for maxIdleTimeMS.
 MAX_IDLE_TIME_MS = None
 
+# Default value for maxIdleTimeMS in seconds.
+MAX_IDLE_TIME_SEC = None
+
+# Default value for waitQueueTimeoutMS in seconds.
+WAIT_QUEUE_TIMEOUT = None
+
 # Default value for localThresholdMS.
 LOCAL_THRESHOLD_MS = 15
 

pymongo/cursor.py

@@ -37,6 +37,7 @@
                              _RawBatchGetMore,
                              _Query,
                              _RawBatchQuery)
+from pymongo.monitoring import ConnectionClosedReason
 
 
 _QUERY_OPTIONS = {
@@ -303,7 +304,8 @@ def __die(self, synchronous=False):
                 # If this is an exhaust cursor and we haven't completely
                 # exhausted the result set we *must* close the socket
                 # to stop the server from sending more data.
-                self.__exhaust_mgr.sock.close()
+                self.__exhaust_mgr.sock.close_socket(
+                    ConnectionClosedReason.ERROR)
             else:
                 address = _CursorAddress(
                     self.__address, self.__collection.full_name)

pymongo/errors.py

@@ -234,7 +234,7 @@ class InvalidURI(ConfigurationError):
     """Raised when trying to parse an invalid mongodb URI."""
 
 
-class ExceededMaxWaiters(Exception):
+class ExceededMaxWaiters(PyMongoError):
     """Raised when a thread tries to get a connection from a pool and
     ``maxPoolSize * waitQueueMultiple`` threads are already waiting.