Trending videos

piped_api/__init__.py

@@ -6,6 +6,9 @@ from .client import PipedClient
 from .models.comments import Comments
 
 
+from setup import __doc__ as __sdoc__
+__doc__ = __sdoc__
+
 
 # Supress unused-import warnings:
 if t.TYPE_CHECKING:

piped_api/client.py

@@ -75,3 +75,16 @@ class PipedClient:
         """
 
         return self._get_json(f"/streams/{video_id}", Video)
+
+
+    def get_trending(self, country_code: str='US') -> t.List[Video.RelatedStream]:
+        """
+            Obtains trending videos for a specific country. If there are no trending videos (or `country_code` is invalid),
+            an empty list is returned.
+
+            ### Parameters:
+            - `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.
+        """
+
+        return [Video.RelatedStream(trending_video) for trending_video in self._get_json(f"/trending", params={'region': country_code.upper()})]

piped_api/models/videos.py

@@ -1,4 +1,3 @@
-from re import S
 import typing as t
 
 from datetime import datetime, date, timedelta
@@ -306,9 +305,9 @@ class Video(BasePipedModel):
 
 
 
-    class RelatedVideo(BasePipedModel):
+    class RelatedStream(BasePipedModel):
         """
-            A related video to the current video (e. g.: from the right sidebar)
+            A related stream (e. g.: related video to the current one from the right sidebar, video related to/uploaded by a channel and trending video).
         """
 
         @property
@@ -411,10 +410,10 @@ class Video(BasePipedModel):
                 The date the related video was uploaded (as a `datetime.datetime` object).
 
                 ### Note:
-                The original value was in POSIX timestamp (`Video.data['uploaded']`), but this package converts it to a `datetime.datetime` object.
+                The original value was in milliseconds since epoch (`Video.data['uploaded']`), but this package converts it to a `datetime.datetime` object.
             """
 
-            return datetime.fromtimestamp(self.data['uploaded'])
+            return datetime.fromtimestamp(self.data['uploaded'] / 1000)
 
 
         @property
@@ -428,12 +427,12 @@ class Video(BasePipedModel):
 
 
     @property
-    def related_videos(self) -> t.List[RelatedVideo]:
+    def related_videos(self) -> t.List[RelatedStream]:
         """
             List of related streams
         """
 
-        return [self.RelatedVideo(video_data) for video_data in self.data['relatedVideos']]
+        return [self.RelatedStream(video_data) for video_data in self.data['relatedVideos']]