Reformat help outputs

Reformatted the help outputs in the swift client to bring them more
in line with the rest of the openstack clients. Changes were added to
all of the st_command_help variables and a new variable
st_command_options was added to help with correct formatting of
help outputs.

Change-Id: I0c549cf96292384ddb36b43ecec41a883d8b2e13
Implements: changes to help outputs

1 files changed, 194 insertions, 70 deletions

diff --git a/bin/swift b/bin/swift
index 35a7675..5398598 100755
--- a/bin/swift
+++ b/bin/swift
@@ -67,13 +67,28 @@ def immediate_exit(signum, frame):
     stderr.write(" Aborted\n")
     os_exit(2)
 
+st_delete_options = '''[-all] [--leave-segments]
+                    [--object-threads <threads>]
+                    [--container-threads <threads>]
+                    <container> <object>
+'''
 
 st_delete_help = '''
-delete [options] --all OR delete container [options] [object] [object] ...
-    Deletes everything in the account (with --all), or everything in a
-    container, or a list of objects depending on the args given. Segments of
-    manifest objects will be deleted as well, unless you specify the
-    --leave-segments option.'''.strip('\n')
+Delete a container or objects within a container
+
+Positional arguments:
+  <container>           Name of container to delete from
+  <object>              Name of object to delete. Specify multiple times
+                        for multiple objects
+
+Optional arguments:
+  --all                 Delete all containers and objects
+  --leave-segments      Do not delete segments of manifest objects
+  --object-threads <threads>
+                        Number of threads to use for deleting objects
+  --container-threads <threads>
+                        Number of threads to use for deleting containers
+'''.strip("\n")
 
 
 def st_delete(parser, args, thread_manager):
@@ -95,8 +110,9 @@ def st_delete(parser, args, thread_manager):
     (options, args) = parse_args(parser, args)
     args = args[1:]
     if (not args and not options.yes_all) or (args and options.yes_all):
-        thread_manager.error('Usage: %s [options] %s',
-                             basename(argv[0]), st_delete_help)
+        thread_manager.error('Usage: %s delete %s\n%s',
+                             basename(argv[0]), st_delete_options,
+                             st_delete_help)
         return
 
     def _delete_segment((container, obj), conn):
@@ -218,17 +234,36 @@ def st_delete(parser, args, thread_manager):
                 for obj in args[1:]:
                     object_queue.put((args[0], obj))
 
+st_download_options = '''[--all] [--marker] [--prefix <prefix>]
+                      [--output <out_file>] [--object-threads <threads>]
+                      [--container-threads <threads>] [--no-download]
+                      <container> <object>
+'''
 
 st_download_help = '''
-download --all [options] OR download container [options] [object] [object] ...
-    Downloads everything in the account (with --all), or everything in all
-    containers in the account matching a prefix (with --all and -p [--prefix]),
-    or everything in a container, or a subset of a container with -p
-    [--prefix], or a list of objects depending on the args given. -p or
-    --prefix is an option that will only download items beginning with that
-    prefix. For a single object download, you may use the -o [--output]
-    <filename> option to redirect the output to a specific file or if "-" then
-    just redirect to stdout.'''.strip('\n')
+Download objects from containers
+
+Positional arguments:
+  <container>           Name of container to download from
+  <object>              Name of object to download. Specify multiple times
+                        for multiple objects
+
+Optional arguments:
+  --all                 Indicates that you really want to download
+                        everything in the account
+  --marker              Marker to use when starting a container or account
+                        download
+  --prefix <prefix>     Only download items beginning with <prefix>
+  --output <out_file>   For a single file download, stream the output to
+                        <out_file>. Specifying "-" as <out_file> will
+                        redirect to stdout
+  --object-threads <threads>
+                        Number of threads to use for downloading objects
+  --container-threads <threads>
+                        Number of threads to use for deleting containers
+  --no-download         Perform download(s), but don't actually write anything
+                        to disk
+'''.strip("\n")
 
 
 def st_download(parser, args, thread_manager):
