doc updates

pytube/cipher.py

@@ -51,19 +51,17 @@ def get_transform_plan(js):
     :param str js:
         The contents of the base.js asset file.
 
-    **Sample Output**:
-
-    .. code-block:: python
-
-       ['DE.AJ(a,15)',
-       'DE.VR(a,3)',
-       'DE.AJ(a,51)',
-       'DE.VR(a,3)',
-       'DE.kT(a,51)',
-       'DE.kT(a,8)',
-       'DE.VR(a,3)',
-       'DE.kT(a,21)']
-
+    **Example**:
+
+    >>> get_transform_plan(js)
+    ['DE.AJ(a,15)',
+    'DE.VR(a,3)',
+    'DE.AJ(a,51)',
+    'DE.VR(a,3)',
+    'DE.kT(a,51)',
+    'DE.kT(a,8)',
+    'DE.VR(a,3)',
+    'DE.kT(a,21)']
     """
     name = re.escape(get_initial_function_name(js))
     pattern = r'%s=function\(\w\){[a-z=\.\(\"\)]*;(.*);(?:.+)}' % name
@@ -85,13 +83,12 @@ def get_transform_object(js, var):
         The obfuscated variable name that stores an object with all functions
         that descrambles the signature.
 
-    **Sample Output**:
+    **Example**:
 
-    .. code-block:: python
-
-       ['AJ:function(a){a.reverse()}',
-        'VR:function(a,b){a.splice(0,b)}',
-        'kT:function(a,b){var c=a[0];a[0]=a[b%a.length];a[b]=c}']
+    >>> get_transform_object(js, 'DE')
+    ['AJ:function(a){a.reverse()}',
+    'VR:function(a,b){a.splice(0,b)}',
+    'kT:function(a,b){var c=a[0];a[0]=a[b%a.length];a[b]=c}']
 
     """
     pattern = r'var %s={(.*?)};' % re.escape(var)
@@ -133,13 +130,13 @@ def reverse(arr, b):
 
     .. code-block:: javascript
 
-       function(a, b) { a.reverse() }.
+       function(a, b) { a.reverse() }
 
     This method takes an unused ``b`` variable as their transform functions
     universally sent two arguments.
 
-    **Example usage**:
-    ~~~~~~~~~~~~~~
+    **Example**:
+
     >>> reverse([1, 2, 3, 4])
     [4, 3, 2, 1]
     """
@@ -153,10 +150,10 @@ def splice(arr, b):
 
     .. code-block:: javascript
 
-       function(a, b) { a.splice(0, b) }.
+       function(a, b) { a.splice(0, b) }
+
+    **Example**:
 
-    **Example usage**:
-    ~~~~~~~~~~~~~~
     >>> splice([1, 2, 3, 4], 2)
     [1, 2]
     """
@@ -170,10 +167,10 @@ def swap(arr, b):
 
     .. code-block:: javascript
 
-       function(a, b) { var c=a[0];a[0]=a[b%a.length];a[b]=c }.
+       function(a, b) { var c=a[0];a[0]=a[b%a.length];a[b]=c }
+
+    **Example**:
 
-    **Example usage**:
-    ~~~~~~~~~~~~~~
     >>> swap([1, 2, 3, 4], 2)
     [3, 2, 1, 4]
     """
@@ -212,20 +209,16 @@ def parse_function(js_func):
     Break a JavaScript transform function down into a two element ``tuple``
     containing the function name and some integer-based argument.
 
-    Sample input:
-
-    .. code-block:: javascript
-
-       DE.AJ(a,15)
-
-    Sample Output:
-
-    .. code-block:: python
-
-       ('AJ', 15)
-
     :param str js_func:
         The JavaScript version of the transform function.
+    :rtype: tuple
+    :returns:
+        two element tuple containing the function name and an argument.
+
+    **Example**:
+
+    >>> parse_function('DE.AJ(a,15)')
+    ('AJ', 15)
 
     """
     logger.debug('parsing transform function')

