hansken.tool — Command line interaction

run(args=None, using_parser=<hansken.py default parser>, with_connection=None, with_context=None, with_multi_context=None, error='raise', with_admin=None, **defaults)[source]

Run the command line tool, either as the command line interface defined by hansken.py itself, or running user code, piggybacking on all the command line argument parsing and resolving done by hansken.py.

Note

run parses the command line by default. If user code does its own command line parsing, either pass applicable args to run or use set_command, passing the resulting argparse.ArgumentParser to run as using_parser after adding additional user arguments.

Note

By default, run calls exit on the argparse.ArgumentParser in case of an error raised from whatever command is called (this includes user-provided commands). This call results in a CLI-like error message containing the exception message of the error that was caught. As the call to exit raises a SystemExit, any user code after the call to run will not be executed. When the error argument to run is set to 'raise' or the arguments parser sets verbose mode, exit is not called, the exception is reraised instead.

Parameters:

  • args – arguments to the tool, a list of str, or None, in which case args will be read from the command line

  • using_parser – the argparse.ArgumentParser to be used, either the parser that processes the command line interface defined by hansken.py itself or one that is the result of set_command

  • with_connection – a user-defined callable to be run with a Connection instance, passed as keyword argument connection

  • with_context – a user-defined callable to be run with a ProjectContext instance, passed as keyword argument context

  • with_multi_context – a user-defined callable to be run with a MultiProjectContext instance, passed as keyword argument context

  • error – how to deal with an error raised from the selected command runner, defaults to propagating errors to the caller of run, set to 'exit' to call using_parser.exit() with a non-zero return code and failure message

  • defaults – named arguments to be used as defaults when parsing the command line, matching the destinations of defined arguments (e.g. project='a-project-uuid')

Returns:

the return value of the command that was ultimately called (when run was called with either with_context or with_admin, the return value of that callable will be returned by run)

create_argument_parser(requires_project=False, **kwargs)[source]

Creates an ArgumentParser to be used with run alongside with_context or with_admin. This parser’s main feature is to not add a -h/--help argument, which is attached to the main argument parser used by run.

Parameters:

  • requires_project – whether the parser should be fitted with a required positional argument project

  • kwargs – any ArgumentParser constructor arguments (see argparse documentation)

Returns:

an ArgumentParser that won’t clash with hansken.py’s parent parser

Return type:

argparse.ArgumentParser