From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Sun, 1 Aug 2010 19:00:58 +0000 (-0400)
Subject: reformatting /cleanup of column type docs, including [ticket:1858]
X-Git-Tag: rel_0_6_4~70
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=62b12e4266e5d2305f7dbc17b44bab6b2b05c622;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

reformatting /cleanup of column type docs, including [ticket:1858]
---

diff --git a/doc/build/reference/dialects/mssql.rst b/doc/build/reference/dialects/mssql.rst
index ebb3598678..658ca8988f 100644
--- a/doc/build/reference/dialects/mssql.rst
+++ b/doc/build/reference/dialects/mssql.rst
@@ -3,6 +3,96 @@ Microsoft SQL Server
 
 .. automodule:: sqlalchemy.dialects.mssql.base
 
+SQL Server Data Types
+-----------------------
+
+As with all SQLAlchemy dialects, all UPPERCASE types that are known to be
+valid with SQL server are importable from the top level dialect, whether
+they originate from :mod:`sqlalchemy.types` or from the local dialect::
+
+    from sqlalchemy.dialects.mssql import \
+        BIGINT, BINARY, BIT, CHAR, DATE, DATETIME, DATETIME2, \
+        DATETIMEOFFSET, DECIMAL, FLOAT, IMAGE, INTEGER, MONEY, \
+        NCHAR, NTEXT, NUMERIC, NVARCHAR, REAL, SMALLDATETIME, \
+        SMALLINT, SMALLMONEY, SQL_VARIANT, TEXT, TIME, \
+        TIMESTAMP, TINYINT, UNIQUEIDENTIFIER, VARBINARY, VARCHAR
+
+Types which are specific to SQL Server, or have SQL Server-specific 
+construction arguments, are as follows:
+
+.. autoclass:: BIT
+   :members: __init__
+   :show-inheritance:
+
+.. autoclass:: CHAR
+   :members: __init__
+   :show-inheritance:
+
+.. autoclass:: DATETIME2
+   :members: __init__
+   :show-inheritance:
+
+.. autoclass:: DATETIMEOFFSET
+   :members: __init__
+   :show-inheritance:
+
+.. autoclass:: IMAGE
+   :members: __init__
+   :show-inheritance:
+
+.. autoclass:: MONEY
+   :members: __init__
+   :show-inheritance:
+
+.. autoclass:: NCHAR
+   :members: __init__
+   :show-inheritance:
+
+.. autoclass:: NTEXT
+   :members: __init__
+   :show-inheritance:
+
+.. autoclass:: NVARCHAR
+   :members: __init__
+   :show-inheritance:
+
+.. autoclass:: REAL
+   :members: __init__
+   :show-inheritance:
+
+.. autoclass:: SMALLDATETIME
+   :members: __init__
+   :show-inheritance:
+
+.. autoclass:: SMALLMONEY
+   :members: __init__
+   :show-inheritance:
+
+.. autoclass:: SQL_VARIANT
+   :members: __init__
+   :show-inheritance:
+
+.. autoclass:: TEXT
+   :members: __init__
+   :show-inheritance:
+
+.. autoclass:: TIME
+   :members: __init__
+   :show-inheritance:
+
+.. autoclass:: TINYINT
+   :members: __init__
+   :show-inheritance:
+
+.. autoclass:: UNIQUEIDENTIFIER
+   :members: __init__
+   :show-inheritance:
+
+.. autoclass:: VARCHAR
+   :members: __init__
+   :show-inheritance:
+
+
 PyODBC
 ------
 .. automodule:: sqlalchemy.dialects.mssql.pyodbc
diff --git a/doc/build/reference/dialects/mysql.rst b/doc/build/reference/dialects/mysql.rst
index f05d751c55..8796adb3e3 100644
--- a/doc/build/reference/dialects/mysql.rst
+++ b/doc/build/reference/dialects/mysql.rst
@@ -3,140 +3,154 @@ MySQL
 
 .. automodule:: sqlalchemy.dialects.mysql.base
 
-MySQL Column Types
+MySQL Data Types
 ------------------
 
-.. autoclass:: NUMERIC
-   :members: __init__
-   :show-inheritance:
+As with all SQLAlchemy dialects, all UPPERCASE types that are known to be
+valid with MySQL are importable from the top level dialect::
 
