Improvement/channel docs (#1011)

* Docstring improvements

* Documentation for the channel object

* Additional metadata available from the channel object, with unit tests

docs/api.rst

@@ -20,6 +20,13 @@ Playlist Object
    :members:
    :inherited-members:
 
+Channel Object
+--------------
+
+.. autoclass:: pytube.contrib.channel.Channel
+   :members:
+   :inherited-members:
+
 Stream Object
 -------------
 

docs/index.rst

@@ -58,6 +58,7 @@ of pytube.
    user/streams
    user/captions
    user/playlist
+   user/channel
    user/cli
    user/exceptions
 

docs/user/channel.rst

@@ -0,0 +1,46 @@
+.. _channel:
+
+Using Channels
+==============
+
+This guide will walk you through the basics of working with pytube Channels.
+
+Creating a Channel
+------------------
+
+Using pytube to interact with channels is similar to interacting with playlists. 
+Begin by importing the Channel class::
+
+    >>> from pytube import Channel
+
+Now let's create a channel object. You can do this by initializing the object with a channel URL::
+
+    >>> c = Channel('https://www.youtube.com/c/ProgrammingKnowledge')
+
+Or you can create one from a link to the channel's video page::
+
+    >>> c = Channel('https://www.youtube.com/c/ProgrammingKnowledge/videos')
+
+Now, we have a :class:`Channel <pytube.Channel>` object called ``c`` that we can do some work with.
+
+Interacting with a channel
+--------------------------
+
+Fundamentally, a Channel object is just a container for YouTube objects.
+
+If, for example, we wanted to download all of the videos created by a channel, we would do the following::
+
+    >>> print(f'Downloading videos by: {c.channel_name}')
+    Downloading videos by: ProgrammingKnowledge
+    >>> for video in c.videos:
+    >>>     video.streams.first().download()
+
+Or, if we're only interested in the URLs for the videos, we can look at those as well::
+
+    >>> for url in c.video_urls[:3]:
+    >>>     print(url)
+    ['https://www.youtube.com/watch?v=tMqMU1U2MCU',
+    'https://www.youtube.com/watch?v=YBfInrtWq8Y',
+    'https://www.youtube.com/watch?v=EP9WrMw6Gzg']
+
+And that's basically all there is to it!

docs/user/playlist.rst

@@ -39,8 +39,8 @@ Or, if we're only interested in the URLs for the videos, we can look at those as
 
     >>> for url in p.video_urls[:3]:
     >>>     print(url)
-    Python Tutorial for Beginners 1 - Getting Started and Installing Python (For Absolute Beginners)
-    Python Tutorial for Beginners 2 - Numbers and Math in Python
-    Python Tutorial for Beginners 3 - Variables and Inputs
+    ['https://www.youtube.com/watch?v=41qgdwd3zAg',
+    'https://www.youtube.com/watch?v=Lbs7vmx3YwU',
+    'https://www.youtube.com/watch?v=YtX-Rmoea0M']
 
-And that's basically all there is to it! The Playlist class is relatively straightforward.
+And that's basically all there is to it!

pytube/__main__.py

@@ -36,8 +36,6 @@ class YouTube:
 
         :param str url:
             A valid YouTube watch URL.
-        :param bool defer_prefetch_init:
-            Defers executing any network requests.
         :param func on_progress_callback:
             (Optional) User defined callback function for stream download
             progress events.
@@ -420,6 +418,7 @@ class YouTube:
     @property
     def keywords(self) -> List[str]:
         """Get the video keywords.
+
         :rtype: List[str]
         """
         return self.player_response.get('videoDetails', {}).get('keywords', [])
@@ -427,6 +426,7 @@ class YouTube:
     @property
     def channel_id(self) -> str:
         """Get the video poster's channel id.
+
         :rtype: str
         """
         return self.player_response.get('videoDetails', {}).get('channelId', None)
@@ -434,6 +434,7 @@ class YouTube:
     @property
     def channel_url(self) -> str:
         """Construct the channel url for the video's poster from the channel id.
+
         :rtype: str
         """
         return f'https://www.youtube.com/channel/{self.channel_id}'

pytube/contrib/channel.py

@@ -12,6 +12,13 @@ logger = logging.getLogger(__name__)
 
 class Channel(Playlist):
     def __init__(self, url: str, proxies: Optional[Dict[str, str]] = None):
+        """Construct a :class:`Channel <Channel>`.
+
+        :param str url:
+            A valid YouTube channel URL.
+        :param proxies:
+            (Optional) A dictionary of proxies to use for web requests.
+        """
         super().__init__(url, proxies)
 
         self.channel_uri = extract.channel_name(url)
@@ -19,6 +26,7 @@ class Channel(Playlist):
         self.channel_url = (
             f"https://www.youtube.com{self.channel_uri}"
         )
+
         self.videos_url = self.channel_url + '/videos'
         self.playlists_url = self.channel_url + '/playlists'
         self.community_url = self.channel_url + '/community'
@@ -31,8 +39,40 @@ class Channel(Playlist):
         self._featured_channels_html = None
         self._about_html = None
 
+    @property
+    def channel_name(self):
+        """Get the name of the YouTube channel.
+
+        :rtype: str
+        """
+        return self.initial_data['metadata']['channelMetadataRenderer']['title']
+
+    @property
+    def channel_id(self):
+        """Get the ID of the YouTube channel.
+
+        This will return the underlying ID, not the vanity URL.
+
+        :rtype: str
+        """
+        return self.initial_data['metadata']['channelMetadataRenderer']['externalId']
+
+    @property
+    def vanity_url(self):
+        """Get the vanity URL of the YouTube channel.
+
+        Returns None if it doesn't exist.
+
+        :rtype: str
+        """
+        return self.initial_data['metadata']['channelMetadataRenderer'].get('vanityChannelUrl', None)  # noqa:E501
+
     @property
     def html(self):
+        """Get the html for the /videos page.
+
+        :rtype: str
+        """
         if self._html:
             return self._html
         self._html = request.get(self.videos_url)
@@ -40,6 +80,12 @@ class Channel(Playlist):
 
     @property
     def playlists_html(self):
+        """Get the html for the /playlists page.
+
+        Currently unused for any functionality.
+
+        :rtype: str
+        """
         if self._playlists_html:
             return self._playlists_html
         else:
@@ -48,6 +94,12 @@ class Channel(Playlist):
 
     @property
     def community_html(self):
+        """Get the html for the /community page.
+
+        Currently unused for any functionality.
+
+        :rtype: str
+        """
         if self._community_html:
             return self._community_html
         else:
@@ -56,6 +108,12 @@ class Channel(Playlist):
 
     @property
     def featured_channels_html(self):
+        """Get the html for the /channels page.
+
+        Currently unused for any functionality.
+
+        :rtype: str
+        """
         if self._featured_channels_html:
             return self._featured_channels_html
         else:
@@ -64,6 +122,12 @@ class Channel(Playlist):
 
     @property
     def about_html(self):
+        """Get the html for the /about page.
+
+        Currently unused for any functionality.
+
+        :rtype: str
+        """
         if self._about_html:
             return self._about_html
         else:

pytube/contrib/playlist.py

@@ -30,6 +30,10 @@ class Playlist(Sequence):
 
     @property
     def playlist_id(self):
+        """Get the playlist id.
+
+        :rtype: str
+        """
         if self._playlist_id:
             return self._playlist_id
         self._playlist_id = extract.playlist_id(self._input_url)
@@ -37,10 +41,18 @@ class Playlist(Sequence):
 
     @property
     def playlist_url(self):
+        """Get the base playlist url.
+
+        :rtype: str
+        """
         return f"https://www.youtube.com/playlist?list={self.playlist_id}"
 
     @property
     def html(self):
+        """Get the playlist page html.
+
+        :rtype: str
+        """
         if self._html:
             return self._html
         self._html = request.get(self.playlist_url)
@@ -48,6 +60,10 @@ class Playlist(Sequence):
 
     @property
     def ytcfg(self):
+        """Extract the ytcfg from the playlist page html.
+
+        :rtype: dict
+        """
         if self._ytcfg:
             return self._ytcfg
         self._ytcfg = extract.get_ytcfg(self.html)
@@ -55,6 +71,10 @@ class Playlist(Sequence):
 
     @property
     def initial_data(self):
+        """Extract the initial data from the playlist page html.
+
+        :rtype: dict
+        """
         if self._initial_data:
             return self._initial_data
         else:
@@ -63,6 +83,10 @@ class Playlist(Sequence):
 
     @property
     def sidebar_info(self):
+        """Extract the sidebar info from the playlist page html.
+
+        :rtype: dict
+        """
         if self._sidebar_info:
             return self._sidebar_info
         else:
@@ -72,6 +96,10 @@ class Playlist(Sequence):
 
     @property
     def yt_api_key(self):
+        """Extract the INNERTUBE_API_KEY from the playlist ytcfg.
+
+        :rtype: str
+        """
         return self.ytcfg['INNERTUBE_API_KEY']
 
     def _paginate(

tests/contrib/test_channel.py

@@ -16,12 +16,39 @@ def test_init_with_url(request_get, channel_videos_html):
 
 
 @mock.patch('pytube.request.get')
-def test_channel_name(request_get, channel_videos_html):
+def test_channel_uri(request_get, channel_videos_html):
     request_get.return_value = channel_videos_html
 
     c = Channel('https://www.youtube.com/c/ProgrammingKnowledge/videos')
     assert c.channel_uri == '/c/ProgrammingKnowledge'
 
+    c = Channel('https://www.youtube.com/channel/UCs6nmQViDpUw0nuIx9c_WvA/videos')
+    assert c.channel_uri == '/channel/UCs6nmQViDpUw0nuIx9c_WvA'
+
+
+@mock.patch('pytube.request.get')
+def test_channel_name(request_get, channel_videos_html):
+    request_get.return_value = channel_videos_html
+
+    c = Channel('https://www.youtube.com/c/ProgrammingKnowledge/videos')
+    assert c.channel_name == 'ProgrammingKnowledge'
+
+
+@mock.patch('pytube.request.get')
+def test_channel_id(request_get, channel_videos_html):
+    request_get.return_value = channel_videos_html
+
+    c = Channel('https://www.youtube.com/c/ProgrammingKnowledge/videos')
+    assert c.channel_id == 'UCs6nmQViDpUw0nuIx9c_WvA'
+
+
+@mock.patch('pytube.request.get')
+def test_channel_vanity_url(request_get, channel_videos_html):
+    request_get.return_value = channel_videos_html
+
+    c = Channel('https://www.youtube.com/c/ProgrammingKnowledge/videos')
+    assert c.vanity_url == 'http://www.youtube.com/c/ProgrammingKnowledge'
+
 
 @mock.patch('pytube.request.get')
 def test_channel_video_list(request_get, channel_videos_html):