Update SQLAlchemy

libs/sqlalchemy/dialects/mssql/pyodbc.py

@@ -1,5 +1,5 @@
 # mssql/pyodbc.py
-# Copyright (C) 2005-2012 the SQLAlchemy authors and contributors <see AUTHORS file>
+# Copyright (C) 2005-2013 the SQLAlchemy authors and contributors <see AUTHORS file>
 #
 # This module is part of SQLAlchemy and is released under
 # the MIT License: http://www.opensource.org/licenses/mit-license.php
@@ -35,14 +35,14 @@ Examples of pyodbc connection string URLs:
 
     dsn=mydsn;UID=user;PWD=pass;LANGUAGE=us_english
 
-* ``mssql+pyodbc://user:pass@host/db`` - connects using a connection 
+* ``mssql+pyodbc://user:pass@host/db`` - connects using a connection
   that would appear like::
 
     DRIVER={SQL Server};Server=host;Database=db;UID=user;PWD=pass
 
 * ``mssql+pyodbc://user:pass@host:123/db`` - connects using a connection
   string which includes the port
-  information using the comma syntax. This will create the following 
+  information using the comma syntax. This will create the following
   connection string::
 
     DRIVER={SQL Server};Server=host,123;Database=db;UID=user;PWD=pass
@@ -80,6 +80,34 @@ the python shell. For example::
     >>> urllib.quote_plus('dsn=mydsn;Database=db')
     'dsn%3Dmydsn%3BDatabase%3Ddb'
 
+Unicode Binds
+^^^^^^^^^^^^^
+
+The current state of PyODBC on a unix backend with FreeTDS and/or
+EasySoft is poor regarding unicode; different OS platforms and versions of UnixODBC
+versus IODBC versus FreeTDS/EasySoft versus PyODBC itself dramatically
+alter how strings are received.  The PyODBC dialect attempts to use all the information
+it knows to determine whether or not a Python unicode literal can be
+passed directly to the PyODBC driver or not; while SQLAlchemy can encode
+these to bytestrings first, some users have reported that PyODBC mis-handles
+bytestrings for certain encodings and requires a Python unicode object,
+while the author has observed widespread cases where a Python unicode
+is completely misinterpreted by PyODBC, particularly when dealing with
+the information schema tables used in table reflection, and the value
+must first be encoded to a bytestring.
+
+It is for this reason that whether or not unicode literals for bound
+parameters be sent to PyODBC can be controlled using the
+``supports_unicode_binds`` parameter to ``create_engine()``.  When
+left at its default of ``None``, the PyODBC dialect will use its
+best guess as to whether or not the driver deals with unicode literals
+well.  When ``False``, unicode literals will be encoded first, and when
+``True`` unicode literals will be passed straight through.  This is an interim
+flag that hopefully should not be needed when the unicode situation stabilizes
+for unix + PyODBC.
+
+.. versionadded:: 0.7.7
+    ``supports_unicode_binds`` parameter to ``create_engine()``\ .
 
 """
 
@@ -171,7 +199,7 @@ class MSExecutionContext_pyodbc(MSExecutionContext):
 
         super(MSExecutionContext_pyodbc, self).pre_exec()
 
-        # don't embed the scope_identity select into an 
+        # don't embed the scope_identity select into an
         # "INSERT .. DEFAULT VALUES"
         if self._select_lastrowid and \
                 self.dialect.use_scope_identity and \
@@ -183,11 +211,11 @@ class MSExecutionContext_pyodbc(MSExecutionContext):
     def post_exec(self):
         if self._embedded_scope_identity:
             # Fetch the last inserted id from the manipulated statement
-            # We may have to skip over a number of result sets with 
+            # We may have to skip over a number of result sets with
             # no data (due to triggers, etc.)
             while True:
                 try:
-                    # fetchall() ensures the cursor is consumed 
+                    # fetchall() ensures the cursor is consumed
                     # without closing it (FreeTDS particularly)
                     row = self.cursor.fetchall()[0]
                     break
@@ -217,7 +245,8 @@ class MSDialect_pyodbc(PyODBCConnector, MSDialect):
     def __init__(self, description_encoding='latin-1', **params):
         super(MSDialect_pyodbc, self).__init__(**params)
         self.description_encoding = description_encoding
-        self.use_scope_identity = self.dbapi and \
+        self.use_scope_identity = self.use_scope_identity and \
+                        self.dbapi and \
                         hasattr(self.dbapi.Cursor, 'nextset')
         self._need_decimal_fix = self.dbapi and \
                             self._dbapi_version() < (2, 1, 8)