From 8aea7ef3509629c7528e58f9bd987f4e7c8ba46a Mon Sep 17 00:00:00 2001 From: Dominik Lindner Date: Fri, 23 Jul 2021 11:53:25 +0100 Subject: [PATCH 1/3] Update CLI import option documentation --- omero/downloads/cli/help.out | 172 +++++++++++++++++++++++++++-------- omero/users/cli/import.rst | 25 ++++- 2 files changed, 156 insertions(+), 41 deletions(-) diff --git a/omero/downloads/cli/help.out b/omero/downloads/cli/help.out index 854bb6c508..9b86dd6b9d 100644 --- a/omero/downloads/cli/help.out +++ b/omero/downloads/cli/help.out @@ -1,49 +1,141 @@ -Import any number of files into an OMERO instance. -If "-" is the only path, a list of files or directories -is read from standard in. Directories will be searched for -all valid imports. - -Session arguments: - Mandatory arguments for creating a session are 1- either the OMERO server hostname, -username and password or 2- the OMERO server hostname and a valid session key. - -s SERVER OMERO server hostname - -u USER OMERO username - -w PASSWORD OMERO password - -k KEY OMERO session key (UUID of an active session) - -p PORT OMERO server port (default: 4064) +Run the Java-based command-line importer + +This is a Python wrapper around the Java importer. Login is handled by Python +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 +"--". + +Bulk imports: + +Rather than passing one or more files to the import command, a single +dictionary-like file (e.g. yml or json) can be passed to the `--bulk` +argument. Most keys in the bulk file will be treated like additional +command-line arguments. Special keys include: + + * columns A list of columns for parsing the value of path + * continue Like the "-c" changes error handling + * dry_run If true, print out additional arguments rather than run them. + If another string other than false, use as a template for + storing the import commands. (e.g. /tmp/%s.sh) + * include Relative path (from the bulk file) of a parent bulk file + * path A file which will be parsed line by line based on its file + ending. Lines containing zero or more keys along with a + single file to be imported. Options for formats include: + - .tsv and .csv files will be parsed by the existing library + - other files will be parsed with shlex + - unless no columns are specified, in which case each line + is treated as a file + +Optional Arguments: + In addition to any higher level options + + -h, --help show this help message and exit + --javahelp, --java-help Show the Java help text + +Login arguments: + Environment variables: + + OMERO_USERDIR Set the base directory containing the user's files. + Default: $HOME/omero + OMERO_SESSIONDIR Set the base directory containing local sessions. + Default: $OMERO_USERDIR/sessions + OMERO_TMPDIR Set the base directory containing temporary files. + Default: $OMERO_USERDIR/tmp + OMERO_PASSWORD Set the user's password for creating new sessions. + Ignored if -w or --password is used. + + + Optional session arguments: + + -C, --create Create a new session regardless of existing ones + -s SERVER, --server SERVER OMERO server hostname + -p PORT, --port PORT OMERO server port + -g GROUP, --group GROUP OMERO server default group + -u USER, --user USER OMERO username + -w PASSWORD, --password PASSWORD OMERO password + -k KEY, --key KEY OMERO session key (UUID of an active session) + --sudo ADMINUSER Create session as this admin. Changes meaning of password! + -q, --quiet Quiet mode. Causes most warning and diagnostic messages to be suppressed. + +Python arguments: + Optional arguments which are used to configure import. + + --bulk [BULK] Bulk YAML file for driving multiple imports + --logprefix [LOGPREFIX] Directory or file prefix for --file and --errs + --file [FILE] File for storing the standard output from the Java process + --errs [ERRS] File for storing the standard error from the Java process + --clientdir CLIENTDIR Path to the directory containing the client JARs. Default: lib/client + --logback LOGBACK Path to a logback xml file. Default: etc/logback-cli.xml + --fetch-jars FETCH_JARS Download this version of OMERO.java jars and exit + --depth DEPTH Number of directories to scan down for files + --skip {all,checksum,minmax,thumbnails,upgrade} + Optional step to skip during import + path Path to be passed to the Java process Naming arguments: -All naming arguments are optional - -n NAME Image or plate name to use - -x DESCRIPTION Image or plate description to use - --name NAME Image or plate name to use - --description DESCRIPTION Image or plate description to use - -Optional arguments: - -h Display this help and exit - -f Display the used files and exit - -c Continue importing after errors - -l READER_FILE Use the list of readers rather than the default - -d DATASET_ID OMERO dataset ID to import image into - -r SCREEN_ID OMERO screen ID to import plate into - -T TARGET target for imports - --report Report errors to the OME team - --upload Upload broken files and log file (if any) with report. Required --report - --logs Upload log file (if any) with report. Required --report - --email EMAIL Email for reported errors. Required --report - --debug LEVEL Turn debug logging on (optional level) - --annotation-ns ANNOTATION_NS Namespace to use for subsequent annotation - --annotation-text ANNOTATION_TEXT Content for a text annotation - --annotation-link ANNOTATION_LINK Comment annotation ID to link all images to + Optional arguments passed strictly to Java. + + -n NAME, --name NAME Image or plate name to use (**) + -x DESCRIPTION, --description DESCRIPTION + Image or plate description to use (**) + +Feedback arguments: + Optional arguments passed strictly to Java allowing to report errors to the OME team. + + --report Report errors to the OME team (**) + --upload Upload broken files and log file (if any) with report. Required --report (**) + --logs Upload log file (if any) with report. Required --report (**) + --email EMAIL Email for reported errors. Required --report (**) + +Annotation arguments: + Optional arguments passed strictly to Java allowing to annotate imports. + + --annotation-ns ANNOTATION_NS Namespace to use for subsequent annotation (**) + --annotation-text ANNOTATION_TEXT Content for a text annotation (**) + --annotation-link ANNOTATION_LINK Comment annotation ID to link all images to (**) + +Java arguments: + Optional arguments passed strictly to Java. + + -f Display the used files and exit (**) + -c Continue importing after errors (**) + -l READER_FILE, --readers READER_FILE + Use the list of readers rather than the default (**) + -d DATASET_ID OMERO dataset ID to import image into (**) + -r SCREEN_ID OMERO screen ID to import plate into (**) + -T TARGET, --target TARGET OMERO target specification (**) + --debug LEVEL Turn debug logging on (**) + --output TYPE Set an alternative output style + --encrypted TYPE Whether the import should use SSL or not + +Advanced Java arguments: + Optional arguments passed strictly to Java. For more information, see --advanced-help. + + --advanced-help Show the advanced help text + --transfer [TYPE] Transfer methods like in-place import + --exclude [TYPE] Exclusion filters for preventing re-import + --checksum-algorithm [TYPE] Alternative hashing mechanisms balancing speed & accuracy + --parallel-upload COUNT Number of file upload threads to run at the same time + --parallel-fileset COUNT Number of fileset candidates to import at the same time Examples: - $ importer-cli -s localhost -u user -w password -d 50 foo.tiff - $ importer-cli -s localhost -u user -w password -d Dataset:50 foo.tiff - $ importer-cli -f foo.tiff - $ importer-cli -s localhost -u username -w password -d 50 --debug ALL foo.tiff + # Display help + $ omero import -h + # Import foo.tiff using current login + $ omero import ~/Data/my_file.dv + # Import foo.tiff using input credentials + $ omero import -s localhost -u user -w password foo.tiff + # Set Java debugging level to ALL + $ omero import foo.tiff -- --debug=ALL + # Display used files for importing foo.tiff + $ omero import foo.tiff -f + # Limit debugging output + $ omero import -- --debug=ERROR foo.tiff For additional information, see: https://docs.openmicroscopy.org/latest/omero/users/cli/import.html -Report bugs at https://www.openmicroscopy.org/forums +Report bugs to \ No newline at end of file diff --git a/omero/users/cli/import.rst b/omero/users/cli/import.rst index 0b9cf0dbd4..b824654aa1 100644 --- a/omero/users/cli/import.rst +++ b/omero/users/cli/import.rst @@ -40,7 +40,7 @@ Some of the options available to the import command are: $ omero import -s SERVER -p PORT -u USER -g GROUP image.tif -.. option:: -d DATASET_ID, -T TARGET, --target TARGET +.. option:: -d DATASET_ID, -r SCREEN_ID, -T TARGET, --target TARGET To import images into a Dataset:: @@ -50,6 +50,29 @@ Some of the options available to the import command are: See :doc:`import-target` for more information on import targets. + --logprefix [LOGPREFIX] Directory or file prefix for --file and --errs + --file [FILE] File for storing the standard output from the Java process + --errs [ERRS] File for storing the standard error from the Java process + +.. option:: --file FILE + + File for storing the standard output from the Java process + +.. option:: --errs FILE + + File for storing the standard error from the Java process + +.. option:: --logprefix DIR + + Directory or file prefix for --file and --errs + +.. option:: --output TYPE + + Set an alternative output style, for example:: + + $ omero import --output=yaml ... + + Scanning folders prior to Import ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ From 5463813f7e3297a4ad0ae3f1a76104059e7dde0b Mon Sep 17 00:00:00 2001 From: Dominik Lindner Date: Fri, 30 Jul 2021 09:00:24 +0100 Subject: [PATCH 2/3] Point to image.sc forum --- omero/downloads/cli/help.out | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/omero/downloads/cli/help.out b/omero/downloads/cli/help.out index 9b86dd6b9d..5013c9cc89 100644 --- a/omero/downloads/cli/help.out +++ b/omero/downloads/cli/help.out @@ -138,4 +138,4 @@ Examples: For additional information, see: https://docs.openmicroscopy.org/latest/omero/users/cli/import.html -Report bugs to \ No newline at end of file +Report bugs at https://forum.image.sc/ From 06b56259c8cdcbd50e35fb0833ab38dac63d5893 Mon Sep 17 00:00:00 2001 From: Jean-Marie Burel Date: Fri, 3 Dec 2021 13:47:43 +0000 Subject: [PATCH 3/3] use image.sc tag --- omero/downloads/cli/help.out | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/omero/downloads/cli/help.out b/omero/downloads/cli/help.out index 5013c9cc89..bbc56ef35b 100644 --- a/omero/downloads/cli/help.out +++ b/omero/downloads/cli/help.out @@ -138,4 +138,4 @@ Examples: For additional information, see: https://docs.openmicroscopy.org/latest/omero/users/cli/import.html -Report bugs at https://forum.image.sc/ +Report bugs at https://forum.image.sc/tag/omero-cli