-.. autoclass:: DECIMAL
-   :members: __init__
-   :show-inheritance:
+    from sqlalchemy.dialects.mysql import \
+            BIGINT, BINARY, BIT, BLOB, BOOLEAN, CHAR, DATE, \
+            DATETIME, DECIMAL, DECIMAL, DOUBLE, ENUM, FLOAT, INTEGER, \
+            LONGBLOB, LONGTEXT, MEDIUMBLOB, MEDIUMINT, MEDIUMTEXT, NCHAR, \
+            NUMERIC, NVARCHAR, REAL, SET, SMALLINT, TEXT, TIME, TIMESTAMP, \
+            TINYBLOB, TINYINT, TINYTEXT, VARBINARY, VARCHAR, YEAR
 
-.. autoclass:: DOUBLE
-   :members: __init__
-   :show-inheritance:
-
-.. autoclass:: REAL
-   :members: __init__
-   :show-inheritance:
-
-.. autoclass:: FLOAT
-   :members: __init__
-   :show-inheritance:
-
-.. autoclass:: INTEGER
-   :members: __init__
-   :show-inheritance:
+Types which are specific to MySQL, or have MySQL-specific 
+construction arguments, are as follows:
 
 .. autoclass:: BIGINT
-   :members: __init__
-   :show-inheritance:
+    :members: __init__
+    :show-inheritance:
 
-.. autoclass:: MEDIUMINT
-   :members: __init__
-   :show-inheritance:
+.. autoclass:: BINARY
+    :members: __init__
+    :show-inheritance:
 
-.. autoclass:: TINYINT
-   :members: __init__
-   :show-inheritance:
+.. autoclass:: BIT
+    :members: __init__
+    :show-inheritance:
 
-.. autoclass:: SMALLINT
-   :members: __init__
-   :show-inheritance:
+.. autoclass:: BLOB
+    :members: __init__
+    :show-inheritance:
 
-.. autoclass:: BIT
-   :members: __init__
-   :show-inheritance:
+.. autoclass:: BOOLEAN
+    :members: __init__
+    :show-inheritance:
 
-.. autoclass:: DATETIME
-   :members: __init__
-   :show-inheritance:
+.. autoclass:: CHAR
+    :members: __init__
+    :show-inheritance:
 
 .. autoclass:: DATE
-   :members: __init__
-   :show-inheritance:
+    :members: __init__
+    :show-inheritance:
 
-.. autoclass:: TIME
-   :members: __init__
-   :show-inheritance:
+.. autoclass:: DATETIME
+    :members: __init__
+    :show-inheritance:
 
-.. autoclass:: TIMESTAMP
-   :members: __init__
-   :show-inheritance:
+.. autoclass:: DECIMAL
+    :members: __init__
+    :show-inheritance:
 
-.. autoclass:: YEAR
-   :members: __init__
-   :show-inheritance:
+.. autoclass:: DOUBLE
+    :members: __init__
+    :show-inheritance:
 
-.. autoclass:: TEXT
-   :members: __init__
-   :show-inheritance:
+.. autoclass:: ENUM
+    :members: __init__
+    :show-inheritance:
 
-.. autoclass:: TINYTEXT
-   :members: __init__
-   :show-inheritance:
+.. autoclass:: FLOAT
+    :members: __init__
+    :show-inheritance:
 
-.. autoclass:: MEDIUMTEXT
-   :members: __init__
-   :show-inheritance:
+.. autoclass:: INTEGER
+    :members: __init__
+    :show-inheritance:
+
+.. autoclass:: LONGBLOB
+    :members: __init__
+    :show-inheritance:
 
 .. autoclass:: LONGTEXT
-   :members: __init__
-   :show-inheritance:
+    :members: __init__
+    :show-inheritance:
 
-.. autoclass:: VARCHAR
-   :members: __init__
-   :show-inheritance:
+.. autoclass:: MEDIUMBLOB
+    :members: __init__
+    :show-inheritance:
 
-.. autoclass:: CHAR
-   :members: __init__
-   :show-inheritance:
+.. autoclass:: MEDIUMINT
+    :members: __init__
+    :show-inheritance:
 
-.. autoclass:: NVARCHAR
-   :members: __init__
-   :show-inheritance:
+.. autoclass:: MEDIUMTEXT
+    :members: __init__
+    :show-inheritance:
 
 .. autoclass:: NCHAR
-   :members: __init__
-   :show-inheritance:
+    :members: __init__
+    :show-inheritance:
 
-.. autoclass:: VARBINARY
-   :members: __init__
-   :show-inheritance:
+.. autoclass:: NUMERIC
+    :members: __init__
+    :show-inheritance:
 
-.. autoclass:: BINARY
-   :members: __init__
-   :show-inheritance:
+.. autoclass:: NVARCHAR
+    :members: __init__
+    :show-inheritance:
 
