Merge pull request #2154 from sbesson/rebased/develop/12010_cli_usage

Unify command-line importer help (rebased onto develop)

components/blitz/src/ome/formats/importer/cli/CommandLineImporter.java

@@ -264,56 +264,59 @@ public void cleanup() {
      * Prints usage to STDERR and exits with return code 1.
      */
     public static void usage() {
-        System.err
-                .println(String
-                        .format(
-                                "\n"
-                                        + " Usage:  %s [OPTION]... [DIR|FILE]... \n"
-                                        + "   or:   %s [OPTION]... - \n"
-                                        + "\n"
-                                        + "Import any number of files into an OMERO instance.\n"
-                                        + "If \"-\" is the only path, a list of files or directories \n"
-                                        + "is read from standard in. Directories will be searched for \n"
-                                        + "all valid imports.\n"
-                                        + "\n"
-                                        + "Mandatory arguments:\n"
-                                        + "  -s\tOMERO server hostname\n"
-                                        + "  -u\tOMERO experimenter name (username)\n"
-                                        + "  -w\tOMERO experimenter password\n"
-                                        + "  -k\tOMERO session key (can be used in place of -u and -w)\n"
-                                        + "  -f\tDisplay the used files (does not require other mandatory arguments)\n"
-                                        + "\n"
-                                        + "Naming arguments:\n"
-                                        + "(All are optional but only image OR plate values should be set)\n"
-                                        + "  -n\tImage name to use\n"
-                                        + "  -x\tImage description to use\n"
-                                        + "  --plate_name\t\tPlate name to use\n"
-                                        + "  --plate_description\tPlate description to use\n"
-                                        + "\n"
-                                        + "Optional arguments:\n"
-                                        + "  -c\tContinue importing after errors\n"
-                                        + "  -l\tUse the list of readers rather than the default\n"
-                                        + "  -d\tOMERO dataset Id to import image into\n"
-                                        + "  -r\tOMERO screen Id to import plate into\n"
-                                        + "  -p\tOMERO server port [defaults to 4064]\n"
-                                        + "  -h\tDisplay this help and exit\n"
-                                        + "\n"
-                                        + "  --no_thumbnails\tDo not perform thumbnailing after import\n"
-                                        + "  --plate_name\t\tPlate name to use\n"
-                                        + "  --plate_description\tPlate description to use\n"
-                                        + "  --debug[ALL|DEBUG|ERROR|FATAL|INFO|TRACE|WARN]\tTurn debug logging on (optional level)\n"
-                                        + "  --report\t\tReport errors to the OME team\n"
-                                        + "  --upload\t\tUpload broken files with report\n"
-                                        + "  --logs\t\tUpload log file with report\n"
-                                        + "  --email\t\tEmail for reported errors\n"
-                                        + "  --annotation_ns\tNamespace to use for subsequent annotation\n"
-                                        + "  --annotation_text\tContent for a text annotation (requires namespace)\n"
-                                        + "  --annotation_link\tComment annotation ID to link all images to\n"
-                                        + "\n"
-                                        + "ex. %s -s localhost -u bart -w simpson -d 50 foo.tiff\n"
-                                        + "\n"
-                                        + "Report bugs to <ome-users@lists.openmicroscopy.org.uk>",
-                                APP_NAME, APP_NAME, APP_NAME));
+        System.err.println(String.format("\n"
+            + " Usage:  %s [OPTION]... [path [path ...]]... \n"
+            + "   or:   %s [OPTION]... - \n"
+            + "\n"
+            + "Import any number of files into an OMERO instance.\n"
+            + "If \"-\" is the only path, a list of files or directories \n"
+            + "is read from standard in. Directories will be searched for \n"
+            + "all valid imports.\n"
+            + "\n"
+            + "Session arguments:\n"
+            + "  Mandatory arguments for creating a session are 1- either the OMERO server hostname,\n"
+            + "username and password or 2- the OMERO server hostname and a valid session key.\n"
+            + "  -s SERVER\tOMERO server hostname\n"
+            + "  -u USER\tOMERO username\n"
+            + "  -w PASSWORD\tOMERO password\n"
+            + "  -k KEY\tOMERO session key (UUID of an active session)\n"
+            + "  -p PORT\tOMERO server port (default: 4064)\n"
+            + "\n"
+            + "Naming arguments:\n"
+            + "All naming arguments are optional but only image OR plate values should be set\n"
+            + "  -n NAME\t\t\t\tImage name to use\n"
+            + "  -x DESCRIPTION\t\t\tImage description to use\n"
+            + "  --plate_name NAME\t\t\tPlate name to use\n"
+            + "  --plate_description DESCRIPTION\tPlate description to use\n"
+            + "\n"
+            + "Optional arguments:\n"
+            + "  -h\t\t\t\t\tDisplay this help and exit\n"
+            + "  -f\t\t\t\t\tDisplay the used files and exit\n"
+            + "  -c\t\t\t\t\tContinue importing after errors\n"
+            + "  -l READER_FILE\t\t\tUse the list of readers rather than the default\n"
+            + "  -d DATASET_ID\t\t\t\tOMERO dataset ID to import image into\n"
+            + "  -r SCREEN_ID\t\t\t\tOMERO screen ID to import plate into\n"
+
+            + "  --report\t\t\t\tReport errors to the OME team\n"
+            + "  --upload\t\t\t\tUpload broken files with report\n"
+            + "  --logs\t\t\t\tUpload log file with report\n"
+            + "  --email EMAIL\t\t\t\tEmail for reported errors\n"
+            + "  --debug LEVEL\t\t\t\tTurn debug logging on (optional level)\n"
+            + "  --annotation_ns ANNOTATION_NS\t\tNamespace to use for subsequent annotation\n"
+            + "  --annotation_text ANNOTATION_TEXT\tContent for a text annotation (requires namespace)\n"
+            + "  --annotation_link ANNOTATION_LINK\tComment annotation ID to link all images to\n"
+            + "  --no_thumbnails\t\t\tDo not perform thumbnailing after import\n"
+            + "\n"
+            + "Examples:\n"
+            + "\n"
+            + "  $ %s -s localhost -u user -w password -d 50 foo.tiff\n"
+            + "  $ %s -f foo.tiff\n"
+            + "  $ %s -s localhost -u username -w password -d 50 --debug ALL foo.tiff\n"
+            + "\n"
+            + "For additional information, see:\n"
+            + "http://www.openmicroscopy.org/site/support/omero5/users/command-line-import.html\n"
+            + "Report bugs to <ome-users@lists.openmicroscopy.org.uk>",
+            APP_NAME, APP_NAME, APP_NAME, APP_NAME, APP_NAME));
         System.exit(1);
     }
 

components/blitz/test/ome/formats/test/util/TestEngine.java

@@ -263,18 +263,18 @@ public static void usage()
                 "\n" +
                 "Optional arguments:\n" +
                 "  -s\tOMERO server hostname\n" +
-                "  -u\tOMERO experimenter name (username)\n" +
-                "  -w\tOMERO experimenter password\n" +
+                "  -u\tOMERO username\n" +
+                "  -w\tOMERO password\n" +
                 "  -k\tOMERO session key (can be used in place of -u and -w)\n" +
-                "  -p\tOMERO server port [defaults to 4064]\n" +
+                "  -p\tOMERO server port [default: 4064]\n" +
                 "  -e\tRaise error on given situation: any, minimal, never [defaults to any]\n" +
-                "  -f\tOMERO feedback url [defaults to %s]\n" +
+                "  -f\tOMERO feedback url [default: %s]\n" +
                 "  -c\tConfiguration file location (instead of any of the above arguments)\n" +
                 "  -x\tPopulate initiation files with metadata [defaults to False]\n" +
                 "  -h, --help\tDisplay this help and exit\n" +
                 "  --no-recurse\tSingle directory test run\n" +
                 "\n" +
-                "ex. %s -s localhost -u bart -w simpson ShortRunImages\n" +
+                "ex. %s -s localhost -u username -w password ShortRunImages\n" +
                 "\n" +
                 "Report bugs to <ome-users@lists.openmicroscopy.org.uk>",
                 APP_NAME, TestEngineConfig.DEFAULT_FEEDBACK, APP_NAME));

