feat: random manga and anime

anmoku/clients/async_.py

@@ -7,7 +7,7 @@
     from ..typing.anmoku import SnowflakeT
     from ..typing.jikan import SearchResultData
 
-    from .base import ResourceGenericT, SearchResourceGenericT
+    from .base import ResourceGenericT, SearchResourceGenericT, RandomResourceGenericT
 
 from aiohttp import ClientSession
 from devgoldyutils import Colours
@@ -77,6 +77,17 @@ async def search(self, resource: Type[SearchResourceGenericT], query: str) -> Se
 
         return SearchResult(json_data, resource)
 
+    async def random(self, resource: Type[RandomResourceGenericT]) -> RandomResourceGenericT:
+        """Fetches a random object of the specified resource."""
+        url = resource._random_endpoint
+
+        if url is None:
+            raise ResourceNotSupportedError(resource, "random")
+
+        json_data = await self._request(url)
+
+        return resource(json_data)
+
     async def _request(
         self, 
         route: str, 

anmoku/clients/base.py

@@ -20,6 +20,12 @@
         resources.Manga
     )
 
+    RandomResourceGenericT = TypeVar(
+        "RandomResourceGenericT", 
+        resources.Anime,
+        resources.Manga
+    )
+
 import logging
 from urllib.parse import quote
 from abc import ABC, abstractmethod
@@ -65,6 +71,11 @@ def get(self, resource: Type[ResourceGenericT], id: SnowflakeT) -> ResourceGener
     def search(self, resource: Type[SearchResourceGenericT], query: str) -> SearchResult[SearchResourceGenericT]:
         """Searches for the resource and returns a list of the results."""
         ...
+
+    @abstractmethod
+    def random(self, resource: Type[RandomResourceGenericT]) -> RandomResourceGenericT:
+        """Fetches a random object of the specified resource."""
+        ...
 
     def _format_url(self, unformatted_url: str, resource: Type[ResourceGenericT], *args: str, **kwargs: str) -> str:
         """Formats the URL while also taking URL encoding into account."""

anmoku/clients/sync.py

@@ -7,7 +7,7 @@
     from ..typing.anmoku import SnowflakeT
     from ..typing.jikan import SearchResultData
 
-    from .base import ResourceGenericT, SearchResourceGenericT
+    from .base import ResourceGenericT, SearchResourceGenericT, RandomResourceGenericT
 
 from requests import Session
 from devgoldyutils import Colours
@@ -74,6 +74,17 @@ def search(self, resource: Type[SearchResourceGenericT], query: str) -> SearchRe
         json_data: SearchResultData[Any] = self._request(url, params = {"q": query})
 
         return SearchResult(json_data, resource)
+
+    def random(self, resource: Type[RandomResourceGenericT]) -> RandomResourceGenericT:
+        """Fetches a random object of the specified resource."""
+        url = resource._random_endpoint
+
+        if url is None:
+            raise ResourceNotSupportedError(resource, "random")
+
+        json_data = self._request(url)
+
+        return resource(json_data)
 
     def _request(
         self, 

anmoku/resources/anime/anime.py

@@ -71,6 +71,8 @@ class Anime(JikanResource):
     """
     _get_endpoint = "/anime/{id}"
     _search_endpoint = "/anime"
+    _random_endpoint = "/random/anime"
+
 
     data: JikanResponseData[AnimeData] = field(repr = False)
 

anmoku/resources/base.py

@@ -14,5 +14,7 @@ class JikanResource():
     """The jikan api endpoint where you can get this object."""
     _search_endpoint: Optional[str] = field(init = False, default = None)
     """The jikan api endpoint to search with this resource."""
+    _random_endpoint: Optional[str] = field(init = False, default = None)
+    """The jikan api endpoint to get a random object with this resource."""
 
     data: JikanResponseData[Any]

anmoku/resources/manga/manga.py

@@ -64,6 +64,7 @@ class Manga(JikanResource):
     """
     _get_endpoint = "/manga/{id}"
     _search_endpoint = "/manga"
+    _random_endpoint = "/random/manga"
 
     data: JikanResponseData[MangaData] = field(repr = False)