-.. autoclass:: BLOB
-   :members: __init__
-   :show-inheritance:
+.. autoclass:: REAL
+    :members: __init__
+    :show-inheritance:
+
+.. autoclass:: SET
+    :members: __init__
+    :show-inheritance:
+
+.. autoclass:: SMALLINT
+    :members: __init__
+    :show-inheritance:
+
+.. autoclass:: TEXT
+    :members: __init__
+    :show-inheritance:
+
+.. autoclass:: TIME
+    :members: __init__
+    :show-inheritance:
+
+.. autoclass:: TIMESTAMP
+    :members: __init__
+    :show-inheritance:
 
 .. autoclass:: TINYBLOB
-   :members: __init__
-   :show-inheritance:
+    :members: __init__
+    :show-inheritance:
 
-.. autoclass:: MEDIUMBLOB
-   :members: __init__
-   :show-inheritance:
+.. autoclass:: TINYINT
+    :members: __init__
+    :show-inheritance:
 
-.. autoclass:: LONGBLOB
-   :members: __init__
-   :show-inheritance:
+.. autoclass:: TINYTEXT
+    :members: __init__
+    :show-inheritance:
 
-.. autoclass:: ENUM
-   :members: __init__
-   :show-inheritance:
+.. autoclass:: VARBINARY
+    :members: __init__
+    :show-inheritance:
 
-.. autoclass:: SET
-   :members: __init__
-   :show-inheritance:
+.. autoclass:: VARCHAR
+    :members: __init__
+    :show-inheritance:
+
+.. autoclass:: YEAR
+    :members: __init__
+    :show-inheritance:
 
-.. autoclass:: BOOLEAN
-   :members: __init__
-   :show-inheritance:
 
 MySQL-Python Notes
 --------------------
diff --git a/doc/build/reference/dialects/oracle.rst b/doc/build/reference/dialects/oracle.rst
index 56b6bce50d..363cebffd4 100644
--- a/doc/build/reference/dialects/oracle.rst
+++ b/doc/build/reference/dialects/oracle.rst
@@ -3,11 +3,21 @@ Oracle
 
 .. automodule:: sqlalchemy.dialects.oracle.base
 
-Oracle Column Types
+Oracle Data Types
 -------------------
 
-In addition to those types at :ref:`types`, datatypes specific to the
-Oracle dialect include those listed here.
+As with all SQLAlchemy dialects, all UPPERCASE types that are known to be
+valid with Oracle are importable from the top level dialect, whether
+they originate from :mod:`sqlalchemy.types` or from the local dialect::
+
+    from sqlalchemy.dialects.oracle import \
+                BFILE, BLOB, CHAR, CLOB, DATE, DATETIME, \
+                DOUBLE_PRECISION, FLOAT, INTERVAL, LONG, NCLOB, \
+                NUMBER, NVARCHAR, NVARCHAR2, RAW, TIMESTAMP, VARCHAR, \
+                VARCHAR2
+
+Types which are specific to Oracle, or have Oracle-specific 
+construction arguments, are as follows:
 
 .. autoclass:: BFILE
   :members: __init__
diff --git a/doc/build/reference/dialects/postgresql.rst b/doc/build/reference/dialects/postgresql.rst
index d0a04a7041..fe1fcb2f7f 100644
--- a/doc/build/reference/dialects/postgresql.rst
+++ b/doc/build/reference/dialects/postgresql.rst
@@ -3,9 +3,22 @@ PostgreSQL
 
 .. automodule:: sqlalchemy.dialects.postgresql.base
 
-PostgresSQL Column Types
+PostgreSQL Data Types
 ------------------------
 
+As with all SQLAlchemy dialects, all UPPERCASE types that are known to be
+valid with Postgresql are importable from the top level dialect, whether
+they originate from :mod:`sqlalchemy.types` or from the local dialect::
+
+    from sqlalchemy.dialects.postgresql import \
+        ARRAY, BIGINT, BIT, BOOLEAN, BYTEA, CHAR, CIDR, DATE, \
+        DOUBLE_PRECISION, ENUM, FLOAT, INET, INTEGER, INTERVAL, \
+        MACADDR, NUMERIC, REAL, SMALLINT, TEXT, TIME, TIMESTAMP, \
+        UUID, VARCHAR
+
+Types which are specific to PostgreSQL, or have PostgreSQL-specific 
+construction arguments, are as follows:
+
 .. autoclass:: ARRAY
     :members: __init__
     :show-inheritance:
