Improve program documentation
[youtube-dl] / youtube-dl
index d3f2771101aa0bb0b0811ce08d02ec89a9468035..46d45d37d95630d5fd742ee16d182530a3dcb34f 100755 (executable)
@@ -17,7 +17,7 @@ import urllib
 import urllib2
 
 std_headers = {        
-       'User-Agent': 'UserAgent: Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US; rv:1.9) Gecko/2008052906 Firefox/3.0',
+       'User-Agent': 'Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US; rv:1.9.0.1) Gecko/2008070208 Firefox/3.0.1',
        'Accept-Charset': 'ISO-8859-1,utf-8;q=0.7,*;q=0.7',
        'Accept': 'text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5',
        'Accept-Language': 'en-us,en;q=0.5',
@@ -55,15 +55,19 @@ class FileDownloader(object):
        password:       Password for authentication purposes.
        usenetrc:       Use netrc for authentication instead.
        quiet:          Do not print messages to stdout.
+       forceurl:       Force printing final URL.
+       forcetitle:     Force printing title.
        simulate:       Do not download the video files.
        format:         Video format code.
        outtmpl:        Template for output names.
+       ignoreerrors:   Do not stop on download errors.
        """
 
        _params = None
        _ies = []
 
        def __init__(self, params):
+               """Create a FileDownloader object with the given options."""
                self._ies = []
                self.set_params(params)
        
@@ -152,9 +156,32 @@ class FileDownloader(object):
        def to_stderr(self, message):
                """Print message to stderr."""
                sys.stderr.write('%s\n' % message)
+       
+       def fixed_template(self):
+               """Checks if the output template is fixed."""
+               return (re.search(ur'(?u)%\(.+?\)s', self._params['outtmpl']) is None)
+
+       def trouble(self, message=None):
+               """Determine action to take when a download problem appears.
+
+               Depending on if the downloader has been configured to ignore
+               download errors or not, this method may exit the program or
+               not when errors are found, after printing the message. If it
+               doesn't exit, it returns an error code suitable to be returned
+               later as a program exit code to indicate error.
+               """
+               if message is not None:
+                       self.to_stderr(message)
+               if not self._params.get('ignoreerrors', False):
+                       sys.exit(1)
+               return 1
 
        def download(self, url_list):
                """Download a given list of URLs."""
+               retcode = 0
+               if len(url_list) > 1 and self.fixed_template():
+                       sys.exit('ERROR: fixed output name but more than one file to download')
+
                for url in url_list:
                        suitable_found = False
                        for ie in self._ies:
@@ -162,42 +189,55 @@ class FileDownloader(object):
                                        continue
                                # Suitable InfoExtractor found
                                suitable_found = True
-                               results = [x for x in ie.extract(url) if x is not None]
+                               all_results = ie.extract(url)
+                               results = [x for x in all_results if x is not None]
+                               if len(results) != len(all_results):
+                                       retcode = self.trouble()
 
-                               if (len(url_list) > 1 or len(results) > 1) and re.search(r'%\(.+?\)s', self._params['outtmpl']) is None:
+                               if len(results) > 1 and self.fixed_template():
                                        sys.exit('ERROR: fixed output name but more than one file to download')
 
-                               if self._params.get('simulate', False):
-                                       continue
-
                                for result in results:
+
+                                       # Forced printings
+                                       if self._params.get('forcetitle', False):
+                                               print result['title']
+                                       if self._params.get('forceurl', False):
+                                               print result['url']
+                                               
+                                       # Do nothing else if in simulate mode
+                                       if self._params.get('simulate', False):
+                                               continue
+
                                        try:
                                                filename = self._params['outtmpl'] % result
                                        except (ValueError, KeyError), err:
-                                               self.to_stderr('ERROR: invalid output template: %s' % str(err))
+                                               retcode = self.trouble('ERROR: invalid output template: %s' % str(err))
                                                continue
                                        try:
                                                self.pmkdir(filename)
                                        except (OSError, IOError), err:
-                                               self.to_stderr('ERROR: unable to create directories: %s' % str(err))
+                                               retcode = self.trouble('ERROR: unable to create directories: %s' % str(err))
                                                continue
                                        try:
                                                outstream = open(filename, 'wb')
                                        except (OSError, IOError), err:
-                                               self.to_stderr('ERROR: unable to open for writing: %s' % str(err))
+                                               retcode = self.trouble('ERROR: unable to open for writing: %s' % str(err))
                                                continue
                                        try:
                                                self._do_download(outstream, result['url'])
                                                outstream.close()
                                        except (OSError, IOError), err:
-                                               self.to_stderr('ERROR: unable to write video data: %s' % str(err))
+                                               retcode = self.trouble('ERROR: unable to write video data: %s' % str(err))
                                                continue
                                        except (urllib2.URLError, httplib.HTTPException, socket.error), err:
-                                               self.to_stderr('ERROR: unable to download video data: %s' % str(err))
+                                               retcode = self.trouble('ERROR: unable to download video data: %s' % str(err))
                                                continue
                                break
                        if not suitable_found:
-                               self.to_stderr('ERROR: no suitable InfoExtractor: %s' % url)
+                               retcode = self.trouble('ERROR: no suitable InfoExtractor: %s' % url)
+
+               return retcode
        
        def _do_download(self, stream, url):
                request = urllib2.Request(url, None, std_headers)
@@ -266,7 +306,7 @@ class InfoExtractor(object):
                return True
 
        def initialize(self):
-               """Initializes an instance (login, etc)."""
+               """Initializes an instance (authentication, etc)."""
                if not self._ready:
                        self._real_initialize()
                        self._ready = True
@@ -281,10 +321,12 @@ class InfoExtractor(object):
                self._downloader = downloader
        
        def to_stdout(self, message):
+               """Print message to stdout if downloader is not in quiet mode."""
                if self._downloader is None or not self._downloader.get_params().get('quiet', False):
                        print message
        
        def to_stderr(self, message):
+               """Print message to stderr."""
                sys.stderr.write('%s\n' % message)
 
        def _real_initialize(self):
@@ -342,10 +384,10 @@ class YoutubeIE(InfoExtractor):
                        self.to_stdout('[youtube] Logging in')
                        login_results = urllib2.urlopen(request).read()
                        if re.search(r'(?i)<form[^>]* name="loginForm"', login_results) is not None:
-                               self.to_stderr('WARNING: Unable to log in: bad username or password')
+                               self.to_stderr('WARNING: unable to log in: bad username or password')
                                return
                except (urllib2.URLError, httplib.HTTPException, socket.error), err:
-                       self.to_stderr('WARNING: Unable to log in: %s' % str(err))
+                       self.to_stderr('WARNING: unable to log in: %s' % str(err))
                        return
        
                # Confirm age
@@ -358,13 +400,13 @@ class YoutubeIE(InfoExtractor):
                        self.to_stdout('[youtube] Confirming age')
                        age_results = urllib2.urlopen(request).read()
                except (urllib2.URLError, httplib.HTTPException, socket.error), err:
-                       sys.exit('ERROR: Unable to confirm age: %s' % str(err))
+                       sys.exit('ERROR: unable to confirm age: %s' % str(err))
 
        def _real_extract(self, url):
                # Extract video id from URL
                mobj = re.match(r'^((?:http://)?(?:\w+\.)?youtube\.com/(?:(?:v/)|(?:(?:watch(?:\.php)?)?\?(?:.+&)?v=)))?([0-9A-Za-z_-]+)(?(1).+)?$', url)
                if mobj is None:
-                       self.to_stderr('ERROR: Invalid URL: %s' % url)
+                       self.to_stderr('ERROR: invalid URL: %s' % url)
                        return [None]
                video_id = mobj.group(2)
 
@@ -375,7 +417,7 @@ class YoutubeIE(InfoExtractor):
                        format_param = params.get('format', None)
 
                # Extension
-               video_extension = {18: 'mp4'}.get(format_param, 'flv')
+               video_extension = {'18': 'mp4'}.get(format_param, 'flv')
 
                # Normalize URL, including format
                normalized_url = 'http://www.youtube.com/watch?v=%s' % video_id
@@ -386,13 +428,13 @@ class YoutubeIE(InfoExtractor):
                        self.to_stdout('[youtube] %s: Downloading video webpage' % video_id)
                        video_webpage = urllib2.urlopen(request).read()
                except (urllib2.URLError, httplib.HTTPException, socket.error), err:
-                       sys.exit('ERROR: Unable to download video: %s' % str(err))
+                       sys.exit('ERROR: unable to download video: %s' % str(err))
                self.to_stdout('[youtube] %s: Extracting video information' % video_id)
                
                # "t" param
                mobj = re.search(r', "t": "([^"]+)"', video_webpage)
                if mobj is None:
-                       self.to_stderr('ERROR: Unable to extract "t" parameter')
+                       self.to_stderr('ERROR: unable to extract "t" parameter')
                        return [None]
                video_real_url = 'http://www.youtube.com/get_video?video_id=%s&t=%s' % (video_id, mobj.group(1))
                if format_param is not None:
@@ -402,21 +444,22 @@ class YoutubeIE(InfoExtractor):
                # uploader
                mobj = re.search(r'More From: ([^<]*)<', video_webpage)
                if mobj is None:
-                       self.to_stderr('ERROR: Unable to extract uploader nickname')
+                       self.to_stderr('ERROR: unable to extract uploader nickname')
                        return [None]
                video_uploader = mobj.group(1)
 
                # title
                mobj = re.search(r'(?im)<title>YouTube - ([^<]*)</title>', video_webpage)
                if mobj is None:
-                       self.to_stderr('ERROR: Unable to extract video title')
+                       self.to_stderr('ERROR: unable to extract video title')
                        return [None]
                video_title = mobj.group(1).decode('utf-8')
-               video_title = re.sub(u'&(.+?);', lambda x: unichr(htmlentitydefs.name2codepoint[x.group(1)]), video_title)
+               video_title = re.sub(ur'(?u)&(.+?);', lambda x: unichr(htmlentitydefs.name2codepoint[x.group(1)]), video_title)
+               video_title = video_title.replace(os.sep, u'%')
 
                # simplified title
-               simple_title = re.sub(u'([^%s]+)' % simple_title_chars, u'_', video_title)
-               simple_title = simple_title.strip(u'_')
+               simple_title = re.sub(ur'(?u)([^%s]+)' % simple_title_chars, ur'_', video_title)
+               simple_title = simple_title.strip(ur'_')
 
                # Return information
                return [{
@@ -430,29 +473,89 @@ class YoutubeIE(InfoExtractor):
 
 if __name__ == '__main__':
        try:
+               # Modules needed only when running the main program
+               import getpass
+               import optparse
+
                # General configuration
                urllib2.install_opener(urllib2.build_opener(urllib2.ProxyHandler()))
                urllib2.install_opener(urllib2.build_opener(urllib2.HTTPCookieProcessor()))
+               socket.setdefaulttimeout(300) # 5 minutes should be enough (famous last words)
+
+               # Parse command line
+               parser = optparse.OptionParser(
+                               usage='Usage: %prog [options] url...',
+                               version='INTERNAL',
+                               conflict_handler='resolve',
+                               )
+               parser.add_option('-h', '--help',
+                               action='help', help='print this help text and exit')
+               parser.add_option('-v', '--version',
+                               action='version', help='print program version and exit')
+               parser.add_option('-u', '--username',
+                               dest='username', metavar='UN', help='account username')
+               parser.add_option('-p', '--password',
+                               dest='password', metavar='PW', help='account password')
+               parser.add_option('-o', '--output',
+                               dest='outtmpl', metavar='TPL', help='output filename template')
+               parser.add_option('-q', '--quiet',
+                               action='store_true', dest='quiet', help='activates quiet mode', default=False)
+               parser.add_option('-s', '--simulate',
+                               action='store_true', dest='simulate', help='do not download video', default=False)
+               parser.add_option('-t', '--title',
+                               action='store_true', dest='usetitle', help='use title in file name', default=False)
+               parser.add_option('-l', '--literal',
+                               action='store_true', dest='useliteral', help='use literal title in file name', default=False)
+               parser.add_option('-n', '--netrc',
+                               action='store_true', dest='usenetrc', help='use .netrc authentication data', default=False)
+               parser.add_option('-g', '--get-url',
+                               action='store_true', dest='geturl', help='simulate, quiet but print URL', default=False)
+               parser.add_option('-e', '--get-title',
+                               action='store_true', dest='gettitle', help='simulate, quiet but print title', default=False)
+               parser.add_option('-f', '--format',
+                               dest='format', metavar='FMT', help='video format code')
+               parser.add_option('-b', '--best-quality',
+                               action='store_const', dest='video_format', help='alias for -f 18', const='18')
+               parser.add_option('-i', '--ignore-errors',
+                               action='store_true', dest='ignoreerrors', help='continue on download errors', default=False)
+               (opts, args) = parser.parse_args()
+
+               # Conflicting, missing and erroneous options
+               if len(args) < 1:
+                       sys.exit('ERROR: you must provide at least one URL')
+               if opts.usenetrc and (opts.username is not None or opts.password is not None):
+                       sys.exit('ERROR: using .netrc conflicts with giving username/password')
+               if opts.password is not None and opts.username is None:
+                       sys.exit('ERROR: account username missing')
+               if opts.outtmpl is not None and (opts.useliteral or opts.usetitle):
+                       sys.exit('ERROR: using output template conflicts with using title or literal title')
+               if opts.usetitle and opts.useliteral:
+                       sys.exit('ERROR: using title conflicts with using literal title')
+               if opts.username is not None and opts.password is None:
+                       opts.password = getpass.getpass('Type account password and press return:')
 
                # Information extractors
                youtube_ie = YoutubeIE()
 
                # File downloader
                fd = FileDownloader({
-                       'usenetrc': False,
-                       'username': None,
-                       'password': None,
-                       'quiet': False,
-                       'simulate': False,
-                       'format': None,
-                       'outtmpl': '%(ext)s/%(ext)s/%(id)s.%(ext)s'
+                       'usenetrc': opts.usenetrc,
+                       'username': opts.username,
+                       'password': opts.password,
+                       'quiet': (opts.quiet or opts.geturl or opts.gettitle),
+                       'forceurl': opts.geturl,
+                       'forcetitle': opts.gettitle,
+                       'simulate': (opts.simulate or opts.geturl or opts.gettitle),
+                       'format': opts.format,
+                       'outtmpl': ((opts.outtmpl is not None and opts.outtmpl)
+                               or (opts.usetitle and '%(stitle)s-%(id)s.%(ext)s')
+                               or (opts.useliteral and '%(title)s-%(id)s.%(ext)s')
+                               or '%(id)s.%(ext)s'),
+                       'ignoreerrors': opts.ignoreerrors,
                        })
                fd.add_info_extractor(youtube_ie)
-               fd.download([
-                       'http://www.youtube.com/watch?v=t7qdwI7TVe8',
-                       'http://www.youtube.com/watch?v=IJyn3pRcy_Q',
-                       'http://www.youtube.com/watch?v=DZRXe1wtC-M',
-                       ])
+               retcode = fd.download(args)
+               sys.exit(retcode)
 
        except KeyboardInterrupt:
                sys.exit('\nERROR: Interrupted by user')