From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Thu, 22 Sep 2016 15:08:09 +0000 (-0400)
Subject: - clarify documentation on timezone flag, since Oracle has both
X-Git-Tag: rel_1_1_0~19
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=0cc8267286f848f3cc3ab46c1e543956866a561e;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

- 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
---

diff --git a/doc/build/core/type_basics.rst b/doc/build/core/type_basics.rst
index 9edba0061c..e4f5c74c25 100644
--- a/doc/build/core/type_basics.rst
+++ b/doc/build/core/type_basics.rst
@@ -173,6 +173,7 @@ its exact name in DDL with ``CREATE TABLE`` is issued.
 
 
 .. autoclass:: TIMESTAMP
+    :members:
 
 
 .. autoclass:: VARBINARY
diff --git a/lib/sqlalchemy/sql/sqltypes.py b/lib/sqlalchemy/sql/sqltypes.py
index b55d435ad0..66e5f3e937 100644
--- a/lib/sqlalchemy/sql/sqltypes.py
+++ b/lib/sqlalchemy/sql/sqltypes.py
@@ -735,6 +735,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'
@@ -742,10 +749,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
@@ -2229,10 +2240,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