diff --git a/doc/build/reference/dialects/sqlite.rst b/doc/build/reference/dialects/sqlite.rst
index 8361876c38..a4e87e1b05 100644
--- a/doc/build/reference/dialects/sqlite.rst
+++ b/doc/build/reference/dialects/sqlite.rst
@@ -3,6 +3,18 @@ SQLite
 
 .. automodule:: sqlalchemy.dialects.sqlite.base
 
+SQLite Data Types
+------------------------
+
+As with all SQLAlchemy dialects, all UPPERCASE types that are known to be
+valid with SQLite are importable from the top level dialect, whether
+they originate from :mod:`sqlalchemy.types` or from the local dialect::
+
+    from sqlalchemy.dialects.sqlite import \
+                BLOB, BOOLEAN, CHAR, DATE, DATETIME, DECIMAL, FLOAT, \
+                INTEGER, NUMERIC, SMALLINT, TEXT, TIME, TIMESTAMP, \
+                VARCHAR
+
 Pysqlite
 --------
 
diff --git a/lib/sqlalchemy/dialects/mssql/base.py b/lib/sqlalchemy/dialects/mssql/base.py
index 4fb7744821..88ca36dbdf 100644
--- a/lib/sqlalchemy/dialects/mssql/base.py
+++ b/lib/sqlalchemy/dialects/mssql/base.py
@@ -13,11 +13,13 @@ Auto Increment Behavior
 ``IDENTITY`` columns are supported by using SQLAlchemy
 ``schema.Sequence()`` objects. In other words::
 
-    Table('test', mss_engine,
+    from sqlalchemy import Table, Integer, Sequence, Column
+    
+    Table('test', metadata,
            Column('id', Integer,
                   Sequence('blah',100,10), primary_key=True),
            Column('name', String(20))
-         ).create()
+         ).create(some_engine)
 
 would yield::
 
@@ -47,9 +49,11 @@ collation parameter accepts a Windows Collation Name or a SQL
 Collation Name. Supported types are MSChar, MSNChar, MSString,
 MSNVarchar, MSText, and MSNText. For example::
 
-    Column('login', String(32, collation='Latin1_General_CI_AS'))
+    from sqlalchemy.dialects.mssql import VARCHAR
+    Column('login', VARCHAR(32, collation='Latin1_General_CI_AS'))
 
-will yield::
+When such a column is associated with a :class:`Table`, the
+CREATE TABLE statement for this column will yield::
 
     login VARCHAR(32) COLLATE Latin1_General_CI_AS NULL
 
diff --git a/lib/sqlalchemy/dialects/mysql/base.py b/lib/sqlalchemy/dialects/mysql/base.py
index 08978dfe3b..1c61f47e18 100644
--- a/lib/sqlalchemy/dialects/mysql/base.py
+++ b/lib/sqlalchemy/dialects/mysql/base.py
@@ -42,23 +42,6 @@ Connecting
 
 See the API documentation on individual drivers for details on connecting.
     
-Data Types
-----------
-
-All of MySQL's standard types are supported.   These can also be specified within 
-table metadata, for the purpose of issuing CREATE TABLE statements
-which include MySQL-specific extensions.   The types are available
-from the module, as in::
-
-    from sqlalchemy.dialects import mysql
-
-    Table('mytable', metadata,
-          Column('id', Integer, primary_key=True),
-          Column('ittybittyblob', mysql.TINYBLOB),
-          Column('biggy', mysql.BIGINT(unsigned=True)))
-
-See the API documentation on specific column types for further details.
-
 Connection Timeouts
 -------------------
 
@@ -817,7 +800,7 @@ class NCHAR(_StringType, sqltypes.NCHAR):
     __visit_name__ = 'NCHAR'
 
     def __init__(self, length=None, **kwargs):
-        """Construct an NCHAR.  Arguments are:
+        """Construct an NCHAR.
 
         :param length: Maximum data length, in characters.
 
@@ -862,8 +845,6 @@ class ENUM(sqltypes.Enum, _StringType):
 
           Column('myenum', MSEnum("foo", "bar", "baz"))
 
-        Arguments are:
-
         :param enums: The range of valid values for this ENUM.  Values will be
           quoted when generating the schema according to the quoting flag (see
           below).
@@ -975,8 +956,6 @@ class SET(_StringType):
 
           Column('myset', MSSet("'foo'", "'bar'", "'baz'"))
 
-        Arguments are:
-
         :param values: The range of valid values for this SET.  Values will be
           used exactly as they appear when generating schemas.  Strings must
           be quoted, as in the example above.  Single-quotes are suggested for