Add Holidays service (#13)

Author: ebram96

src/abstract_api/__init__.py

@@ -2,6 +2,7 @@
 
 from .avatars import Avatars
 from .email_validation import EmailValidation
+from .holidays import Holidays
 from .iban_validation import IBANValidation
 from .ip_geolocation import IPGeolocation
 from .phone_validation import PhoneValidation
@@ -10,6 +11,7 @@
 __all__: Final[list[str]] = [
     "Avatars",
     "EmailValidation",
+    "Holidays",
     "IBANValidation",
     "IPGeolocation",
     "PhoneValidation",

src/abstract_api/holidays/__init__.py

@@ -0,0 +1,9 @@
+from typing import Final
+
+from .holidays import Holidays
+from .holidays_response import HolidaysResponse
+
+__all__: Final[list[str]] = [
+    "Holidays",
+    "HolidaysResponse"
+]

src/abstract_api/holidays/holidays.py

@@ -0,0 +1,60 @@
+from abstract_api.bases import BaseService
+from abstract_api.exceptions import ResponseParseError
+
+from .holidays_response import HolidaysResponse
+
+
+class Holidays(BaseService):
+    """AbstractAPI Holidays service.
+
+    Used to get the public, local, religious, and other holidays of a
+    particular country.
+
+    Attributes:
+        _subdomain: Holidays service subdomain.
+    """
+    _subdomain: str = "holidays"
+
+    def lookup(
+        self,
+        country: str,
+        year: int | None = None,
+        month: int | None = None,
+        day: int | None = None
+    ) -> HolidaysResponse:
+        """Gets the list of holidays of a particular country.
+
+        Can get the public, local, religious, and other holidays.
+
+        Args:
+            country: The country’s two-letter ISO 3166-1 alpha-2 code.
+            year: The year to get the holiday(s) from. Note that this is
+                optional on paid plans and required on free plans, and if left
+                blank it will default to the current year.
+            month: The month to get the holiday(s) from, in the format
+                of 1-12 (e.g., 1 is January, 2 is February, etc.).
+                Note that this is optional on paid plans and required on
+                free plans, and if left blank it will default to the current
+                month.
+            day: The day to get the holiday(s) from, in the format of 1-31.
+                Note that this is optional on paid plans and required on free
+                plans, and if left blank it will default to the current day.
+
+        Returns:
+            HolidaysResponse representing API call response.
+        """
+        response = self._service_request(
+            country=country,
+            year=year,
+            month=month,
+            day=day
+        )
+
+        try:
+            holidays_response = HolidaysResponse(response=response)
+        except Exception as e:
+            raise ResponseParseError(
+                "Failed to parse response as HolidaysResponse"
+            ) from e
+
+        return holidays_response

src/abstract_api/holidays/holidays_response.py

@@ -0,0 +1,137 @@
+from typing import TYPE_CHECKING
+
+import requests
+
+from abstract_api.bases import JSONResponse
+
+from .response_fields import RESPONSE_FIELDS
+
+
+class Holiday:
+    """Holiday entity in VAT Holidays response."""
+
+    def __init__(
+        self,
+        name: str,
+        name_local: str,
+        language: str,
+        description: str,
+        country: str,
+        location: str,
+        type: str,
+        date: str,
+        date_year: str,
+        date_month: str,
+        date_day: str,
+        week_day: str
+    ) -> None:
+        """Initializes a new Holiday."""
+        self._name = name
+        self._name_local = name_local
+        self._language = language
+        self._description = description
+        self._country = country
+        self._location = location
+        self._type = type
+        self._date = date
+        self._date_year = date_year
+        self._date_month = date_month
+        self._date_day = date_day
+        self._week_day = week_day
+
+    @property
+    def name(self) -> str:
+        """The name of the holiday."""
+        return self._name
+
+    @property
+    def name_local(self) -> str:
+        """The local name of the holiday."""
+        return self._name_local
+
+    @property
+    def language(self) -> str:
+        """The language in which name_local is in."""
+        return self._language
+
+    @property
+    def description(self) -> str:
+        """A short description or additional details on the holiday.
+
+        Such as the holiday is a part of a long weekend.
+        """
+        return self._description
+
+    @property
+    def country(self) -> str:
+        """The country in which the holiday occurs.
+
+        Returned directly from the request.
+        """
+        return self._country
+
+    @property
+    def location(self) -> str:
+        """The location or region in which the holiday occurs.
+
+        If the holiday is that specific.
+        """
+        return self._location
+
+    @property
+    def type(self) -> str:
+        """The type of holiday it is.
+
+        (e.g., public holiday, religious holiday, etc.).
+        """
+        return self._type
+
+    @property
+    def date(self) -> str:
+        """The date on which the holiday occurs."""
+        return self._date
+
+    @property
+    def date_year(self) -> str:
+        """The year in which the holiday occurs."""
+        return self._date_year
+
+    @property
+    def date_month(self) -> str:
+        """The month in which the holiday occurs."""
+        return self._date_month
+
+    @property
+    def date_day(self) -> str:
+        """The day in which the holiday occurs."""
+        return self._date_day
+
+    @property
+    def week_day(self) -> str:
+        """The day of the week on which the holiday occurs.
+
+        (Monday, Tuesday, Wednesday, etc.).
+        """
+        return self._week_day
+
+
+class HolidaysResponse(JSONResponse):
+    """Holidays service response."""
+
+    def __init__(self, response: requests.models.Response) -> None:
+        """Initializes a new VATValidationResponse."""
+        super().__init__(response)
+        self._response_fields = RESPONSE_FIELDS
+
+        if self.meta.body_json is not None:
+            holidays = []
+            for c in self.meta.body_json:
+                if TYPE_CHECKING:
+                    assert isinstance(c, dict)
+                holidays.append(Holiday(**c))
+            self._holidays = frozenset(holidays)
+
+    @property
+    def holidays(self) -> frozenset[Holiday]:
+        """The returned holidays."""
+        return self._get_response_field("holidays")

src/abstract_api/holidays/response_fields.py

@@ -0,0 +1,9 @@
+"""Response fields of Holidays service endpoint."""
+
+
+# The response body does not contain 'holidays' field. This is just to be
+# able to initialize and use the response in a Pythonic way and conform with
+# other parts of the code.
+RESPONSE_FIELDS: frozenset[str] = frozenset({
+    "holidays"
+})