From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Sat, 4 Feb 2012 19:31:10 +0000 (-0500)
Subject: - add a warning regarding tuple.in_(), [ticket:2395]
X-Git-Tag: rel_0_7_6~70
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=e0ec05366f7363edd1873c4d095e11151cdd4dff;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

- add a warning regarding tuple.in_(), [ticket:2395]
- cleanup of exc.DBAPIError docstrings
---

diff --git a/lib/sqlalchemy/exc.py b/lib/sqlalchemy/exc.py
index 64f25a22ff..91ffc2811b 100644
--- a/lib/sqlalchemy/exc.py
+++ b/lib/sqlalchemy/exc.py
@@ -162,7 +162,7 @@ UnmappedColumnError = None
 class StatementError(SQLAlchemyError):
     """An error occurred during execution of a SQL statement.
     
-    :class:`.StatementError` wraps the exception raised
+    :class:`StatementError` wraps the exception raised
     during execution, and features :attr:`.statement`
     and :attr:`.params` attributes which supply context regarding
     the specifics of the statement which had an issue.
@@ -172,6 +172,15 @@ class StatementError(SQLAlchemyError):
     
     """
 
+    statement = None
+    """The string SQL statement being invoked when this exception occurred."""
+
+    params = None
+    """The parameter list being used when this exception occurred."""
+
+    orig = None
+    """The DBAPI exception object."""
+
     def __init__(self, message, statement, params, orig):
         SQLAlchemyError.__init__(self, message)
         self.statement = statement
@@ -192,21 +201,21 @@ class StatementError(SQLAlchemyError):
 class DBAPIError(StatementError):
     """Raised when the execution of a database operation fails.
 
-    ``DBAPIError`` wraps exceptions raised by the DB-API underlying the
+    Wraps exceptions raised by the DB-API underlying the
     database operation.  Driver-specific implementations of the standard
     DB-API exception types are wrapped by matching sub-types of SQLAlchemy's
-    ``DBAPIError`` when possible.  DB-API's ``Error`` type maps to
-    ``DBAPIError`` in SQLAlchemy, otherwise the names are identical.  Note
+    :class:`DBAPIError` when possible.  DB-API's ``Error`` type maps to
+    :class:`DBAPIError` in SQLAlchemy, otherwise the names are identical.  Note
     that there is no guarantee that different DB-API implementations will
     raise the same exception type for any given error condition.
 
-    :class:`.DBAPIError` features :attr:`.statement`
-    and :attr:`.params` attributes which supply context regarding
+    :class:`DBAPIError` features :attr:`~.StatementError.statement`
+    and :attr:`~.StatementError.params` attributes which supply context regarding
     the specifics of the statement which had an issue, for the 
     typical case when the error was raised within the context of
     emitting a SQL statement.
 
-    The wrapped exception object is available in the :attr:`.orig` attribute.
+    The wrapped exception object is available in the :attr:`~.StatementError.orig` attribute.
     Its type and properties are DB-API implementation specific.
 
     """
diff --git a/lib/sqlalchemy/sql/expression.py b/lib/sqlalchemy/sql/expression.py
index bff086e4b3..859ee04372 100644
--- a/lib/sqlalchemy/sql/expression.py
+++ b/lib/sqlalchemy/sql/expression.py
@@ -832,6 +832,14 @@ def tuple_(*expr):
             [(1, 2), (5, 12), (10, 19)]
         )
 
+    .. warning::
+    
+        The composite IN construct is not supported by all backends, 
+        and is currently known to work on Postgresql and MySQL,
+        but not SQLite.   Unsupported backends will raise
+        a subclass of :class:`~sqlalchemy.exc.DBAPIError` when such 
+        an expression is invoked.
+
     """
     return _Tuple(*expr)