PYTHON-4724 - Document the behavior of using an async client across multiple event loop

Author: NoahStapp

pymongo/asynchronous/mongo_client.py

@@ -878,6 +878,14 @@ def __init__(
 
         self._opened = False
         self._closed = False
+        self._loop: Optional[asyncio.AbstractEventLoop] = None
+        if not _IS_SYNC:
+            # Check if the client was created within a running event loop.
+            try:
+                self._loop = asyncio.get_running_loop()
+            # It wasn't, so the loop will be stored during the first performed operation
+            except RuntimeError:
+                pass
         if not is_srv:
             self._init_background()
 
@@ -1709,6 +1717,12 @@ async def _get_topology(self) -> Topology:
         If this client was created with "connect=False", calling _get_topology
         launches the connection process in the background.
         """
+        if not _IS_SYNC:
+            if self._loop is None:
+                self._loop = asyncio.get_running_loop()
+            else:
+                if self._loop != asyncio.get_running_loop():
+                    raise RuntimeError("Cannot use AsyncMongoClient in different event loop")
         if not self._opened:
             if self._resolve_srv_info["is_srv"]:
                 await self._resolve_srv()

pymongo/synchronous/mongo_client.py

@@ -876,6 +876,14 @@ def __init__(
 
         self._opened = False
         self._closed = False
+        self._loop: Optional[asyncio.AbstractEventLoop] = None
+        if not _IS_SYNC:
+            # Check if the client was created within a running event loop.
+            try:
+                self._loop = asyncio.get_running_loop()
+            # It wasn't, so the loop will be stored during the first performed operation
+            except RuntimeError:
+                pass
         if not is_srv:
             self._init_background()
 
@@ -1703,6 +1711,12 @@ def _get_topology(self) -> Topology:
         If this client was created with "connect=False", calling _get_topology
         launches the connection process in the background.
         """
+        if not _IS_SYNC:
+            if self._loop is None:
+                self._loop = asyncio.get_running_loop()
+            else:
+                if self._loop != asyncio.get_running_loop():
+                    raise RuntimeError("Cannot use MongoClient in different event loop")
         if not self._opened:
             if self._resolve_srv_info["is_srv"]:
                 self._resolve_srv()

test/asynchronous/test_async_loop_safety.py

@@ -0,0 +1,34 @@
+# Copyright 2025-present MongoDB, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Test that the asynchronous API detects event loop changes and fails correctly."""
+from __future__ import annotations
+
+import asyncio
+import unittest
+
+from pymongo import AsyncMongoClient
+
+
+class TestClientLoopSafety(unittest.TestCase):
+    def test_client_errors_on_different_loop(self):
+        client = AsyncMongoClient()
+        loop1 = asyncio.new_event_loop()
+        loop1.run_until_complete(client.server_info())
+        loop2 = asyncio.new_event_loop()
+        with self.assertRaisesRegex(
+            RuntimeError, "Cannot use AsyncMongoClient in different event loop"
+        ):
+            loop2.run_until_complete(client.server_info())
+        loop1.run_until_complete(client.close())

tools/synchro.py

@@ -179,7 +179,12 @@
 
 def async_only_test(f: str) -> bool:
     """Return True for async tests that should not be converted to sync."""
-    return f in ["test_locks.py", "test_concurrency.py", "test_async_cancellation.py"]
+    return f in [
+        "test_locks.py",
+        "test_concurrency.py",
+        "test_async_cancellation.py",
+        "test_async_loop_safety.py",
+    ]
 
 
 test_files = [