Feature: cli: default download; improved REAME and documentation (#902)

* Additional CLI documentation in README
* CLI page for readthedocs
* Added default download behavior to download highest resolution progressive stream
* Added `-lc` flag to list available caption codes
* Adds CLI argument for logfile output
* `setup_logger` can now take an argument for file output

README.md

@@ -234,26 +234,53 @@ Similarly, if your application requires on-download progress logic, pytube expos
  >>> yt.register_on_progress_callback(show_progress_bar)
 ```
 
-Download video(s) to specific directory with specific name
+You can also download videos to a specific directory with specific filename:
 
 ```python
 >>> yt = YouTube('https://youtube.com/watch?v=2lAe1cqCOXo')
 >>> yt.streams.first().download(output_path="/tmp" ,filename='output')
 ```
 
-## Command-line interface
+## Command-line interface (CLI)
 
-pytube also ships with a tiny cli interface for downloading and probing videos.
+Pytube also ships with a tiny CLI for interacting with videos and playlists.
 
-Let's start with downloading:
+To download the highest resolution progressive stream:
 
 ```bash
-$ pytube http://youtube.com/watch?v=2lAe1cqCOXo --itag=22
+$ pytube https://www.youtube.com/watch?v=2lAe1cqCOXo
 ```
+
 To view available streams:
 
 ```bash
-$ pytube http://youtube.com/watch?v=2lAe1cqCOXo --list
+$ pytube https://www.youtube.com/watch?v=2lAe1cqCOXo --list
+```
+
+To download a specific stream, use the itag
+
+```bash
+$ pytube https://www.youtube.com/watch?v=2lAe1cqCOXo --itag=22
+```
+
+To get a list of all subtitles (caption codes) 
+
+```bash
+$ pytube https://www.youtube.com/watch?v=2lAe1cqCOXo --list-captions
 ```
 
+To download a specific subtitle (caption code) - in this case the
+english subtitles (in srt format) - use:
+
+```bash
+$ pytube https://www.youtube.com/watch?v=2lAe1cqCOXo -c en
+```
+
+It is also possible to just download the audio stream (default AAC/mp4):
+
+```bash
+$ pytube https://www.youtube.com/watch?v=2lAe1cqCOXo -a
+```
+
+
 Finally, if you're filing a bug report, the cli contains a switch called ``--build-playback-report``, which bundles up the state, allowing others to easily replay your issue.

docs/index.rst

@@ -64,6 +64,7 @@ This part of the documentation begins with some background information about the
    user/install
    user/quickstart
    user/playlist
+   user/cli
 
 The API Documentation / Guide
 -----------------------------

docs/user/cli.rst

@@ -0,0 +1,54 @@
+.. _cli:
+
+Command-line interface (CLI)
+=============================
+
+Pytube also ships with a tiny CLI for interacting with videos and playlists.
+
+To download the highest resolution progressive stream:
+
+.. code:: bash
+
+    $ pytube https://www.youtube.com/watch?v=2lAe1cqCOXo
+
+To view available streams:
+
+.. code:: bash
+
+    $ pytube https://www.youtube.com/watch?v=2lAe1cqCOXo --list
+
+To download a specific stream, use the itag
+
+.. code:: bash
+
+    $ pytube https://www.youtube.com/watch?v=2lAe1cqCOXo --itag=22
+
+To get a list of all subtitles (caption codes)
+
+.. code:: bash
+
+    $ pytube https://www.youtube.com/watch?v=2lAe1cqCOXo --list-captions
+
+To download a specific subtitle (caption code) - in this case the
+english subtitles (in srt format) - use:
+
+.. code:: bash
+
+    $ pytube https://www.youtube.com/watch?v=2lAe1cqCOXo -c en
+
+It is also possible to just download the audio stream (default AAC/mp4):
+
+.. code:: bash
+
+    $ pytube https://www.youtube.com/watch?v=2lAe1cqCOXo -a
+
+To list all command line options, simply type
+
+.. code:: bash
+
+    $ pytube --help
+
+
+Finally, if you're filing a bug report, the cli contains a switch called
+``--build-playback-report``, which bundles up the state, allowing others
+to easily replay your issue.

pytube/cli.py

@@ -18,7 +18,7 @@ from pytube import CaptionQuery
 from pytube import Playlist
 from pytube import Stream
 from pytube import YouTube
-from pytube.exceptions import PytubeError
+from pytube.exceptions import PytubeError, VideoUnavailable
 from pytube.helpers import safe_filename
 from pytube.helpers import setup_logger
 
@@ -29,8 +29,11 @@ def main():
     parser = argparse.ArgumentParser(description=main.__doc__)
     args = _parse_args(parser)
     if args.verbosity:
+        log_filename = None
         log_level = min(args.verbosity, 4) * 10
-        setup_logger(logging.FATAL - log_level)
+        if args.logfile:
+            log_filename = args.logfile
+        setup_logger(logging.FATAL - log_level, log_filename=log_filename)
 
     if not args.url or "youtu" not in args.url:
         parser.print_help()
@@ -56,13 +59,19 @@ def main():
 def _perform_args_on_youtube(
     youtube: YouTube, args: argparse.Namespace
 ) -> None:
+    if len(sys.argv) == 2 :  # no arguments parsed
+        download_highest_resolution_progressive(
+            youtube=youtube, resolution="highest", target=args.target
+        )
+    if args.list_captions:
+        _print_available_captions(youtube.captions)
     if args.list:
         display_streams(youtube)
     if args.build_playback_report:
         build_playback_report(youtube)
     if args.itag:
         download_by_itag(youtube=youtube, itag=args.itag, target=args.target)
-    if hasattr(args, "caption_code"):
+    if args.caption_code:
         download_caption(
             youtube=youtube, lang_code=args.caption_code, target=args.target
         )
@@ -115,6 +124,11 @@ def _parse_args(
         dest="verbosity",
         help="Verbosity level, use up to 4 to increase logging -vvvv",
     )
+    parser.add_argument(
+        "--logfile",
+        action="store",
+        help="logging debug and error messages into a log file",
+    )
     parser.add_argument(
         "--build-playback-report",
         action="store_true",
@@ -124,13 +138,19 @@ def _parse_args(
         "-c",
         "--caption-code",
         type=str,
-        default=argparse.SUPPRESS,
-        nargs="?",
         help=(
             "Download srt captions for given language code. "
             "Prints available language codes if no argument given"
         ),
     )
+    parser.add_argument(
+        '-lc',
+        '--list-captions',
+        action='store_true',
+        help=(
+            "List available caption codes for a video"
+        )
+    )
     parser.add_argument(
         "-t",
         "--target",
@@ -441,6 +461,30 @@ def download_by_resolution(
         sys.exit()
 
 
+def download_highest_resolution_progressive(
+    youtube: YouTube, resolution: str, target: Optional[str] = None
+) -> None:
+    """Start downloading the highest resolution progressive stream.
+
+    :param YouTube youtube:
+        A valid YouTube object.
+    :param str resolution:
+        YouTube video resolution.
+    :param str target:
+        Target directory for download
+    """
+    youtube.register_on_progress_callback(on_progress)
+    try:
+        stream = youtube.streams.get_highest_resolution()
+    except VideoUnavailable as err:
+        print(f"No video streams available: {err}")
+    else:
+        try:
+            _download(stream, target=target)
+        except KeyboardInterrupt:
+            sys.exit()
+
+
 def display_streams(youtube: YouTube) -> None:
     """Probe YouTube video and lists its available formats.
 
@@ -472,10 +516,6 @@ def download_caption(
     :param str target:
         Target directory for download
     """
-    if lang_code is None:
-        _print_available_captions(youtube.captions)
-        return
-
     try:
         caption = youtube.captions[lang_code]
         downloaded_path = caption.download(

pytube/helpers.py

@@ -88,7 +88,7 @@ def safe_filename(s: str, max_length: int = 255) -> str:
     return filename[:max_length].rsplit(" ", 0)[0]
 
 
-def setup_logger(level: int = logging.ERROR):
+def setup_logger(level: int = logging.ERROR, log_filename: Optional[str] = None) -> None:
     """Create a configured instance of logger.
 
     :param int level:
@@ -98,14 +98,19 @@ def setup_logger(level: int = logging.ERROR):
     date_fmt = "%H:%M:%S"
     formatter = logging.Formatter(fmt, datefmt=date_fmt)
 
-    handler = logging.StreamHandler()
-    handler.setFormatter(formatter)
-
     # https://github.com/nficano/pytube/issues/163
     logger = logging.getLogger("pytube")
-    logger.addHandler(handler)
     logger.setLevel(level)
 
+    stream_handler = logging.StreamHandler()
+    stream_handler.setFormatter(formatter)
+    logger.addHandler(stream_handler)
+
+    if log_filename is not None:
+        file_handler = logging.FileHandler(log_filename)
+        file_handler.setFormatter(formatter)
+        logger.addHandler(file_handler)
+
 
 GenericType = TypeVar("GenericType")
 

tests/test_cli.py

@@ -178,7 +178,7 @@ def test_main_logging_setup(setup_logger):
     with pytest.raises(SystemExit):
         cli.main()
     # Then
-    setup_logger.assert_called_with(40)
+    setup_logger.assert_called_with(40, log_filename=None)
 
 
 @mock.patch("pytube.cli.YouTube", return_value=None)
@@ -222,7 +222,7 @@ def test_main_display_streams(youtube):
 @mock.patch("pytube.cli.YouTube", return_value=None)
 def test_main_download_caption(youtube):
     parser = argparse.ArgumentParser()
-    args = parse_args(parser, ["http://youtube.com/watch?v=9bZkp7q19f0", "-c"])
+    args = parse_args(parser, ["http://youtube.com/watch?v=9bZkp7q19f0", "-c", "en"])
     cli._parse_args = MagicMock(return_value=args)
     cli.download_caption = MagicMock()
     cli.main()