@@ -263,8 +298,8 @@ def st_download(parser, args, thread_manager):
     if options.out_file and len(args) != 2:
         exit('-o option only allowed for single file downloads')
     if (not args and not options.yes_all) or (args and options.yes_all):
-        thread_manager.error('Usage: %s [options] %s', basename(argv[0]),
-                             st_download_help)
+        thread_manager.error('Usage: %s download %s\n%s', basename(argv[0]),
+                             st_download_options, st_download_help)
         return
 
     def _download_object(queue_arg, conn):
@@ -448,16 +483,23 @@ def prt_bytes(bytes, human_flag):
 
     return(bytes)
 
-
+st_list_options = '''[--long] [--lh] [--totals]
+                  [--container-threads <threads>]
+'''
 st_list_help = '''
-list [options] [container]
-    Lists the containers for the account or the objects for a container. -p or
-    --prefix is an option that will only list items beginning with that prefix.
-    -l produces output formatted like 'ls -l' and --lh like 'ls -lh'.
-    -t used with -l or --lh, only report totals
-    -d or --delimiter is option (for container listings only) that will roll up
-    items with the given delimiter (see http://docs.openstack.org/
-        api/openstack-object-storage/1.0/content/list-objects.html)
+Lists the containers for the account or the objects for a container
+
+Positional arguments:
+  <container>           Name of container to list object in
+
+Optional arguments:
+  --long                Long listing format, similar to ls -l
+  --lh                  Report sizes in human readable format similar to ls -lh
+  --totals              Used with -l or --ls, only report totals
+  --prefix              Only list items beginning with the prefix
+  --delimiter           Roll up items with the given delimiter. For containers
+                        only. See OpenStack Swift API documentation for what
+                        this means.
 '''.strip('\n')
 
 
