From c56a7eebf4c72844ddf625ee30d1ca004f48dbbd Mon Sep 17 00:00:00 2001
From: Sebastien LOVERGNE <sebastien.lovergne@rfconception.com>
Date: Wed, 15 Feb 2023 09:52:10 +0100
Subject: [PATCH] Add support for the multiple formats of
 marshmallow.fields.DateTime

---
 AUTHORS.rst                                   |  1 +
 docs/using_plugins.rst                        | 16 ++++
 .../ext/marshmallow/field_converter.py        | 43 ++++++++++
 tests/test_ext_marshmallow_field.py           | 85 ++++++++++++++++++-
 4 files changed, 141 insertions(+), 4 deletions(-)

diff --git a/AUTHORS.rst b/AUTHORS.rst
index afe779fb..0195cec0 100644
--- a/AUTHORS.rst
+++ b/AUTHORS.rst
@@ -76,3 +76,4 @@ Contributors (chronological)
 - `<https://github.com/kasium>`_
 - Edwin Erdmanis `@vorticity <https://github.com/vorticity>`_
 - Mounier Florian `@paradoxxxzero <https://github.com/paradoxxxzero>`_
+- Sebastien Lovergne `@TheBigRoomXXL <https://github.com/TheBigRoomXXL>`_
diff --git a/docs/using_plugins.rst b/docs/using_plugins.rst
index 8dd2b4bc..60ea6b2a 100644
--- a/docs/using_plugins.rst
+++ b/docs/using_plugins.rst
@@ -235,6 +235,22 @@ Schema Modifiers
 
 apispec will respect schema modifiers such as ``exclude`` and ``partial`` in the generated schema definition. If a schema is initialized with modifiers, apispec will treat each combination of modifiers as a unique schema definition.
 
+Custom DateTime format
+*************
+
+apispec support all four basic formats of `marshmallow.fields.DateTime`: ``"rfc"`` (for RFC822), ``"iso"`` (for ISO8601), 
+``"timestamp"``, ``"timestamp_ms"`` (for a POSIX timestamp).
+
+If you are using a custom DateTime format you should pass a regex string to the ``pattern`` parametter in your field ``metadata``. 
+
+.. code-block:: python
+
+    class SchemaWithCustomDate(Schema):
+        french_date = ma.DateTime(
+            format="%d-%m%Y %H:%M:%S",
+            metadata={"pattern": r"^\d{2}-\d{2}-\d{4} \d{2}:\d{2}:\d{2}$"},
+        )
+
 Custom Fields
 *************
 
diff --git a/src/apispec/ext/marshmallow/field_converter.py b/src/apispec/ext/marshmallow/field_converter.py
index 20bc56ff..2e5f0c10 100644
--- a/src/apispec/ext/marshmallow/field_converter.py
+++ b/src/apispec/ext/marshmallow/field_converter.py
@@ -111,6 +111,7 @@ def init_attribute_functions(self):
             self.list2properties,
             self.dict2properties,
             self.timedelta2properties,
+            self.datetime2properties,
         ]
 
     def map_to_openapi_type(self, field_cls, *args):
@@ -516,6 +517,48 @@ def enum2properties(self, field, **kwargs: typing.Any) -> dict:
             ret["enum"] = [field.field._serialize(v, None, None) for v in choices]
         return ret
 