pytube/extract.py

@@ -9,22 +9,30 @@ from pytube.helpers import regex_search
 
 
 def video_id(url):
-    """Extract the ``video_id`` part of /watch?v=<video_id>.
+    """Extract the ``video_id`` from a YouTube url.
 
-    :param str url:
-        A url YouTube id containing a video_id.
+    This function supports the following patterns:
+
+    - :samp:`https://www.youtube.com/watch?v={video_id}`
+    - :samp:`https://youtu.be/{video_id}`
 
+    :param str url:
+        A YouTube url containing a video id.
+    :rtype: str
+    :returns:
+        YouTube video id.
     """
-    # TODO(nficano): support url-shortened version
-    return regex_search(r'.*(?:v=|/v/|^)(?P<id>[^&]*)', url, group=1)
+    return regex_search(r'(?:v=|\/)([0-9A-Za-z_-]{11}).*', url, group=1)
 
 
 def watch_url(video_id):
-    """Construct a YouTube watch url, given a video id.
+    """Construct a sanitized YouTube watch url, given a video id.
 
     :param str video_id:
         A YouTube video identifer.
-
+    :rtype: str
+    :returns:
+        Sanitized YouTube watch url.
     """
     return 'https://youtube.com/watch?v=' + video_id
 
@@ -79,13 +87,16 @@ def mime_type_codec(mime_type_codec):
     mime type and codecs serialized together, and splits them into separate
     elements.
 
+    **Example**:
+
+    >>> mime_type_codec('audio/webm; codecs="opus"')
+    ('audio/webm', ['opus'])
+
     :param str mime_type_codec:
-        String containing mime type and codecs, for example:
-        'audio/webm; codecs="opus"'
+        String containing mime type and codecs.
     :rtype: tuple
     :returns:
-        The mime type and a list of codecs, for example:
-        ('audio/webm', ['opus'])
+        The mime type and a list of codecs.
 
     """
     pattern = r'(\w+\/\w+)\;\scodecs=\"([a-zA-Z-0-9.,\s]*)\"'
@@ -104,7 +115,7 @@ def get_ytplayer_config(watch_html):
         The html contents of the watch page.
     :rtype: str
     :returns:
-        Substring of the html containing the serialized manifest data.
+        Substring of the html containing the encoded manifest data.
     """
     pattern = r';ytplayer\.config\s*=\s*({.*?});'
     yt_player_config = regex_search(pattern, watch_html, group=1)

pytube/query.py

@@ -174,10 +174,14 @@ class StreamQuery:
         return self
 
     def get_by_itag(self, itag):
-        """Get a :class:`Stream <Stream>` for an itag, or ``None`` if not found.
+        """Get the corresponding :class:`Stream <Stream>` for a given itag.
 
         :param str itag:
             YouTube format identifier code.
+        :rtype: :class:`Stream <Stream>` or ``None``
+        :returns:
+            The :class:`Stream <Stream>` matching the given itag or ``None`` if
+            not found.
 
         """
         try:
@@ -186,10 +190,12 @@ class StreamQuery:
             pass
 
     def first(self):
-        """Get the first element in the results.
+        """Get the first :class:`Stream <Stream>` in the results.
 
-        Return the first result of this query or ``None`` if the result doesn't
-        contain any streams.
+        :rtype: :class:`Stream <Stream>` or ``None``
+        :returns:
+            the first result of this query or ``None`` if the result doesn't
+            contain any streams.
 
         """
         try:
@@ -198,10 +204,12 @@ class StreamQuery:
             pass
 
     def last(self):
-        """Get the last element in the results.
+        """Get the last :class:`Stream <Stream>` in the results.
 
-        Return the last result of this query or ``None`` if the result doesn't
-        contain any streams.
+        :rtype: :class:`Stream <Stream>` or ``None``
+        :returns:
+            Return the last result of this query or ``None`` if the result
+            doesn't contain any streams.
 
         """
         try: