Some tweaks

piped_api/client.py

@@ -5,7 +5,7 @@ from requests import Session
 from .models import BasePipedModel
 from .models.comments import Comments
 from .models.videos import Video
-from .models.channels import Channel
+from .models.channels import NextPageChannel, Channel
 
 
 _MDL = t.TypeVar('_MDL', bound=t.Type[BasePipedModel])
@@ -35,7 +35,7 @@ class PipedClient:
 
 
 
-    def _get_json(self, uri: str, as_model: t.Optional[_MDL]=None, **kwargs) -> t.Union[_MDL, t.Dict[str, t.Any]]:
+    def _get_json(self, uri: str, as_model: t.Optional[_MDL]=None, **kwargs) -> t.Union[_MDL, t.Dict[str, t.Any], t.List[t.Any]]:
         """
             Obtains JSON data from specific URI of the Piped API.
 
@@ -56,6 +56,19 @@ class PipedClient:
         return json
 
 
+    def get_video(self, video_id: str, **kwargs) -> Video:
+        """
+            Gets information about a specific video.
+
+            ### Parameters:
+            - `video_id` - The ID of the video to get information for
+            - `**kwargs` - Additional keyword arguments to pass to `requests.Session.get`
+
+            [Piped Documentation](https://piped-docs.kavin.rocks/docs/api-documentation/#streamsvideoid)
+        """
+
+        return self._get_json(f"/streams/{video_id}", Video, **kwargs)
+
 
     def get_comments(self, video_id: str, nextpage: t.Optional[t.Dict[str, t.Optional[str]]]=None, **kwargs) -> Comments:
         """
@@ -66,29 +79,15 @@ class PipedClient:
             - `nextpage` - Nextpage data, obtained from `.models.comments.Comments.nextpage` property. If this is `None`, the first page of comments is returned.
                 There are often 20 comments per page.
             - `**kwargs` - Additional keyword arguments to pass to `requests.Session.get`
-        """
 
-        kw = kwargs.copy()
+            [Piped Documentation](https://piped-docs.kavin.rocks/docs/api-documentation/#commentsvideoid)
+        """
 
         if nextpage is not None:
-            kw.update({'params': {'nextpage': nextpage}})
-            return self._get_json(f"/nextpage/comments/{video_id}", Comments, **kw)
+            kwargs.update({'params': {'nextpage': nextpage}})
+            return self._get_json(f"/nextpage/comments/{video_id}", Comments, **kwargs)
 
-        else:
-            return self._get_json(f"/comments/{video_id}", Comments, **kw)
-
-
-
-    def get_video(self, video_id: str, **kwargs) -> Video:
-        """
-            Gets information about a specific video.
-
-            ### Parameters:
-            - `video_id` - The ID of the video to get information for
-            - `**kwargs` - Additional keyword arguments to pass to `requests.Session.get`
-        """
-
-        return self._get_json(f"/streams/{video_id}", Video, **kwargs)
+        return self._get_json(f"/comments/{video_id}", Comments, **kwargs)
 
 
     def get_trending(self, country_code: str='US', **kwargs) -> t.List[Video.RelatedStream]:
@@ -100,23 +99,30 @@ class PipedClient:
             - `country_code` - The country code ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements)) to get trending videos for. This is automatically capitalized by this package,
                 since Piped for some reason doesn't accept lowercase country codes. Note: countries such as China or North Korea don't have trending videos, so they will always return an empty list.
             - `**kwargs` - Additional keyword arguments to pass to `requests.Session.get`