components/tools/OmeroPy/src/omero/cli.py

@@ -166,16 +166,16 @@ def add_login_arguments(self):
         group.add_argument("-C", "--create", action = "store_true",
             help = "Create a new session regardless of existing ones")
         group.add_argument("-s", "--server",
-            help = "Hostname of the OMERO server")
+            help = "OMERO server hostname")
         group.add_argument("-p", "--port",
-            help = "Port of the OMERO server")
+            help = "OMERO server port")
         group.add_argument("-g", "--group",
             help = "OMERO server default group")
         group.add_argument("-u", "--user",
-            help = "OMERO server login username")
+            help = "OMERO username")
         group.add_argument("-w", "--password",
-            help = "OMERO server login password")
-        group.add_argument("-k", "--key", help = "UUID of an active session")
+            help = "OMERO password")
+        group.add_argument("-k", "--key", help = "OMERO session key (UUID of an active session)")
 
     def _check_value(self, action, value):
         # converted value must be one of the choices (if specified)
@@ -1070,16 +1070,16 @@ def close(self):
     ## Plugin registry
     ##
 
-    def register(self, name, Control, help):
-        self.register_only(name, Control, help)
+    def register(self, name, Control, help, epilog=None):
+        self.register_only(name, Control, help, epilog=epilog)
         self.configure_plugins()
 
