Permalink
Browse files

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

Unify command-line importer help (rebased onto develop)
  • Loading branch information...
2 parents 6d2c73b + 4c897b7 commit e6901a72eff06b12ab2c187f281a319cff7355b8 @sbesson sbesson committed Mar 12, 2014
@@ -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);
}
@@ -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));
@@ -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__"):
@@ -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:])
@@ -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)

0 comments on commit e6901a7

Please sign in to comment.