+    def datetime2properties(self, field, **kwargs: typing.Any) -> dict:
+        """Return a dictionary of properties from :class:`DateTime <marshmallow.fields.DateTime` fields.
+
+        :param Field field: A marshmallow field.
+        :rtype: dict
+        """
+        ret = {}
+        if isinstance(field, marshmallow.fields.DateTime) and not isinstance(
+            field, marshmallow.fields.Date
+        ):
+            if field.format == "iso" or field.format is None:
+                # Will return { "type": "string", "format": "date-time" }
+                # as specified inside DEFAULT_FIELD_MAPPING
+                pass
+            elif field.format == "rfc":
+                ret = {
+                    "type": "string",
+                    "format": None,
+                    "example": "Wed, 02 Oct 2002 13:00:00 GMT",
+                    "pattern": r"((Mon|Tue|Wed|Thu|Fri|Sat|Sun), ){0,1}\d{2} "
+                    + r"(Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) \d{4} \d{2}:\d{2}:\d{2} "
+                    + r"(UT|GMT|EST|EDT|CST|CDT|MST|MDT|PST|PDT|(Z|A|M|N)|(\+|-)\d{4})",
+                }
+            elif "timestamp" in field.format:
+                ret = {
+                    "type": "number",
+                    "format": "float",
+                    "example": "1676451245.596",
+                    "min": "0",
+                }
+                if "_ms" in field.format:
+                    ret["example"] = "1676451277514.654"
+            else:
+                ret = {
+                    "type": "string",
+                    "format": None,
+                    "pattern": field.metadata["pattern"]
+                    if field.metadata.get("pattern")
+                    else None,
+                }
+        return ret
+
 
 def make_type_list(types):
     """Return a list of types from a type attribute
diff --git a/tests/test_ext_marshmallow_field.py b/tests/test_ext_marshmallow_field.py
index 41143dd6..3b9288af 100644
--- a/tests/test_ext_marshmallow_field.py
+++ b/tests/test_ext_marshmallow_field.py
@@ -26,7 +26,7 @@ def test_field2choices_preserving_order(openapi):
         (fields.Boolean, "boolean"),
         (fields.Bool, "boolean"),
         (fields.UUID, "string"),
-        (fields.DateTime, "string"),
+        (fields.DateTime, ["string", "integer"]),
         (fields.Date, "string"),
         (fields.Time, "string"),
         (fields.TimeDelta, "integer"),
@@ -40,7 +40,10 @@ def test_field2choices_preserving_order(openapi):
 def test_field2property_type(FieldClass, jsontype, spec_fixture):
     field = FieldClass()
     res = spec_fixture.openapi.field2property(field)
-    assert res["type"] == jsontype
+    if isinstance(jsontype, list):
+        assert res["type"] in jsontype
+    else:
+        assert res["type"] == jsontype
 
 
 @pytest.mark.parametrize("FieldClass", [fields.Field, fields.Raw])
@@ -62,7 +65,7 @@ def test_formatted_field_translates_to_array(ListClass, spec_fixture):
     ("FieldClass", "expected_format"),
     [
         (fields.UUID, "uuid"),
-        (fields.DateTime, "date-time"),
+        (fields.DateTime, ["date-time", "timestamp", "timestamp_ms"]),
         (fields.Date, "date"),
         (fields.Email, "email"),
         (fields.URL, "url"),
@@ -71,7 +74,11 @@ def test_formatted_field_translates_to_array(ListClass, spec_fixture):
 def test_field2property_formats(FieldClass, expected_format, spec_fixture):
     field = FieldClass()
     res = spec_fixture.openapi.field2property(field)
-    assert res["format"] == expected_format
+
+    if isinstance(expected_format, list):
+        assert res["format"] in expected_format
+    else:
+        assert res["format"] == expected_format
 
 
 def test_field_with_description(spec_fixture):
@@ -364,6 +371,76 @@ def test_nested_field_with_property(spec_fixture):
     }
 
 
+def test_datetime2property_iso(spec_fixture):
+    field = fields.DateTime(format="iso")
+    res = spec_fixture.openapi.field2property(field)
+    print(test_datetime2property_iso)
+    assert res == {
+        "type": "string",
+        "format": "date-time",
+    }
+
+
+def test_datetime2property_rfc(spec_fixture):
+    field = fields.DateTime(format="rfc")
+    res = spec_fixture.openapi.field2property(field)
+    assert res == {
+        "type": "string",
+        "format": None,
+        "example": "Wed, 02 Oct 2002 13:00:00 GMT",
+        "pattern": r"((Mon|Tue|Wed|Thu|Fri|Sat|Sun), ){0,1}\d{2} "
+        + r"(Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) \d{4} \d{2}:\d{2}:\d{2} "
+        + r"(UT|GMT|EST|EDT|CST|CDT|MST|MDT|PST|PDT|(Z|A|M|N)|(\+|-)\d{4})",
+    }
+
+
+def test_datetime2property_timestamp(spec_fixture):
+    field = fields.DateTime(format="timestamp")
+    res = spec_fixture.openapi.field2property(field)
+    assert res == {
+        "type": "number",
+        "format": "float",
+        "min": "0",
+        "example": "1676451245.596",
+    }
+
+
+def test_datetime2property_timestamp_ms(spec_fixture):
+    field = fields.DateTime(format="timestamp_ms")
+    res = spec_fixture.openapi.field2property(field)
+    assert res == {
+        "type": "number",
+        "format": "float",
+        "min": "0",
+        "example": "1676451277514.654",
+    }
+
+
+def test_datetime2property_custom_format(spec_fixture):
+    field = fields.DateTime(
+        format="%d-%m%Y %H:%M:%S",
+        metadata={
+            "pattern": r"^((?:(\d{4}-\d{2}-\d{2})T(\d{2}:\d{2}:\d{2}(?:\.\d+)?))(Z|[\+-]\d{2}:\d{2})?)$"
+        },
+    )
+    res = spec_fixture.openapi.field2property(field)
+    assert res == {
+        "type": "string",
+        "format": None,
+        "pattern": r"^((?:(\d{4}-\d{2}-\d{2})T(\d{2}:\d{2}:\d{2}(?:\.\d+)?))(Z|[\+-]\d{2}:\d{2})?)$",
+    }
+
+
+def test_datetime2property_custom_format_missing_regex(spec_fixture):
+    field = fields.DateTime(format="%d-%m%Y %H:%M:%S")
+    res = spec_fixture.openapi.field2property(field)
+    assert res == {
+        "type": "string",
+        "format": None,
+        "pattern": None,
+    }
+
+
 class TestField2PropertyPluck:
     @pytest.fixture(autouse=True)
     def _setup(self, spec_fixture):