-    def register_only(self, name, Control, help):
+    def register_only(self, name, Control, help, epilog=None):
         """ This method is added to the globals when execfile() is
         called on each plugin. A Control class should be
         passed to the register method which will be added to the CLI.
         """
-        self.controls[name] = (Control, help)
+        self.controls[name] = (Control, help, epilog)
 
     def configure_plugins(self):
         """
@@ -1091,11 +1091,13 @@ def configure_plugins(self):
             if isinstance(control, tuple):
                 Control = control[0]
                 help = control[1]
+                epilog = control[2]
                 control = Control(ctx = self, dir = self.dir)
                 self.controls[name] = control
                 setattr(self, "complete_%s" % name, control._complete)
                 parser = self.subparsers.add_parser(name, help=help)
                 parser.description = help
+                parser.epilog = epilog
                 if hasattr(control, "_configure"):
                     control._configure(parser)
                 elif hasattr(control, "__call__"):

components/tools/OmeroPy/src/omero/plugins/import.py

@@ -19,17 +19,30 @@
 HELP = """Run the Java-based command-line importer
 
 This is a Python wrapper around the Java importer. Login is handled by Python
-OmeroCli. To see more options, use "--javahelp".
+OMERO.cli. To see more options, use "--javahelp".
 
 Options marked with "**" are passed strictly to Java. If they interfere with
 any of the Python arguments, you may need to end precede your arguments with a
 "--".
-
+"""
+EXAMPLES = """
 Examples:
 
