- added new flag to String and create_engine(), assert_unicode=(True|False|None).

When convert_unicode=True, this flag also defaults to `True`, and results in all
unicode conversion operations raising an exception when a non-unicode bytestring
is passed as a bind parameter.  It is strongly advised that all unicode-aware
applications make proper use of Python unicode objects (i.e. u'hello' and
not 'hello').

2 files changed, 46 insertions, 13 deletions

diff --git a/doc/build/content/dbengine.txt b/doc/build/content/dbengine.txt
index a8b6e5bce..9fc0ae591 100644
--- a/doc/build/content/dbengine.txt
+++ b/doc/build/content/dbengine.txt
@@ -126,6 +126,7 @@ Keyword options can also be specified to `create_engine()`, following the string
 
 A list of all standard options, as well as several that are used by particular database dialects, is as follows:
 
+* **assert_unicode=None** - defaults to `True` when `convert_unicode==True`.  This will assert that all incoming string bind parameters are instances of `unicode`.  Only takes effect when `convert_unicode==True`.  Set to `False` to disable unicode assertions when `convert_unicode==True`.  This flag is also available on the `String` type and its decsendants. New in 0.4.2.  
 * **connect_args** - a dictionary of options which will be passed directly to the DBAPI's `connect()` method as additional keyword arguments.
 * **convert_unicode=False** - if set to True, all String/character based types will convert Unicode values to raw byte values going into the database, and all raw byte values to Python Unicode coming out in result sets.  This is an engine-wide method to provide unicode conversion across the board.  For unicode conversion on a column-by-column level, use the `Unicode` column type instead, described in [types](rel:types).
 * **creator** - a callable which returns a DBAPI connection.  This creation function will be passed to the underlying connection pool and will be used to create all new database connections.  Usage of this function causes connection parameters specified in the URL argument to be bypassed.
diff --git a/doc/build/content/types.txt b/doc/build/content/types.txt
index 4abe508df..8f9cb1f7c 100644
--- a/doc/build/content/types.txt
+++ b/doc/build/content/types.txt
@@ -5,10 +5,53 @@ The package `sqlalchemy.types` defines the datatype identifiers which may be use
 
 ### Built-in Types {@name=standard}
 
-SQLAlchemy comes with a set of standard generic datatypes, which are defined as classes.   
+SQLAlchemy comes with a set of standard generic datatypes, which are defined as classes.  Types are usually used when defining tables, and can be left as a class or instantiated, for example:
 
-The standard set of generic types are:
+    {python}
+    mytable = Table('mytable', metadata,
+        Column('myid', Integer, primary_key=True),
+        Column('data', String(30)),
+        Column('info', Unicode(100)),
+        Column('value', Number(7,4)) 
+        )
+
+Following is a rundown of the standard types.
+
+#### String
+
+This type is the base type for all string and character types, such as `Unicode`, `Text`, `CLOB`, etc.  By default it generates a VARCHAR in DDL.  It includes an argument `length`, which indicates the length in characters of the type, as well as `convert_unicode` and `assert_unicode`, which are booleans.  `length` will be used as the length argument when generating DDL.  If `length` is omitted, the `String` type resolves into the `Text` type.
+
+`convert_unicode=True` indicates that incoming strings, if they are Python `unicode` strings, will be encoded into a raw bytestring using the `encoding` attribute of the dialect (defaults to `utf-8`).  Similarly, raw bytestrings coming back from the database will be decoded into `unicode` objects on the way back.
+
+`assert_unicode=True` is set to true by default when `convert_unicode=True`, and indicates that incoming bind parameters will be checked that they are in fact  `unicode` objects, else an error is raised.  (this flag is new as of version 0.4.2)
+
+Both `convert_unicode` and `assert_unicode` may be set at the engine level as flags to `create_engine()`.
+
+#### Unicode
+
+The `Unicode` type is shorthand for `String` with `convert_unicode=True` and `assert_unicode=True`.  When writing a unicode-aware appication, it is strongly recommended that this type is used, and that only unicode strings are used in the application.  By "unicode string" we mean a string with a u, i.e. `u'hello'`.  Otherwise, particularly when using the ORM, data will be converted to unicode when it returns from the database, but local data which was generated locally will not be in unicode format, which can create confusion.
+
+#### Numeric
+
+TODO
+
+#### Float
 
+TODO
+
+#### Datetime/Date/Time
+
+TODO
+
+#### Binary
+
+TODO
+
+#### Boolean
+
+TODO
+
+#### Summary of Types
     {python title="package sqlalchemy.types"}
     class String(TypeEngine):
         def __init__(self, length=None)
@@ -66,17 +109,6 @@ More specific subclasses of these types are available, which various database en
 When using a specific database engine, these types are adapted even further via a set of database-specific subclasses defined by the database engine.
 There may eventually be more type objects that are defined for specific databases.  An example of this would be Postgres' Array type.
 
-Type objects are specified to table meta data using either the class itself, or an instance of the class.  Creating an instance of the class allows you to specify parameters for the type, such as string length, numerical precision, etc.:
-
-    {python}
-    mytable = Table('mytable', engine, 
-        # define type using a class
-        Column('my_id', Integer, primary_key=True), 
-        
-        # define type using an object instance
-        Column('value', Number(7,4)) 
-    )
-
 ### Dialect Specific Types {@name=dialect}
 
 Each dialect has its own set of types, many of which are available only within that dialect.  For example, MySQL has a `BigInteger` type and Postgres has an `Inet` type.  To use these, import them from the module explicitly: