Release 1.0.0 (#5)

* update tests

update tests so that it reflect the new api change using facade design
pattern.

* update docs

this update the reference and tutorial to reflect new facade api design
pattern.

* move enums outside weather_forecast folder

move these enums in order to implement facade design pattern.

* use one file for exception

there are only two exception, so just place it in one file.

* use only one file for types

* move schema into one folder

move all schemas into one folder and create a new schema called
`Shakemap` for storing information about shakemap.

* move all parser into separate file in one folder

* create api folder

this api folder contains all api wrapper needed by pybmkg.

* change version to 1.0.0

* small typo in error msg

* add test_parsers

these tests mainly testing the exception that may raised by parser.

* update tests

some tests is not work as expected due to __getitem__ mock. Hopefully
now it fixed.

docs/reference/api.md

@@ -1,2 +1,4 @@
-::: bmkg.earthquake
-::: bmkg.weather_forecast
+::: bmkg.BMKG
+::: bmkg.api.earthquake.Earthquake
+::: bmkg.api.weather_forecast.WeatherForecast
+::: bmkg.api.shakemap.Shakemap

docs/reference/enum.md

@@ -1 +1 @@
-::: bmkg.weather_forecast.enums
+::: bmkg.enums

docs/reference/exception.md

@@ -1,2 +1 @@
-::: bmkg.common.exception
-::: bmkg.weather_forecast.exception
+::: bmkg.exception

docs/reference/schema.md

@@ -1,3 +1 @@
-::: bmkg.common.schemas
-::: bmkg.earthquake.schemas
-::: bmkg.weather_forecast.schemas
+::: bmkg.schemas

docs/tutorials.md

@@ -32,12 +32,12 @@ Code example:
 import asyncio
 from dataclasses import fields
 
-from bmkg.earthquake import Earthquake
+from bmkg import BMKG
 
 
 async def main():
-    async with Earthquake() as earthquake:
-        latest_earthquake = await earthquake.get_latest_earthquake()
+    async with BMKG() as bmkg:
+        latest_earthquake = await bmkg.earthquake.get_latest_earthquake()
 
         print(latest_earthquake.earthquake.datetime)
         print(latest_earthquake.earthquake.coordinate)
@@ -67,7 +67,7 @@ Coordinate(latitude=-3.63, longitude=140.46)
 46 km BaratDaya KEEROM-PAPUA
 Tidak berpotensi tsunami
 -
-20240118013237.mmi.jpg
+Shakemap(file_name='20240118013237.mmi.jpg')
 ```
 
 ### get_latest_earthquake_shakemap
@@ -82,26 +82,26 @@ Code example:
 
 ```python
 import asyncio
-from dataclasses import fields
 
-from bmkg.earthquake import Earthquake
+from bmkg import BMKG
 
 
 async def main():
-    async with Earthquake() as earthquake:
-        latest_earthquake = await earthquake.get_latest_earthquake()
+    async with BMKG() as bmkg:
+        latest_earthquake = await bmkg.earthquake.get_latest_earthquake()
+        shakemap = latest_earthquake.shakemap
+        shakemap_content = await shakemap.get_content()
 
-        shakemap = await earthquake.get_latest_earthquake_shakemap(
-            latest_earthquake.shakemap
-        )
-        print(shakemap)
+        print(shakemap.file_name)
+        print(shakemap_content)
 
 asyncio.run(main())
 ```
 
 Example output:
 
 ```console
+20240203152510.mmi.jpg
 b'\xff\xd8\xff\xe0\x00\x10JFIF\x00\x01\x01\x01\x00...'
 ```
 
@@ -120,12 +120,12 @@ Code example:
 import asyncio
 from dataclasses import fields
 
-from bmkg.earthquake import Earthquake
+from bmkg import BMKG
 
 
 async def main():
-    async with Earthquake() as earthquake:
-        strong_earthquakes = await earthquake.get_strong_earthquake()
+    async with BMKG() as bmkg:
+        strong_earthquakes = await bmkg.earthquake.get_strong_earthquake()
 
         for strong_earthquake in strong_earthquakes:
             print(strong_earthquake.earthquake.datetime)
@@ -170,12 +170,12 @@ Code example:
 import asyncio
 from dataclasses import fields
 
-from bmkg.earthquake import Earthquake
+from bmkg import BMKG
 
 
 async def main():
-    async with Earthquake() as earthquake:
-        felt_earthquakes = await earthquake.get_felt_earthquake()
+    async with BMKG() as bmkg:
+        felt_earthquakes = await bmkg.earthquake.get_felt_earthquake()
 
         for felt_earthquake in felt_earthquakes:
             print(felt_earthquake.earthquake.datetime)
@@ -228,15 +228,14 @@ Code example:
 
 ```python
 import asyncio
-from dataclasses import fields
 
-from bmkg.weather_forecast import WeatherForecast
-from bmkg.weather_forecast.enums import Province, Type
+from bmkg import BMKG
+from bmkg.enums import Province, Type
 
 
 async def main():
-    async with WeatherForecast() as weather_forecast:
-        weather_forecast_data = await weather_forecast.get_weather_forecast(Province.ACEH)
+    async with BMKG() as bmkg:
+        weather_forecast_data = await bmkg.weather_forecast.get_weather_forecast(Province.ACEH)
 
         print(weather_forecast_data.data)
         print(weather_forecast_data.forecast)

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "PyBMKG"
-version = "0.2.0"
+version = "1.0.0"
 description = "Python BMKG API Wrapper"
 authors = ["Kira <kiraware@github.com>"]
 packages = [

src/bmkg/__init__.py

@@ -1,7 +1,3 @@
-from .earthquake import Earthquake
-from .weather_forecast import WeatherForecast
+from .api import BMKG
 
-__all__ = [
-    "Earthquake",
-    "WeatherForecast",
-]
+__all__ = ["BMKG"]

src/bmkg/api/__init__.py

@@ -0,0 +1,3 @@
+from .bmkg import BMKG
+
+__all__ = ["BMKG"]

src/bmkg/api/api.py

@@ -0,0 +1,14 @@
+from aiohttp import ClientSession
+
+__all__ = ["API"]
+
+
+class API:
+    """
+    Base API class.
+    """
+
+    def __init__(self, session: ClientSession | None = None) -> None:
+        self._session = (
+            session if session is not None else ClientSession("https://data.bmkg.go.id")
+        )

src/bmkg/api/bmkg.py

@@ -0,0 +1,39 @@
+from traceback import TracebackException
+from types import TracebackType
+from typing import Self
+
+from .api import API
+from .earthquake import Earthquake
+from .weather_forecast import WeatherForecast
+
+__all__ = ["BMKG"]
+
+
+class BMKG(API):
+    """
+    Base BMKG API wrapper.
+
+    Attributes:
+        earthquake (Earthquake): earthquake api interface.
+        weather_forecast (WeatherForecast): weather forecast api interface.
+    """
+
+    def __init__(self) -> None:
+        API.__init__(self)
+
+        self.earthquake = Earthquake(self._session)
+        self.weather_forecast = WeatherForecast(self._session)
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: Exception,
+        exc_val: TracebackException,
+        traceback: TracebackType,
+    ) -> None:
+        await self.close()
+
+    async def close(self) -> None:
+        await self._session.close()

src/bmkg/api/earthquake.py

@@ -0,0 +1,89 @@
+from collections.abc import Iterator
+
+from .. import schemas
+from ..parsers import (
+    parse_felt_earthquake_data,
+    parse_latest_earthquake_data,
+    parse_strong_earthquake_data,
+)
+from .api import API
+from .shakemap import Shakemap
+
+__all__ = ["Earthquake"]
+
+
+class Earthquake(API):
+    """
+    Earthquake API Wrapper from BMKG API.
+    """
+
+    url = "/DataMKG/TEWS"
+
+    async def get_latest_earthquake(self) -> schemas.LatestEarthquake:
+        """
+        Request latest earthquake from earthquake API.
+
+        Returns:
+            A `LatestEarthquake` schema.
+
+        Examples:
+            >>> import asyncio
+            >>> from bmkg import BMKG
+            >>> async def main():
+            ...     async with BMKG() as bmkg:
+            ...         latest_earthquake = await bmkg.earthquake.get_latest_earthquake()
+            ...         print(latest_earthquake)
+            >>> asyncio.run(main())
+            LatestEarthquake(earthquake=Earthquake(datetime=datetime.datetime(...)
+
+        Notes:
+            The `LatestEarthquake` schema has a `shakemap` field which is the `Shakemap` API.
+        """  # noqa: E501
+        async with self._session.get(f"{self.url}/autogempa.json") as response:
+            latest_earthquake = parse_latest_earthquake_data(await response.json())  # type: ignore
+
+            latest_earthquake.shakemap = Shakemap(
+                self._session, latest_earthquake.shakemap.file_name
+            )
+
+            return latest_earthquake
+
+    async def get_strong_earthquake(self) -> Iterator[schemas.StrongEarthquake]:
+        """
+        Request strong earthquake that has magnitude 5.0 above from earthquake API.
+
+        Returns:
+            An iterator of fifteen `StrongEarthquake` schema.
+
+        Examples:
+            >>> import asyncio
+            >>> from bmkg import BMKG
+            >>> async def main():
+            ...     async with BMKG() as bmkg:
+            ...         strong_earthquake = await bmkg.earthquake.get_strong_earthquake()
+            ...         print(strong_earthquake)
+            >>> asyncio.run(main())
+            <generator object parse_strong_earthquake_data at ...>
+        """  # noqa: E501
+        async with self._session.get(f"{self.url}/gempaterkini.json") as response:
+            return parse_strong_earthquake_data(await response.json())  # type: ignore
+
+    async def get_felt_earthquake(self) -> Iterator[schemas.FeltEarthquake]:
+        """
+        Request felt earthquake from earthquake API.
+
+        Returns:
+            An iterator of fifteen `FeltEarthquake` schema.
+
+        Examples:
+            >>> import asyncio
+            >>> from bmkg import BMKG
+            >>> async def main():
+            ...     async with BMKG() as bmkg:
+            ...         felt_earthquake = await bmkg.earthquake.get_felt_earthquake()
+            ...         print(felt_earthquake)
+            >>> asyncio.run(main())
+            <generator object parse_felt_earthquake_data at ...>
+        """
+        async with self._session.get(f"{self.url}/gempadirasakan.json") as response:
+            return parse_felt_earthquake_data(await response.json())  # type: ignore

src/bmkg/api/shakemap.py

@@ -0,0 +1,40 @@
+from aiohttp import ClientSession
+
+from .. import schemas
+from .api import API
+
+__all__ = ["Shakemap"]
+
+
+class Shakemap(API, schemas.Shakemap):
+    """
+    Shakemap API Wrapper from BMKG API.
+    """
+
+    url = "/DataMKG/TEWS"
+
+    def __init__(self, session: ClientSession, file_name: str) -> None:
+        API.__init__(self, session)
+        schemas.Shakemap.__init__(self, file_name)
+
+    async def get_content(self) -> bytes:
+        """
+        Get the shakemap file content.
+
+        Returns:
+            A bytes of `Shakemap` image.
+
+        Examples:
+            >>> import asyncio
+            >>> from bmkg import BMKG
+            >>> async def main():
+            ...     async with BMKG() as bmkg:
+            ...         latest_earthquake = await bmkg.earthquake.get_latest_earthquake()
+            ...         shakemap = latest_earthquake.shakemap
+            ...         shakemap_content = await shakemap.get_content()
+            ...         print(shakemap_content)
+            >>> asyncio.run(main())
+            b'...'
+        """  # noqa: E501
+        async with self._session.get(f"{self.url}/{self.file_name}") as response:
+            return await response.read()

src/bmkg/weather_forecast/weather_forecast.py → src/bmkg/api/weather_forecast.py

@@ -1,12 +1,12 @@
-from ..bmkg import BMKG
-from .enums import Province
-from .parser import parse_weather_forecast_data
-from .schemas import WeatherForecast as WeatherForecastData
+from ..enums import Province
+from ..parsers import parse_weather_forecast_data
+from ..schemas import WeatherForecast as WeatherForecastData
+from .api import API
 
 __all__ = ["WeatherForecast"]
 
 
-class WeatherForecast(BMKG):
+class WeatherForecast(API):
     """
     Weather Forecast API Wrapper from BMKG API.
     """
@@ -25,10 +25,11 @@ async def get_weather_forecast(self, province: Province) -> WeatherForecastData:
 
         Examples:
             >>> import asyncio
+            >>> from bmkg import BMKG
             >>> async def main():
-            ...     async with WeatherForecast() as weather_forecast:
-            ...         weather_forecast_data = await weather_forecast.get_weather_forecast(
-            ...             Province.ACEH
+            ...     async with BMKG() as bmkg:
+            ...         weather_forecast_data = (
+            ...             await bmkg.weather_forecast.get_weather_forecast(Province.ACEH)
             ...         )
             ...         print(weather_forecast_data)
             >>> asyncio.run(main())