@@ -470,7 +512,8 @@ def st_list(parser, args, thread_manager):
         "similar to ls -lh switch, but -h taken", action='store_true',
         default=False)
     parser.add_option(
-        '-t', dest='totals', help='used with -l or --ls, only report totals',
+        '-t', '--totals', dest='totals', help='used with -l or --ls, '
+                                              'only report totals',
         action='store_true', default=False)
     parser.add_option(
         '-p', '--prefix', dest='prefix',
@@ -484,8 +527,8 @@ def st_list(parser, args, thread_manager):
     if options.delimiter and not args:
         exit('-d option only allowed for container listings')
     if len(args) > 1 or len(args) == 1 and args[0].find('/') >= 0:
-        thread_manager.error('Usage: %s [options] %s', basename(argv[0]),
-                             st_list_help)
+        thread_manager.error('Usage: %s list %s\n%s', basename(argv[0]),
+                             st_list_options, st_list_help)
         return
 
     conn = get_conn(options)
@@ -559,11 +602,21 @@ def st_list(parser, args, thread_manager):
         else:
             thread_manager.error('Container %r not found', args[0])
 
+st_stat_options = '''[--lh]
+                  <container> <object>
+'''
+
 st_stat_help = '''
-stat [container] [object]
-    Displays information for the account, container, or object depending on the
-    args given (if any). --lh will print number of objects and total sizes
-    like 'list --lh' noting number of objs a multiple of 1024'''.strip('\n')
+Displays information for the account, container, or object
+
+Positional arguments:
+  <container>           Name of container to stat from
+  <object>              Name of object to stat. Specify multiple times
+                        for multiple objects
+
+Optional arguments:
+  --lh                  Report sizes in human readable format similar to ls -lh
+'''.strip('\n')
 
 
 def st_stat(parser, args, thread_manager):
@@ -687,19 +740,38 @@ Write ACL: %s
                 raise
             thread_manager.error("Object %s/%s not found", args[0], args[1])
     else:
-        thread_manager.error('Usage: %s [options] %s', basename(argv[0]),
-                             st_stat_help)
+        thread_manager.error('Usage: %s stat %s\n%s', basename(argv[0]),
+                             st_stat_options, st_stat_help)
+
 
+st_post_options = '''[--read-acl <acl>] [--write-acl <acl>] [--sync-to]
+                  [--sync-key <sync-key>] [--meta <name:value>]
+                  [--header <header>]
+                  <container> <object>
+'''
 
 st_post_help = '''
-post [options] [container] [object]
-    Updates meta information for the account, container, or object depending on
-    the args given. If the container is not found, it will be created
-    automatically; but this is not true for accounts and objects. Containers
-    also allow the -r (or --read-acl) and -w (or --write-acl) options. The -m
-    or --meta option is allowed on all and used to define the user meta data
-    items to set in the form Name:Value. This option can be repeated. Example:
-    post -m Color:Blue -m Size:Large'''.strip('\n')
+Updates meta information for the account, container, or object.
+If the container is not found, it will be created automatically.
+
+Positional arguments:
+  <container>           Name of container to post to
+  <object>              Name of object to post. Specify multiple times
+                        for multiple objects
+
+Optional arguments:
+  --read-acl <acl>      Read ACL for containers. Quick summary of ACL syntax:
+                        .r:*, .r:-.example.com, .r:www.example.com, account1,
+                        account2:user2
+  --write-acl <acl>     Write ACL for containers. Quick summary of ACL syntax:
+                        account1 account2:user2
+  --sync-to <sync-to>   Sync To for containers, for multi-cluster replication
+  --sync-key <sync-key> Sync Key for containers, for multi-cluster replication
+  --meta <name:value>   Sets a meta data item. This option may be repeated.
+                        Example: -m Color:Blue -m Size:Large
+  --header <header>     Set request headers. This option may be repeated.
+                        Example -H "content-type:text/plain"
+'''.strip('\n')
 
 
 def st_post(parser, args, thread_manager):
@@ -724,7 +796,7 @@ def st_post(parser, args, thread_manager):
     parser.add_option(
         '-H', '--header', action='append', dest='header',
         default=[], help='Set request headers with the syntax header:value. '
-        ' This option may be repeated. Example -H content-type:text/plain '
+        ' This option may be repeated. Example -H "content-type:text/plain" '
         '-H "Content-Length: 4000"')
     (options, args) = parse_args(parser, args)
     args = args[1:]
@@ -773,18 +845,49 @@ def st_post(parser, args, thread_manager):
                 raise
             thread_manager.error("Object '%s/%s' not found", args[0], args[1])
     else:
-        thread_manager.error('Usage: %s [options] %s', basename(argv[0]),
-                             st_post_help)
+        thread_manager.error('Usage: %s post %s\n%s', basename(argv[0]),
+                             st_post_options, st_post_help)
 
+st_upload_options = '''[--changed] [--segment-size <size>]
+                    [--segment-container <container>] [--leave-segments]
+                    [--object-threads <thread>] [--segment-threads <threads>]
+                    [--header <header>] [--use-slo]
+                    <container> <file_or_directory>
+'''
 
 st_upload_help = '''
-upload [options] container file_or_directory [file_or_directory] [...]
-    Uploads to the given container the files and directories specified by the
-    remaining args. -c or --changed is an option that will only upload files
-    that have changed since the last upload. -S <size> or --segment-size <size>
-    will upload the files in segments no larger than size. -C <container> or
-    --segment-container <container> will specify the location of the segments
-    to <container>. --leave-segments are options as well (see --help for more).
+Uploads specified files and directories to the given container
+
+Positional arguments:
+  <container>           Name of container to upload to
+  <file_or_directory>   Name of file or directory to upload. Specify multiple
+                        times for multiple uploads
+
+Optional arguments:
+  --changed             Only upload files that have changed since the last
+                        upload
+  --segment-size <size> Upload files in segments no larger than <size> and
+                        then create a "manifest" file that will download all
+                        the segments as if it were the original file
+  --segment-container <container>
+                        Upload the segments into the specified container. If
+                        not specified, the segments will be uploaded to a
+                        <container>_segments container so as to not pollute the
+                        main <container> listings.
+  --leave-segments      Indicates that you want the older segments of manifest
+                        objects left alone (in the case of overwrites)
+  --object-threads <threads>
+                        Number of threads to use for uploading full objects.
+                        Default is 10.
+  --segment-threads <threads>
+                        Number of threads to use for uploading object segments.
+                        Default is 10.
+  --header <header>     Set request headers with the syntax header:value.
+                        This option may be repeated.
+                        Example -H "content-type:text/plain".
+  --use-slo             When used in conjunction with --segment-size will
+                        create a Static Large Object instead of the default
+                        Dynamic Large Object.
 '''.strip('\n')
 
 
@@ -818,17 +921,19 @@ def st_upload(parser, args, thread_manager):
     parser.add_option(
         '-H', '--header', action='append', dest='header',
         default=[], help='Set request headers with the syntax header:value. '
-        ' This option may be repeated. Example -H content-type:text/plain '
+        ' This option may be repeated. Example -H "content-type:text/plain" '
         '-H "Content-Length: 4000"')
-    parser.add_option('', '--use-slo', action='store_true', default=False,
-                      help='When used in conjuction with --segment-size will '
-                      'create a Static Large Object instead of the default '
-                      'Dynamic Large Object.')
+    parser.add_option(
+        '', '--use-slo', action='store_true', default=False,
+        help='When used in conjunction with --segment-size will '
+        'create a Static Large Object instead of the default '
+        'Dynamic Large Object.')
     (options, args) = parse_args(parser, args)
     args = args[1:]
     if len(args) < 2:
         thread_manager.error(
-            'Usage: %s [options] %s', basename(argv[0]), st_upload_help)
+            'Usage: %s upload %s\n%s', basename(argv[0]), st_upload_options,
+            st_upload_help)
         return
 
     def _segment_job(job, conn):
