PYTHON-2256 Document that a ClientSession cannot be used for multiple operations concurrently (#460)

Author: ShaneHarvey

pymongo/client_session.py

@@ -336,7 +336,17 @@ def _within_time_limit(start_time):
 
 
 class ClientSession(object):
-    """A session for ordering sequential operations."""
+    """A session for ordering sequential operations.
+
+    :class:`ClientSession` instances are **not thread-safe or fork-safe**.
+    They can only be used by one thread or process at a time. A single
+    :class:`ClientSession` cannot be used to run multiple operations
+    concurrently.
+
+    Should not be initialized directly by application developers - to create a
+    :class:`ClientSession`, call
+    :meth:`~pymongo.mongo_client.MongoClient.start_session`.
+    """
     def __init__(self, client, server_session, options, authset, implicit):
         # A MongoClient, a _ServerSession, a SessionOptions, and a set.
         self._client = client
@@ -461,6 +471,10 @@ def callback(session, custom_arg, custom_kwarg=None):
         however, ``with_transaction`` will return without taking further
         action.
 
+        :class:`ClientSession` instances are **not thread-safe or fork-safe**.
+        Consequently, the ``callback`` must not attempt to execute multiple
+        operations concurrently.
+
         When ``callback`` raises an exception, ``with_transaction``
         automatically aborts the current transaction. When ``callback`` or
         :meth:`~ClientSession.commit_transaction` raises an exception that

pymongo/mongo_client.py

@@ -1779,7 +1779,10 @@ def start_session(self,
         deprecated method :meth:`~pymongo.database.Database.authenticate`.
 
         A :class:`~pymongo.client_session.ClientSession` may only be used with
-        the MongoClient that started it.
+        the MongoClient that started it. :class:`ClientSession` instances are
+        **not thread-safe or fork-safe**. They can only be used by one thread
+        or process at a time. A single :class:`ClientSession` cannot be used
+        to run multiple operations concurrently.
 
         :Returns:
           An instance of :class:`~pymongo.client_session.ClientSession`.