+
+            [Piped Documentation](https://piped-docs.kavin.rocks/docs/api-documentation/#trending)
         """
 
-        kw = kwargs.copy()
-        kw.update({'params': {'region': country_code.upper()}})
+        kwargs.update({'params': {'region': country_code.upper()}})
 
-        return [Video.RelatedStream(trending_video) for trending_video in self._get_json(f"/trending", **kw)]
+        return [Video.RelatedStream(trending_video) for trending_video in self._get_json(f"/trending", **kwargs)]
 
 
-    def get_channel_by_id(self, channel_id: str, **kwargs) -> Channel:
+    def get_channel_by_id(self, channel_id: str, nextpage: t.Optional[t.Dict[str, t.Optional[str]]]=None, **kwargs) -> t.Union[NextPageChannel, Channel]:
         """
             Gets information about a specific channel by its ID.
 
             ### Parameters:
             - `channel_id` - The ID of the channel to get information for
             - `**kwargs` - Additional keyword arguments to pass to `requests.Session.get`
+
+            [Piped Documentation](https://piped-docs.kavin.rocks/docs/api-documentation/#channelchannelid)
         """
 
+        if nextpage is not None:
+            kwargs.update({'params': {'nextpage': nextpage}})
+            return self._get_json(f"/nextpage/channel/{channel_id}", NextPageChannel, **kwargs)
+
         return self._get_json(f"/channel/{channel_id}", Channel, **kwargs)
 
 
@@ -128,6 +134,24 @@ class PipedClient:
             ### Parameters:
             - `channel_name` - The name of the channel to get information for
             - `**kwargs` - Additional keyword arguments to pass to `requests.Session.get`
+
+            [Piped Documentation](https://piped-docs.kavin.rocks/docs/api-documentation/#cname)
         """
 
         return self._get_json(f"/c/{channel_name}", Channel, **kwargs)
+
+
+    def get_search_suggestions(self, search_query: str, **kwargs) -> t.List[str]:
+        """
+            Obtains search suggestions for a query.
+
+            ### Parameters:
+            - `search_query` - The query to get search suggestions for
+            - `**kwargs` - Additional keyword arguments to pass to `requests.Session.get`
+
+            [Piped Documentation](https://piped-docs.kavin.rocks/docs/api-documentation/#suggestions)
+        """
+
+        kwargs.update({'params': {'query': search_query}})
+
+        return self._get_json(f"/suggestions", **kwargs)

piped_api/models/channels.py

@@ -5,9 +5,40 @@ from .videos import Video
 
 
 
-class Channel(BasePipedModel):
+class NextPageChannel(BasePipedModel):
     """
-        Represents a YouTube channel
+        Represents a channel obtained via the `nextpage` endpoint.
+
+        This model contains only `nextpage` and `relatedStreams`. It's a parent for `Channel`.
+    """
+
+    @property
+    def nextpage(self) -> str:
+        """
+            A JSON encoded string to be passed to the `'nextpage'` endpoint(s) when
+            obtaining paginated data.
+        """
+
+        return self.data['nextpage']
+
+
+    @property
+    def uploaded_videos(self) -> t.List[Video.RelatedStream]:
+        """
+            List of uploaded videos from the current fetched data
+
+            There are max. 30 videos per page
+        """
+
+        return [Video.RelatedStream(video_data) for video_data in self.data['relatedStreams']]
+
+
+
+class Channel(NextPageChannel):
+    """
+        Represents a YouTube channel.
+
+        Contains properties of `NextPageChannel`.
     """
 
     @property
@@ -55,16 +86,6 @@ class Channel(BasePipedModel):
         return self.data['description']
 
 
-    @property
-    def nextpage(self) -> str:
-        """
-            A JSON encoded string to be passed to the `'nextpage'` endpoint(s) when
-            obtaining paginated data.
-        """
-
-        return self.data['nextpage']
-
-
     @property
     def subscriber_count(self) -> int:
         """
@@ -81,12 +102,3 @@ class Channel(BasePipedModel):
         """
 
         return self.data['verified']
-
-
-    @property
-    def uploaded_videos(self) -> t.List[Video.RelatedStream]:
-        """
-            List of uploaded videos from the current fetched data
-        """
-
-        return [Video.RelatedStream(video_data) for video_data in self.data['relatedVideos']]

piped_api/models/videos.py

@@ -432,7 +432,7 @@ class Video(BasePipedModel):
             List of related streams
         """
 
-        return [self.RelatedStream(video_data) for video_data in self.data['relatedVideos']]
+        return [self.RelatedStream(video_data) for video_data in self.data['relatedStreams']]