- Documented SQLite DATE/TIME/DATETIME types.

[ticket:2029] (also in 0.6.7)
- add "currentmodule" directive to all the dialect type docs to
ensure users import from the dialect package, not the "base" module

diff --git a/CHANGES b/CHANGES
index 15c07087017d3f13281a80d53836384f2f2a17ff..5ec0dae420d22ec4eba00f8b2071cb656279aa59 100644 (file)
--- a/CHANGES
+++ b/CHANGES
@@ -50,6 +50,10 @@ CHANGES
     talking to cx_oracle.  [ticket:2100]  (Also
     in 0.6.7)
 
+- documentation
+  - Documented SQLite DATE/TIME/DATETIME types.
+    [ticket:2029] (also in 0.6.7)
+
 0.7.0b3
 =======
 - general

diff --git a/doc/build/dialects/drizzle.rst b/doc/build/dialects/drizzle.rst
index 0857ca8598990e40a73f415d576d618362406640..ab1b703da304ae4a962312dc787d968f1204d58e 100644 (file)
--- a/doc/build/dialects/drizzle.rst
+++ b/doc/build/dialects/drizzle.rst
@@ -17,6 +17,8 @@ valid with Drizzle are importable from the top level dialect::
 Types which are specific to Drizzle, or have Drizzle-specific 
 construction arguments, are as follows:
 
+.. currentmodule:: sqlalchemy.dialects.drizzle
+
 .. autoclass:: BIGINT
     :members: __init__
     :show-inheritance:

diff --git a/doc/build/dialects/mssql.rst b/doc/build/dialects/mssql.rst
index 658ca8988fda466db07d713535493163b654ac33..3b676060214329400e3280d6244c4ef7024f34b2 100644 (file)
--- a/doc/build/dialects/mssql.rst
+++ b/doc/build/dialects/mssql.rst
@@ -20,6 +20,8 @@ they originate from :mod:`sqlalchemy.types` or from the local dialect::
 Types which are specific to SQL Server, or have SQL Server-specific 
 construction arguments, are as follows:
 
+.. currentmodule:: sqlalchemy.dialects.mssql
+
 .. autoclass:: BIT
    :members: __init__
    :show-inheritance:

diff --git a/doc/build/dialects/mysql.rst b/doc/build/dialects/mysql.rst
index c8edbceab922ebebc100e79f12f984f2ff390f24..ff8f37bcb503881dc99852ab1483393c5db1b4f9 100644 (file)
--- a/doc/build/dialects/mysql.rst
+++ b/doc/build/dialects/mysql.rst
@@ -19,6 +19,8 @@ valid with MySQL are importable from the top level dialect::
 Types which are specific to MySQL, or have MySQL-specific 
 construction arguments, are as follows:
 
+.. currentmodule:: sqlalchemy.dialects.mysql
+
 .. autoclass:: BIGINT
     :members: __init__
     :show-inheritance:

diff --git a/doc/build/dialects/oracle.rst b/doc/build/dialects/oracle.rst
index 363cebffd441def47ad8405c088d892a62d45206..d5cd969ea40a0ea9774883b88c15357ce86abb17 100644 (file)
--- a/doc/build/dialects/oracle.rst
+++ b/doc/build/dialects/oracle.rst
@@ -19,6 +19,8 @@ they originate from :mod:`sqlalchemy.types` or from the local dialect::
 Types which are specific to Oracle, or have Oracle-specific 
 construction arguments, are as follows:
 
+.. currentmodule:: sqlalchemy.dialects.oracle
+
 .. autoclass:: BFILE
   :members: __init__
   :show-inheritance:

diff --git a/doc/build/dialects/postgresql.rst b/doc/build/dialects/postgresql.rst
index 02e714b6a2c9cb33ff41c86fa84b32755836333b..6e45992eb7dc1dace7bd05537a56972c13dd7979 100644 (file)
--- a/doc/build/dialects/postgresql.rst
+++ b/doc/build/dialects/postgresql.rst
@@ -21,6 +21,8 @@ they originate from :mod:`sqlalchemy.types` or from the local dialect::
 Types which are specific to PostgreSQL, or have PostgreSQL-specific 
 construction arguments, are as follows:
 
+.. currentmodule:: sqlalchemy.dialects.postgresql
+
 .. autoclass:: ARRAY
     :members: __init__
     :show-inheritance:

diff --git a/doc/build/dialects/sqlite.rst b/doc/build/dialects/sqlite.rst
index e331e7ba8eec9b6b6ef32b56f4a26bf54a4fb83d..21fd4e3aa5234c44149b31527db29dcceb930214 100644 (file)
--- a/doc/build/dialects/sqlite.rst
+++ b/doc/build/dialects/sqlite.rst
@@ -17,6 +17,14 @@ they originate from :mod:`sqlalchemy.types` or from the local dialect::
                 INTEGER, NUMERIC, SMALLINT, TEXT, TIME, TIMESTAMP, \
                 VARCHAR
 
+.. module:: sqlalchemy.dialects.sqlite
+
+.. autoclass:: DATETIME
+
+.. autoclass:: DATE
+
+.. autoclass:: TIME
+
 Pysqlite
 --------
 

