diff --git a/docs/command-line-reference.md b/docs/command-line-reference.md index 71b289b78..0580cba7a 100644 --- a/docs/command-line-reference.md +++ b/docs/command-line-reference.md @@ -10,6 +10,7 @@ local: true --- ``` +(exit-codes)= ## Exit Codes When a command is executed from the command line, then an exit code is return. The exit code, also called exit status or exit status code, is a positive integer that tells you whether the command executed with or without errors. @@ -44,5 +45,6 @@ To access the exit code, execute the command, then do the following depending: .. code-block:: text > echo %ERRORLEVEL% - ``` + +For Click specific behavior on exit codes, see {ref}`exception-handling-exit-codes`. diff --git a/docs/exceptions.rst b/docs/exceptions.rst index dec89da8c..3e73a078a 100644 --- a/docs/exceptions.rst +++ b/docs/exceptions.rst @@ -1,5 +1,7 @@ -Exception Handling -================== +.. _exception-handling-exit-codes: + +Exception Handling and Exit Codes +================================== .. currentmodule:: click @@ -7,6 +9,10 @@ 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. +.. contents:: + :depth: 1 + :local: + Where are Errors Handled? ------------------------- @@ -71,3 +77,50 @@ The following common subclasses exist: the parameter name if possible. * :exc:`FileError` this is an error that is raised by the :exc:`FileType` if Click encounters issues opening the file. + + +.. _help-page-exit-codes: + +Help Pages and Exit Codes +-------------------------- + +Triggering the a help page intentionally (by passing in ``--help``) returns exit code 0. If a help page is displayed due to incorrect user input, the program returns exit code 2. See :ref:`exit-codes` for more general information. + +For clarity, here is an example. + +.. click:example:: + + @click.group('printer_group') + def printer_group(): + pass + + @printer_group.command('printer') + @click.option('--this') + def printer(this): + if this: + click.echo(this) + +.. click:run:: + invoke(printer_group, args=['--help']) + +The above invocation returns exit code 0. + +.. click:run:: + invoke(printer_group, args=[]) + +The above invocation returns exit code 2 since the user invoked the command incorrectly. However, since this is such a common error when first using a command, Click invokes the help page for the user. To see that `printer-group` is an invalid invocation, turn `no_args_is_help` off. + +.. click:example:: + + @click.group('printer_group', no_args_is_help=False) + def printer_group(): + pass + + @printer_group.command('printer') + @click.option('--this') + def printer(this): + if this: + click.echo(this) + +.. click:run:: + invoke(printer_group, args=[])