- clarify documentation on timezone flag, since Oracle has both

DATE / TIMESTAMP separately the timezone flag will not bump the
type to TIMESTAMP WITH TIMEZONE on that backend.

Change-Id: I185992093472e1620b8cf84872631a4d48f8edc3
(cherry picked from commit 0cc8267286f848f3cc3ab46c1e543956866a561e)

diff --git a/doc/build/core/type_basics.rst b/doc/build/core/type_basics.rst
index 1ff1baac2424f8d799a979effae6d146d69271f4..a091c0db81d224281a1fcfe82ddf96c37537c0ed 100644 (file)
--- a/doc/build/core/type_basics.rst
+++ b/doc/build/core/type_basics.rst
@@ -163,6 +163,7 @@ on all databases.
 
 
 .. autoclass:: TIMESTAMP
+    :members:
 
 
 .. autoclass:: VARBINARY

diff --git a/lib/sqlalchemy/sql/sqltypes.py b/lib/sqlalchemy/sql/sqltypes.py
index 20a9b21e35e6ec54a90edbf41d24ae07ce377a41..a4763e63e73a0ad1e87d63931f6248b22068137e 100644 (file)
--- a/lib/sqlalchemy/sql/sqltypes.py
+++ b/lib/sqlalchemy/sql/sqltypes.py
@@ -701,6 +701,13 @@ class DateTime(_DateAffinity, TypeEngine):
     SQLite, date and time types are stored as strings which are then
     converted back to datetime objects when rows are returned.
 
+    For the time representation within the datetime type, some
+    backends include additional options, such as timezone support and
+    fractional seconds support.  For fractional seconds, use the
+    dialect-specific datatype, such as :class:`.mysql.TIME`.  For
+    timezone support, use at least the :class:`~.types.TIMESTAMP` datatype,
+    if not the dialect-specific datatype object.
+
     """
 
     __visit_name__ = 'datetime'
@@ -708,10 +715,14 @@ class DateTime(_DateAffinity, TypeEngine):
     def __init__(self, timezone=False):
         """Construct a new :class:`.DateTime`.
 
-        :param timezone: boolean.  If True, and supported by the
-         backend, will produce 'TIMESTAMP WITH TIMEZONE'. For backends
-         that don't support timezone aware timestamps, has no
-         effect.
+        :param timezone: boolean.  Indicates that the datetime type should
+         enable timezone support, if available on the
+         **base date/time-holding type only**.   It is recommended
+         to make use of the :class:`~.types.TIMESTAMP` datatype directly when
+         using this flag, as some databases include separate generic
+         date/time-holding types distinct from the timezone-capable
+         TIMESTAMP datatype, such as Oracle.
+
 
         """
         self.timezone = timezone
@@ -1510,10 +1521,30 @@ class BIGINT(BigInteger):
 
 class TIMESTAMP(DateTime):
 
-    """The SQL TIMESTAMP type."""
+    """The SQL TIMESTAMP type.
+
+    :class:`~.types.TIMESTAMP` datatypes have support for timezone
+    storage on some backends, such as Postgresql and Oracle.  Use the
+    :paramref:`~types.TIMESTAMP.timezone` argument in order to enable
+    "TIMESTAMP WITH TIMEZONE" for these backends.
+
+    """
 
     __visit_name__ = 'TIMESTAMP'
 
+    def __init__(self, timezone=False):
+        """Construct a new :class:`.TIMESTAMP`.
+
+        :param timezone: boolean.  Indicates that the TIMESTAMP type should
+         enable timezone support, if available on the target database.
+         On a per-dialect basis is similar to "TIMESTAMP WITH TIMEZONE".
+         If the target database does not support timezones, this flag is
+         ignored.
+
+
+        """
+        super(TIMESTAMP, self).__init__(timezone=timezone)
+
     def get_dbapi_type(self, dbapi):
         return dbapi.TIMESTAMP