-  bin/omero import ~/Data/my_file.dv                    # Use current login
-  bin/omero import -- --debug=ALL ~/Data/my_file2.png   # Set Java debug
-
+  # Display help
+  $ bin/omero import -h
+  # Import foo.tiff using current login
+  $ bin/omero import ~/Data/my_file.dv
+  # Import foo.tiff using input credentials
+  $ bin/omero import -s localhost -u user -w password foo.tiff
+  # Set Java debugging level to ALL
+  $ bin/omero import foo.tiff -- --debug=ALL
+  # Display used files for importing foo.tiff
+  $ bin/omero import foo.tiff -f
+
+For additional information, see:
+http://www.openmicroscopy.org/site/support/omero5/users/\
+command-line-import.html
+Report bugs to <ome-users@lists.openmicroscopy.org.uk>
 """
 TESTHELP = """Run the Importer TestEngine suite (devs-only)"""
 
@@ -39,6 +52,8 @@ class ImportControl(BaseControl):
     COMMAND = [START_CLASS]
 
     def _configure(self, parser):
+        parser.add_login_arguments()
+
         parser.add_argument(
             "--javahelp", action="store_true", help="Show the Java help text")
         parser.add_argument(
@@ -48,66 +63,78 @@ def _configure(self, parser):
             "---errs", nargs="?",
             help="File for storing the standard err of the Java process")
         # The following arguments are strictly passed to Java
-        parser.add_argument(
+        name_group = parser.add_argument_group(
+            'Naming arguments', 'Optional arguments passed strictly to Java. '
+            'Only image OR plate arguments should be set')
+        name_group.add_argument(
+            "-n", dest="java_n",
+            help="Image name to use (**)",
+            metavar="IMAGE_NAME")
+        name_group.add_argument(
+            "-x", dest="java_x",
+            help="Image description to use (**)",
+            metavar="IMAGE_DESCRIPTION")
+        name_group.add_argument(
+            "--plate_name", dest="java_plate_name",
+            help="Plate name to use (**)",
+            metavar="PLATE_NAME")
+        name_group.add_argument(
+            "--plate_description", dest="java_plate_description",
+            help="Plate description to use (**)",
+            metavar="PLATE_DESCRIPTION")
+
+        java_group = parser.add_argument_group(
+            'Java arguments', 'Optional arguments passed strictly to Java')
+        java_group.add_argument(
             "-f", dest="java_f", action="store_true",
-            help="Display used files (**)")
-        parser.add_argument(
+            help="Display the used files and exit (**)")
+        java_group.add_argument(
             "-c", dest="java_c", action="store_true",
             help="Continue importing after errors (**)")
-        parser.add_argument(
+        java_group.add_argument(
             "-l", dest="java_l",
             help="Use the list of readers rather than the default (**)",
             metavar="READER_FILE")
-        parser.add_argument(
+        java_group.add_argument(
             "-d", dest="java_d",
-            help="OMERO dataset Id to import image into (**)",
+            help="OMERO dataset ID to import image into (**)",
             metavar="DATASET_ID")
-        parser.add_argument(
+        java_group.add_argument(
             "-r", dest="java_r",
-            help="OMERO screen Id to import plate into (**)",
+            help="OMERO screen ID to import plate into (**)",
             metavar="SCREEN_ID")
-        parser.add_argument(
-            "-n", dest="java_n",
-            help="Image name to use (**)",
-            metavar="NAME")
-        parser.add_argument(
-            "-x", dest="java_x",
-            help="Image description to use (**)",
-            metavar="DESCRIPTION")
-        parser.add_argument(
+        java_group.add_argument(
             "--report", action="store_true", dest="java_report",
             help="Report errors to the OME team (**)")
-        parser.add_argument(
+        java_group.add_argument(
             "--upload", action="store_true", dest="java_upload",
             help="Upload broken files with report (**)")
-        parser.add_argument(
+        java_group.add_argument(
             "--logs", action="store_true", dest="java_logs",
             help="Upload log file with report (**)")
-        parser.add_argument(
+        java_group.add_argument(
             "--email", dest="java_email",
             help="Email for reported errors (**)", metavar="EMAIL")
-        parser.add_argument(
+        java_group.add_argument(
             "--debug", dest="java_debug",
-            help="Turn debug logging on (**; must be preceded by '--')",
+            help="Turn debug logging on (**)",
             choices=["ALL", "DEBUG", "ERROR", "FATAL", "INFO", "TRACE",
                      "WARN"],
             metavar="LEVEL")
-
-        parser.add_argument(
-            "--annotation_ns", dest="java_ns",
-            help="Namespace to use for subsequent annotation")
-        parser.add_argument(
-            "--annotation_text", dest="java_text",
-            help="Content for a text annotation (requires namespace)")
-        parser.add_argument(
-            "--annotation_link", dest="java_link",
-            help="Comment annotation ID to link all images to")
-
-        parser.add_argument(
-            "arg", nargs="*",
-            help="Arguments to be passed to the Java process")
+        java_group.add_argument(
+            "--annotation_ns", dest="java_ns", metavar="ANNOTATION_NS",
+            help="Namespace to use for subsequent annotation (**)")
+        java_group.add_argument(
+            "--annotation_text", dest="java_text", metavar="ANNOTATION_TEXT",
+            help="Content for a text annotation (requires namespace) (**)")
+        java_group.add_argument(
+            "--annotation_link", dest="java_link", metavar="ANNOTATION_LINK",
+            help="Comment annotation ID to link all images to (**)")
+
+        parser.add_argument(
+            "path", nargs="*",
+            help="Path to be passed to the Java process")
         parser.set_defaults(func=self.importer)
-        parser.add_login_arguments()
 
     def importer(self, args):
 
@@ -154,6 +181,8 @@ def importer(self, args):
             "java_r": "-r",
             "java_n": "-n",
             "java_x": "-x",
+            "java_plate_name": "--plate_name",
+            "java_plate_description": "--plate_description",
             "java_report": "--report",
             "java_upload": "--upload",
             "java_logs": "--logs",
@@ -171,7 +200,7 @@ def importer(self, args):
                 if isinstance(arg_value, (str, unicode)):
                     login_args.append(arg_value)
 
-        a = self.COMMAND + login_args + args.arg
+        a = self.COMMAND + login_args + args.path
         p = omero.java.popen(
             a, debug=False, xargs=xargs, stdout=out, stderr=err)
         self.ctx.rv = p.wait()
@@ -181,11 +210,11 @@ class TestEngine(ImportControl):
     COMMAND = [TEST_CLASS]
 
 try:
-    register("import", ImportControl, HELP)
+    register("import", ImportControl, HELP, epilog=EXAMPLES)
     register("testengine", TestEngine, TESTHELP)
 except NameError:
     if __name__ == "__main__":
         cli = CLI()
-        cli.register("import", ImportControl, HELP)
+        cli.register("import", ImportControl, HELP, epilog=EXAMPLES)
         cli.register("testengine", TestEngine, TESTHELP)
         cli.invoke(sys.argv[1:])

components/tools/OmeroPy/test/unit/clitest/test_import.py

@@ -20,7 +20,7 @@
 pluginDir = rootDir / "src" / "omero" / "plugins"
 
 
-def register(key, klass, help):
+def register(key, klass, help, epilog=None):
     map[key] = klass
 loc = {"register": register}
 execfile(str(pluginDir/"import.py"), loc)