Implemented Marshmallow Schemas amidts other small fixes

src/api/schemas.py

@@ -0,0 +1,74 @@
+"""
+Provides a bunch of Marshmallow Schemas to validate rainfall data processed through the API.
+"""
+
+from typing import Optional, Union
+
+from flasgger import Schema, fields
+
+from src.core.utils.enums.time_modes import TimeMode
+
+
+class BaseRainfall(Schema):
+    """
+    Base schema for depicting a value linked to rainfall data.
+    Should be used as a parent class.
+    """
+    value: Union[float, int] = fields.Number()
+    begin_year: int = fields.Int()
+    end_year: Optional[int] = fields.Int()
+    time_mode: str = fields.Str()
+
+
+class AverageYearlyRainfall(BaseRainfall):
+    """
+    Schema for depicting an average rainfall for a yearly time mode.
+    """
+    name: str = fields.Str(load_default='average rainfall')
+    value: float = fields.Float()
+    time_mode: str = fields.Str(load_default=TimeMode.YEARLY.value)
+
+
+class NormalYearlyRainfall(BaseRainfall):
+    """
+    Schema for depicting a rainfall normal for a yearly time mode.
+    """
+    name: str = fields.Str(load_default='rainfall normal')
+    value: float = fields.Float()
+    time_mode: str = fields.Str(load_default=TimeMode.YEARLY.value)
+
+
+class RelativeDistanceToNormalYearlyRainfall(BaseRainfall):
+    """
+    Schema for depicting a relative distance to rainfall normal for a yearly time mode.
+    """
+    name: str = fields.Str(load_default='rainfall relative distance to normal')
+    value: float = fields.Float()
+    time_mode: str = fields.Str(load_default=TimeMode.YEARLY.value)
+
+
+class StandardDeviationYearlyRainfall(BaseRainfall):
+    """
+    Schema for depicting a rainfall standard deviation for a yearly time mode.
+    """
+    name: str = fields.Str(load_default='rainfall standard deviation')
+    value: float = fields.Float()
+    time_mode: str = fields.Str(load_default=TimeMode.YEARLY.value)
+
+
+class YearsAboveNormalSchema(BaseRainfall):
+    """
+    Schema for giving the number of years above rainfall normal for a yearly time mode.
+    """
+    name: str = fields.Str(load_default='years above rainfall normal')
+    value: float = fields.Int()
+    time_mode: str = fields.Str(load_default=TimeMode.YEARLY.value)
+
+
+class YearsBelowNormalSchema(BaseRainfall):
+    """
+    Schema for giving the number of years below rainfall normal for a yearly time mode.
+    """
+    name: str = fields.Str(load_default='years below rainfall normal')
+    value: float = fields.Int()
+    time_mode: str = fields.Str(load_default=TimeMode.YEARLY.value)

src/api/swagger/rainfall/average_specs.py

@@ -9,7 +9,7 @@
 """
 
 import src.api.swagger.parameters_specs as param
-
+from src.api.schemas import AverageYearlyRainfall
 
 route_specs: dict = {
     "operationId": "getRainfallAverage",
@@ -22,11 +22,8 @@
     ],
     "responses": {
         "200": {
-            "description": "the average rainfall (in mm)",
-            "schema": {
-                "type": "number",
-                "example": 623.75
-            }
+            "description": "The average rainfall (in mm)",
+            "schema": AverageYearlyRainfall
         }
     },
     "parameters": [

src/api/swagger/rainfall/normal_specs.py

@@ -8,7 +8,7 @@
 """
 
 import src.api.swagger.parameters_specs as param
