epoch - tests & doc

Author: commonism

docs/source/advanced.rst

@@ -484,3 +484,14 @@ Limiting the concurrency to a certain number of clients:
                 break
             else:
                 done, pending = await asyncio.wait(pending, return_when=asyncio.FIRST_COMPLETED)
+
+Epoch Types
+===========
+
+If installed, pydantic-extra-types is used to provide an epoch data type for integers and float values mapping to datetime.datetime.
+
+A :ref:`Document Plugin <plugin:Document>` can be used to modify a description document to add a format: date-time to the numeric type definition for a posix timestamp.
+
+.. code:: yaml
+        type: integer
+        format: date-time

docs/source/plugin.rst

@@ -128,6 +128,16 @@ Using a Document plugin to modify the parsed description document to state the c
     api = OpenAPI.load_sync("https://try.gitea.io/swagger.v1.json", plugins=[ContentType()])
 
 
+Another example is adding the "format" specifier to an epoch timestamp to have it de-serialized as datetime instead of number/integer.
+
+.. code:: python
+
+    class EpochTimestamp(aiopenapi3.plugin.Document):
+        def parsed(self, ctx):
+            ctx.document["components"]["schemas"]["LogEvent"]["properties"]["timestamp"]["format"] = "date-time"
+            return ctx
+
+
 Message
 =======
 

tests/fixtures/petstore-expanded.yaml

@@ -131,10 +131,13 @@ components:
         - type: object
           required:
             - id
+            - properties
           properties:
             id:
               type: integer
               format: int64
+            created:
+              type: integer
 
     NewPet:
       type: object

tests/plugin_test.py

@@ -1,7 +1,7 @@
-import httpx
-
+import datetime
 from pathlib import Path
 
+import httpx
 import yarl
 
 from aiopenapi3 import FileSystemLoader, OpenAPI
@@ -43,6 +43,7 @@ def parsed(self, ctx):
                     },
                 }
             )
+            ctx.document["components"]["schemas"]["Pet"]["allOf"][1]["properties"]["created"]["format"] = "date-time"
         else:
             raise ValueError(f"unexpected url {ctx.url.path} expecting {self.url}")
 
@@ -57,7 +58,7 @@ def sending(self, ctx):
         return ctx
 
     def received(self, ctx):
-        ctx.received = """[{"id":1,"name":"theanimal", "weight": null}]"""
+        ctx.received = """[{"id":1,"name":"theanimal", "created":4711,"weight": null}]"""
         return ctx
 
     def parsed(self, ctx):
@@ -94,3 +95,4 @@ def test_Plugins(httpx_mock, with_plugin_base):
     assert item.id == 3
     assert item.weight == None  # default does not apply as it it unsed
     assert item.color == "red"  # default does not apply
+    assert item.created == datetime.datetime.fromtimestamp(4711, tz=datetime.timezone.utc)