Selection of bugfixes and improvements (#1090)

* Change Search client to WEB.

* Add documentation for oauth functionality.

* Return raw 'last_updated' string where it is not parseable.

docs/user/quickstart.rst

@@ -41,7 +41,9 @@ when you create a YouTube object::
             'http://youtube.com/watch?v=2lAe1cqCOXo',
             on_progress_callback=progress_func,
             on_complete_callback=complete_func,
-            proxies=my_proxies
+            proxies=my_proxies,
+            use_oauth=False,
+            allow_oauth_cache=True
         )
 
 When instantiating a YouTube object, these named arguments can be passed in to
@@ -57,5 +59,12 @@ downloaded, and is called with two arguments: the stream and the file path.
 This could be used, for example, to perform post-download processing on a video
 like trimming the length of it.
 
+The use_oauth and allow_oauth_cache flags allow you to authorize pytube to
+interact with YouTube using your account, and can be used to bypass age
+restrictions or access private videos and playlists. If allow_oauth_cache is
+set to True, you should only be prompted to do so once, after which point
+pytube will cache the tokens it needs to act on your behalf. Otherwise, you
+will be prompted again for each action that requires you to be authenticated.
+
 Once you have a YouTube object set up, you're ready to start looking at
 different media streams for the video, which is discussed in the next section.

pytube/__main__.py

@@ -43,7 +43,14 @@ class YouTube:
         :param func on_complete_callback:
             (Optional) User defined callback function for stream download
             complete events.
-
+        :param dict proxies:
+            (Optional) A dict mapping protocol to proxy address which will be used by pytube.
+        :param bool use_oauth:
+            (Optional) Prompt the user to authenticate to YouTube.
+            If allow_oauth_cache is set to True, the user should only be prompted once.
+        :param bool allow_oauth_cache:
+            (Optional) Cache OAuth tokens locally on the machine. Defaults to True.
+            These tokens are only generated if use_oauth is set to True as well.
         """
         self._js: Optional[str] = None  # js fetched by js_url
         self._js_url: Optional[str] = None  # the url to the js, parsed from watch html

pytube/contrib/playlist.py

@@ -319,18 +319,26 @@ class Playlist(Sequence):
     def last_updated(self) -> Optional[date]:
         """Extract the date that the playlist was last updated.
 
-        :return: Date of last playlist update
+        For some playlists, this will be a specific date, which is returned as a datetime
+        object. For other playlists, this is an estimate such as "1 week ago". Due to the
+        fact that this value is returned as a string, pytube does a best-effort parsing
+        where possible, and returns the raw string where it is not possible.
+
+        :return: Date of last playlist update where possible, else the string provided
         :rtype: datetime.date
         """
         last_updated_text = self.sidebar_info[0]['playlistSidebarPrimaryInfoRenderer'][
             'stats'][2]['runs'][1]['text']
-        date_components = last_updated_text.split()
-        month = date_components[0]
-        day = date_components[1].strip(',')
-        year = date_components[2]
-        return datetime.strptime(
-            f"{month} {day:0>2} {year}", "%b %d %Y"
-        ).date()
+        try:
+            date_components = last_updated_text.split()
+            month = date_components[0]
+            day = date_components[1].strip(',')
+            year = date_components[2]
+            return datetime.strptime(
+                f"{month} {day:0>2} {year}", "%b %d %Y"
+            ).date()
+        except (IndexError, KeyError):
+            return last_updated_text
 
     @property
     @cache

pytube/contrib/search.py

@@ -18,7 +18,7 @@ class Search:
             Search query provided by the user.
         """
         self.query = query
-        self._innertube_client = InnerTube()
+        self._innertube_client = InnerTube(client='WEB')
 
         # The first search, without a continuation, is structured differently
         #  and contains completion suggestions, so we must store this separately