Feature/validations (#26)

* Add validation for avatars service parameters

* Add validation for exchange rate service

* Add validation for holidays service

* Add validation for image processing service

* Add validation for timezone service

* Add validation for VAT service

* Add validation for website screenshot service

Author: ebram96

src/abstract_api/avatars/avatars.py

@@ -1,4 +1,6 @@
 from ..core.bases import BaseService
+from ..core.exceptions import ClientRequestError
+from ..core.validators import numerical
 from .avatars_response import AvatarsResponse
 
 
@@ -13,6 +15,23 @@ class Avatars(BaseService[AvatarsResponse]):
     """
     _subdomain = "avatars"
 
+    @staticmethod
+    def _validate_params(**kwargs) -> None:
+        """Validates passed service parameters."""
+        ranged = {
+            "image_size": (6, 512),
+            "font_size": (0.1, 1.0),
+            "char_limit": (1, 2)
+        }
+        for param, allowed_range in ranged.items():
+            numerical.between(param, kwargs[param], *allowed_range)
+
+        image_format = kwargs["image_format"]
+        if image_format and image_format not in ["png", "svg"]:
+            raise ClientRequestError(
+                "'image_format' must be either 'png' or 'svg'"
+            )
+
     def create(
         self,
         name: str,
@@ -63,7 +82,7 @@ def create(
         Returns:
             AvatarsResponse representing API call response.
         """
-        # TODO: Validation
+        self._validate_params(**locals())
         return self._service_request(
             _response_class=AvatarsResponse,
             name=name,

src/abstract_api/core/validators/__init__.py

@@ -0,0 +1,53 @@
+from typing import Any
+
+from abstract_api.core.exceptions import ClientRequestError
+
+
+def between(
+    param: str,
+    value: Any,
+    start: int | float,
+    end: int | float
+) -> None:
+    """Validate a value to be in a range (inclusive).
+
+    Args:
+        param: Parameter name.
+        value: Parameter value.
+        start: Beginning of the range.
+        end: End of the range.
+
+    Raises:
+        ClientRequestError if the given value is not in the range (inclusive).
+    """
+    if value is None:
+        return
+
+    if not (start <= value <= end):
+        raise ClientRequestError(
+            f"'{param}' must be in range from {start} to {end} (inclusive)"
+        )
+
+
+def greater_or_equal(
+    param: str,
+    value: Any,
+    threshold: int | float
+) -> None:
+    """Validate a value to be in a range (inclusive).
+
+    Args:
+        param: Parameter name.
+        value: Parameter value.
+        threshold: Threshold that the given value must be greater than.
+
+    Raises:
+        ClientRequestError if the given value is less than given threshold.
+    """
+    if value is None:
+        return
+
+    if value < threshold:
+        raise ClientRequestError(
+            f"'{param}' must be greater than or equal to {threshold}"
+        )

src/abstract_api/core/validators/numerical.py

@@ -1,6 +1,7 @@
 from typing import Iterable
 
 from ..core.bases import BaseService
+from ..core.validators import numerical
 from .exchange_rates_conversion_response import ExchangeRatesConversionResponse
 from .historical_exchange_rates_response import HistoricalExchangeRatesResponse
 from .live_exchange_rates_response import LiveExchangeRatesResponse
@@ -87,6 +88,7 @@ def convert(
         Returns:
             ExchangeRatesConversionResponse representing API call response.
         """
+        numerical.greater_or_equal("base_amount", base_amount, 0)
         return self._service_request(
             _response_class=ExchangeRatesConversionResponse,
             _action="convert",

src/abstract_api/exchange_rates/exchange_rates.py

@@ -1,4 +1,5 @@
 from ..core.bases import BaseService
+from ..core.validators import numerical
 from .holidays_response import HolidaysResponse
 
 
@@ -13,6 +14,17 @@ class Holidays(BaseService[HolidaysResponse]):
     """
     _subdomain = "holidays"
 
+    @staticmethod
+    def _validate_params(**kwargs) -> None:
+        """Validates passed service parameters."""
+        ranged = {
+            "year": (1800, 2100),
+            "month": (1, 12),
+            "day": (1, 31)
+        }
+        for param, allowed_range in ranged.items():
+            numerical.between(param, kwargs[param], *allowed_range)
+
     def lookup(
         self,
         country: str,
@@ -41,6 +53,7 @@ def lookup(
         Returns:
             HolidaysResponse representing API call response.
         """
+        self._validate_params(**locals())
         return self._service_request(
             _response_class=HolidaysResponse,
             country=country,

src/abstract_api/holidays/holidays.py

@@ -3,6 +3,7 @@
 
 from ..core.bases import BaseService
 from ..core.exceptions import ClientRequestError
+from ..core.validators import numerical
 from .image_processing_response import ImageProcessingResponse
 from .strategies import BaseStrategy
 
@@ -107,6 +108,8 @@ def _process(
         if image is None and url is None:
             raise ClientRequestError("Image or URL must be passed")
 
+        numerical.between("quality", quality, 0, 100)
+
         data: dict[str, Any] = {"api_key": self._api_key}
         if resize is not None:
             data["resize"] = resize.json()

src/abstract_api/image_processing/image_processing.py

@@ -1,4 +1,7 @@
+from typing import Annotated
+
 from ..core.bases import BaseService
+from ..core.exceptions import ClientRequestError
 from .current_timezone_response import CurrentTimezoneResponse
 from .timezone_conversion_response import TimezoneConversionResponse
 
@@ -13,9 +16,26 @@ class Timezone(BaseService):
     """
     _subdomain = "timezone"
 
+    @staticmethod
+    def _validate_location(
+        param: str,
+        location: str | Annotated[list[float], 2] | tuple[float, float]
+    ) -> None:
+        """Validates a given location.
+
+        Args:
+            param: Name of the parameter passed to service.
+            location: Value of location passed.
+        """
+        if isinstance(location, (list, tuple)):
+            if len(location) != 2:
+                raise ClientRequestError(
+                    f"'{param}' must contain both/only longitude and latitude."
+                )
+
     @staticmethod
     def _location_as_param(
-        location: str | list[float] | tuple[float, ...]
+        location:  str | Annotated[list[float], 2] | tuple[float, float]
     ) -> str:
         """Converts location to a request query parameter value.
 
@@ -29,14 +49,13 @@ def _location_as_param(
         Returns:
             A string with location as query parameter value.
         """
-        if isinstance(location, list) or isinstance(location, tuple):
+        if isinstance(location, (list, tuple)):
             location = ",".join(map(str, location))
-
         return location
 
     def current(
         self,
-        location: str | list[float] | tuple[float, ...]
+        location: str | Annotated[list[float], 2] | tuple[float, float]
     ) -> CurrentTimezoneResponse:
         """Finds the current time, date, and timezone of a given location.
 
@@ -50,6 +69,7 @@ def current(
         Returns:
             CurrentTimezoneResponse representing API call response.
         """
+        self._validate_location("location", location)
         return self._service_request(
             _response_class=CurrentTimezoneResponse,
             _action="current_time",
@@ -58,8 +78,8 @@ def current(
 
     def convert(
         self,
-        base_location: str | list[float] | tuple[float, ...],
-        target_location: str | list[float] | tuple[float, ...],
+        base_location: str | Annotated[list[float], 2] | tuple[float, float],
+        target_location: str | Annotated[list[float], 2] | tuple[float, float],
         base_datetime: str | None = None
     ) -> TimezoneConversionResponse:
         """Converts datetime of base location to target location's datetime.
@@ -83,6 +103,8 @@ def convert(
         Returns:
             TimezoneConversionResponse representing API call response.
         """
+        self._validate_location("base_location", base_location)
+        self._validate_location("target_location", target_location)
         return self._service_request(
             _response_class=TimezoneConversionResponse,
             _action="convert_time",

src/abstract_api/timezone/timezone.py

@@ -1,4 +1,5 @@
 from ..core.bases import BaseService
+from ..core.validators import numerical
 from .vat_calculation_response import VATCalculationResponse
 from .vat_categories_response import VATCategoriesResponse
 from .vat_validation_response import VATValidationResponse
@@ -56,6 +57,7 @@ def calculate(
         Returns:
             VATCalculationResponse representing API call response.
         """
+        numerical.greater_or_equal("amount", amount, 0)
         return self._service_request(
             _response_class=VATCalculationResponse,
             _action="calculate",

src/abstract_api/vat/vat.py

@@ -1,4 +1,6 @@
 from ..core.bases import BaseService
+from ..core.exceptions import ClientRequestError
+from ..core.validators import numerical
 from .website_screenshot_response import WebsiteScreenshotResponse
 
 
@@ -12,6 +14,21 @@ class WebsiteScreenshot(BaseService[WebsiteScreenshotResponse]):
     """
     _subdomain = "screenshot"
 
+    @staticmethod
+    def _validate_params(**kwargs) -> None:
+        """Validates passed service parameters."""
+        capture_full_page = kwargs["capture_full_page"]
+        dimensions = ["width", "height"]
+        for d in dimensions:
+            value = kwargs[d]
+            if value is not None:
+                if capture_full_page is not None and capture_full_page:
+                    raise ClientRequestError(
+                        f"'{d}' is not a valid option when"
+                        f" 'capture_full_page' is True"
+                    )
+                numerical.greater_or_equal(d, value, 0)
+
     def capture(
         self,
         url: str,
@@ -45,6 +62,7 @@ def capture(
         Returns:
             WebsiteScreenshotResponse representing API call response.
         """
+        self._validate_params(**locals())
         return self._service_request(
             _response_class=WebsiteScreenshotResponse,
             url=url,