Update readme, precommit config, and makefile

.pre-commit-config.yaml

@@ -1,27 +1,54 @@
--   repo: https://github.com/pre-commit/pre-commit-hooks
-    sha: v0.9.5
+repos:
+  - repo: 'https://github.com/pre-commit/pre-commit-hooks'
+    rev: v3.1.0
     hooks:
-    -   id: autopep8-wrapper
-    -   id: check-ast
-    -   id: check-case-conflict
-    -   id: check-merge-conflict
-    -   id: double-quote-string-fixer
-    -   id: end-of-file-fixer
-    -   id: flake8
-    -   id: requirements-txt-fixer
-    -   id: trailing-whitespace
-    -   id: fix-encoding-pragma
-    -   id: debug-statements
--   repo: https://github.com/asottile/reorder_python_imports
-    sha: v0.3.5
+      - id: pretty-format-json
+        name: 'Pretty format JSON'
+        args:
+          - '--no-sort-keys'
+          - '--autofix'
+          - '--indent=2'
+      - id: trailing-whitespace
+        name: 'Fix trailing whitespace'
+        exclude: setup.cfg
+      - id: end-of-file-fixer
+        name: 'Fix missing EOF'
+        exclude: setup.cfg
+      - id: check-executables-have-shebangs
+        name: 'Check exeutables for shebangs'
+      - id: check-merge-conflict
+        name: 'Check for merge conflict fragments'
+      - id: check-case-conflict
+        name: 'Check for filesystem character case conflicts'
+      - id: detect-private-key
+        name: 'Check for cleartext private keys stored'
+      - id: check-json
+        name: 'Validate JSON'
+      - id: check-ast
+        name: 'Check Python abstract syntax tree'
+  - repo: 'https://github.com/asottile/reorder_python_imports'
+    rev: v1.8.0
     hooks:
-    -   id: reorder-python-imports
-        language_version: python3.7
--   repo: https://github.com/Lucas-C/pre-commit-hooks-safety
-    sha: v1.1.0
+      - id: reorder-python-imports
+        name: 'Reorder Python imports'
+  - repo: 'https://github.com/pre-commit/mirrors-autopep8'
+    rev: ''
     hooks:
-    -   id: python-safety-dependencies-check
--   repo: https://github.com/asottile/add-trailing-comma
-    sha: v0.6.4
+      - id: autopep8
+        name: 'Pretty format Python'
+    args:
+      - '--in-place'
+      - '--aggressive'
+      - '--aggressive'
+      - '--experimental'
+      - '--remove-all-unused-imports'
+      - '--ignore-init-module-imports'
+      - '--remove-unused-variable'
+  - repo: https://github.com/psf/black
+    rev: stable
     hooks:
-    -   id: add-trailing-comma
+    - id: black
+      name: 'Ruthlessly format Python'
+      language_version: python3.7
+      args:
+        - '--line-length=79'

Makefile

