hrm_omero.cli

  1"""Command-line interface related functions."""
  2
  3import argparse
  4import os
  5import sys
  6
  7import omero.gateway
  8
  9from loguru import logger as log
 10
 11from .__init__ import __version__
 12from . import formatting
 13from . import hrm
 14from . import omero as _omero
 15from . import transfer
 16from .misc import printlog
 17
 18
 19def bool_to_exitstatus(value):
 20    """Convert a boolean to a POSIX process exit code.
 21
 22    As boolean values in Python are a subset of int, `True` corresponds to the int value
 23    '1', which is the opposite of a successful POSIX return code. Therefore, this
 24    function simply inverts the boolean value to turn it into a proper exit code. In
 25    case the provided value is not of type `bool` it will be returned unchanged.
 26
 27    Parameters
 28    ----------
 29    value : bool or int
 30        The value to be converted.
 31
 32    Returns
 33    -------
 34    int
 35        0 in case `value` is `True`, 1 in case `value` is `False` and `value` itself in
 36        case it is not a bool.
 37    """
 38    if isinstance(value, bool):
 39        return not value
 40
 41    return value
 42
 43
 44def arguments_parser():
 45    """Set up the commandline arguments parser.
 46
 47    Returns
 48    -------
 49    argparse.ArgumentParser
 50        The parser instance ready to be run using its `parse_args()` method.
 51    """
 52    # log.debug("Parsing command line arguments...")
 53    argparser = argparse.ArgumentParser(
 54        description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter
 55    )
 56    argparser.add_argument(
 57        "-v",
 58        "--verbose",
 59        dest="verbosity",
 60        action="count",
 61        default=0,
 62        help="verbose messages (repeat for more details)",
 63    )
 64
 65    argparser.add_argument(
 66        "--version",
 67        action="version",
 68        version=f"%(prog)s {__version__}",
 69    )
 70
 71    argparser.add_argument(
 72        "-c",
 73        "--config",
 74        default="/etc/hrm.conf",
 75        help="the HRM configuration file (default: '/etc/hrm.conf')",
 76    )
 77
 78    argparser.add_argument(
 79        "--dry-run",
 80        action="store_true",
 81        default=False,
 82        help="print requested action and parameters without actually performing it",
 83    )
 84
 85    # required arguments group
 86    req_args = argparser.add_argument_group(
 87        "required arguments", "NOTE: MUST be given before any subcommand!"
 88    )
 89    req_args.add_argument("-u", "--user", required=True, help="OMERO username")
 90
 91    subparsers = argparser.add_subparsers(
 92        help=".",
 93        dest="action",
 94        description="Action to be performed, one of the following:",
 95    )
 96
 97    # checkCredentials parser
 98    subparsers.add_parser(
 99        "checkCredentials", help="check if login credentials are valid"
100    )
101
102    # retrieveChildren parser
103    parser_subtree = subparsers.add_parser(
104        "retrieveChildren", help="get the children of a given node object (JSON)"
105    )
106    parser_subtree.add_argument(
107        "--id",
108        type=str,
109        required=True,
110        help='ID of the parent object, e.g. "ROOT", "G:4:Experimenter:7',
111    )
112
113    # OMEROtoHRM parser
114    parser_o2h = subparsers.add_parser(
115        "OMEROtoHRM", help="download an image from the OMERO server"
116    )
117    parser_o2h.add_argument(
118        "-i",
119        "--imageid",
120        required=True,
121        help='the OMERO ID of the image to download, e.g. "G:4:Image:42"',
122    )
123    parser_o2h.add_argument(
124        "-d",
125        "--dest",
126        type=str,
127        required=True,
128        help="the destination directory where to put the downloaded file",
129    )
130
131    # HRMtoOMERO parser
132    parser_h2o = subparsers.add_parser(
133        "HRMtoOMERO", help="upload an image to the OMERO server"
134    )
135    parser_h2o.add_argument(
136        "-d",
137        "--dset",
138        required=True,
139        dest="dset",
140        help='the ID of the target dataset in OMERO, e.g. "G:7:Dataset:23"',
141    )
142    parser_h2o.add_argument(
143        "-f",
144        "--file",
145        type=str,
146        required=True,
147        help="the image file to upload, including the full path",
148    )
149    parser_h2o.add_argument(
150        "-n",
151        "--name",
152        type=str,
153        required=False,
154        help="a label to use for the image in OMERO",
155    )
156    parser_h2o.add_argument(
157        "-a",
158        "--ann",
159        type=str,
160        required=False,
161        help="annotation text to be added to the image in OMERO",
162    )
163
164    return argparser
165
166
167def verbosity_to_loglevel(verbosity):
168    """Map the verbosity count to a named log level for `loguru`.
169
170    Parameters
171    ----------
172    verbosity : int
173        Verbosity count as returned e.g. by the following argparse code:
174        `argparser.add_argument("-v", dest="verbosity", action="count", default=0)`
175
176    Returns
177    -------
178    str
179        A log level name that can be used with `loguru.logger.add()`.
180    """
181    log_level = "WARNING"  # no verbosity flag has been provided -> use "WARNING"
182    if verbosity > 3:  # -vvvv (4) and more will result in "TRACE"
183        log_level = "TRACE"
184    if verbosity == 3:  # -vvv will be "DEBUG"
185        log_level = "DEBUG"
186    elif verbosity == 2:  # -vv will be "INFO"
187        log_level = "INFO"
188    elif verbosity == 1:  # -v will be "SUCCESS"
189        log_level = "SUCCESS"
190    return log_level
191
192
193def logger_add_file_sink(hrm_config, target=""):
194    """Helper to add a file sink to the logger unless disabled in the config file.
195
196    By default logging messages from the connector into a separate file is desired, so
197    this function will try to add a file sink by default. Only if the HRM configuration
198    file explicitly asks for no log file to be created it will skip this step.
199
200    Parameters
201    ----------
202    hrm_config : dict
203        A parsed HRM configuration file as returned by `hrm_omero.hrm.parse_config()`.
204    target : str, optional
205        The path for the log file to be used. If empty (or skipped) the default
206        `$HRM_LOG/omero-connector.log` will be used, falling back to
207        `HRM_LOG="/var/log/hrm"` in case `$HRM_LOG` is not set in the hrm configuration.
208    """
209    disable_file_logging = hrm_config.get("OMERO_CONNECTOR_LOGFILE_DISABLED", "")
210    if disable_file_logging:
211        return
212
213    if not target:
214        log_base = hrm_config.get("HRM_LOG", "/var/log/hrm")
215        target = f"{log_base}/omero-connector.log"
216
217    log_level = hrm_config.get("OMERO_CONNECTOR_LOGLEVEL", "INFO")
218    try:
219        log.add(target, level=log_level)
220        log.trace(f"Added file sink for logging: {target}.")
221    except Exception as err:  # pylint: disable-msg=broad-except
222        log.error(f"Adding a file sink for logging failed: {err}")
223
224
225def run_task(args):
226    """Parse commandline arguments and initiate the requested tasks."""
227    argparser = arguments_parser()
228    args = argparser.parse_args(args)
229
230    # one of the downsides of loguru is that the level of an existing logger can't be
231    # changed - so to adjust verbosity we actually need to remove the default logger and
232    # re-add it with the new level (see https://github.com/Delgan/loguru/issues/138)
233    log_level = verbosity_to_loglevel(args.verbosity)
234    log.remove()
235    log.add(sys.stderr, level=log_level)
236
237    log.success(f"Logging verbosity requested: {args.verbosity} ({log_level})")
238
239    hrm_config = hrm.parse_config(args.config)
240    host = hrm_config.get("OMERO_HOSTNAME", "localhost")
241    port = hrm_config.get("OMERO_PORT", 4064)
242    omero_logfile = hrm_config.get("OMERO_DEBUG_LOG", "")
243
244    log_level = hrm_config.get("OMERO_CONNECTOR_LOGLEVEL")
245    if log_level:
246        log.remove()
247        log.add(sys.stderr, level=log_level)
248        log.success(f"Log level set from config file: {log_level}")
249
250    logger_add_file_sink(hrm_config)
251
252    # NOTE: reading the OMERO password from an environment variable instead of an
253    # argument supplied on the command line improves handling of this sensitive data as
254    # the value is *NOT* immediately revealed to anyone with shell access by simply
255    # looking at the process list (which is an absolute standard procedure to do). Since
256    # it is not passed to any other functions here (except the call to `BlitzGateway`)
257    # this also prevents it from being shown in an annotated stack trace in case an
258    # uncaught exception is coming through.
259    # However, this doesn't provide super-high security as it will still be possible for
260    # an admin to inspect the environment of a running process. Nevertheless going
261    # beyond this seems a bit pointless here as an admin could also modify the code that
262    # is actually calling the connector to get hold of user credentials.
263    passwd = os.environ.get("OMERO_PASSWORD")
264    if not passwd:
265        printlog("ERROR", "ERROR: no password given to connect to OMERO!")
266        return False
267
268    if args.action == "checkCredentials":
269        log.trace("checkCredentials")
270        perform_action = _omero.check_credentials
271        kwargs = {}
272
273    elif args.action == "retrieveChildren":
274        log.trace("retrieveChildren")
275        perform_action = formatting.print_children_json
276        kwargs = {"omero_id": args.id}
277
278    elif args.action == "OMEROtoHRM":
279        log.trace("OMEROtoHRM")
280        perform_action = transfer.from_omero
281        kwargs = {
282            "omero_id": args.imageid,
283            "dest": args.dest,
284        }
285
286    elif args.action == "HRMtoOMERO":
287        log.trace("HRMtoOMERO")
288        perform_action = transfer.to_omero
289        kwargs = {
290            "omero_id": args.dset,
291            "image_file": args.file,
292            "omero_logfile": omero_logfile,
293        }
294
295    else:
296        printlog("ERROR", "No valid action specified that should be performed!")
297        return False
298
299    conn = omero.gateway.BlitzGateway(
300        username=args.user,
301        passwd=passwd,
302        host=host,
303        port=port,
304        secure=True,
305        useragent="hrm-omero.py",
306    )
307
308    try:
309        if args.dry_run:
310            printlog("INFO", "*** dry-run, only showing action and parameters ***")
311            printlog("INFO", f"function: {perform_action.__qualname__}")
312            for key, value in kwargs.items():
313                printlog("INFO", f"{key}: [{str(value)}]")
314
315            return True
316
317        return perform_action(conn, **kwargs)
318
319    except Exception as err:  # pylint: disable-msg=broad-except  # pragma: no cover
320        log.error(f"An unforeseen error occured: {err}")
321        return False
322    finally:
323        conn.close()
324        log.info(f"Closed OMERO connection [user={args.user}].")
325
326
327@log.catch
328def main(args=None):
329    """Wrapper to call the run_task() function and return its exit code."""
330    if not args:
331        args = sys.argv[1:]
332    sys.exit(bool_to_exitstatus(run_task(args)))