feat: implement manga and some anime endpoints.

.github/workflows/test.yml

@@ -2,7 +2,6 @@ name: Test anmoku (pytest & ruff)
 
 on:
   push:
-  pull_request:
   workflow_dispatch:
 
 jobs:

anmoku/__init__.py

@@ -6,4 +6,4 @@
 from .resources import *
 from .errors import *
 
-__version__ = "1.0.0dev3"
+__version__ = "1.0.0alpha1"

anmoku/clients/async_.py

@@ -1,13 +1,18 @@
 from __future__ import annotations
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, overload
 
 if TYPE_CHECKING:
     from typing import Any, Optional, Type, Dict, Tuple
 
-    from ..typing.anmoku import SnowflakeT
+    from ..typing.anmoku import StrOrIntT
     from ..typing.jikan import SearchResultData
 
-    from .base import ResourceGenericT, SearchResourceGenericT
+    from .base import (
+        ResourceGenericT, 
+        SearchResourceGenericT, 
+        RandomResourceGenericT, 
+        NoArgsResourceGenericT
+    )
 
 from aiohttp import ClientSession
 from devgoldyutils import Colours
@@ -56,10 +61,21 @@ def __init__(
             }
         )
 
-    async def get(self, resource: Type[ResourceGenericT], id: SnowflakeT, **kwargs) -> ResourceGenericT:
-        """Get's the exact resource by id."""
+    @overload
+    async def get(self, resource: Type[NoArgsResourceGenericT]) -> NoArgsResourceGenericT:
+        ...
+
+    @overload
+    async def get(self, resource: Type[ResourceGenericT], id: StrOrIntT, **kwargs) -> ResourceGenericT:
+        ...
+
+    async def get(self, resource: Type[ResourceGenericT], id: Optional[StrOrIntT] = None, **kwargs) -> ResourceGenericT:
+        """Get's the exact resource typically by id."""
+        if id is not None:
+            kwargs["id"] = id
+
         url = self._format_url(
-            resource._get_endpoint, resource, id = id, **kwargs
+            resource._get_endpoint, resource, **kwargs
         )
 
         json_data = await self._request(url)
