improved help text a lot

flickr_download/filename_handlers.py

@@ -8,10 +8,23 @@
 from __future__ import unicode_literals
 from collections import defaultdict
 
+DEFAULT_HANDLER = 'title'
+"""The default handler if none is specified"""
+
+
+def _get_short_docstring(docstring):
+    """
+    Given a docstring return the first sentence of it.
+
+    @param: docstring: str, the docstring to parsde
+    @return: str, the short docstring
+    """
+    return docstring.split('.')[0].strip()
+
 
 def title(pset, photo, suffix):
     """
-    Name file after title. Falls back to photo id.
+    Name file after title (falls back to photo id).
 
     @param pset: Flickr.Photoset, the photoset
     @param photo: Flickr.Photo, the photo
@@ -26,7 +39,7 @@ def title(pset, photo, suffix):
 
 def idd(pset, photo, suffix):
     """
-    Name file after id
+    Name file after photo id.
 
     @param pset: Flickr.Photoset, the photoset
     @param photo: Flickr.Photo, the photo
@@ -38,7 +51,7 @@ def idd(pset, photo, suffix):
 
 def title_and_id(pset, photo, suffix):
     """
-    Name file after title and photo id
+    Name file after title and photo id.
 
     @param pset: Flickr.Photoset, the photoset
     @param photo: Flickr.Photo, the photo
@@ -57,7 +70,7 @@ def title_and_id(pset, photo, suffix):
 
 def title_increment(pset, photo, suffix):
     """
-    Name file after photo title, but add an incrementing counter on duplicates
+    Name file after photo title, but add an incrementing counter on duplicates.
 
     @param pset: Flickr.Photoset, the photoset
     @param photo: Flickr.Photo, the photo
@@ -83,10 +96,25 @@ def title_increment(pset, photo, suffix):
 }
 
 
-def get_filename_handler(name='title'):
+def get_filename_handler(name):
     """
     Returns the given filename handler as a function
     @param name: str, name of the handler to return
     @return: Function, handler
     """
-    return HANDLERS[name]
+    return HANDLERS[name or DEFAULT_HANDLER]
+
+
+def get_filename_handler_help():
+    """
+    Returns a description of each handler to be used for help output.
+
+    @return: str, help text
+    """
+    ret = []
+    for name, func in HANDLERS.iteritems():
+        ret.append('  {handler} - {doc}{default}'
+                   .format(handler=name,
+                           doc=_get_short_docstring(func.__doc__),
+                           default=(' (DEFAULT)' if name == DEFAULT_HANDLER else '')))
+    return 'Naming modes:\n' + '\n'.join(ret)

flickr_download/flick_download.py

@@ -20,6 +20,7 @@
 import yaml
 
 from flickr_download.filename_handlers import get_filename_handler
+from flickr_download.filename_handlers import get_filename_handler_help
 from flickr_download.utils import get_full_path
 
 CONFIG_FILE = "~/.flickr_download"
@@ -154,7 +155,26 @@ def print_sets(username):
 
 
 def main():
-    parser = argparse.ArgumentParser('Download a Flickr Set')
+    parser = argparse.ArgumentParser(
+        formatter_class=argparse.RawTextHelpFormatter,
+        description='Downloads one or more Flickr photo sets.\n'
+        '\n'
+        'To use it you need to get your own Flickr API key here:\n'
+        'https://www.flickr.com/services/api/misc.api_keys.html\n'
+        '\n'
+        'For more information see:\n'
+        'https://github.com/beaufour/flickr-download',
+        epilog='examples:\n'
+        '  list all sets for a user:\n'
+        '  > {app} -k <api_key> -s <api_secret> -l beaufour\n'
+        '\n'
+        '  download a given set:\n'
+        '  > {app} -k <api_key> -s <api_secret> -d 72157622764287329\n'
+        '\n'
+        '  download a given set, keeping duplicate names:\n'
+        '  > {app} -k <api_key> -s <api_secret> -d 72157622764287329 -n title_increment\n'
+        .format(app=sys.argv[0])
+    )
     parser.add_argument('-k', '--api_key', type=str,
                         help='Flickr API key')
     parser.add_argument('-s', '--api_secret', type=str,
@@ -170,11 +190,17 @@ def main():
     parser.add_argument('-q', '--quality', type=str, metavar='SIZE_LABEL',
                         default=None, help='Quality of the picture')
     parser.add_argument('-n', '--naming', type=str, metavar='NAMING_MODE',
-                        default='title', help='Photo naming mode')
+                        help='Photo naming mode')
+    parser.add_argument('-m', '--list_naming', action='store_true',
+                        help='List naming modes')
     parser.set_defaults(**_load_defaults())
 
     args = parser.parse_args()
 
+    if args.list_naming:
+        print(get_filename_handler_help())
+        return 1
+
     if not args.api_key or not args.api_secret:
         print ('You need to pass in both "api_key" and "api_secret" arguments', file=sys.stderr)
         return 1
@@ -185,7 +211,9 @@ def main():
 
     if args.list:
         print_sets(args.list)
-    elif args.download or args.download_user:
+        return 0
+
+    if args.download or args.download_user:
         try:
             get_filename = get_filename_handler(args.naming)
             if args.download:
@@ -194,10 +222,11 @@ def main():
                 download_user(args.download_user, get_filename, args.quality)
         except KeyboardInterrupt:
             print('Forcefully aborting. Last photo download might be partial :(', file=sys.stderr)
-    else:
-        print('ERROR: Must pass either --list or --download\n', file=sys.stderr)
-        parser.print_help()
-        return 1
+        return 0
+
+    print('ERROR: Must pass either --list or --download\n', file=sys.stderr)
+    parser.print_help()
+    return 1
 
 if __name__ == '__main__':
     sys.exit(main())