Rules for Migrating TypeEngine classes to 0.6
---------------------------------------------

1. the TypeEngine classes are used for:

    a. Specifying behavior which needs to occur for bind parameters
    or result row columns.

    b. Specifying types that are entirely specific to the database
    in use and have no analogue in the sqlalchemy.types package.

    c. Specifying types where there is an analogue in sqlalchemy.types,
    but the database in use takes vendor-specific flags for those
    types.

    d. If a TypeEngine class doesn't provide any of this, it should be
    *removed* from the dialect.

2. the TypeEngine classes are *no longer* used for generating DDL.  Dialects
now have a TypeCompiler subclass which uses the same visit_XXX model as
other compilers.

3. the "ischema_names" and "colspecs" dictionaries are now required members on
the Dialect class.

4. The names of types within dialects are now important.   If a dialect-specific type
is a subclass of an existing generic type and is only provided for bind/result behavior, 
the current mixed case naming can remain, i.e. _PGNumeric for Numeric - in this case, 
end users would never need to use _PGNumeric directly.   However, if a dialect-specific 
type is specifying a type *or* arguments that are not present generically, it should
match the real name of the type on that backend, in uppercase.  E.g. postgresql.INET,
mysql.ENUM, postgresql.ARRAY.

Or follow this handy flowchart:

    is the type meant to provide bind/result                  is the type the same name as an
    behavior to a generic type (i.e. MixedCase)  ---- no ---> UPPERCASE type in types.py ?
    type in types.py ?                                          |                     |
                    |                                           no                    yes
                   yes                                          |                     |
                    |                                           |             does your type need special
                    |                                           +<--- yes --- behavior or arguments ?
                    |                                           |                               |
                    |                                           |                              no
           name the type using                                  |                               |
           _MixedCase, i.e.                                     v                               V
           _OracleBoolean. it                          name the type                        don't make a
           stays private to the dialect                identically as that                  type, make sure the dialect's
           and is invoked *only* via                   within the DB,                       base.py imports the types.py
           the colspecs dict.                          using UPPERCASE                      UPPERCASE name into its namespace
                    |                                  (i.e. BIT, NCHAR, INTERVAL).
                    |                                  Users can import it.
                    |                                       |
                    v                                       v
           subclass the closest                        is the name of this type
           MixedCase type types.py,                    identical to an UPPERCASE
           i.e.                        <--- no ------- name in types.py ?
           class _DateTime(types.DateTime),
           class DATETIME2(types.DateTime),                   |
           class BIT(types.TypeEngine).                      yes
                                                              |
                                                              v
                                                        the type should
                                                        subclass the
                                                        UPPERCASE
                                                        type in types.py
                                                        (i.e. class BLOB(types.BLOB))


Example 1.   pysqlite needs bind/result processing for the DateTime type in types.py, 
which applies to all DateTimes and subclasses.   It's named _SLDateTime and 
subclasses types.DateTime.

Example 2.  MS-SQL has a TIME type which takes a non-standard "precision" argument
that is rendered within DDL.   So it's named TIME in the MS-SQL dialect's base.py, 
and subclasses types.TIME.  Users can then say mssql.TIME(precision=10).

Example 3.  MS-SQL dialects also need special bind/result processing for date 
But its DATE type doesn't render DDL differently than that of a plain 
DATE, i.e. it takes no special arguments.  Therefore we are just adding behavior
to types.Date, so it's named _MSDate in the MS-SQL dialect's base.py, and subclasses
types.Date.

Example 4.  MySQL has a SET type, there's no analogue for this in types.py. So
MySQL names it SET in the dialect's base.py, and it subclasses types.String, since 
it ultimately deals with strings.

Example 5.  Postgresql has a DATETIME type.  The DBAPIs handle dates correctly,
and no special arguments are used in PG's DDL beyond what types.py provides.
Postgresql dialect therefore imports types.DATETIME into its base.py.

Ideally one should be able to specify a schema using names imported completely from a 
dialect, all matching the real name on that backend:

   from sqlalchemy.dialects.postgresql import base as pg

   t = Table('mytable', metadata,
              Column('id', pg.INTEGER, primary_key=True),
              Column('name', pg.VARCHAR(300)),
              Column('inetaddr', pg.INET)
   )

where above, the INTEGER and VARCHAR types are ultimately from sqlalchemy.types, 
but the PG dialect makes them available in its own namespace.

5. "colspecs" now is a dictionary of generic or uppercased types from sqlalchemy.types
linked to types specified in the dialect.   Again, if a type in the dialect does not
specify any special behavior for bind_processor() or result_processor() and does not
indicate a special type only available in this database, it must be *removed* from the 
module and from this dictionary.

6. "ischema_names" indicates string descriptions of types as returned from the database
linked to TypeEngine classes.

    a. The string name should be matched to the most specific type possible within
    sqlalchemy.types, unless there is no matching type within sqlalchemy.types in which
    case it points to a dialect type.   *It doesn't matter* if the dialect has it's 
    own subclass of that type with special bind/result behavior - reflect to the types.py
    UPPERCASE type as much as possible.   With very few exceptions, all types
    should reflect to an UPPERCASE type.

    b. If the dialect contains a matching dialect-specific type that takes extra arguments 
    which the generic one does not, then point to the dialect-specific type.  E.g.
    mssql.VARCHAR takes a "collation" parameter which should be preserved.

5. DDL, or what was formerly issued by "get_col_spec()", is now handled exclusively by
a subclass of compiler.GenericTypeCompiler.

    a. your TypeCompiler class will receive generic and uppercase types from 
    sqlalchemy.types.  Do not assume the presence of dialect-specific attributes on
    these types. 

    b. the visit_UPPERCASE methods on GenericTypeCompiler should *not* be overridden with
    methods that produce a different DDL name.   Uppercase types don't do any kind of 
    "guessing" - if visit_TIMESTAMP is called, the DDL should render as TIMESTAMP in
    all cases, regardless of whether or not that type is legal on the backend database.

    c. the visit_UPPERCASE methods *should* be overridden with methods that add additional
    arguments and flags to those types.

    d. the visit_lowercase methods are overridden to provide an interpretation of a generic 
    type.  E.g.  visit_large_binary() might be overridden to say "return self.visit_BIT(type_)".

    e. visit_lowercase methods should *never* render strings directly - it should always
    be via calling a visit_UPPERCASE() method.