@@ -77,6 +93,17 @@ async def search(self, resource: Type[SearchResourceGenericT], query: str, sfw:
 
         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

@@ -2,10 +2,10 @@
 from typing import TYPE_CHECKING, cast
 
 if TYPE_CHECKING:
-    from typing import Any, Mapping, TypeVar, Type
+    from typing import Any, Mapping, TypeVar, Type, Optional
 
     from .. import resources
-    from ..typing.anmoku import SnowflakeT
+    from ..typing.anmoku import StrOrIntT
     from ..resources.helpers import SearchResult
 
     ResourceGenericT = TypeVar(
@@ -15,8 +15,22 @@
 
     SearchResourceGenericT = TypeVar(
         "SearchResourceGenericT", 
-        resources.Anime, 
+        resources.Anime,
         resources.Character,
+        resources.Manga
+    )
+
+    RandomResourceGenericT = TypeVar(
+        "RandomResourceGenericT", 
+        resources.Anime,
+        resources.Character,
+        resources.Manga
+    )
+
+    NoArgsResourceGenericT = TypeVar(
+        "NoArgsResourceGenericT", 
+        resources.AnimeGenres,
+        resources.MangaGenres
     )
 
 import logging
@@ -56,7 +70,7 @@ def __init__(self, debug: bool = False) -> None:
         super().__init__()
 
     @abstractmethod
-    def get(self, resource: Type[ResourceGenericT], id: SnowflakeT) -> ResourceGenericT:
+    def get(self, resource: Type[ResourceGenericT], id: Optional[StrOrIntT] = None, **kwargs) -> ResourceGenericT:
         """Get's the exact resource by id."""
         ...
 
@@ -65,6 +79,11 @@ def search(self, resource: Type[SearchResourceGenericT], query: str, sfw: bool =
         """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."""
         try:

anmoku/clients/sync.py

@@ -1,13 +1,18 @@
 from __future__ import annotations
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, overload
 
 if TYPE_CHECKING:
     from typing import Any, Optional, Type, Tuple
 
-    from ..typing.anmoku import SnowflakeT
+    from ..typing.anmoku import StrOrIntT
     from ..typing.jikan import SearchResultData
 
-    from .base import ResourceGenericT, SearchResourceGenericT
+    from .base import (
+        ResourceGenericT,
+        SearchResourceGenericT,
+        NoArgsResourceGenericT,
+        RandomResourceGenericT
+    )
 
 from requests import Session
 from devgoldyutils import Colours
@@ -54,10 +59,21 @@ def __init__(
         self._second_rate_limiter = TimesPerRateLimiter(second_rate_limits[0], second_rate_limits[1])
         self._minute_rate_limiter = TimesPerRateLimiter(minute_rate_limits[0], minute_rate_limits[1])
 
-    def get(self, resource: Type[ResourceGenericT], id: SnowflakeT, **kwargs) -> ResourceGenericT:
-        """Get's the exact resource by id."""
+    @overload
+    def get(self, resource: Type[NoArgsResourceGenericT]) -> NoArgsResourceGenericT:
+        ...
+
+    @overload
+    def get(self, resource: Type[ResourceGenericT], id: StrOrIntT, **kwargs) -> ResourceGenericT:
+        ...
+
+    def get(self, resource: Type[ResourceGenericT], id: Optional[StrOrIntT] = None, **kwargs) -> ResourceGenericT:
+        """Get's the exact resource typically by id."""
+        if id is not None:
+            kwargs["id"] = id
+
         url = self._format_url(
-            resource._get_endpoint, resource, id = id, **kwargs
+            resource._get_endpoint, resource, **kwargs
         )
 
         json_data = self._request(url)
@@ -75,6 +91,17 @@ def search(self, resource: Type[SearchResourceGenericT], query: str, sfw: bool =
 
         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, 
         route: str, 

anmoku/resources/__init__.py

@@ -1,3 +1,4 @@
 from .base import *
 from .anime import *
+from .manga import *
 from .character import *

anmoku/resources/anime/__init__.py

@@ -1,4 +1,12 @@
 from .anime import *
 from .characters import *
 from .staff import *
-from .episodes import *
+from .episodes import *
+from .news import *
+from .forum import *
+from .pictures import *
+from .recommendations import *
+from .reviews import *
+from .relations import *
+from .external import *
+from .genre import *

anmoku/resources/anime/anime.py

@@ -13,6 +13,7 @@
         AnimeData, 
         FullAnimeData, 
         JikanResponseData,
+        MoreInfoData
     )
     from ...typing.mal import MALRatings
 
@@ -49,6 +50,14 @@ class Anime(JikanResource):
     """
     Get or search for anime.
 
+    [`jikan`_]
+
+    .. _jikan: https://docs.api.jikan.moe/#tag/anime/operation/getAnimeById
+
+    Required Params
+    -----------------
+    * `id` - Manga ID
+
     ------------
 
     ⭐ Example:
@@ -70,6 +79,7 @@ class Anime(JikanResource):
     """
     _get_endpoint = "/anime/{id}"
     _search_endpoint = "/anime"
+    _random_endpoint = "/random/anime"
 
     data: JikanResponseData[AnimeData] = field(repr = False)
 
@@ -173,6 +183,19 @@ class FullAnime(Anime): # TODO: Finish this. You can use the FullAnimeData type
 
     data: JikanResponseData[FullAnimeData] = field(repr=False)
 
+@dataclass
+class AnimeMoreInfo(JikanResource):
+    _get_endpoint = "/anime/{id}/moreinfo"
+
+    data: JikanResponseData[MoreInfoData] = field(repr=False)
+
+    more_info: Optional[str] = field(init = False, default = None)
+
+    def __post_init__(self):
+        more_info = self.data["data"]["moreinfo"]
+
+        if more_info is not None:
+            self.more_info = more_info
 
 @dataclass
 class Trailer():

anmoku/resources/anime/characters.py

@@ -2,28 +2,29 @@
 from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
-    from typing import List
-    from ...typing.jikan import (
-        AnimeCharacterData, 
-        JikanResponseData
-    )
+    from typing import List, Generator, Any
+    from ...typing.jikan import AnimeCharacterData, JikanResponseData
 
     from ...typing.jikan.anime.characters import VoiceActorData
 
 from dataclasses import dataclass, field
 
 from ..helpers import Image
-from ..base import JikanResource
+from ..base import JikanIterableResource
 
 __all__ = (
     "AnimeCharacters",
 )
 
 @dataclass
-class AnimeCharacters(JikanResource):
+class AnimeCharacters(JikanIterableResource):
     """
     Get data of the characters from a particular anime.
 
+    Required Params
+    -----------------
+    * `id` - Anime ID
+
     ------------
 
     ⭐ Example:
@@ -37,18 +38,22 @@ class AnimeCharacters(JikanResource):
         anime_characters = client.get(AnimeCharacters, id = 28851) # ID for the anime film "A Silent Voice".
 
         for character in anime_characters:
-        print(f"{character.name} ({character.url})")
+            print(f"{character.name} ({character.url})")
 
         client.close()
     """
     _get_endpoint = "/anime/{id}/characters"
 
     data: JikanResponseData[List[AnimeCharacterData]]
 
-    def __iter__(self):
+    def __post_init__(self):
+        super().__post_init__(AnimeCharacter)
+
+    def __next__(self) -> AnimeCharacter:
+        return super().__next__()
 
-        for character in self.data["data"]:
-            yield AnimeCharacter(character)
+    def __iter__(self) -> Generator[AnimeCharacter, Any, None]:
+        return super().__iter__()
 
 @dataclass
 class AnimeCharacter():

anmoku/resources/anime/episodes.py

@@ -2,7 +2,7 @@
 from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
-    from typing import List, Optional
+    from typing import List, Optional, Generator, Any
     from ...typing.jikan import (
         AnimeEpisodeData,
         SingleAnimeEpisodeData,
@@ -14,24 +14,36 @@
 from dataclasses import dataclass, field
 
 from ..helpers import Title
-from ..base import JikanResource
+from ..base import JikanResource, JikanIterableResource
 
 __all__ = (
     "AnimeEpisodes",
     "SingleAnimeEpisode"
 )
 
 @dataclass
-class AnimeEpisodes(JikanResource):
-    """Get an anime's episodes with anime's ID."""
+class AnimeEpisodes(JikanIterableResource):
+    """
+    Get an anime's episodes with anime's ID.
+
+    -----------------
+
+    Required Params
+    -----------------
+    * `id` - Anime ID
+    """
     _get_endpoint = "/anime/{id}/episodes"
 
     data: JikanPageResponseData[List[AnimeEpisodeData]]
 
-    def __iter__(self):
+    def __post_init__(self):
+        super().__post_init__(AnimeEpisode)
+
+    def __next__(self) -> AnimeEpisode:
+        return super().__next__()
 
-        for episode in self.data["data"]:
-            yield AnimeEpisode(episode)
+    def __iter__(self) -> Generator[AnimeEpisode, Any, None]:
+        return super().__iter__()
 
 @dataclass
 class SingleAnimeEpisode(JikanResource):