Enh/first code revamp (#20)

* Add multi-line parameter to isort configuration

* Move response parsing to BaseService

* Create and use ResponseFieldsMixin

* Move response instances initialization to JSONResponse

* Add relative imports instead of using library name

* Small type hint enhance

* Move response fields to separate modules for company enrichment and IP geolocation

* Create and use _prepare_selected_fields to centralize selected fields preparation

* Create and use NestedEntitiesMixin

* Move all non-service code into core

Author: ebram96

.pre-commit-config.yaml

@@ -17,6 +17,7 @@ repos:
     rev: 5.11.5
     hooks:
     -   id: isort
+        args: [--multi-line=VERTICAL_HANGING_INDENT]
 
 -   repo: https://github.com/pycqa/pydocstyle
     rev: 6.3.0

src/abstract_api/avatars/avatars.py

@@ -1,10 +1,8 @@
-from abstract_api.bases import BaseService
-from abstract_api.exceptions import ResponseParseError
-
+from ..core.bases import BaseService
 from .avatars_response import AvatarsResponse
 
 
-class Avatars(BaseService):
+class Avatars(BaseService[AvatarsResponse]):
     """AbstractAPI avatar generation service.
 
     Used for creating highly customizable avatar images with a person's name or
@@ -66,7 +64,8 @@ def create(
             AvatarsResponse representing API call response.
         """
         # TODO: Validation
-        response = self._service_request(
+        return self._service_request(
+            _response_class=AvatarsResponse,
             name=name,
             image_size=image_size,
             image_format=image_format,
@@ -79,12 +78,3 @@ def create(
             is_italic=is_italic,
             is_bold=is_bold
         )
-
-        try:
-            avatars_response = AvatarsResponse(response=response)
-        except Exception as e:
-            raise ResponseParseError(
-                "Failed to parse response as AvatarsResponse"
-            ) from e
-
-        return avatars_response

src/abstract_api/avatars/avatars_response.py

@@ -1,4 +1,4 @@
-from abstract_api.bases import FileResponse
+from ..core.bases import FileResponse
 
 
 class AvatarsResponse(FileResponse):

src/abstract_api/company_enrichment/company_enrichment.py

@@ -1,13 +1,15 @@
 from typing import Iterable
 
-from abstract_api.bases import BaseService
-from abstract_api.exceptions import ClientRequestError, ResponseParseError
-
+from ..core.bases import BaseService
+from ..core.mixins import ResponseFieldsMixin
 from .company_enrichment_response import CompanyEnrichmentResponse
 from .response_fields import RESPONSE_FIELDS
 
 
-class CompanyEnrichment(BaseService):
+class CompanyEnrichment(
+    ResponseFieldsMixin,
+    BaseService[CompanyEnrichmentResponse]
+):
     """AbstractAPI company enrichment service.
 
     Used to find a company's details using its domain.
@@ -16,65 +18,7 @@ class CompanyEnrichment(BaseService):
         _subdomain: Company enrichment service subdomain.
     """
     _subdomain: str = "companyenrichment"
-
-    def __init__(
-        self,
-        *,
-        response_fields: Iterable[str] | None = None,
-        **kwargs
-    ) -> None:
-        """Constructs a CompanyEnrichment.
-
-        Args:
-            response_fields: Selected response fields.
-        """
-        super().__init__(**kwargs)
-        if response_fields is not None:
-            self.response_fields = frozenset(response_fields)
-        else:
-            self.response_fields = RESPONSE_FIELDS
-
-    @staticmethod
-    def _validate_response_fields(response_fields: Iterable[str]) -> None:
-        """Validates whether all the given fields are acceptable.
-
-        Args:
-            response_fields: Selected response fields.
-        """
-        for field in response_fields:
-            if field not in RESPONSE_FIELDS:
-                raise ClientRequestError(
-                    f"Field '{field}' is not a valid response field for "
-                    f"Company Enrichment service."
-                )
-
-    @property
-    def response_fields(self) -> frozenset[str]:
-        """Gets selected response fields."""
-        if self._response_fields:
-            return self._response_fields
-        return RESPONSE_FIELDS
-
-    @response_fields.setter
-    def response_fields(self, fields: Iterable[str]) -> None:
-        """Sets selected response fields."""
-        self._validate_response_fields(fields)
-        self._response_fields = frozenset(fields)
-
-    @staticmethod
-    def _response_fields_as_param(response_fields: Iterable[str]) -> str:
-        """Builds 'fields' URL query parameter.
-
-         Builds a string that contains selected response fields to be used
-         as a URL query parameter.
-
-        Args:
-            response_fields: Selected response fields.
-
-        Returns:
-            Comma-separated string with all selected response fields.
-        """
-        return ",".join(response_fields)
+    _response_fields = RESPONSE_FIELDS
 
     def check(
         self,
@@ -85,31 +29,16 @@ def check(
 
         Args:
             domain: The domain of the company you want to get data from.
-            fields: Selected response fields.
+            fields: Selected response fields (optional).
 
         Returns:
             CompanyEnrichmentResponse representing API call response.
         """
-        if fields:
-            self._validate_response_fields(fields)
-            response_fields = frozenset(fields)
-        else:
-            response_fields = self.response_fields
+        selected_fields = self._prepare_selected_fields(fields)
 
-        # TODO: Handle request errors.
-        response = self._service_request(
+        return self._service_request(
+            _response_class=CompanyEnrichmentResponse,
+            _response_class_kwargs={"response_fields": selected_fields},
             domain=domain,
-            fields=self._response_fields_as_param(response_fields)
+            fields=self._response_fields_as_param(selected_fields)
         )
-
-        try:
-            company_enrichment_response = CompanyEnrichmentResponse(
-                response=response,
-                response_fields=response_fields
-            )
-        except Exception as e:
-            raise ResponseParseError(
-                "Failed to parse response as CompanyEnrichmentResponse"
-            ) from e
-
-        return company_enrichment_response

src/abstract_api/company_enrichment/company_enrichment_response.py

@@ -1,30 +1,9 @@
-from typing import TYPE_CHECKING
-
-import requests.models
-
-from abstract_api.bases import JSONResponse
+from ..core.bases import JSONResponse
 
 
 class CompanyEnrichmentResponse(JSONResponse):
     """Company enrichment service response."""
 
-    def __init__(
-        self,
-        response: requests.models.Response,
-        response_fields: frozenset[str]
-    ) -> None:
-        """Initializes a new CompanyEnrichmentResponse."""
-        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 name(self) -> str | None:
         """The name of the company."""

src/abstract_api/core/__init__.py

@@ -1,14 +1,21 @@
-from abc import ABC
 from io import BytesIO
-from typing import Any, Final
+from typing import TYPE_CHECKING, Any, Final, Generic, Type, TypeVar
 
 import requests
 from requests import codes
 
-from abstract_api.exceptions import APIRequestError, ClientRequestError
+from ..exceptions import (
+    APIRequestError,
+    ClientRequestError,
+    ResponseParseError
+)
 
+if TYPE_CHECKING:
+    from ._base_response import BaseResponse
+BaseResponseT = TypeVar("BaseResponseT", bound="BaseResponse")
 
-class BaseService(ABC):
+
+class BaseService(Generic[BaseResponseT]):
     """Base class for all AbstractAPI service classes.
 
     Attributes:
@@ -43,12 +50,14 @@ def _service_url(self, action: str = "") -> str:
 
     def _service_request(
         self,
+        _response_class: Type[BaseResponseT],
+        _response_class_kwargs: dict[str, Any] | None = None,
         _method: str = "GET",
         _body: dict[str, Any] | None = None,
         _files: dict[str, BytesIO] | None = None,
         _action: str = "",
         **params
-    ) -> requests.models.Response:
+    ) -> BaseResponseT:
         """Makes the HTTP call to Abstract API service endpoint.
 
         Args:
@@ -86,4 +95,17 @@ def _service_request(
 
         if response.status_code not in [codes.OK, codes.NO_CONTENT]:
             APIRequestError.raise_from_response(response)
-        return response
+
+        if _response_class_kwargs is None:
+            _response_class_kwargs = {}
+
+        try:
+            parsed_response = _response_class(
+                response=response, **_response_class_kwargs
+            )
+        except Exception as e:
+            raise ResponseParseError(
+                f"Failed to parse response as {_response_class.__name__}"
+            ) from e
+
+        return parsed_response