Feature/exchange rates (#14)

ebram96 · web-flow · commit 12e2e130c8c8 · 2023-10-30T01:54:18.000+02:00
* Add live exchange rates service

* Add exchange rates conversion service

* Add historical exchange rates service
diff --git a/src/abstract_api/__init__.py b/src/abstract_api/__init__.py
@@ -2,6 +2,7 @@
 
 from .avatars import Avatars
 from .email_validation import EmailValidation
+from .exchange_rates import ExchangeRates
 from .holidays import Holidays
 from .iban_validation import IBANValidation
 from .ip_geolocation import IPGeolocation
@@ -11,6 +12,7 @@
 __all__: Final[list[str]] = [
     "Avatars",
     "EmailValidation",
+    "ExchangeRates",
     "Holidays",
     "IBANValidation",
     "IPGeolocation",
diff --git a/src/abstract_api/exchange_rates/__init__.py b/src/abstract_api/exchange_rates/__init__.py
@@ -0,0 +1,13 @@
+from typing import Final
+
+from .exchange_rates import ExchangeRates
+from .exchange_rates_conversion_response import ExchangeRatesConversionResponse
+from .historical_exchange_rates_response import HistoricalExchangeRatesResponse
+from .live_exchange_rates_response import LiveExchangeRatesResponse
+
+__all__: Final[list[str]] = [
+    "ExchangeRates",
+    "ExchangeRatesConversionResponse",
+    "HistoricalExchangeRatesResponse",
+    "LiveExchangeRatesResponse"
+]
diff --git a/src/abstract_api/exchange_rates/_multiple_exchange_rates_response.py b/src/abstract_api/exchange_rates/_multiple_exchange_rates_response.py
@@ -0,0 +1,63 @@
+from typing import TYPE_CHECKING
+
+import requests
+
+from abstract_api.bases import JSONResponse
+
+
+class ExchangeRate:
+    """Exchange rate entity in live/historical exchange rates response."""
+
+    def __init__(self, currency: str, rate: float) -> None:
+        """Initializes a new Country."""
+        self._currency = currency
+        self._rate = rate
+
+    @property
+    def currency(self) -> str:
+        """Target currency."""
+        return self._currency
+
+    @property
+    def rate(self) -> float:
+        """Exchange rate versus the base currency."""
+        return self._rate
+
+
+class MultipleExchangeRatesResponse(JSONResponse):
+    """Base response for services that return multiple exchange rates."""
+
+    def __init__(
+        self,
+        response: requests.models.Response,
+        response_fields: frozenset[str]
+    ) -> None:
+        """Initializes a new MultipleExchangeRatesResponse."""
+        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:
+                # TODO: Move to parent class
+                if field == "exchange_rates":
+                    exchange_rates = []
+                    for currency, rate in value.items():
+                        exchange_rates.append(
+                            ExchangeRate(currency=currency, rate=rate)
+                        )
+                    value = frozenset(exchange_rates)
+                setattr(self, f"_{field}", value)
+
+    @property
+    def base(self) -> str | None:
+        """The base currency used to get the exchange rates."""
+        return self._get_response_field("base")
+
+    @property
+    def exchange_rates(self) -> frozenset[ExchangeRate] | None:
+        """Target currencies exchange rates versus the base currency."""
+        return self._get_response_field("exchange_rates")
diff --git a/src/abstract_api/exchange_rates/exchange_rates.py b/src/abstract_api/exchange_rates/exchange_rates.py
@@ -0,0 +1,160 @@
+from typing import Iterable
+
+from abstract_api.bases import BaseService
+from abstract_api.exceptions import ResponseParseError
+
+from .exchange_rates_conversion_response import ExchangeRatesConversionResponse
+from .historical_exchange_rates_response import HistoricalExchangeRatesResponse
+from .live_exchange_rates_response import LiveExchangeRatesResponse
+
+
+class ExchangeRates(BaseService):
+    """AbstractAPI exchange rates service.
+
+    Used to looking up the latest exchange rates for 80+ currencies, getting
+    historical exchange rates, and converting an arbitrary amount from one
+    currency to another.
+
+    Attributes:
+        _subdomain: Exchange rates service subdomain.
+    """
+    _subdomain: str = "exchange-rates"
+
+    @staticmethod
+    def _target_as_param(target: Iterable[str] | None = None) -> str | None:
+        """Builds 'target' URL query parameter.
+
+        Builds a string that contains selected target currencies to be used
+        as a URL query parameter.
+
+        Args:
+            target: Selected target currencies.
+
+        Returns:
+            Comma-separated string with all selected target currencies.
+        """
+        if target is None:
+            return None
+
+        return ",".join(target)
+
+    def live(
+        self,
+        base: str,
+        target: Iterable[str] | None = None
+    ) -> LiveExchangeRatesResponse:
+        """Finds exchange rates from base currency to target currency/ies.
+
+        Args:
+            base: Base currency used to get the latest exchange rate(s) for.
+                Uses the ISO 4217 currency standard (e.g., USD for United
+                States Dollars).
+            target: The target currency or currencies to get the exchange rate
+                of versus the base currency. Like the base parameters, any
+                currency passed here follows the ISO 4217 standard.
+
+        Returns:
+            VATValidationResponse representing API call response.
+        """
+        response = self._service_request(
+            action="live",
+            base=base,
+            target=self._target_as_param(target)
+        )
+
+        try:
+            live_exchange_rates_response = LiveExchangeRatesResponse(
+                response=response
+            )
+        except Exception as e:
+            raise ResponseParseError(
+                "Failed to parse response as LiveExchangeRatesResponse"
+            ) from e
+
+        return live_exchange_rates_response
+
+    def convert(
+        self,
+        base: str,
+        target: str,
+        date: str | None = None,
+        base_amount: float | None = None
+    ) -> ExchangeRatesConversionResponse:
+        """Finds exchange rates from base currency to target currency/ies.
+
+        Args:
+            base: Base currency used to get the latest exchange rate(s) for.
+                Uses the ISO 4217 currency standard (e.g., USD for United
+                States Dollars).
+            target: The target currency to convert the base_amount to.
+                Like the base parameters, any currency passed here follows the
+                ISO 4217 standard. Note that unlike the other endpoints,
+                convert only accepts one target currency at a time.
+            date: The historical date you’d like to get rates from, in the
+                format of YYYY-MM-DD. If you leave this blank, it will use the
+                latest available rate.
+            base_amount: The amount of the base currency you would like to
+                convert to the target currency.
+
+        Returns:
+            ExchangeRatesConversionResponse representing API call response.
+        """
+        response = self._service_request(
+            action="convert",
+            base=base,
+            target=target,
+            date=date,
+            base_amount=base_amount
+        )
+
+        try:
+            exchange_rate_conversion_response = (
+                ExchangeRatesConversionResponse(response=response)
+            )
+        except Exception as e:
+            raise ResponseParseError(
+                "Failed to parse response as "
+                "ExchangeRatesConversionResponse"
+            ) from e
+
+        return exchange_rate_conversion_response
+
+    def historical(
+        self,
+        base: str,
+        date: str,
+        target: Iterable[str] | None = None
+    ) -> HistoricalExchangeRatesResponse:
+        """Finds historical exchange rates from base to target currencies.
+
+        Args:
+            base: Base currency used to get the latest exchange rate(s) for.
+                Uses the ISO 4217 currency standard (e.g., USD for United
+                States Dollars).
+            date: The historical date you’d like to get rates from, in the
+                format of YYYY-MM-DD.
+            target: The target currency or currencies to get the exchange rate
+                of versus the base currency. Like the base parameters, any
+                currency passed here follows the ISO 4217 standard.
+
+        Returns:
+            HistoricalExchangeRatesResponse representing API call response.
+        """
+        response = self._service_request(
+            action="historical",
+            base=base,
+            target=self._target_as_param(target),
+            date=date
+        )
+
+        try:
+            historical_exchange_rate_response = (
+                HistoricalExchangeRatesResponse(response=response)
+            )
+        except Exception as e:
+            raise ResponseParseError(
+                "Failed to parse response as "
+                "HistoricalExchangeRatesResponse"
+            ) from e
+
+        return historical_exchange_rate_response
diff --git a/src/abstract_api/exchange_rates/exchange_rates_conversion_response.py b/src/abstract_api/exchange_rates/exchange_rates_conversion_response.py
@@ -0,0 +1,67 @@
+from typing import TYPE_CHECKING
+
+import requests
+
+from abstract_api.bases import JSONResponse
+
+from .response_fields import CONVERSION_RESPONSE_FIELDS
+
+
+class ExchangeRatesConversionResponse(JSONResponse):
+    """Exchange rate conversion service response."""
+
+    def __init__(self, response: requests.models.Response) -> None:
+        """Initializes a new ExchangeRateConversionResponse."""
+        super().__init__(response)
+        self._response_fields = CONVERSION_RESPONSE_FIELDS
+        not_in_response = object()
+        for field in CONVERSION_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:
+                # TODO: Move to parent class
+                setattr(self, f"_{field}", value)
+
+    @property
+    def base(self) -> str | None:
+        """The base currency used to get the exchange rates."""
+        return self._get_response_field("base")
+
+    @property
+    def target(self) -> str | None:
+        """The target currency that the base_amount was converted into."""
+        return self._get_response_field("target")
+
+    @property
+    def date(self) -> str | None:
+        """The date the currencies were pulled from.
+
+        This is per successful request.
+        """
+        return self._get_response_field("date")
+
+    @property
+    def base_amount(self) -> str | None:
+        """The amount of the base currency from the request."""
+        return self._get_response_field("base_amount")
+
+    @property
+    def converted_amount(self) -> str | None:
+        """The amount after conversion.
+
+        The amount of the target currency that the base_amount has been
+        converted into.
+        """
+        return self._get_response_field("converted_amount")
+
+    @property
+    def exchange_rate(self) -> str | None:
+        """The exchange rate used in conversion."""
+        return self._get_response_field("exchange_rate")
+
+    @property
+    def last_updated(self) -> str | None:
+        """The exchange rate used in conversion."""
+        return self._get_response_field("last_updated")
diff --git a/src/abstract_api/exchange_rates/historical_exchange_rates_response.py b/src/abstract_api/exchange_rates/historical_exchange_rates_response.py
@@ -0,0 +1,20 @@
+import requests
+
+from ._multiple_exchange_rates_response import MultipleExchangeRatesResponse
+from .response_fields import HISTORICAL_RESPONSE_FIELDS
+
+
+class HistoricalExchangeRatesResponse(MultipleExchangeRatesResponse):
+    """Historical exchange rates service response."""
+
+    def __init__(self, response: requests.models.Response) -> None:
+        """Initializes a new HistoricalExchangeRatesResponse."""
+        super().__init__(response, HISTORICAL_RESPONSE_FIELDS)
+
+    @property
+    def date(self) -> str | None:
+        """The date the currencies were pulled from.
+
+        This is per successful request.
+        """
+        return self._get_response_field("date")
diff --git a/src/abstract_api/exchange_rates/live_exchange_rates_response.py b/src/abstract_api/exchange_rates/live_exchange_rates_response.py
@@ -0,0 +1,17 @@
+import requests
+
+from ._multiple_exchange_rates_response import MultipleExchangeRatesResponse
+from .response_fields import LIVE_RESPONSE_FIELDS
+
+
+class LiveExchangeRatesResponse(MultipleExchangeRatesResponse):
+    """Live exchange rates service response."""
+
+    def __init__(self, response: requests.models.Response) -> None:
+        """Initializes a new LiveExchangeRatesResponse."""
+        super().__init__(response, LIVE_RESPONSE_FIELDS)
+
+    @property
+    def last_updated(self) -> int | None:
+        """The Unix timestamp of when the returned data was last updated."""
+        return self._get_response_field("last_updated")
diff --git a/src/abstract_api/exchange_rates/response_fields/__init__.py b/src/abstract_api/exchange_rates/response_fields/__init__.py
@@ -0,0 +1,11 @@
+from typing import Final
+
+from .conversion import CONVERSION_RESPONSE_FIELDS
+from .historical import HISTORICAL_RESPONSE_FIELDS
+from .live import LIVE_RESPONSE_FIELDS
+
+__all__: Final[list[str]] = [
+    "CONVERSION_RESPONSE_FIELDS",
+    "HISTORICAL_RESPONSE_FIELDS",
+    "LIVE_RESPONSE_FIELDS"
+]
diff --git a/src/abstract_api/exchange_rates/response_fields/conversion.py b/src/abstract_api/exchange_rates/response_fields/conversion.py
@@ -0,0 +1,12 @@
+"""Response fields of exchange rates conversion service endpoint."""
+
+
+CONVERSION_RESPONSE_FIELDS: frozenset[str] = frozenset({
+    "base",
+    "target",
+    "date",
+    "base_amount",
+    "converted_amount",
+    "exchange_rate",
+    "last_updated"
+})
diff --git a/src/abstract_api/exchange_rates/response_fields/historical.py b/src/abstract_api/exchange_rates/response_fields/historical.py
@@ -0,0 +1,8 @@
+"""Response fields of historical exchange rates service endpoint."""
+
+
+HISTORICAL_RESPONSE_FIELDS: frozenset[str] = frozenset({
+    "base",
+    "date",
+    "exchange_rates"
+})
diff --git a/src/abstract_api/exchange_rates/response_fields/live.py b/src/abstract_api/exchange_rates/response_fields/live.py