-
+from src.api.schemas import NormalYearlyRainfall
 
 route_specs: dict = {
     "operationId": "getRainfallNormal",
@@ -19,11 +19,8 @@
     ],
     "responses": {
         "200": {
-            "description": "the 30 years normal (in mm)",
-            "schema": {
-                "type": "number",
-                "example": 607.28
-            }
+            "description": "The 30 years normal (in mm)",
+            "schema": NormalYearlyRainfall
         }
     },
     "parameters": [

src/api/swagger/rainfall/relative_distance_to_normal_specs.py

@@ -13,7 +13,7 @@
 """
 
 import src.api.swagger.parameters_specs as param
-
+from src.api.schemas import RelativeDistanceToNormalYearlyRainfall
 
 route_specs: dict = {
     "operationId": "getRainfallRelativeDistanceToNormal",
@@ -30,11 +30,8 @@
     ],
     "responses": {
         "200": {
-            "description": "the relative distance to normal as a percentage.",
-            "schema": {
-                "type": "number",
-                "example": -25.67
-            }
+            "description": "The relative distance to normal as a percentage.",
+            "schema": RelativeDistanceToNormalYearlyRainfall
         }
     },
     "parameters": [

src/api/swagger/rainfall/standard_deviation_specs.py

@@ -9,7 +9,7 @@
 """
 
 import src.api.swagger.parameters_specs as param
-
+from src.api.schemas import StandardDeviationYearlyRainfall
 
 route_specs: dict = {
     "operationId": "getRainfallStandardDeviation",
@@ -22,11 +22,8 @@
     ],
     "responses": {
         "200": {
-            "description": "the rainfall standard deviation (in mm)",
-            "schema": {
-                "type": "number",
-                "example": 172.43
-            }
+            "description": "The rainfall standard deviation (in mm)",
+            "schema": StandardDeviationYearlyRainfall
         }
     },
     "parameters": [

src/api/swagger/year/above_normal_specs.py

@@ -8,7 +8,7 @@
 """
 
 import src.api.swagger.parameters_specs as param
-
+from src.api.schemas import YearsAboveNormalSchema
 
 route_specs: dict = {
     "operationId": "getYearsAboveNormal",
@@ -21,10 +21,7 @@
     "responses": {
         "200": {
             "description": "the number of years above normal",
-            "schema": {
-                "type": "integer",
-                "example": 23
-            }
+            "schema": YearsAboveNormalSchema
         }
     },
     "parameters": [

src/api/swagger/year/below_normal_specs.py

@@ -8,7 +8,7 @@
 """
 
 import src.api.swagger.parameters_specs as param
-
+from src.api.schemas import YearsBelowNormalSchema
 
 route_specs: dict = {
     "operationId": "getYearsBelowNormal",
@@ -20,11 +20,8 @@
     ],
     "responses": {
         "200": {
-            "description": "the number of years below normal",
-            "schema": {
-                "type": "integer",
-                "example": 27
-            }
+            "description": "The number of years below normal",
+            "schema": YearsBelowNormalSchema
         }
     },
     "parameters": [

src/app.py

@@ -11,6 +11,7 @@
 from flask import Flask, jsonify, request, Response
 
 from api.parameters import Parameter
+import src.api.schemas as model
 from src.api.swagger.rainfall import (average_specs, normal_specs,
                                       relative_distance_to_normal_specs,
                                       standard_deviation_specs)
@@ -30,57 +31,99 @@
 @app.route(f"{swagger.template['basePath']}/rainfall/average")
 @swag_from(average_specs.route_specs)
 def average_rainfall() -> Response:
-    return jsonify(all_rainfall.yearly_rainfall.get_average_yearly_rainfall(
-        begin_year=request.args.get(*Parameter.BEGIN_YEAR.value),
-        end_year=request.args.get(*Parameter.END_YEAR.value)
-    ))
+    begin_year: int = request.args.get(*Parameter.BEGIN_YEAR.value)
+    end_year: int = request.args.get(*Parameter.END_YEAR.value)
+    value: float = all_rainfall.yearly_rainfall.get_average_yearly_rainfall(begin_year, end_year)
+
+    return jsonify(model.AverageYearlyRainfall().load({
+        "value": value,
+        "begin_year": begin_year,
+        "end_year": end_year,
+    }))
 
 
 @app.route(f"{swagger.template['basePath']}/rainfall/normal")
 @swag_from(normal_specs.route_specs)
 def normal_rainfall() -> Response:
-    return jsonify(all_rainfall.yearly_rainfall.get_normal(
-        begin_year=request.args.get(*Parameter.BEGIN_YEAR.value))
-    )
+    begin_year: int = request.args.get(*Parameter.BEGIN_YEAR.value)
+    value: float = all_rainfall.yearly_rainfall.get_normal(begin_year)
+
+    return jsonify(model.NormalYearlyRainfall().load({
+        "value": value,
+        "begin_year": begin_year,
+        "end_year": begin_year + 29
+    }))
 
 
 @app.route(f"{swagger.template['basePath']}/rainfall/relative_distance_to_normal")
 @swag_from(relative_distance_to_normal_specs.route_specs)
 def rainfall_relative_distance_to_normal() -> Response:
-    return jsonify(all_rainfall.yearly_rainfall.get_relative_distance_from_normal(
-        normal_year=request.args.get(*Parameter.NORMAL_YEAR.value),
-        begin_year=request.args.get(*Parameter.BEGIN_YEAR.value),
-        end_year=request.args.get(*Parameter.END_YEAR.value)
-    ))
+    normal_year: int = request.args.get(*Parameter.NORMAL_YEAR.value)
+    begin_year: int = request.args.get(*Parameter.BEGIN_YEAR.value)
+    end_year: int = request.args.get(*Parameter.END_YEAR.value)
+    value: float = all_rainfall.yearly_rainfall.get_relative_distance_from_normal(
+        normal_year,
+        begin_year,
+        end_year
+    )
+
+    return jsonify(model.RelativeDistanceToNormalYearlyRainfall().load({
+        "value": value,
+        "begin_year": begin_year,
+        "end_year": end_year,
+    }))
 
 
 @app.route(f"{swagger.template['basePath']}/rainfall/standard_deviation")
 @swag_from(standard_deviation_specs.route_specs)
 def standard_deviation() -> Response:
-    return jsonify(all_rainfall.yearly_rainfall.get_standard_deviation(
-        begin_year=request.args.get(*Parameter.BEGIN_YEAR.value),
-        end_year=request.args.get(*Parameter.END_YEAR.value)
-    ))
+    begin_year: int = request.args.get(*Parameter.BEGIN_YEAR.value)
+    end_year: int = request.args.get(*Parameter.END_YEAR.value)
+    value: float = all_rainfall.yearly_rainfall.get_standard_deviation(begin_year, end_year)
+
+    return jsonify(model.StandardDeviationYearlyRainfall().load({
+        "value": value,
+        "begin_year": begin_year,
+        "end_year": end_year,
+    }))
 
 
 @app.route(f"{swagger.template['basePath']}/year/below_normal")
 @swag_from(below_normal_specs.route_specs)
 def years_below_normal() -> Response:
-    return jsonify(all_rainfall.yearly_rainfall.get_years_below_normal(
-        normal_year=request.args.get(*Parameter.NORMAL_YEAR.value),
-        begin_year=request.args.get(*Parameter.BEGIN_YEAR.value),
-        end_year=request.args.get(*Parameter.END_YEAR.value)
-    ))
+    normal_year: int = request.args.get(*Parameter.NORMAL_YEAR.value)
+    begin_year: int = request.args.get(*Parameter.BEGIN_YEAR.value)
+    end_year: int = request.args.get(*Parameter.END_YEAR.value)
+    value: float = all_rainfall.yearly_rainfall.get_years_below_normal(
+        normal_year,
+        begin_year,
+        end_year
+    )
+
+    return jsonify(model.YearsBelowNormalSchema().load({
+        "value": value,
+        "begin_year": begin_year,
+        "end_year": end_year,
+    }))
 
 
 @app.route(f"{swagger.template['basePath']}/year/above_normal")
 @swag_from(above_normal_specs.route_specs)
 def years_above_normal() -> Response:
-    return jsonify(all_rainfall.yearly_rainfall.get_years_above_normal(
-        normal_year=request.args.get(*Parameter.NORMAL_YEAR.value),
-        begin_year=request.args.get(*Parameter.BEGIN_YEAR.value),
-        end_year=request.args.get(*Parameter.END_YEAR.value)
-    ))
+    normal_year: int = request.args.get(*Parameter.NORMAL_YEAR.value)
+    begin_year: int = request.args.get(*Parameter.BEGIN_YEAR.value)
+    end_year: int = request.args.get(*Parameter.END_YEAR.value)
+    value: float = all_rainfall.yearly_rainfall.get_years_above_normal(
+        normal_year,
+        begin_year,
+        end_year
+    )
+
+    return jsonify(model.YearsAboveNormalSchema().load({
+        "value": value,
+        "begin_year": begin_year,
+        "end_year": end_year,
+    }))
 
 
 if __name__ == '__main__':

src/core/utils/enums/seasons.py

@@ -1,6 +1,7 @@
 """
 Provides list of Month (Enum) equivalents for all four seasons of the year.
 """
+
 from enum import Enum
 
 from src.core.utils.enums.months import Month

src/core/utils/enums/time_modes.py

@@ -0,0 +1,14 @@
+"""
+Provides list of Time modes (Enum) to inform on what timeframe is used on current rainfall data.
+"""
+
+from enum import Enum
+
+
+class TimeMode(str, Enum):
+    """
+    An enum listing time modes (yearly, monthly and seasonal) represented by strings.
+    """
+    YEARLY: str = 'yearly'
+    SEASONAL: str = 'seasonal'
+    MONTHLY: str = 'monthly'

src/core/utils/functions/metrics.py

@@ -72,5 +72,5 @@ def get_normal(yearly_rainfall: pd.DataFrame, begin_year) -> float:
     return get_average_rainfall(
         df_opr.get_rainfall_within_year_interval(yearly_rainfall,
                                                  begin_year,
-                                                 begin_year + 30)
+                                                 begin_year + 29)
     )