add UTC time zone always. (#37)

* add UTC time zone always.

Author: flask-pro

CHANGES.md

@@ -1,3 +1,7 @@
+## Version 0.20.0
+
+* For date and time from `date-dime` format fields, the time zone is enforced set in the UTC.
+
 ## Version 0.19.1
 
 * Fix ref resolver.

README.md

@@ -10,6 +10,7 @@ Flask extension for using "specification first" and "API-first" principles.
   - [Settings](#settings)
   - [Tools](#tools)
   - [Data types](#data-types)
+    - [`date-time` format](#date-time-format)
   - [Examples](#examples)
     - [Simple example](#simple-example)
     - [Specification from multiple file](#specification-from-multiple-file)
@@ -30,6 +31,7 @@ Flask extension for using "specification first" and "API-first" principles.
 * Provides a Swagger UI.
 * Support OpenAPI version 3.1.0.
 * Support specification from multiple file.
+* The time zone is always UTC.
 
 ## Installation
 
@@ -79,6 +81,11 @@ Supported formats for string type field:
 * uri
 * binary
 
+### `date-time` format
+
+For `date-dime` format, the time zone is enforced set in the UTC. The time zone of the incoming
+DateTime object is discarded and set as UTC.
+
 ## Examples
 
 ### Simple example

pyproject.toml

@@ -23,7 +23,7 @@ license = {file = "LICENSE"}
 name = "Flask-First"
 readme = "README.md"
 requires-python = ">=3.9"
-version = "0.19.1"
+version = "0.20.0"
 
 [project.optional-dependencies]
 dev = [

src/flask_first/__init__.py

@@ -141,7 +141,7 @@ def add_request_validating() -> None:
             route_as_in_spec = self.route_to_openapi_format(route)
 
             method = self._extract_method_from_request(request)
-            params_schemas = self.spec.serialized_spec['paths'][route_as_in_spec][method].get(
+            params_schemas = self.spec.deserialized_spec['paths'][route_as_in_spec][method].get(
                 'parameters'
             )
             args = self._resolved_params(request.args)
@@ -188,7 +188,7 @@ def add_response_validating(response: Response) -> Response:
             route_as_in_spec = self.route_to_openapi_format(route)
 
             try:
-                route_schema: dict = self.spec.serialized_spec['paths'][route_as_in_spec]
+                route_schema: dict = self.spec.deserialized_spec['paths'][route_as_in_spec]
             except KeyError as e:
                 raise FirstResponseJSONValidation(
                     f'Route <{e.args[0]}> not defined in specification.'

src/flask_first/first/serializers.py

@@ -28,7 +28,7 @@ def __init__(
         json: dict = None,
     ) -> None:
         self.spec = spec
-        self._paths_schema = self.spec.serialized_spec['paths']
+        self._paths_schema = self.spec.deserialized_spec['paths']
 
         self.method = method.lower()
         self.endpoint = endpoint

src/flask_first/first/specification.py

@@ -25,7 +25,7 @@ def __init__(
         self.raw_spec = load_from_yaml(self.path)
         self._validating_openapi_file(self.path, self.experimental_validator)
         self.resolved_spec = self._convert_parameters_to_schema(self.raw_spec)
-        self.serialized_spec = self._convert_schemas(self.resolved_spec)
+        self.deserialized_spec = self._convert_schemas(self.resolved_spec)
 
     def _validating_openapi_file(self, path: Path, experimental_validator: bool):
         if experimental_validator:

src/flask_first/schema/schema_maker.py

@@ -1,3 +1,4 @@
+from datetime import timezone
 from typing import Any
 from typing import Optional
 
@@ -39,7 +40,7 @@ class HashmapField(fields.Field):
 
 FIELDS_VIA_FORMATS = {
     'uuid': fields.UUID,
-    'date-time': fields.DateTime,
+    'date-time': fields.AwareDateTime,
     'date': fields.Date,
     'time': fields.Time,
     'email': fields.Email,
@@ -96,7 +97,9 @@ def _make_array_field(schema: dict, datetime_format: Optional[str] = None) -> fi
         field = nested_field
     elif data_format in FIELDS_VIA_FORMATS:
         if data_format == 'date-time':
-            nested_field = FIELDS_VIA_FORMATS['date-time'](format=datetime_format)
+            nested_field = FIELDS_VIA_FORMATS['date-time'](
+                format=datetime_format, default_timezone=timezone.utc
+            )
         else:
             nested_field = FIELDS_VIA_FORMATS[data_format]()
         field = fields.List(nested_field)
@@ -144,7 +147,9 @@ def make_marshmallow_schema(
         field = _make_multiple_field(schema['oneOf'], 'oneOf')
     elif schema.get('format'):
         if schema['format'] == 'date-time':
-            field = FIELDS_VIA_FORMATS['date-time'](format=datetime_format)
+            field = FIELDS_VIA_FORMATS['date-time'](
+                format=datetime_format, default_timezone=timezone.utc
+            )
         else:
             field = FIELDS_VIA_FORMATS[schema['format']]()
 

tests/fields/test_format_datetime.py

@@ -0,0 +1,54 @@
+from datetime import datetime
+from pathlib import Path
+
+import pytest
+from flask import request
+from flask_first.first.exceptions import FirstRequestJSONValidation
+from flask_first.first.exceptions import FirstResponseJSONValidation
+
+from tests.conftest import BASEDIR
+
+
+def test_format_datetime(fx_create_app):
+    def create_datetime() -> dict:
+        datetime = request.extensions['first']['json']['datetime'].strftime("%Y-%m-%dT%H:%M:%S.%fZ")
+        return {'datetime': datetime}
+
+    test_client = fx_create_app(
+        Path(BASEDIR, 'specs/v3.1.0/datetime.openapi.yaml'), [create_datetime]
+    )
+
+    json = {'datetime': datetime.utcnow().strftime("%Y-%m-%dT%H:%M:%S.%fZ")}
+    r = test_client.post('/datetime', json=json)
+    assert r.status_code == 200
+    assert r.json['datetime'] == json['datetime']
+
+
+def test_request_datetime_error(fx_create_app):
+    def create_datetime() -> dict:
+        datetime = request.extensions['first']['json']['datetime']
+        return {'datetime': datetime}
+
+    test_client = fx_create_app(
+        Path(BASEDIR, 'specs/v3.1.0/datetime.openapi.yaml'), [create_datetime]
+    )
+
+    json = {'datetime': datetime.utcnow().isoformat()}
+
+    with pytest.raises(FirstRequestJSONValidation):
+        test_client.post('/datetime', json=json)
+
+
+def test_response_datetime_error(fx_create_app):
+    def create_datetime() -> dict:
+        datetime = request.extensions['first']['json']['datetime'].isoformat()
+        return {'datetime': datetime}
+
+    test_client = fx_create_app(
+        Path(BASEDIR, 'specs/v3.1.0/datetime.openapi.yaml'), [create_datetime]
+    )
+
+    json = {'datetime': datetime.utcnow().strftime("%Y-%m-%dT%H:%M:%S.%fZ")}
+
+    with pytest.raises(FirstResponseJSONValidation):
+        test_client.post('/datetime', json=json)

tests/test_flask_first.py

@@ -310,12 +310,12 @@ def mini_endpoint(uuid_from_path: str, datetime_from_path: str) -> dict:
 
         assert isinstance(uuid_from_query, uuid.UUID)
         assert uuid_from_path == str(uuid_from_query)
-        assert datetime_from_path == str(datetime_from_query).replace(' ', 'T')
+        assert datetime_from_path == datetime_from_query.strftime("%Y-%m-%dT%H:%M:%S.%fZ")
 
         return {
             'uuid_from_path': uuid_from_path,
             'uuid_from_query': str(uuid_from_query),
-            'datetime_from_query': str(datetime_from_query).replace(' ', 'T'),
+            'datetime_from_query': datetime_from_query.strftime("%Y-%m-%dT%H:%M:%S.%fZ"),
         }
 
     first = First(Path(BASEDIR, 'specs/v3.1.0/parameters.openapi.yaml'))
@@ -325,6 +325,7 @@ def create_app():
         app.debug = 1
         app.testing = 1
         app.config['FIRST_RESPONSE_VALIDATION'] = True
+        app.config['FIRST_DATETIME_FORMAT'] = "%Y-%m-%dT%H:%M:%S.%fZ"
         first.init_app(app)
         first.add_view_func(mini_endpoint)
         return app
@@ -333,10 +334,10 @@ def create_app():
 
     with app.test_client() as test_client:
         test_uuid = str(uuid.uuid4())
-        test_datetime = '2021-12-24T18:32:05'
+        test_datetime = '2021-12-24T18:32:05.123456Z'
+        query_string = {'uuid_from_query': test_uuid, 'datetime_from_query': test_datetime}
         r = test_client.get(
-            f'/parameters_endpoint/{test_uuid}/{test_datetime}',
-            query_string={'uuid_from_query': test_uuid, 'datetime_from_query': test_datetime},
+            f'/parameters_endpoint/{test_uuid}/{test_datetime}', query_string=query_string
         )
         assert r.status_code == 200
         assert r.json == {

tests/test_responses.py

@@ -1,10 +1,6 @@
-from datetime import datetime
 from pathlib import Path
 
-import pytest
 from flask import request
-from flask_first.first.exceptions import FirstRequestJSONValidation
-from flask_first.first.exceptions import FirstResponseJSONValidation
 
 from .conftest import BASEDIR
 
@@ -20,48 +16,3 @@ def default_responses() -> dict:
     r = test_client.post('/message', json={'message': 'OK'})
     assert r.status_code == 200
     assert r.json['message'] == 'OK'
-
-
-def test_responses__datetime(fx_create_app):
-    def create_datetime() -> dict:
-        datetime = request.extensions['first']['json']['datetime'].strftime("%Y-%m-%dT%H:%M:%S.%fZ")
-        return {'datetime': datetime}
-
-    test_client = fx_create_app(
-        Path(BASEDIR, 'specs/v3.1.0/datetime.openapi.yaml'), [create_datetime]
-    )
-
-    json = {'datetime': datetime.utcnow().strftime("%Y-%m-%dT%H:%M:%S.%fZ")}
-    r = test_client.post('/datetime', json=json)
-    assert r.status_code == 200
-    assert r.json['datetime'] == json['datetime']
-
-
-def test_responses__request_datetime_error(fx_create_app):
-    def create_datetime() -> dict:
-        datetime = request.extensions['first']['json']['datetime']
-        return {'datetime': datetime}
-
-    test_client = fx_create_app(
-        Path(BASEDIR, 'specs/v3.1.0/datetime.openapi.yaml'), [create_datetime]
-    )
-
-    json = {'datetime': datetime.utcnow().isoformat()}
-
-    with pytest.raises(FirstRequestJSONValidation):
-        test_client.post('/datetime', json=json)
-
-
-def test_responses__response_datetime_error(fx_create_app):
-    def create_datetime() -> dict:
-        datetime = request.extensions['first']['json']['datetime'].isoformat()
-        return {'datetime': datetime}
-
-    test_client = fx_create_app(
-        Path(BASEDIR, 'specs/v3.1.0/datetime.openapi.yaml'), [create_datetime]
-    )
-
-    json = {'datetime': datetime.utcnow().strftime("%Y-%m-%dT%H:%M:%S.%fZ")}
-
-    with pytest.raises(FirstResponseJSONValidation):
-        test_client.post('/datetime', json=json)