@@ -1,22 +1,49 @@
+dev:
+	pipenv install --dev
+
+pipenv:
+	pip install pipenv
+	pipenv install --dev
+
+deploy-patch: clean requirements bumpversion-patch upload clean
+
+deploy-minor: clean requirements bumpversion-minor upload clean
+
+deploy-major: clean requirements bumpversion-major upload clean
+
+requirements:
+	pipenv_to_requirements
+
+bumpversion-patch:
+	bumpversion patch
+	git push
+	git push --tags
+
+bumpversion-minor:
+	bumpversion minor
+	git push
+	git push --tags
+
+bumpversion-major:
+	bumpversion major
+	git push
+	git push --tags
+
+upload:
+	python setup.py sdist bdist_wheel
+	twine upload dist/*
+
 help:
 	@echo "clean - remove all build, test, coverage and Python artifacts"
 	@echo "clean-build - remove build artifacts"
 	@echo "clean-pyc - remove Python file artifacts"
 	@echo "install - install the package to the active Python's site-packages"
 
-pipenv:
+ci:
 	pip install pipenv
-	pipenv install --dev
-
-test:
-	pipenv run flake8 pytube/
-	pipenv run flake8 tests/
-	pipenv run black pytube --check
-	pipenv run black tests --check
-	pipenv run mypy pytube
-	pipenv run pytest --cov-report term-missing --cov=pytube
-
-ci: pipenv test
+	pipenv install --dev --skip-lock
+	pipenv run flake8
+	pipenv run pytest --cov-report term-missing --cov=humps
 
 clean: clean-build clean-pyc
 
@@ -33,27 +60,6 @@ clean-pyc:
 	find . -name '*.pyo' -exec rm -f {} +
 	find . -name '*~' -exec rm -f {} +
 	find . -name '__pycache__' -exec rm -fr {} +
-	find . -name '.pytest_cache' -exec rm -fr {} +
-	find . -name '.mypy_cache' -exec rm -fr {} +
 
 install: clean
 	python setup.py install
-
-package: clean
-	pipenv run python setup.py sdist bdist_wheel
-
-upload:
-	twine upload dist/*
-
-tag:
-	git diff-index --quiet HEAD --  # checks for unstaged/uncomitted files
-	git tag "v`pipenv run python pytube/version.py`"
-	git push --tags
-
-check-master:
-	if [[ `git rev-parse --abbrev-ref HEAD` != "master" ]]; then exit 1; fi
-
-pull:
-	git pull
-
-release: check-master pull clean test tag package upload

README.md

@@ -1,68 +1,74 @@
 
 <div align="center">
+  <p>
+  <img src="https://github.com/nficano/pytube/blob/master/images/pytube.png?raw=true" width="350" height="328" alt="pytube logo" />
+  </p>
   <p align="center">
-	  <a href="https://pypi.org/project/pytube3/"><img src="https://img.shields.io/pypi/v/pytube3.svg" alt="pypi"></a>
-	  <a href="https://pypi.python.org/pypi/pytube3/"><img src="https://img.shields.io/pypi/pyversions/pytube3.svg" /></a>
-	  <a href="https://travis-ci.com/hbmartin/pytube3/"><img src="https://travis-ci.org/hbmartin/pytube3.svg?branch=master" /></a>
-	  <a href='https://pytube3.readthedocs.io/en/latest/?badge=latest'><img src='https://readthedocs.org/projects/pytube3/badge/?version=latest' alt='Documentation Status' /></a>
-	  <a href="https://codecov.io/gh/hbmartin/pytube3"><img src="https://codecov.io/gh/hbmartin/pytube3/branch/master/graph/badge.svg" /></a>
-	  <a href="https://www.codefactor.io/repository/github/hbmartin/pytube3/overview/master"><img src="https://www.codefactor.io/repository/github/hbmartin/pytube3/badge/master" alt="CodeFactor" /></a>
-	  <a href="https://gitter.im/pytube3/community"><img src="https://img.shields.io/badge/chat-gitter-lightgrey" /></a>
+	  <img src="https://img.shields.io/pypi/v/pytube.svg" alt="pypi">
+	  <a href="https://travis-ci.org/nficano/pytube"><img src="https://travis-ci.org/nficano/pytube.svg?branch=master" /></a>
+	  <a href="http://python-pytube.readthedocs.io/en/latest/?badge=latest"><img src="https://readthedocs.org/projects/python-pytube/badge/?version=latest" /></a>
+	  <a href="https://coveralls.io/github/nficano/pytube?branch=master"><img src="https://coveralls.io/repos/github/nficano/pytube/badge.svg?branch=master#23e6f7ac56dd3bde" /></a>
+      <a href="https://pypi.org/project/pytube/"><img src="https://img.shields.io/pypi/dm/pytube.svg" alt="pypi"></a>
+	  <a href="https://pypi.python.org/pypi/pytube/"><img src="https://img.shields.io/pypi/pyversions/pytube.svg" /></a>
+    <p>
   </p>
 </div>
 
-# pytube3
+# pytube
+*pytube* is a very serious, lightweight, dependency-free Python library (and command-line utility) for downloading YouTube Videos.
 
-## Table of Contents
-  * [Installation](#installation)
-  * [Quick start](#quick-start)
-  * [Features](#features)
-  * [Usage](#usage)
-  * [Command-line interface](#command-line-interface)
-  * [Development](#development)
-  * [GUIs and other libraries](#guis-and-other-libraries)
+*pytube* is sponsored by:
+<a href="https://tracking.gitads.io/?repo=pytube/"><img src="https://images.gitads.io/pytube/" alt="GitAds"/></a>
+</p>
 
-## Installation
+## Description
+YouTube is the most popular video-sharing platform in the world and as a hacker you may encounter a situation where you want to script something to download videos.  For this I present to you *pytube*.
 
-Download using pip via pypi.
+*pytube* is a lightweight library written in Python. It has no third party dependencies and aims to be highly reliable.
 
-```bash
-$ pip install pytube3 --upgrade
-```
-(Mac/homebrew users may need to use ``pip3``)
+*pytube* also makes pipelining easy, allowing you to specify callback functions for different download events, such as  ``on progress`` or ``on complete``.
 
+Finally *pytube* also includes a command-line utility, allowing you to quickly download videos right from terminal.
+
+### Behold, a perfect balance of simplicity versus flexibility:
 
-## Quick start
 ```python
- >>> from pytube import YouTube
- >>> YouTube('https://youtu.be/9bZkp7q19f0').streams.get_highest_resolution().download()
- >>>
+ >>> YouTube('https://youtu.be/9bZkp7q19f0').streams.first().download()
  >>> yt = YouTube('http://youtube.com/watch?v=9bZkp7q19f0')
  >>> yt.streams
   ... .filter(progressive=True, file_extension='mp4')
-  ... .order_by('resolution')[-1]
+  ... .order_by('resolution')
+  ... .desc()
+  ... .first()
   ... .download()
 ```
-A GUI frontend for pytube3 is available at [YouTubeDownload](https://github.com/YouTubeDownload/YouTubeDownload)
 
 ## Features
-  * Support for Both Progressive & DASH Streams
-  * Support for downloading complete playlist
-  * Easily Register ``on_download_progress`` & ``on_download_complete`` callbacks
-  * Command-line Interfaced Included
-  * Caption Track Support
-  * Outputs Caption Tracks to .srt format (SubRip Subtitle)
-  * Ability to Capture Thumbnail URL.
-  * Extensively Documented Source Code
-  * No Third-Party Dependencies
-
-## Usage
+- Support for Both Progressive & DASH Streams
+- Support for downloading complete playlist
+- Easily Register ``on_download_progress`` & ``on_download_complete`` callbacks
+- Command-line Interfaced Included
+- Caption Track Support
+- Outputs Caption Tracks to .srt format (SubRip Subtitle)
+- Ability to Capture Thumbnail URL.
+- Extensively Documented Source Code
+- No Third-Party Dependencies
+
+## Installation
+
+Download using pip via pypi.
+
+```bash
+$ pip install pytube
+```
+
+## Getting started
 
 Let's begin with showing how easy it is to download a video with pytube:
 
 ```python
 >>> from pytube import YouTube
->>> YouTube('http://youtube.com/watch?v=9bZkp7q19f0').streams[0].download()
+>>> YouTube('http://youtube.com/watch?v=9bZkp7q19f0').streams.first().download()
 ```
 This example will download the highest quality progressive download stream available.
 
@@ -70,7 +76,7 @@ Next, let's explore how we would view what video streams are available:
 
 ```python
 >>> yt = YouTube('http://youtube.com/watch?v=9bZkp7q19f0')
->>> print(yt.streams)
+>>> yt.streams.all()
  [<Stream: itag="22" mime_type="video/mp4" res="720p" fps="30fps" vcodec="avc1.64001F" acodec="mp4a.40.2">,
  <Stream: itag="43" mime_type="video/webm" res="360p" fps="30fps" vcodec="vp8.0" acodec="vorbis">,
  <Stream: itag="18" mime_type="video/mp4" res="360p" fps="30fps" vcodec="avc1.42001E" acodec="mp4a.40.2">,
@@ -94,9 +100,6 @@ Next, let's explore how we would view what video streams are available:
  <Stream: itag="250" mime_type="audio/webm" abr="70kbps" acodec="opus">,
  <Stream: itag="251" mime_type="audio/webm" abr="160kbps" acodec="opus">]
 ```
-
-### Selecting an itag
-
 You may notice that some streams listed have both a video codec and audio codec, while others have just video or just audio, this is a result of YouTube supporting a streaming technique called Dynamic Adaptive Streaming over HTTP (DASH).
 
 In the context of pytube, the implications are for the highest quality streams; you now need to download both the audio and video tracks and then post-process them with software like FFmpeg to merge them.
@@ -106,7 +109,7 @@ The legacy streams that contain the audio and video in a single file (referred t
 To only view these progressive download streams:
 
 ```python
- >>> yt.streams.filter(progressive=True)
+ >>> yt.streams.filter(progressive=True).all()
   [<Stream: itag="22" mime_type="video/mp4" res="720p" fps="30fps" vcodec="avc1.64001F" acodec="mp4a.40.2">,
   <Stream: itag="43" mime_type="video/webm" res="360p" fps="30fps" vcodec="vp8.0" acodec="vorbis">,
   <Stream: itag="18" mime_type="video/mp4" res="360p" fps="30fps" vcodec="avc1.42001E" acodec="mp4a.40.2">,
@@ -117,7 +120,7 @@ To only view these progressive download streams:
 Conversely, if you only want to see the DASH streams (also referred to as "adaptive") you can do:
 
 ```python
->>> yt.streams.filter(adaptive=True)
+>>> yt.streams.filter(adaptive=True).all()
  [<Stream: itag="137" mime_type="video/mp4" res="1080p" fps="30fps" vcodec="avc1.640028">,
   <Stream: itag="248" mime_type="video/webm" res="1080p" fps="30fps" vcodec="vp9">,
   <Stream: itag="136" mime_type="video/mp4" res="720p" fps="30fps" vcodec="avc1.4d401f">,
@@ -137,26 +140,24 @@ Conversely, if you only want to see the DASH streams (also referred to as "adapt
   <Stream: itag="251" mime_type="audio/webm" abr="160kbps" acodec="opus">]
 ```
 
-### Playlists
-
 You can also download a complete Youtube playlist:
 
 ```python
 >>> from pytube import Playlist
->>> playlist = Playlist("https://www.youtube.com/playlist?list=PLynhp4cZEpTbRs_PYISQ8v_uwO0_mDg_X")
->>> for video in playlist:
->>> 	video.streams.get_highest_resolution().download()
+>>> pl = Playlist("https://www.youtube.com/watch?v=Edpy1szoG80&list=PL153hDY-y1E00uQtCVCVC8xJ25TYX8yPU")
+>>> pl.download_all()
+>>> # or if you want to download in a specific directory
+>>> pl.download_all('/path/to/directory/')
 ```
-This will download the highest progressive stream available (generally 720p) from the given playlist.
-
-### Filtering
+This will download the highest progressive stream available (generally 720p) from the given playlist. Later more options would be given for user's flexibility
+to choose video resolution.
 
 Pytube allows you to filter on every property available (see the documentation for the complete list), let's take a look at some of the most useful ones.
 
 To list the audio only streams:
 
 ```python
->>> yt.streams.filter(only_audio=True)
+>>> yt.streams.filter(only_audio=True).all()
   [<Stream: itag="140" mime_type="audio/mp4" abr="128kbps" acodec="mp4a.40.2">,
   <Stream: itag="171" mime_type="audio/webm" abr="128kbps" acodec="vorbis">,
   <Stream: itag="249" mime_type="audio/webm" abr="50kbps" acodec="opus">,
@@ -167,7 +168,7 @@ To list the audio only streams:
 To list only ``mp4`` streams:
 
 ```python
->>> yt.streams.filter(subtype='mp4')
+>>> yt.streams.filter(subtype='mp4').all()
  [<Stream: itag="22" mime_type="video/mp4" res="720p" fps="30fps" vcodec="avc1.64001F" acodec="mp4a.40.2">,
   <Stream: itag="18" mime_type="video/mp4" res="360p" fps="30fps" vcodec="avc1.42001E" acodec="mp4a.40.2">,
   <Stream: itag="137" mime_type="video/mp4" res="1080p" fps="30fps" vcodec="avc1.640028">,
@@ -182,9 +183,9 @@ To list only ``mp4`` streams:
 Multiple filters can also be specified:
 
 ```python
->>> yt.streams.filter(subtype='mp4', progressive=True)
+>>> yt.streams.filter(subtype='mp4', progressive=True).all()
 >>> # this can also be expressed as:
->>> yt.streams.filter(subtype='mp4').filter(progressive=True)
+>>> yt.streams.filter(subtype='mp4').filter(progressive=True).all()
   [<Stream: itag="22" mime_type="video/mp4" res="720p" fps="30fps" vcodec="avc1.64001F" acodec="mp4a.40.2">,
   <Stream: itag="18" mime_type="video/mp4" res="360p" fps="30fps" vcodec="avc1.42001E" acodec="mp4a.40.2">]
 ```
@@ -198,16 +199,14 @@ You also have an interface to select streams by their itag, without needing to f
 If you need to optimize for a specific feature, such as the "highest resolution" or "lowest average bitrate":
 
 ```python
->>> yt.streams.filter(progressive=True).order_by('resolution').desc()
+>>> yt.streams.filter(progressive=True).order_by('resolution').desc().all()
 ```
-Note: Using ``order_by`` on a given attribute will filter out all streams missing that attribute.
-
-### Callbacks
+Note that ``order_by`` cannot be used if your attribute is undefined in any of the Stream instances, so be sure to apply a filter to remove those before calling it.
 
 If your application requires post-processing logic, pytube allows you to specify an "on download complete" callback function:
 
 ```python
- >>> def convert_to_aac(stream: Stream, file_path: str):
+ >>> def convert_to_aac(stream, file_handle):
          return  # do work
 
  >>> yt.register_on_complete_callback(convert_to_aac)
@@ -216,7 +215,7 @@ If your application requires post-processing logic, pytube allows you to specify
 Similarly, if your application requires on-download progress logic, pytube exposes a callback for this as well:
 
 ```python
- >>> def show_progress_bar(stream: Stream, chunk: bytes, bytes_remaining: int):
+ >>> def show_progress_bar(stream, chunk, file_handle, bytes_remaining):
          return  # do work
 
  >>> yt.register_on_progress_callback(show_progress_bar)
@@ -224,86 +223,17 @@ Similarly, if your application requires on-download progress logic, pytube expos
 
 ## Command-line interface
 
-pytube3 ships with a simple CLI interface for downloading videos, playlists, and captions.
+pytube also ships with a tiny cli interface for downloading and probing videos.
 
 Let's start with downloading:
 
 ```bash
-$ pytube3 http://youtube.com/watch?v=9bZkp7q19f0 --itag=18
+$ pytube http://youtube.com/watch?v=9bZkp7q19f0 --itag=22
 ```
 To view available streams:
 
 ```bash
-$ pytube3 http://youtube.com/watch?v=9bZkp7q19f0 --list
-```
-
-The complete set of flags are:
-
-```
-usage: pytube3 [-h] [--version] [--itag ITAG] [-r RESOLUTION] [-l] [-v]
-               [--build-playback-report] [-c [CAPTION_CODE]] [-t TARGET]
-               [-a [AUDIO]] [-f [FFMPEG]]
-               [url]
-
-Command line application to download youtube videos.
-
-positional arguments:
-  url                   The YouTube /watch or /playlist url
-
-optional arguments:
-  -h, --help            show this help message and exit
-  --version             show program's version number and exit
-  --itag ITAG           The itag for the desired stream
-  -r RESOLUTION, --resolution RESOLUTION
-                        The resolution for the desired stream
-  -l, --list            The list option causes pytube cli to return a list of
-                        streams available to download
-  -v, --verbose         Verbosity level, use up to 4 to increase logging -vvvv
-  --build-playback-report
-                        Save the html and js to disk
-  -c [CAPTION_CODE], --caption-code [CAPTION_CODE]
-                        Download srt captions for given language code. Prints
-                        available language codes if no argument given
-  -t TARGET, --target TARGET
-                        The output directory for the downloaded stream.
-                        Default is current working directory
-  -a [AUDIO], --audio [AUDIO]
-                        Download the audio for a given URL at the highest
-                        bitrate availableDefaults to mp4 format if none is
-                        specified
-  -f [FFMPEG], --ffmpeg [FFMPEG]
-                        Downloads the audio and video stream for resolution
-                        providedIf no resolution is provided, downloads the
-                        best resolutionRuns the command line program ffmpeg to
-                        combine the audio and video
+$ pytube http://youtube.com/watch?v=9bZkp7q19f0 --list
 ```
 
-
-## Development
-
-<a href="https://deepsource.io/gh/hbmartin/pytube3/?ref=repository-badge" target="_blank"><img alt="DeepSource" title="DeepSource" src="https://static.deepsource.io/deepsource-badge-light-mini.svg"></a>
-<a href="https://www.codacy.com/manual/hbmartin/pytube3?utm_source=github.com&amp;utm_medium=referral&amp;utm_content=hbmartin/pytube3&amp;utm_campaign=Badge_Grade"><img src="https://api.codacy.com/project/badge/Grade/53794f06983a46829620b3284c6a5596"/></a>
-<a href="https://github.com/ambv/black"><img src="https://img.shields.io/badge/code%20style-black-000000.svg" /></a>
-
-Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.
-
-To run code checking before a PR use ``make test``
-
-#### Virtual environment
-
-Virtual environment is setup with [pipenv](https://pipenv-fork.readthedocs.io/en/latest/) and can be automatically activated with [direnv](https://direnv.net/docs/installation.html)
-
-#### Code Formatting
-
-This project is linted with [pyflakes](https://github.com/PyCQA/pyflakes), formatted with [black](https://github.com/ambv/black), and typed with [mypy](https://mypy.readthedocs.io/en/latest/introduction.html)
-
-
-#### Code of Conduct
-
-Treat other people with helpfulness, gratitude, and consideration! See the [Python Community Code of Conduct](https://www.python.org/psf/codeofconduct/).
-
-## GUIs and other libraries
-* [YouTubeDownload](https://github.com/YouTubeDownload/YouTubeDownload) - Featured GUI frontend for pytube3
-* [Pytube-GUI](https://github.com/GAO23/Pytube-GUI) - Simple GUI frontend for pytube3
-* [StackOverflow questions](https://stackoverflow.com/questions/tagged/pytube)
-* [PySlackers](https://pyslackers.com/web) - Python Slack group
+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.