Click internally uses exceptions to signal various error conditions that the user of the application might have caused. Primarily this is things like incorrect usage.
Where are Errors Handled?¶
Click’s main error handling is happening in
there it handles all subclasses of
ClickException as well as the
KeyboardInterrupt exceptions. The
latter are internally translated into a
The logic applied is the following:
- If an
KeyboardInterrupthappens, reraise it as
- If an
ClickExceptionis raised, invoke the
ClickException.show()method on it to display it and then exit the program with
- If an
Abortexception is raised print the string
Aborted!to standard error and exit the program with exit code
- if it goes through well, exit the program with exit code
What if I don’t want that?¶
Generally you always have the option to invoke the
yourself. For instance if you have a
Command you can invoke it
manually like this:
ctx = command.make_context('command-name', ['args', 'go', 'here']) with ctx: result = command.invoke(ctx)
In this case exceptions will not be handled at all and bubbled up as you would expect.
Starting with Click 3.0 you can also use the
but disable the standalone mode which will do two things: disable
exception handling and disable the implicit
sys.exit() at the end.
So you can do something like this:
command.main(['command-name', 'args', 'go', 'here'], standalone_mode=False)
Which Exceptions Exist?¶
ClickException has a
show() method which
can render an error message to stderr or the given file object. If you
want to use the exception yourself for doing something check the API docs
about what else they provide.
The following common subclasses exist:
UsageErrorto inform the user that something went wrong.
BadParameterto inform the user that something went wrong with a specific parameter. These are often handled internally in Click and augmented with extra information if possible. For instance if those are raised from a callback Click will automatically augment it with the parameter name if possible.
FileErrorthis is an error that is raised by the
FileTypeif Click encounters issues opening the file.