Merge branch 'master' into pr/1364

Author: dantownsend

docs/src/piccolo/api_reference/index.rst

@@ -114,6 +114,43 @@ UUID
 
 .. autoclass:: UUID7
 
+
+TimestampCustom
+~~~~~~~~~~~~~~~
+
+.. autoclass:: TimestampCustom
+    :members:
+
+TimestampOffset
+~~~~~~~~~~~~~~~
+
+.. autoclass:: TimestampOffset
+    :members:
+
+TimestampNow
+~~~~~~~~~~~~
+
+.. autoclass:: TimestampNow
+    :members:
+
+TimestamptzCustom
+~~~~~~~~~~~~~~~~~
+
+.. autoclass:: TimestamptzCustom
+    :members:
+
+TimestamptzOffset
+~~~~~~~~~~~~~~~~~
+
+.. autoclass:: TimestamptzOffset
+    :members:
+
+TimestamptzNow
+~~~~~~~~~~~~~~
+
+.. autoclass:: TimestamptzNow
+    :members:
+
 -------------------------------------------------------------------------------
 
 Testing

piccolo/columns/column_types.py

@@ -885,7 +885,8 @@ def __set__(self, obj, value: Union[int, None]):
 
 class Timestamp(Column):
     """
-    Used for storing datetimes. Uses the ``datetime`` type for values.
+    Used for storing timezone naive datetimes. Uses the ``datetime`` type for
+    values.
 
     **Example**
 
@@ -905,6 +906,12 @@ class Concert(Table):
         >>> await Concert.select(Concert.starts)
         {'starts': datetime.datetime(2050, 1, 1, 0, 0)}
 
+    .. note::
+        We recommend using
+        :class:`Timestamptz <piccolo.columns.column_types.Timestamptz>`
+        columns if possible - having timezone information makes the timestamp
+        unambiguous.
+
     """
 
     value_type = datetime

piccolo/columns/defaults/__init__.py

@@ -1,5 +1,7 @@
 from .base import *  # noqa
 from .date import *  # noqa
+from .interval import *  # noqa
 from .time import *  # noqa
 from .timestamp import *  # noqa
+from .timestamptz import *  # noqa
 from .uuid import *  # noqa

piccolo/columns/defaults/timestamp.py

@@ -48,6 +48,11 @@ def python(self):
 
 
 class TimestampNow(Default):
+    """
+    The current timestamp, in the local time of the machine that Python is
+    running on.
+    """
+
     @property
     def postgres(self):
         return "current_timestamp"

piccolo/columns/defaults/timestamptz.py

@@ -28,6 +28,10 @@ def python(self):
 
 
 class TimestamptzNow(TimestampNow):
+    """
+    The current timestamp in UTC.
+    """
+
     @property
     def cockroach(self):
         return "current_timestamp"