docs about objects not being threadsafe

2 files changed, 16 insertions, 3 deletions

diff --git a/lib/sqlalchemy/engine/base.py b/lib/sqlalchemy/engine/base.py
index e4ff22746..704767b01 100644
--- a/lib/sqlalchemy/engine/base.py
+++ b/lib/sqlalchemy/engine/base.py
@@ -188,7 +188,9 @@ class Connectable(object):
 class Connection(Connectable):
     """represents a single DBAPI connection returned from the underlying connection pool.  Provides
     execution support for string-based SQL statements as well as ClauseElement, Compiled and DefaultGenerator objects.
-    provides a begin method to return Transaction objects."""
+    provides a begin method to return Transaction objects.
+    
+    The Connection object is **not** threadsafe."""
     def __init__(self, engine, connection=None, close_with_result=False):
         self.__engine = engine
         self.__connection = connection or engine.raw_connection()
@@ -363,7 +365,9 @@ class Connection(Connectable):
         return self._execute_raw(statement, parameters)
 
 class Transaction(object):
-    """represents a Transaction in progress"""
+    """represents a Transaction in progress.
+    
+    the Transaction object is **not** threadsafe."""
     def __init__(self, connection, parent):
         self.__connection = connection
         self.__parent = parent or self
diff --git a/lib/sqlalchemy/orm/session.py b/lib/sqlalchemy/orm/session.py
index 034770b10..8ca1930b3 100644
--- a/lib/sqlalchemy/orm/session.py
+++ b/lib/sqlalchemy/orm/session.py
@@ -9,7 +9,13 @@ import unitofwork, query
 import weakref
 import sqlalchemy
 
+
 class SessionTransaction(object):
+    """represents a Session-level Transaction.  This corresponds to one or
+    more sqlalchemy.engine.Transaction instances behind the scenes, with one
+    Transaction per Engine in use.
+    
+    the SessionTransaction object is **not** threadsafe."""
     def __init__(self, session, parent=None, autoflush=True):
         self.session = session
         self.connections = {}
@@ -63,7 +69,10 @@ class SessionTransaction(object):
         self.session.transaction = None
 
 class Session(object):
-    """encapsulates a set of objects being operated upon within an object-relational operation."""
+    """encapsulates a set of objects being operated upon within an object-relational operation.
+    
+    The Session object is **not** threadsafe.  For thread-management of Sessions, see the
+    sqlalchemy.ext.sessioncontext module."""
     def __init__(self, bind_to=None, hash_key=None, import_session=None, echo_uow=False):
         if import_session is not None:
             self.uow = unitofwork.UnitOfWork(identity_map=import_session.uow.identity_map)