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

@@ -15,6 +15,7 @@ Unreleased
 -   Usage errors now hint at the ``--help`` option. (`#393`_, `#557`_)
 -   Implement streaming pager. (`#409`_, `#889`_)
 -   Extract bar formatting to its own method. (`#414`_)
+-   Add ``DateTime`` type for converting input in given date time formats. (`#423`_)
 -   ``secho``'s first argument can now be ``None``, like in ``echo``. (`#424`_)
 -   Fixes a ``ZeroDivisionError`` in ``ProgressBar.make_step``, when the arg passed to the first call of ``ProgressBar.update`` is 0. (`#447`_, `#1012`_)
 -   Show progressbar only if total execution time is visible. (`#487`_)
@@ -93,6 +94,7 @@ Unreleased
 .. _#393: https://github.com/pallets/click/issues/393
 .. _#409: https://github.com/pallets/click/issues/409
 .. _#414: https://github.com/pallets/click/pull/414
+.. _#423: https://github.com/pallets/click/pull/423
 .. _#424: https://github.com/pallets/click/pull/424
 .. _#447: https://github.com/pallets/click/issues/447
 .. _#487: https://github.com/pallets/click/pull/487

click/types.py

@@ -184,12 +184,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,11 +349,13 @@ 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
+    assert '--start_date [%Y-%m-%d|%Y-%m-%dT%H:%M:%S|%Y-%m-%d %H:%M:%S]' in result.output
 
 
 def test_datetime_option_custom(runner):