Feature/image processing (#19)

* Add image processing service

* Rename action parameter to _action in _service_request(..)

* Add Portrait strategy class

* Add Landscape strategy class

* Add Auto strategy class

* Add Fit strategy class

* Add Crop strategy class

* Create CropModeMixin

* Use CropModeMixin with Fit strategy

* Add Square strategy

* Add Fill strategy

Author: ebram96

src/abstract_api/__init__.py

@@ -6,6 +6,7 @@
 from .exchange_rates import ExchangeRates
 from .holidays import Holidays
 from .iban_validation import IBANValidation
+from .image_processing import ImageProcessing
 from .ip_geolocation import IPGeolocation
 from .phone_validation import PhoneValidation
 from .timezone import Timezone
@@ -20,6 +21,7 @@
     "ExchangeRates",
     "Holidays",
     "IBANValidation",
+    "ImageProcessing",
     "IPGeolocation",
     "PhoneValidation",
     "Timezone",

src/abstract_api/bases/base_service.py

@@ -1,10 +1,11 @@
 from abc import ABC
-from typing import Final
+from io import BytesIO
+from typing import Any, Final
 
 import requests
 from requests import codes
 
-from abstract_api.exceptions import APIRequestError
+from abstract_api.exceptions import APIRequestError, ClientRequestError
 
 
 class BaseService(ABC):
@@ -42,24 +43,47 @@ def _service_url(self, action: str = "") -> str:
 
     def _service_request(
         self,
-        action: str = "",
+        _method: str = "GET",
+        _body: dict[str, Any] | None = None,
+        _files: dict[str, BytesIO] | None = None,
+        _action: str = "",
         **params
     ) -> requests.models.Response:
         """Makes the HTTP call to Abstract API service endpoint.
 
         Args:
-            action: Action to be performed using the service.
+            _method: HTTP method to use.
+            _body: Request body.
+            _files: Files to be attached to the request body (uploading files).
+            _action: Action to be performed using the service.
                 Only for services that have it (i.e. VAT).
             params: The URL parameter that should be used when calling the API
                 endpoints.
 
         Returns:
             AbstractAPI's response.
         """
-        response = requests.get(
-            self._service_url(action),
-            params={"api_key": self._api_key} | params
-        )
+        if _method.lower() not in ["get", "post"]:
+            raise ClientRequestError(
+                f"Invalid or not allowed HTTP method '{_method}'"
+            )
+
+        request_kwargs: dict[str, Any] = {
+            "method": _method,
+            "url": self._service_url(_action)
+        }
+
+        _method = _method.lower()
+        if _method == "get":
+            request_kwargs["params"] = {"api_key": self._api_key} | params
+        else:
+            if _files:
+                request_kwargs["files"] = _files
+            if _body:
+                request_kwargs["json"] = _body
+
+        response = requests.request(**request_kwargs)
+
         if response.status_code not in [codes.OK, codes.NO_CONTENT]:
             APIRequestError.raise_from_response(response)
         return response

src/abstract_api/exchange_rates/exchange_rates.py

@@ -57,7 +57,7 @@ def live(
             VATValidationResponse representing API call response.
         """
         response = self._service_request(
-            action="live",
+            _action="live",
             base=base,
             target=self._target_as_param(target)
         )
@@ -100,7 +100,7 @@ def convert(
             ExchangeRatesConversionResponse representing API call response.
         """
         response = self._service_request(
-            action="convert",
+            _action="convert",
             base=base,
             target=target,
             date=date,
@@ -141,7 +141,7 @@ def historical(
             HistoricalExchangeRatesResponse representing API call response.
         """
         response = self._service_request(
-            action="historical",
+            _action="historical",
             base=base,
             target=self._target_as_param(target),
             date=date

src/abstract_api/image_processing/__init__.py

@@ -0,0 +1,9 @@
+from typing import Final
+
+from .image_processing import ImageProcessing
+from .image_processing_response import ImageProcessingResponse
+
+__all__: Final[list[str]] = [
+    "ImageProcessing",
+    "ImageProcessingResponse"
+]

src/abstract_api/image_processing/image_processing.py

@@ -0,0 +1,143 @@
+import json
+from typing import Any, BinaryIO
+
+from abstract_api.bases import BaseService
+from abstract_api.exceptions import ClientRequestError, ResponseParseError
+
+from .image_processing_response import ImageProcessingResponse
+from .strategies import BaseStrategy
+
+
+class ImageProcessing(BaseService):
+    """AbstractAPI image processing service.
+
+    Used to convert, compress, or optimize an image.
+
+    Attributes:
+        _subdomain: Image processing service subdomain.
+    """
+    _subdomain: str = "images"
+
+    def upload(
+        self,
+        image: BinaryIO,
+        lossy: bool | None = None,
+        quality: int | None = None,
+        resize: BaseStrategy | None = None
+    ) -> ImageProcessingResponse:
+        """Can convert, compress, or optimize an image.
+
+        Args:
+            image: The image to be processed, it should be a file-like or a
+                file opened in binary reading mode.
+            lossy: If True, the API will perform a lossy compression on the
+                image, reducing the size massively with a small drop in
+                image quality. If False, the image size will only be reduced
+                slightly (10% - 20% at most), but there will be no reduction
+                in image quality. The default value is False if this is not
+                provided.
+            quality: This is an integer between 0 and 100 that determines
+                the quality level for lossy compression. If not submitted
+                it will be determined intelligently by AbstractAPI.
+                Generally a quality above 95 is useless and may result in
+                an image that is larger than the input image, and a quality
+                below 25 will result in an image so low in quality that it
+                will be useless.
+            resize: This is an instance of BaseStrategy subclasses that
+                specifies how to resize the image. If not provided, we will
+                only compress the image as desired.
+
+        Returns:
+            ImageProcessingResponse representing API call response.
+        """
+        return self._process(
+            image=image,
+            lossy=lossy,
+            quality=quality,
+            resize=resize
+        )
+
+    def url(
+        self,
+        url: str,
+        lossy: bool | None = None,
+        quality: int | None = None,
+        resize: BaseStrategy | None = None
+    ) -> ImageProcessingResponse:
+        """Can convert, compress, or optimize an image in the given URL.
+
+        Args:
+            url: The URL of the image that you would like to edit.
+                Note that is cannot be more than 32 MB in size.
+            lossy: If True, the API will perform a lossy compression on the
+                image, reducing the size massively with a small drop in
+                image quality. If False, the image size will only be reduced
+                slightly (10% - 20% at most), but there will be no reduction
+                in image quality. The default value is False if this is not
+                provided.
+            quality: This is an integer between 0 and 100 that determines
+                the quality level for lossy compression. If not submitted
+                it will be determined intelligently by AbstractAPI.
+                Generally a quality above 95 is useless and may result in
+                an image that is larger than the input image, and a quality
+                below 25 will result in an image so low in quality that it
+                will be useless.
+            resize: This is an instance of BaseStrategy subclasses that
+                specifies how to resize the image. If not provided, we will
+                only compress the image as desired.
+
+        Returns:
+            ImageProcessingResponse representing API call response.
+        """
+        return self._process(
+            url=url,
+            lossy=lossy,
+            quality=quality,
+            resize=resize
+        )
+
+    def _process(
+        self,
+        image: BinaryIO | None = None,
+        url: str | None = None,
+        lossy: bool | None = None,
+        quality: int | None = None,
+        resize: BaseStrategy | None = None
+    ) -> ImageProcessingResponse:
+
+        if image is None and url is None:
+            raise ClientRequestError("Image or URL must be passed")
+
+        data: dict[str, Any] = {"api_key": self._api_key}
+        if resize is not None:
+            data["resize"] = resize.json()
+        if lossy is not None:
+            data["lossy"] = lossy
+        if quality is not None:
+            data["quality"] = quality
+
+        action = "upload/" if image is not None else "url/"
+        service_kwargs: dict[str, Any] = {
+            "_action": action,
+            "_method": "POST"
+        }
+        if action == "upload/":
+            service_kwargs["_files"] = {
+                "image": image,
+                "data": (None, json.dumps(data))
+            }
+        else:
+            service_kwargs["_body"] = data | {"url": url}
+
+        response = self._service_request(**service_kwargs)
+
+        try:
+            image_processing_response = ImageProcessingResponse(
+                response=response
+            )
+        except Exception as e:
+            raise ResponseParseError(
+                "Failed to parse response as ImageProcessingResponse"
+            ) from e
+
+        return image_processing_response

src/abstract_api/image_processing/image_processing_response.py

@@ -0,0 +1,66 @@
+from typing import TYPE_CHECKING
+
+import requests
+
+from abstract_api.bases import JSONResponse
+
+from .response_fields import RESPONSE_FIELDS
+
+
+class ImageProcessingResponse(JSONResponse):
+    """Image processing service response."""
+    def __init__(
+        self,
+        response: requests.models.Response
+    ) -> None:
+        """Initializes a new ImageProcessingResponse."""
+        super().__init__(response)
+        self._response_fields = RESPONSE_FIELDS
+        not_in_response = object()
+        for field in RESPONSE_FIELDS:
+            if TYPE_CHECKING:
+                assert isinstance(self.meta.body_json, dict)
+            value = self.meta.body_json.get(field, not_in_response)
+            # Set property only if field was returned
+            if value is not not_in_response:
+                setattr(self, f"_{field}", value)
+
+    @property
+    def original_size(self) -> str | None:
+        """The original size of the provided image, in bytes."""
+        return self._get_response_field("original_size")
+
+    @property
+    def original_height(self) -> str | None:
+        """The original height of the provided image, in bytes."""
+        return self._get_response_field("original_height")
+
+    @property
+    def original_width(self) -> str | None:
+        """The original width of the provided image, in bytes."""
+        return self._get_response_field("original_width")
+
+    @property
+    def final_size(self) -> str | None:
+        """The final size of the processed image, in bytes."""
+        return self._get_response_field("final_size")
+
+    @property
+    def bytes_saved(self) -> str | None:
+        """The number of bytes saved by optimizing the image, in bytes."""
+        return self._get_response_field("bytes_saved")
+
+    @property
+    def final_height(self) -> str | None:
+        """The final height of the processed image, in bytes."""
+        return self._get_response_field("final_height")
+
+    @property
+    def final_width(self) -> str | None:
+        """The final width of the processed image, in bytes."""
+        return self._get_response_field("final_width")
+
+    @property
+    def url(self) -> str | None:
+        """The URL with the new processed image."""
+        return self._get_response_field("url")

src/abstract_api/image_processing/response_fields.py

@@ -0,0 +1,13 @@
+"""Response fields of image processing service endpoints."""
+
+
+RESPONSE_FIELDS: frozenset[str] = frozenset({
+    "original_size",
+    "original_height",
+    "original_width",
+    "final_size",
+    "bytes_saved",
+    "final_height",
+    "final_width",
+    "url"
+})

src/abstract_api/image_processing/strategies/__init__.py

@@ -0,0 +1,23 @@
+from typing import Final
+
+from .auto import Auto
+from .base_strategy import BaseStrategy
+from .crop import Crop
+from .exact import Exact
+from .fill import Fill
+from .fit import Fit
+from .landscape import Landscape
+from .portrait import Portrait
+from .square import Square
+
+__all__: Final[list[str]] = [
+    "Auto",
+    "BaseStrategy",
+    "Crop",
+    "Exact",
+    "Fill",
+    "Fit",
+    "Landscape",
+    "Portrait",
+    "Square"
+]

src/abstract_api/image_processing/strategies/_mixins/__init__.py

@@ -0,0 +1,11 @@
+from typing import Final
+
+from .crop_mode_mixin import CropModeMixin
+from .height_mixin import HeightMixin
+from .width_mixin import WidthMixin
+
+__all__: Final[list[str]] = [
+    "CropModeMixin",
+    "HeightMixin",
+    "WidthMixin"
+]

src/abstract_api/image_processing/strategies/_mixins/_json_representable_protocol.py

@@ -0,0 +1,7 @@
+from typing import Protocol
+
+
+class JSONRepresentableProtocol(Protocol):
+    """MyPy protocol to indicate a class having .json() method."""
+    def json(self) -> dict[str, int | str]:  # noqa: D102
+        ...