# -*- coding: utf-8 -*-
"""
:mod:`orion.core.cli` -- Base class and function utilities for cli
==================================================================
.. module:: cli
:platform: Unix
:synopsis: Orion main parser class and helper functions to parse command-line options
"""
import argparse
import logging
import sys
import textwrap
import orion
from orion.core.io.database import DatabaseError
from orion.core.utils.exceptions import (
BranchingEvent, InexecutableUserScript, MissingResultFile, NoConfigurationError, NoNameError)
CLI_DOC_HEADER = "Oríon CLI for asynchronous distributed optimization"
[docs]class OrionArgsParser:
"""Parser object handling the upper-level parsing of Oríon's arguments."""
def __init__(self, description=CLI_DOC_HEADER):
"""Create the pre-command arguments"""
self.description = description
self.parser = argparse.ArgumentParser(
formatter_class=argparse.RawDescriptionHelpFormatter,
description=textwrap.dedent(description))
self.parser.add_argument(
'-V', '--version',
action='version', version='orion ' + orion.core.__version__)
self.parser.add_argument(
'-v', '--verbose',
action='count', default=0,
help="logging levels of information about the process (-v: INFO. -vv: DEBUG)")
self.parser.add_argument(
'-d', '--debug', action='store_true',
help="Use debugging mode with EphemeralDB.")
self.subparsers = self.parser.add_subparsers(dest='command')
[docs] def get_subparsers(self):
"""Return the subparser object for this parser."""
return self.subparsers
[docs] def parse(self, argv):
"""Call argparse and generate a dictionary of arguments' value"""
args = vars(self.parser.parse_args(argv))
verbose = args.pop('verbose', 0)
levels = {0: logging.WARNING,
1: logging.INFO,
2: logging.DEBUG}
logging.basicConfig(level=levels.get(verbose, logging.DEBUG))
if args['command'] is None:
self.parser.parse_args(['--help'])
function = args.pop('func', None)
empty_command = (argv[-1] if argv else sys.argv[-1]) == args['command']
if function is None or (empty_command and args.pop('help_empty', False)):
self.parser.parse_args([args['command'], '--help'])
return args, function
[docs] def execute(self, argv):
"""Execute main function of the subparser"""
try:
args, function = self.parse(argv)
returncode = function(args)
except (NoConfigurationError, NoNameError, DatabaseError, MissingResultFile,
BranchingEvent, InexecutableUserScript) as e:
print('Error:', e, file=sys.stderr)
if args.get('verbose', 0) >= 2:
raise e
return 1
except KeyboardInterrupt:
print('Orion is interrupted.')
return 130
return 0 if returncode is None else returncode
[docs]def get_basic_args_group(
parser,
group_name="Oríon arguments",
group_help="These arguments determine orion's behaviour"):
"""Return the basic arguments for any command."""
basic_args_group = parser.add_argument_group(
group_name, description=group_help)
basic_args_group.add_argument(
'-n', '--name',
type=str, metavar='stringID',
help="experiment's unique name; "
"(default: None - specified either here or in a config)")
basic_args_group.add_argument(
'-u', '--user',
type=str,
help="user associated to experiment's unique name; "
"(default: $USER - can be overriden either here or in a config)")
basic_args_group.add_argument(
'-v', '--version', type=int,
help="specific version of experiment to fetch; "
"(default: None - latest experiment.)")
basic_args_group.add_argument('-c', '--config', type=argparse.FileType('r'),
metavar='path-to-config', help="user provided "
"orion configuration file")
return basic_args_group
[docs]def get_user_args_group(parser):
"""
Return the user group arguments for any command.
User group arguments are composed of the user script and the user args
"""
usergroup = parser.add_argument_group(
"User script related arguments",
description="These arguments determine user's script behaviour "
"and they can serve as orion's parameter declaration.")
usergroup.add_argument(
'user_args', nargs=argparse.REMAINDER, metavar='...',
help="Command line of user script. A configuration "
"file intended to be used with 'userscript' must be given as a path "
"in the **first positional** argument OR using `--config=<path>` "
"keyword argument.")
return usergroup