Add documentation for DateTime param type

Add a docstring which defines the behaviors of the class, including
default formats supported, usage of ``datetime.strptime`` and "first
successful parse wins" behavior.

Also add '%Y-%m-%d %H:%M:%S' to the default formats, as it is at least
as commonly seen as '%Y-%m-%dT%H:%M:%S'.
Minor test fix to handle the new format.

Add ``click.DateTime`` to changelog.

CHANGES.rst

@@ -8,6 +8,7 @@ Version 7.0
 
 (upcoming release with new features, release date to be decided)
 
+- Added ``click.DateTime`` type for converting strings to ``datetime`` (`#423`_)
 - Non-standalone calls to Context.exit return the exit code, rather than
   calling ``sys.exit`` (`#667`_)(`#533`_)
 - Updated test env matrix. (`#1027`_)

click/types.py

@@ -183,12 +183,32 @@ def __repr__(self):
 
 
 class DateTime(ParamType):
+    """The DateTime type converts date strings into `datetime` objects.
+
+    The format strings which are checked are configurable, but default to some
+    common (non-timezone aware) ISO 8601 formats.
+
+    When specifying *DateTime* formats, you should only pass a list or a tuple.
+    Other iterables, like generators, may lead to surprising results.
+
+    The format strings are processed using ``datetime.strptime``, and this
+    consequently defines the format strings which are allowed.
+
+    Parsing is tried using each format, in order, and the first format which
+    parses successfully is used.
+
+    :param formats: A list or tuple of date format strings, in the order in
+                    which they should be tried. Defaults to
+                    ``'%Y-%m-%d'``, ``'%Y-%m-%dT%H:%M:%S'``,
+                    ``'%Y-%m-%d %H:%M:%S'``.
+    """
     name = 'datetime'
 
     def __init__(self, formats=None):
         self.formats = formats or [
             '%Y-%m-%d',
-            '%Y-%m-%dT%H:%M:%S'
+            '%Y-%m-%dT%H:%M:%S',
+            '%Y-%m-%d %H:%M:%S'
         ]
 
     def get_metavar(self, param):

docs/parameters.rst

@@ -70,6 +70,9 @@ different behavior and some are supported out of the box:
 .. autoclass:: FloatRange
   :noindex:
 
+.. autoclass:: DateTime
+   :noindex:
+
 Custom parameter types can be implemented by subclassing
 :class:`click.ParamType`.  For simple cases, passing a Python function that
 fails with a `ValueError` is also supported, though discouraged.

tests/test_basic.py

@@ -349,8 +349,10 @@ def cli(start_date):
 
     result = runner.invoke(cli, ['--start_date=2015-09'])
     assert result.exit_code == 2
-    assert 'Invalid value for "--start_date": invalid datetime format: 2015-09. ' \
-        '(choose from %Y-%m-%d, %Y-%m-%dT%H:%M:%S)' in result.output
+    assert ('Invalid value for "--start_date": '
+            'invalid datetime format: 2015-09. '
+            '(choose from %Y-%m-%d, %Y-%m-%dT%H:%M:%S, %Y-%m-%d %H:%M:%S)'
+            ) in result.output
 
     result = runner.invoke(cli, ['--help'])
     assert '--start_date [%Y-%m-%d|%Y-%m-%dT%H:%M:%S]' in result.output