Add support for inflation

Author: codeofandrin

apininjas/client.py

@@ -35,9 +35,11 @@
     CurrencyConversion,
     Currency,
     IBANValidation,
+    Inflation,
 )
-from .enums import CommodityType
+from .enums import CommodityType, InflationCountry, InflationIndicatorType
 from .errors import StockNotFound
+from .utils import MISSING
 
 if TYPE_CHECKING:
     from typing_extensions import Self
@@ -299,3 +301,61 @@ async def fetch_iban_validation(self, iban: str) -> IBANValidation:
         """
         data = await self._http.get_iban_validation(iban=iban)
         return IBANValidation(data=data)
+
+    async def fetch_inflation(
+        self, country: InflationCountry, *, type: InflationIndicatorType = MISSING
+    ) -> Inflation:
+        """|coro|
+
+        Retrieves an :class:`Inflation` with the specified country.
+
+        Parameters
+        ----------
+        country: :class:`str`
+            The country to retrieve from.
+        type: :class:`InflationIndicatorType`
+            The inflation indicator type.
+
+        Raises
+        -------
+        HTTPException
+            Retrieving the inflation failed.
+
+        Returns
+        -------
+        :class:`Inflation`
+            The retrieved inflation.
+        """
+        fields = {"country": country.value}
+        if type is not MISSING:
+            fields["type"] = type.value
+
+        data = await self._http.get_inflation(**fields)
+        return Inflation(data=data[0])
+
+    async def fetch_inflations(self, *, type: InflationIndicatorType = MISSING) -> List[Inflation]:
+        """|coro|
+
+        Retrieves a list of available :class:`Inflation`.
+
+        Parameters
+        ----------
+        type: :class:`InflationIndicatorType`
+            The inflation indicator type.
+
+        Raises
+        -------
+        HTTPException
+            Retrieving the inflation failed.
+
+        Returns
+        -------
+        List[:class:`Inflation`]
+            The retrieved list of available inflation.
+        """
+        fields = {}
+        if type is not MISSING:
+            fields["type"] = type.value
+
+        data = await self._http.get_inflation(**fields)
+        return [Inflation(data=inflation) for inflation in data]

apininjas/enums.py

@@ -28,6 +28,8 @@
 # fmt: off
 __all__ = (
     "CommodityType",
+    "InflationIndicatorType",
+    "InflationCountry",
 )
 # fmt: on
 
@@ -84,3 +86,51 @@ class CommodityType(enum.Enum, metaclass=EnumMeta):
     gasoline_rbob = "gasoline_rbob"
     heating_oil = "heating_oil"
     class_3_milk = "class_3_milk"
+
+
+class InflationIndicatorType(enum.Enum, metaclass=EnumMeta):
+    cpi = "CPI"
+    hicp = "HICP"
+
+
+class InflationCountry(enum.Enum, metaclass=EnumMeta):
+    austria = "Austria"
+    belgium = "Belgium"
+    brazil = "Brazil"
+    canada = "Canada"
+    chile = "Chile"
+    china = "China"
+    czech_republic = "Czech Republic"
+    czechia = czech_republic
+    denmark = "Denmark"
+    estonia = "Estonia"
+    finland = "Finland"
+    france = "France"
+    germany = "Germany"
+    greece = "Greece"
+    hungary = "Hungary"
+    iceland = "Iceland"
+    india = "India"
+    indonesia = "Indonesia"
+    ireland = "Ireland"
+    israel = "Israel"
+    italy = "Italy"
+    japan = "Japan"
+    mexico = "Mexico"
+    norway = "Norway"
+    poland = "Poland"
+    portugal = "Portugal"
+    russia = "Russia"
+    slovakia = "Slovakia"
+    slovenia = "Slovenia"
+    south_korea = "South Korea"
+    south_africa = "South Africa"
+    spain = "Spain"
+    sweden = "Sweden"
+    switzerland = "Switzerland"
+    netherlands = "The Netherlands"
+    turkiye = "Türkiye"
+    united_kingdom = "United Kingdom"
+    uk = united_kingdom
+    united_states = "United States"
+    usa = united_states

apininjas/finance.py

@@ -24,10 +24,11 @@
 
 from __future__ import annotations
 
+import datetime
 from typing import TYPE_CHECKING, Optional, Union, NamedTuple
 
 import apininjas.abc
-from .enums import CommodityType
+from .enums import CommodityType, InflationIndicatorType, InflationCountry
 from . import utils
 
 if TYPE_CHECKING:
@@ -38,6 +39,7 @@
         Gold as GoldPayload,
         Crypto as CryptoPayload,
         IBANValidation as IBANValidationPayload,
+        Inflation as InflationPayload,
     )
 
 
@@ -48,6 +50,7 @@
     "Commodity",
     "Currency",
     "IBANValidation",
+    "Inflation",
 )
 # fmt: on
 
@@ -488,3 +491,65 @@ def is_valid(self) -> bool:
             This only includes the IBAN checksum validation.
         """
         return self.valid
