From a5a929cc1e216a48ea5f4be7b758bd5ef301906c Mon Sep 17 00:00:00 2001 From: MrS0m30n3 Date: Mon, 22 Dec 2014 01:13:03 +0200 Subject: [PATCH] Update docstrings downloaders.py --- youtube_dl_gui/downloaders.py | 157 +++++++++++++++++++++++----------- 1 file changed, 108 insertions(+), 49 deletions(-) diff --git a/youtube_dl_gui/downloaders.py b/youtube_dl_gui/downloaders.py index 420bb7f..c3c89e3 100644 --- a/youtube_dl_gui/downloaders.py +++ b/youtube_dl_gui/downloaders.py @@ -1,6 +1,16 @@ #!/usr/bin/env python2 -''' Python module to download videos using youtube-dl & subprocess. ''' +"""Python module to download videos. + +This module contains the actual downloaders responsible +for downloading the video files. It's more like a driver module +that connects the youtubedlg with different 3rd party (or not) downloaders. + +Note: + downloaders.py is part of the youtubedlg package but it can be used + as a stand alone driver module for downloading videos. + +""" import os import sys @@ -10,41 +20,26 @@ import subprocess class YoutubeDLDownloader(object): - ''' - OUT_OF_DATE - Download videos using youtube-dl & subprocess. - - Params - youtubedl_path: Absolute path of youtube-dl. - data_hook: Can be any function with one parameter, the data. - log_manager: Can be any log_manager which implements log(). - - Accessible Methods - download() - Params: URL to download - Options list e.g. ['--help'] - - Return: DownlaodObject.OK - YoutubeDLDownloader.ERROR - YoutubeDLDownloader.STOPPED - YoutubeDLDownloader.ALREADY - stop() - Params: None - - Return: None - - Data_hook Keys - 'playlist_index', - 'playlist_size', - 'filesize', - 'filename', - 'percent', - 'status', - 'speed', - 'eta' - ''' - - # download() return codes + """Python class for downloading videos using youtube-dl & subprocess. + + Attributes: + OK, ERROR, STOPPED, ALREADY, FILESIZE_ABORT (int): 'Random' integers + that describe the return code from the download() method. + + Args: + youtubedl_path (string): Absolute path to youtube-dl binary. + + data_hook (function): Optional callback function to retrieve download + process data. + + log_manager (logmanager.LogManager): Object responsible for writing + errors to the log. + + Note: + For available data keys check self._data under __init__() + + """ + OK = 0 ERROR = 1 STOPPED = 2 @@ -70,9 +65,24 @@ class YoutubeDLDownloader(object): } def download(self, url, options): - ''' Download given url using youtube-dl & - return self._return_code. - ''' + """Download url using given options. + + Args: + url (string): URL string to download. + options (list): Python list that contains youtube-dl options. + + Returns: + An integer that shows the status of the download process. + Right now we support 5 different return codes. + + OK (0): The download process completed successfully. + ERROR (1): An error occured during the download process. + STOPPED (2): The download process was stopped from the user. + ALREADY (3): The given url is already downloaded. + FILESIZE_ABORT (4): The corresponding url video file was larger or + smaller from the given options filesize limit. + + """ self._reset() cmd = self._get_cmd(url, options) @@ -94,12 +104,13 @@ class YoutubeDLDownloader(object): return self._return_code def stop(self): - ''' Stop downloading. ''' + """Stop the download process and set return code to STOPPED. """ if self._proc_is_alive(): self._proc.kill() self._return_code = self.STOPPED def _last_data_hook(self): + """Set the last data information based on the return code. """ if self._return_code == self.OK: self._data['status'] = 'Finished' elif self._return_code == self.ERROR: @@ -118,6 +129,7 @@ class YoutubeDLDownloader(object): self._hook_data() def _reset(self): + """Reset the data. """ self._return_code = 0 self._data = { 'playlist_index': None, @@ -131,7 +143,14 @@ class YoutubeDLDownloader(object): } def _sync_data(self, data): - ''' Synchronise self._data with data. ''' + """ Synchronise self._data with data. It also filters some keys. + + Args: + data (dictionary): Python dictionary that contains different + keys. The keys are not standar the dictionary can also be + empty when there are no data to extract. See extract_data(). + + """ for key in data: if key == 'filename': # Keep only the filename on data['filename'] @@ -153,24 +172,35 @@ class YoutubeDLDownloader(object): self._data[key] = data[key] def _log(self, data): - ''' Log data using self.log_manager. ''' + """Log data using log_manager. + + Args: + data (string): String to write in the log file. + + """ if self.log_manager is not None: self.log_manager.log(data) def _hook_data(self): - ''' Pass self._data back to data_hook. ''' + """Pass self._data back to data_hook. """ if self.data_hook is not None: self.data_hook(self._data) def _proc_is_alive(self): - ''' Return True if self._proc is alive. ''' + """Return True if self._proc is alive. Else False. """ if self._proc is None: return False return self._proc.poll() is None def _read(self): - ''' Read subprocess stdout, stderr. ''' + """Read subprocess stdout, stderr. + + Returns: + Python tuple that contains the STDOUT string and + the STDERR string. + + """ stdout = stderr = '' stdout = self._read_stream(self._proc.stdout) @@ -181,14 +211,29 @@ class YoutubeDLDownloader(object): return stdout, stderr def _read_stream(self, stream): - ''' Read subprocess stream. ''' + """Read subprocess stream. + + Args: + stream (subprocess.PIPE): Subprocess pipe. Can be either STDOUT + or STDERR. + + """ if self._proc is None: return '' return stream.readline().rstrip() def _get_cmd(self, url, options): - ''' Return command for subprocess. ''' + """Build the subprocess command. + + Args: + url (string): URL string to download. + options (list): Python list that contains youtube-dl options. + + Returns: + Python list that contains the command to execute. + + """ if os.name == 'nt': cmd = [self.youtubedl_path] + options + [url] else: @@ -197,7 +242,12 @@ class YoutubeDLDownloader(object): return cmd def _create_process(self, cmd): - ''' Create new subprocess. ''' + """Create new subprocess. + + Args: + cmd (list): Python list that contains the command to execute. + + """ encoding = info = None # Hide subprocess window on Windows @@ -224,7 +274,16 @@ class YoutubeDLDownloader(object): def extract_data(stdout): - ''' Extract data from youtube-dl stdout. ''' + """Extract data from youtube-dl stdout. + + Args: + stdout (string): String that contains the youtube-dl stdout. + + Returns: + Python dictionary. For available keys check self._data under + YoutubeDLDownloader.__init__(). + + """ data_dictionary = dict() if not stdout: