Merge branch 'master' into PYTHON-5101

Author: sleepyStick

CONTRIBUTING.md

@@ -178,7 +178,7 @@ documentation including narrative docs, and the [Sphinx docstring format](https:
 You can build the documentation locally by running:
 
 ```bash
-just docs-build
+just docs
 ```
 
 When updating docs, it can be helpful to run the live docs server as:

doc/async-tutorial.rst

@@ -420,3 +420,10 @@ the collection:
    DuplicateKeyError: E11000 duplicate key error index: test_database.profiles.$user_id_1 dup key: { : 212 }
 
 .. seealso:: The MongoDB documentation on `indexes <https://www.mongodb.com/docs/manual/indexes/>`_
+
+Task Cancellation
+-----------------
+`Cancelling <https://docs.python.org/3/library/asyncio-task.html#task-cancellation>`_ an asyncio Task
+that is running a PyMongo operation is treated as a fatal interrupt. Any connections, cursors, and transactions
+involved in a cancelled Task will be safely closed and cleaned up as part of the cancellation. If those resources are
+also used elsewhere, attempting to utilize them after the cancellation will result in an error.

pymongo/asynchronous/change_stream.py

@@ -391,7 +391,8 @@ async def try_next(self) -> Optional[_DocumentType]:
             if not _resumable(exc) and not exc.timeout:
                 await self.close()
             raise
-        except Exception:
+        # Catch KeyboardInterrupt, CancelledError, etc. and cleanup.
+        except BaseException:
             await self.close()
             raise
 

pymongo/asynchronous/client_session.py

@@ -697,7 +697,8 @@ async def callback(session, custom_arg, custom_kwarg=None):
             )
             try:
                 ret = await callback(self)
-            except Exception as exc:
+            # Catch KeyboardInterrupt, CancelledError, etc. and cleanup.
+            except BaseException as exc:
                 if self.in_transaction:
                     await self.abort_transaction()
                 if (

pymongo/asynchronous/cursor.py

@@ -1126,7 +1126,8 @@ async def _send_message(self, operation: Union[_Query, _GetMore]) -> None:
             self._killed = True
             await self.close()
             raise
-        except Exception:
+        # Catch KeyboardInterrupt, CancelledError, etc. and cleanup.
+        except BaseException:
             await self.close()
             raise
 

pymongo/asynchronous/mongo_client.py

@@ -276,17 +276,16 @@ def __init__(
         :param type_registry: instance of
             :class:`~bson.codec_options.TypeRegistry` to enable encoding
             and decoding of custom types.
-        :param datetime_conversion: Specifies how UTC datetimes should be decoded
+        :param kwargs: **Additional optional parameters available as keyword arguments:**
+
+          - `datetime_conversion` (optional): Specifies how UTC datetimes should be decoded
             within BSON. Valid options include 'datetime_ms' to return as a
             DatetimeMS, 'datetime' to return as a datetime.datetime and
             raising a ValueError for out-of-range values, 'datetime_auto' to
             return DatetimeMS objects when the underlying datetime is
             out-of-range and 'datetime_clamp' to clamp to the minimum and
             maximum possible datetimes. Defaults to 'datetime'. See
             :ref:`handling-out-of-range-datetimes` for details.
-
-          | **Other optional parameters can be passed as keyword arguments:**
-
           - `directConnection` (optional): if ``True``, forces this client to
              connect directly to the specified MongoDB host as a standalone.
              If ``false``, the client connects to the entire replica set of

pymongo/asynchronous/pool.py

@@ -559,7 +559,7 @@ async def command(
             )
         except (OperationFailure, NotPrimaryError):
             raise
-        # Catch socket.error, KeyboardInterrupt, etc. and close ourselves.
+        # Catch socket.error, KeyboardInterrupt, CancelledError, etc. and close ourselves.
         except BaseException as error:
             self._raise_connection_failure(error)
 
@@ -576,6 +576,7 @@ async def send_message(self, message: bytes, max_doc_size: int) -> None:
 
         try:
             await async_sendall(self.conn, message)
+        # Catch KeyboardInterrupt, CancelledError, etc. and cleanup.
         except BaseException as error:
             self._raise_connection_failure(error)
 
@@ -586,6 +587,7 @@ async def receive_message(self, request_id: Optional[int]) -> Union[_OpReply, _O
         """
         try:
             return await receive_message(self, request_id, self.max_message_size)
+        # Catch KeyboardInterrupt, CancelledError, etc. and cleanup.
         except BaseException as error:
             self._raise_connection_failure(error)
 
@@ -1269,6 +1271,7 @@ async def connect(self, handler: Optional[_MongoClientErrorHandler] = None) -> A
 
         try:
             sock = await _configured_socket(self.address, self.opts)
+        # Catch KeyboardInterrupt, CancelledError, etc. and cleanup.
         except BaseException as error:
             async with self.lock:
                 self.active_contexts.discard(tmp_context)
@@ -1308,6 +1311,7 @@ async def connect(self, handler: Optional[_MongoClientErrorHandler] = None) -> A
                 handler.contribute_socket(conn, completed_handshake=False)
 
             await conn.authenticate()
+        # Catch KeyboardInterrupt, CancelledError, etc. and cleanup.
         except BaseException:
             async with self.lock:
                 self.active_contexts.discard(conn.cancel_context)
@@ -1369,6 +1373,7 @@ async def checkout(
             async with self.lock:
                 self.active_contexts.add(conn.cancel_context)
             yield conn
+        # Catch KeyboardInterrupt, CancelledError, etc. and cleanup.
         except BaseException:
             # Exception in caller. Ensure the connection gets returned.
             # Note that when pinned is True, the session owns the
@@ -1515,6 +1520,7 @@ async def _get_conn(
                         async with self._max_connecting_cond:
                             self._pending -= 1
                             self._max_connecting_cond.notify()
+        # Catch KeyboardInterrupt, CancelledError, etc. and cleanup.
         except BaseException:
             if conn:
                 # We checked out a socket but authentication failed.

pymongo/periodic_executor.py

@@ -100,6 +100,7 @@ async def _run(self) -> None:
                 if not await self._target():
                     self._stopped = True
                     break
+            # Catch KeyboardInterrupt, CancelledError, etc. and cleanup.
             except BaseException:
                 self._stopped = True
                 raise
@@ -232,6 +233,7 @@ def _run(self) -> None:
                 if not self._target():
                     self._stopped = True
                     break
+            # Catch KeyboardInterrupt, etc. and cleanup.
             except BaseException:
                 with self._lock:
                     self._stopped = True

pymongo/synchronous/change_stream.py

@@ -389,7 +389,8 @@ def try_next(self) -> Optional[_DocumentType]:
             if not _resumable(exc) and not exc.timeout:
                 self.close()
             raise
-        except Exception:
+        # Catch KeyboardInterrupt, CancelledError, etc. and cleanup.
+        except BaseException:
             self.close()
             raise
 

pymongo/synchronous/client_session.py

@@ -694,7 +694,8 @@ def callback(session, custom_arg, custom_kwarg=None):
             self.start_transaction(read_concern, write_concern, read_preference, max_commit_time_ms)
             try:
                 ret = callback(self)
-            except Exception as exc:
+            # Catch KeyboardInterrupt, CancelledError, etc. and cleanup.
+            except BaseException as exc:
                 if self.in_transaction:
                     self.abort_transaction()
                 if (