+
+
+class Inflation:
+    """Represents the inflation of a country from the Inflation API.
+
+    .. container:: operations
+
+        .. describe:: x == y
+
+            Checks if two inflations are equal.
+
+        .. describe:: x != y
+
+            Checks if two inflations are not equal.
+
+    Attributes
+    -----------
+    country: :class:`str`
+        The country to which the inflation belongs.
+    type: :class:`InflationIndicatorType`
+        The type of inflation indicator.
+    monthly_rate: :class:`float`
+        The inflation rate on a monthly basis, in percent.
+    yearly_rate: :class:`float`
+        The inflation rate on a yearly basis, in percent.
+    """
+
+    __slots__ = ("country", "type", "monthly_rate", "yearly_rate", "_period")
+
+    def __init__(self, *, data: InflationPayload):
+        self.country: InflationCountry = InflationCountry(data["country"])
+        self.type: InflationIndicatorType = InflationIndicatorType(data["type"])
+        self.monthly_rate: float = data["monthly_rate_pct"]
+        self.yearly_rate: float = data["yearly_rate_pct"]
+        self._period: str = data["period"]
+
+    def __repr__(self) -> str:
+        attrs = [
+            ("country", self.country),
+            ("type", self.type),
+        ]
+        joined = " ".join([f"{a}={v!r}" for a, v in attrs])
+        return f"<Inflation {joined}>"
+
+    def __eq__(self, other: Inflation) -> bool:
+        return self.country == other.country and self.type == other.type and self.period == other.period
+
+    def __ne__(self, other: Inflation) -> bool:
+        return not self.__eq__(other)
+
+    @property
+    def period(self) -> datetime.datetime:
+        """:class:`datetime.datetime`: The time period for the inflation data."""
+        return datetime.datetime.strptime(self._period, "%b %Y")
+
+    def is_monthly_increased(self) -> bool:
+        """:class:`bool`: Whether the monthly inflation rate increased."""
+        return self.monthly_rate > 0
+
+    def is_yearly_increased(self) -> bool:
+        """:class:`bool`: Whether the yearly inflation rate increased."""
+        return self.yearly_rate > 0

apininjas/http.py

@@ -27,7 +27,7 @@
 import sys
 
 import aiohttp
-from typing import TYPE_CHECKING, TypeVar, Coroutine, Any, ClassVar, Dict, Optional
+from typing import TYPE_CHECKING, TypeVar, Coroutine, Any, ClassVar, Dict, Optional, List
 
 from . import __version__
 from .errors import (
@@ -137,3 +137,8 @@ def get_exchange_rate(self, *, pair: str) -> Response[finance.ExchangeRate]:
     def get_iban_validation(self, *, iban: str) -> Response[finance.IBANValidation]:
         params = {"iban": iban}
         return self.request(Route("GET", "/iban"), params=params)
+
+    def get_inflation(self, **fields: Any) -> Response[List[finance.Inflation]]:
+        valid_keys = ("country", "type")
+        params = {k: v for k, v in fields.items() if k in valid_keys}
+        return self.request(Route("GET", "/inflation"), params=params)

apininjas/types/finance.py

@@ -22,7 +22,7 @@
 SOFTWARE.
 """
 
-from typing import TypedDict, List
+from typing import TypedDict, List, Literal
 
 
 class Gold(TypedDict):
@@ -76,3 +76,11 @@ class IBANValidation(TypedDict):
     checksum: str
     valid: bool
     bban: str
+
+
+class Inflation(TypedDict):
+    country: str
+    type: Literal["CPI", "HICP"]
+    period: str
+    monthly_rate_pct: float
+    yearly_rate_pct: float

apininjas/utils.py

@@ -31,6 +31,7 @@
 
 # fmt: off
 __all__ = (
+    "MISSING",
     "from_timestamp",
 )
 # fmt: on
@@ -39,6 +40,22 @@
 T = TypeVar("T")
 
 
+class _MissingSentinel:
+    __slots__ = ()
+
+    def __eq__(self, other) -> bool:
+        return False
+
+    def __bool__(self) -> bool:
+        return False
+
+    def __repr__(self):
+        return "..."
+
+
+MISSING: Any = _MissingSentinel()
+
+
 def from_timestamp(timestamp: int, /) -> datetime.datetime:
     """A helper function that converts a given timestamp into a :class:`~datetime.datetime` object.