@@ -1160,18 +1265,37 @@ if __name__ == '__main__':
     version = version_info.version_string()
     parser = OptionParser(version='%%prog %s' % version,
                           usage='''
-Usage: %%prog <command> [options] [args]
-
-Commands:
-  %(st_stat_help)s
-  %(st_list_help)s
-  %(st_upload_help)s
-  %(st_post_help)s
-  %(st_download_help)s
-  %(st_delete_help)s
+usage: %%prog [--version] [--help] [--snet] [--verbose]
+             [--debug] [--quiet] [--auth <auth_url>]
+             [--auth-version <auth_version>] [--user <username>]
+             [--key <api_key>] [--retries <num_retries>]
+             [--os-username <auth-user-name>] [--os-password <auth-password>]
+             [--os-tenant-id <auth-tenant-id>]
+             [--os-tenant-name <auth-tenant-name>]
+             [--os-auth-url <auth-url>] [--os-auth-token <auth-token>]
+             [--os-storage-url <storage-url>] [--os-region-name <region-name>]
+             [--os-service-type <service-type>]
+             [--os-endpoint-type <endpoint-type>]
+             [--os-cacert <ca-certificate>] [--insecure]
+             [--no-ssl-compression]
+             <subcommand> ...
+
+Command-line interface to the OpenStack Swift API.
+
+Positional arguments:
+  <subcommand>
+    delete               Delete a container or objects within a container
+    downlad              Download objects from containers
+    list                 Lists the containers for the account or the objects
+                         for a container
+    post                 Updates meta information for the account, container,
+                         or object
+    stat                 Displays information for the account, container,
+                         or object
+    upload               Uploads files or directories to the given container
 
 Examples:
-  %%prog -A https://auth.api.rackspacecloud.com/v1.0 -U user -K key stat -v
+  %%prog -A https://auth.api.rackspacecloud.com/v1.0 -U user -K api_key stat -v
 
   %%prog --os-auth-url https://api.example.com/v2.0 --os-tenant-name tenant \\
       --os-username user --os-password password list