marathon doc updating session including a rewrite of unicode paragraphs

5 files changed, 37 insertions, 32 deletions

diff --git a/lib/sqlalchemy/dialects/drizzle/mysqldb.py b/lib/sqlalchemy/dialects/drizzle/mysqldb.py
index dcf02609e..01116fa93 100644
--- a/lib/sqlalchemy/dialects/drizzle/mysqldb.py
+++ b/lib/sqlalchemy/dialects/drizzle/mysqldb.py
@@ -13,10 +13,11 @@ Connect string format::
 
     drizzle+mysqldb://<user>:<password>@<host>[:<port>]/<dbname>
 
-Character Sets
---------------
+Unicode
+-------
 
-Drizzle is all utf8 all the time.
+Drizzle accommodates Python ``unicode`` objects directly and 
+uses the ``utf8`` encoding in all cases.
 
 Known Issues
 -------------
diff --git a/lib/sqlalchemy/dialects/mysql/mysqldb.py b/lib/sqlalchemy/dialects/mysql/mysqldb.py
index 1b0ea85cb..044b9110a 100644
--- a/lib/sqlalchemy/dialects/mysql/mysqldb.py
+++ b/lib/sqlalchemy/dialects/mysql/mysqldb.py
@@ -19,35 +19,38 @@ Connect string format::
 
     mysql+mysqldb://<user>:<password>@<host>[:<port>]/<dbname>
 
-Character Sets
---------------
+Unicode
+-------
 
-Many MySQL server installations default to a ``latin1`` encoding for client
-connections.  All data sent through the connection will be converted into
-``latin1``, even if you have ``utf8`` or another character set on your tables
+MySQLdb will accommodate Python ``unicode`` objects if the
+``use_unicode=1`` parameter, or the ``charset`` parameter,
+is passed as a connection argument.
+
+Without this setting, many MySQL server installations default to 
+a ``latin1`` encoding for client connections, which has the effect
+of all data being converted into ``latin1``, even if you have ``utf8`` 
+or another character set configured on your tables
 and columns.  With versions 4.1 and higher, you can change the connection
 character set either through server configuration or by including the
-``charset`` parameter in the URL used for ``create_engine``.  The ``charset``
-option is passed through to MySQL-Python and has the side-effect of also
-enabling ``use_unicode`` in the driver by default.  For regular encoded
-strings, also pass ``use_unicode=0`` in the connection arguments::
+``charset`` parameter.  The ``charset``
+parameter as received by MySQL-Python also has the side-effect of 
+enabling ``use_unicode=1``::
+
+    # set client encoding to utf8; all strings come back as unicode
+    create_engine('mysql+mysqldb:///mydb?charset=utf8')
 
-  # set client encoding to utf8; all strings come back as unicode
-  create_engine('mysql+mysqldb:///mydb?charset=utf8')
+Manually configuring ``use_unicode=0`` will cause MySQL-python to 
+return encoded strings::
 
-  # set client encoding to utf8; all strings come back as utf8 str
-  create_engine('mysql+mysqldb:///mydb?charset=utf8&use_unicode=0')
+    # set client encoding to utf8; all strings come back as utf8 str
+    create_engine('mysql+mysqldb:///mydb?charset=utf8&use_unicode=0')
 
 Known Issues
 -------------
 
 MySQL-python version 1.2.2 has a serious memory leak related
 to unicode conversion, a feature which is disabled via ``use_unicode=0``.
-Using a more recent version of MySQL-python is recommended. The 
-recommended connection form with SQLAlchemy is::
-  
-    engine = create_engine('mysql://scott:tiger@localhost/test?charset=utf8&use_unicode=0', pool_recycle=3600)
-
+It is strongly advised to use the latest version of MySQL-Python.
 
 """
 
diff --git a/lib/sqlalchemy/dialects/mysql/oursql.py b/lib/sqlalchemy/dialects/mysql/oursql.py
index 2678d9dc9..25273a619 100644
--- a/lib/sqlalchemy/dialects/mysql/oursql.py
+++ b/lib/sqlalchemy/dialects/mysql/oursql.py
@@ -17,8 +17,8 @@ Connect string format::
 
     mysql+oursql://<user>:<password>@<host>[:<port>]/<dbname>
 
-Character Sets
---------------
+Unicode
+-------
 
 oursql defaults to using ``utf8`` as the connection charset, but other
 encodings may be used instead. Like the MySQL-Python driver, unicode support
diff --git a/lib/sqlalchemy/dialects/oracle/cx_oracle.py b/lib/sqlalchemy/dialects/oracle/cx_oracle.py
index 29d9e2ab0..078136f70 100644
--- a/lib/sqlalchemy/dialects/oracle/cx_oracle.py
+++ b/lib/sqlalchemy/dialects/oracle/cx_oracle.py
@@ -50,6 +50,8 @@ Unicode
 cx_oracle 5 fully supports Python unicode objects.   SQLAlchemy will pass
 all unicode strings directly to cx_oracle, and additionally uses an output
 handler so that all string based result values are returned as unicode as well.
+Generally, the ``NLS_LANG`` environment variable determines the nature
+of the encoding to be used.
 
 Note that this behavior is disabled when Oracle 8 is detected, as it has been 
 observed that issues remain when passing Python unicodes to cx_oracle with Oracle 8.
diff --git a/lib/sqlalchemy/dialects/sqlite/pysqlite.py b/lib/sqlalchemy/dialects/sqlite/pysqlite.py
index c8739f242..ad8d5c6f9 100644
--- a/lib/sqlalchemy/dialects/sqlite/pysqlite.py
+++ b/lib/sqlalchemy/dialects/sqlite/pysqlite.py
@@ -173,15 +173,14 @@ way.
 Unicode
 -------
 
-In contrast to SQLAlchemy's active handling of date and time types for pysqlite, pysqlite's 
-default behavior regarding Unicode is that all strings are returned as Python unicode objects
-in all cases.  So even if the :class:`~sqlalchemy.types.Unicode` type is 
-*not* used, you will still always receive unicode data back from a result set.  It is 
-**strongly** recommended that you do use the :class:`~sqlalchemy.types.Unicode` type
-to represent strings, since it will raise a warning if a non-unicode Python string is 
-passed from the user application.  Mixing the usage of non-unicode objects with returned unicode objects can
-quickly create confusion, particularly when using the ORM as internal data is not 
-always represented by an actual database result string.
+The pysqlite driver only returns Python ``unicode`` objects in result sets, never
+plain strings, and accommodates ``unicode`` objects within bound parameter
+values in all cases.   Regardless of the SQLAlchemy string type in use, 
+string-based result values will by Python ``unicode`` in Python 2.  
+The :class:`.Unicode` type should still be used to indicate those columns that
+require unicode, however, so that non-``unicode`` values passed inadvertently
+will emit a warning.  Pysqlite will emit an error if a non-``unicode`` string
+is passed containing non-ASCII characters.
 
 """