datetime types docs added (#431)

* datetime types docs added

* datetime docs format changed

HISTORY.rst

@@ -6,6 +6,7 @@ History
 v0.21.1 (unreleased)
 ....................
 * add ``IPv{4,6,Any}Network`` and ``IPv{4,6,Any}Interface`` types from ``ipaddress`` stdlib, #333 by @pilosus
+* add docs for ``datetime`` types, #386 by @pilosus
 
 
 v0.21.0 (2019-03-15)

docs/examples/datetime.py

@@ -0,0 +1,22 @@
+from datetime import date, datetime, time, timedelta
+from pydantic import BaseModel
+
+class Model(BaseModel):
+    d: date = None
+    dt: datetime = None
+    t: time = None
+    td: timedelta = None
+
+
+m = Model(
+    d=1966280412345.6789,
+    dt='2032-04-23T10:20:30.400+02:30',
+    t=time(4, 8, 16),
+    td='P3DT12H30M5S'
+)
+
+print(m.dict())
+# > {'d': datetime.date(2032, 4, 22),
+# 'dt': datetime.datetime(2032, 4, 23, 10, 20, 30, 400000, tzinfo=datetime.timezone(datetime.timedelta(seconds=9000))),
+# 't': datetime.time(4, 8, 16),
+# 'td': datetime.timedelta(days=3, seconds=45005)}

docs/index.rst

@@ -393,6 +393,50 @@ You can also define your own error class with abilities to specify custom error
 
 (This script is complete, it should run "as is")
 
+datetime Types
+...............
+
+*Pydantic* supports the following `datetime <https://docs.python.org/library/datetime.html#available-types>`__
+types:
+
+* ``datetime`` fields can be:
+
+  * ``datetime``, existing ``datetime`` object
+  * ``int`` or ``float``, assumed as Unix time, e.g. seconds (if <= ``2e10``) or milliseconds (if > ``2e10``) since 1 January 1970
+  * ``str``, following formats work:
+
+    * ``YYYY-MM-DD[T]HH:MM[:SS[.ffffff]][Z[±]HH[:]MM]]]``
+    * ``int`` or ``float`` as a string (assumed as Unix time)
+
+* ``date`` fields can be:
+
+  * ``date``, existing ``date`` object
+  * ``int`` or ``float``, see ``datetime``
+  * ``str``, following formats work:
+
+    * ``YYYY-MM-DD``
+    * ``int`` or ``float``, see ``datetime``
+
+* ``time`` fields can be:
+
+  * ``time``, existing ``time`` object
+  * ``str``, following formats work:
+
+    * ``HH:MM[:SS[.ffffff]]``
+
+* ``timedelta`` fields can be:
+
+  * ``timedelta``, existing ``timedelta`` object
+  * ``int`` or ``float``, assumed as seconds
+  * ``str``, following formats work:
+
+    * ``[-][DD ][HH:MM]SS[.ffffff]``
+    * ``[±]P[DD]T[HH]H[MM]M[SS]S`` (ISO 8601 format for timedelta)
+
+
+.. literalinclude:: examples/datetime.py
+
+
 Exotic Types
 ............