diff --git a/lib/sqlalchemy/dialects/sqlite/base.py b/lib/sqlalchemy/dialects/sqlite/base.py
index eb7c6de21aaecadeaf49ae3ece724317944f2717..36357597cc0e6fd78db4943d94cdbba880b6265b 100644 (file)
--- a/lib/sqlalchemy/dialects/sqlite/base.py
+++ b/lib/sqlalchemy/dialects/sqlite/base.py
@@ -66,7 +66,6 @@ from sqlalchemy.types import BLOB, BOOLEAN, CHAR, DATE, DATETIME, DECIMAL,\
                             FLOAT, INTEGER, NUMERIC, SMALLINT, TEXT, TIME,\
                             TIMESTAMP, VARCHAR
 
-
 class _DateTimeMixin(object):
     _reg = None
     _storage_format = None
@@ -79,6 +78,41 @@ class _DateTimeMixin(object):
             self._storage_format = storage_format
 
 class DATETIME(_DateTimeMixin, sqltypes.DateTime):
+    """Represent a Python datetime object in SQLite using a string.
+    
+    The default string storage format is::
+    
+        "%04d-%02d-%02d %02d:%02d:%02d.%06d" % (value.year, 
+                                value.month, value.day,
+                                value.hour, value.minute, 
+                                value.second, value.microsecond)
+    
+    e.g.::
+    
+        2011-03-15 12:05:57.10558
+    
+    The storage format can be customized to some degree using the 
+    ``storage_format`` and ``regexp`` parameters, such as::
+        
+        import re
+        from sqlalchemy.dialects.sqlite import DATETIME
+        
+        dt = DATETIME(
+                storage_format="%04d/%02d/%02d %02d-%02d-%02d-%06d",
+                regexp=re.compile("(\d+)/(\d+)/(\d+) (\d+)-(\d+)-(\d+)(?:-(\d+))?")
+            )
+    
+    :param storage_format: format string which will be appled to the 
+     tuple ``(value.year, value.month, value.day, value.hour,
+     value.minute, value.second, value.microsecond)``, given a
+     Python datetime.datetime() object.
+    
+    :param regexp: regular expression which will be applied to 
+     incoming result rows. The resulting match object is appled to
+     the Python datetime() constructor via ``*map(int,
+     match_obj.groups(0))``.
+    """
+
     _storage_format = "%04d-%02d-%02d %02d:%02d:%02d.%06d"
 
     def bind_processor(self, dialect):
@@ -108,6 +142,38 @@ class DATETIME(_DateTimeMixin, sqltypes.DateTime):
             return processors.str_to_datetime
 
 class DATE(_DateTimeMixin, sqltypes.Date):
+    """Represent a Python date object in SQLite using a string.
+
+    The default string storage format is::
+    
+        "%04d-%02d-%02d" % (value.year, value.month, value.day)
+    
+    e.g.::
+    
+        2011-03-15
+    
+    The storage format can be customized to some degree using the 
+    ``storage_format`` and ``regexp`` parameters, such as::
+    
+        import re
+        from sqlalchemy.dialects.sqlite import DATE
+
+        d = DATE(
+                storage_format="%02d/%02d/%02d",
+                regexp=re.compile("(\d+)/(\d+)/(\d+)")
+            )
+    
+    :param storage_format: format string which will be appled to the 
+     tuple ``(value.year, value.month, value.day)``,
+     given a Python datetime.date() object.
+    
+    :param regexp: regular expression which will be applied to 
+     incoming result rows. The resulting match object is appled to
+     the Python date() constructor via ``*map(int,
+     match_obj.groups(0))``.
+     
+    """
+
     _storage_format = "%04d-%02d-%02d"
 
     def bind_processor(self, dialect):
@@ -131,6 +197,40 @@ class DATE(_DateTimeMixin, sqltypes.Date):
             return processors.str_to_date
 
 class TIME(_DateTimeMixin, sqltypes.Time):
+    """Represent a Python time object in SQLite using a string.
+    
+    The default string storage format is::
+    
+        "%02d:%02d:%02d.%06d" % (value.hour, value.minute, 
+                                value.second,
+                                 value.microsecond)
+    
+    e.g.::
+    
+        12:05:57.10558
+    
+    The storage format can be customized to some degree using the 
+    ``storage_format`` and ``regexp`` parameters, such as::
+    
+        import re
+        from sqlalchemy.dialects.sqlite import TIME
+
+        t = TIME(
+                storage_format="%02d-%02d-%02d-%06d",
+                regexp=re.compile("(\d+)-(\d+)-(\d+)-(?:-(\d+))?")
+            )
+    
+    :param storage_format: format string which will be appled 
+     to the tuple ``(value.hour, value.minute, value.second,
+     value.microsecond)``, given a Python datetime.time() object.
+    
+    :param regexp: regular expression which will be applied to 
+     incoming result rows. The resulting match object is appled to
+     the Python time() constructor via ``*map(int,
+     match_obj.groups(0))``.
+
+    """
+
     _storage_format = "%02d:%02d:%02d.%06d"
 
     def bind_processor(self, dialect):