Merge branch 'master' into PYTHON-5075

Author: NoahStapp

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:

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

@@ -21,7 +21,7 @@
 
 .. code-block:: python
 
-  with client.start_session(causal_consistency=True) as session:
+  async with client.start_session(causal_consistency=True) as session:
       collection = client.db.collection
       await collection.update_one({"_id": 1}, {"$set": {"x": 10}}, session=session)
       secondary_c = collection.with_options(read_preference=ReadPreference.SECONDARY)
@@ -53,16 +53,16 @@
 
   orders = client.db.orders
   inventory = client.db.inventory
-  with client.start_session() as session:
-      async with session.start_transaction():
+  async with client.start_session() as session:
+      async with await session.start_transaction():
           await orders.insert_one({"sku": "abc123", "qty": 100}, session=session)
           await inventory.update_one(
               {"sku": "abc123", "qty": {"$gte": 100}},
               {"$inc": {"qty": -100}},
               session=session,
           )
 
-Upon normal completion of ``async with session.start_transaction()`` block, the
+Upon normal completion of ``async with await session.start_transaction()`` block, the
 transaction automatically calls :meth:`AsyncClientSession.commit_transaction`.
 If the block exits with an exception, the transaction automatically calls
 :meth:`AsyncClientSession.abort_transaction`.
@@ -113,7 +113,7 @@
 .. code-block:: python
 
   # Each read using this session reads data from the same point in time.
-  with client.start_session(snapshot=True) as session:
+  async with client.start_session(snapshot=True) as session:
       order = await orders.find_one({"sku": "abc123"}, session=session)
       inventory = await inventory.find_one({"sku": "abc123"}, session=session)
 
@@ -619,7 +619,7 @@ async def callback(session):
               await inventory.update_one({"sku": "abc123", "qty": {"$gte": 100}},
                                    {"$inc": {"qty": -100}}, session=session)
 
-          with client.start_session() as session:
+          async with client.start_session() as session:
               await session.with_transaction(callback)
 
         To pass arbitrary arguments to the ``callback``, wrap your callable
@@ -628,7 +628,7 @@ async def callback(session):
           async def callback(session, custom_arg, custom_kwarg=None):
               # Transaction operations...
 
-          with client.start_session() as session:
+          async with client.start_session() as session:
               await session.with_transaction(
                   lambda s: callback(s, "custom_arg", custom_kwarg=1))
 
@@ -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 (

pymongo/synchronous/cursor.py

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