This part of the documentation lists the full API reference of all public classes and functions.
click.command(name: Callable[[...], Any]) → Command Creates a new Command and uses the decorated function as callback. This will also automatically attach all decorated option()s and argument()s as parameters to the command.
The name of the command defaults to the name of the function with underscores replaced by dashes. If you want to change that, you can pass the intended name as the first argument.
All keyword arguments are forwarded to the underlying command class. For the params argument, any decorated params are appended to the end of the list.
Once decorated the function turns into a Command instance that can be invoked as a command line utility or be attached to a command Group.
Command.Changed in version 8.1: This decorator can be applied without parentheses.
Changed in version 8.1: The params argument can be used. Decorated params are appended to the end of the list.
click.group(name: Callable[[...], Any]) → Group Creates a new Group with a function as callback. This works otherwise the same as command() just that the cls parameter is set to Group.
Changed in version 8.1: This decorator can be applied without parentheses.
click.argument(*param_decls, cls=None, **attrs) Attaches an argument to the command. All positional arguments are passed as parameter declarations to Argument; all keyword arguments are forwarded unchanged (except cls). This is equivalent to creating an Argument instance manually and attaching it to the Command.params list.
For the default argument class, refer to Argument and Parameter for descriptions of parameters.
click.option(*param_decls, cls=None, **attrs) Attaches an option to the command. All positional arguments are passed as parameter declarations to Option; all keyword arguments are forwarded unchanged (except cls). This is equivalent to creating an Option instance manually and attaching it to the Command.params list.
For the default option class, refer to Option and Parameter for descriptions of parameters.
click.password_option(*param_decls, **kwargs) Add a --password option which prompts for a password, hiding input and asking to enter the value again for confirmation.
click.confirmation_option(*param_decls, **kwargs) Add a --yes option which shows a prompt before continuing if not passed. If the prompt is declined, the program will exit.
click.version_option(version=None, *param_decls, package_name=None, prog_name=None, message=None, **kwargs) Add a --version option which immediately prints the version number and exits the program.
If version is not provided, Click will try to detect it using importlib.metadata.version() to get the version for the package_name. On Python < 3.8, the importlib_metadata backport must be installed.
If package_name is not provided, Click will try to detect it by inspecting the stack frames. This will be used to detect the version, so it must match the name of the installed package.
"--version".%(prog)s, %(package)s, and %(version)s are available. Defaults to "%(prog)s, version %(version)s".option().RuntimeError – version could not be detected.
Callable[[FC], FC]
Changed in version 8.0: Add the package_name parameter, and the %(package)s value for messages.
Changed in version 8.0: Use importlib.metadata instead of pkg_resources. The version is detected based on the package name, not the entry point name. The Python package name must match the installed package name, or be passed with package_name=.
click.help_option(*param_decls, **kwargs) Add a --help option which immediately prints the help page and exits the program.
This is usually unnecessary, as the --help option is added to each command automatically unless add_help_option=False is passed.
click.pass_context(f) Marks a callback as wanting to receive the current context object as first argument.
f (t.Callable[te.Concatenate[Context, P], R]) –
t.Callable[P, R]
click.pass_obj(f) Similar to pass_context(), but only pass the object on the context onwards (Context.obj). This is useful if that object represents the state of a nested system.
f (t.Callable[te.Concatenate[t.Any, P], R]) –
t.Callable[P, R]
click.make_pass_decorator(object_type, ensure=False) Given an object type this creates a decorator that will work similar to pass_obj() but instead of passing the object of the current context, it will find the innermost context of type object_type().
This generates a decorator that works roughly like this:
from functools import update_wrapper
def decorator(f):
@pass_context
def new_func(ctx, *args, **kwargs):
obj = ctx.find_object(object_type)
return ctx.invoke(f, obj, *args, **kwargs)
return update_wrapper(new_func, f)
return decorator
click.decorators.pass_meta_key(key, *, doc_description=None) Create a decorator that passes a key from click.Context.meta as the first argument to the decorated function.
t.Callable[[t.Callable[te.Concatenate[t.Any, P], R]], t.Callable[P, R]]
New in version 8.0.
click.echo(message=None, file=None, nl=True, err=False, color=None) Print a message and newline to stdout or a file. This should be used instead of print() because it provides better support for different data, files, and environments.
Compared to print(), this does the following:
stdout.stderr instead of stdout.None
Changed in version 6.0: Support Unicode output on the Windows console. Click does not modify sys.stdout, so sys.stdout.write() and print() will still not support Unicode.
Changed in version 4.0: Added the color parameter.
New in version 3.0: Added the err parameter.
Changed in version 2.0: Support colors on Windows if colorama is installed.
click.echo_via_pager(text_or_generator, color=None) This function takes a text and shows it via an environment specific pager on stdout.
Changed in version 3.0: Added the color flag.
click.prompt(text, default=None, hide_input=False, confirmation_prompt=False, type=None, value_proc=None, prompt_suffix=': ', show_default=True, err=False, show_choices=True) Prompts a user for input. This is a convenience function that can be used to prompt a user for input later.
If the user aborts the input by sending an interrupt signal, this function will catch it and raise a Abort exception.
True to customize the message.stderr instead of stdout, the same as with echo.New in version 8.0: confirmation_prompt can be a custom string.
New in version 7.0: Added the show_choices parameter.
New in version 6.0: Added unicode support for cmd.exe on Windows.
New in version 4.0: Added the err parameter.
click.confirm(text, default=False, abort=False, prompt_suffix=': ', show_default=True, err=False) Prompts for confirmation (yes/no question).
If the user aborts the input by sending a interrupt signal this function will catch it and raise a Abort exception.
None, repeat until input is given.True a negative answer aborts the exception by raising Abort.stderr instead of stdout, the same as with echo.Changed in version 8.0: Repeat until input is given if default is None.
New in version 4.0: Added the err parameter.
click.progressbar(iterable=None, length=None, label=None, show_eta=True, show_percent=None, show_pos=False, item_show_func=None, fill_char='#', empty_char='-', bar_template='%(label)s [%(bar)s] %(info)s', info_sep=' ', width=36, file=None, color=None, update_min_steps=1) This function creates an iterable context manager that can be used to iterate over something while showing a progress bar. It will either iterate over the iterable or length items (that are counted up). While iteration happens, this function will print a rendered progress bar to the given file (defaults to stdout) and will attempt to calculate remaining time and more. By default, this progress bar will not be rendered if the file is not a terminal.
The context manager creates the progress bar. When the context manager is entered the progress bar is already created. With every iteration over the progress bar, the iterable passed to the bar is advanced and the bar is updated. When the context manager exits, a newline is printed and the progress bar is finalized on screen.
Note: The progress bar is currently designed for use cases where the total progress can be expected to take at least several seconds. Because of this, the ProgressBar class object won’t display progress that is considered too fast, and progress where the time between steps is less than a second.
No printing must happen or the progress bar will be unintentionally destroyed.
Example usage:
with progressbar(items) as bar:
for item in bar:
do_something_with(item)
Alternatively, if no iterable is specified, one can manually update the progress bar through the update() method instead of directly iterating over the progress bar. The update method accepts the number of steps to increment the bar with:
with progressbar(length=chunks.total_bytes) as bar:
for chunk in chunks:
process_chunk(chunk)
bar.update(chunks.bytes)
The update() method also takes an optional value specifying the current_item at the new position. This is useful when used together with item_show_func to customize the output for each manual step:
with click.progressbar(
length=total_size,
label='Unzipping archive',
item_show_func=lambda a: a.filename
) as bar:
for archive in zip_file:
archive.extract()
bar.update(archive.size, archive)
True if the iterable has a length or False if not.False.None nothing is shown. The current item can be None, such as when entering and exiting the bar.label for the label, bar for the progress bar and info for the info section.ProgressBar[V]
Changed in version 8.0: Output is shown even if execution time is less than 0.5 seconds.
Changed in version 8.0: item_show_func shows the current item, not the previous one.
Changed in version 8.0: Labels are echoed if the output is not a TTY. Reverts a change in 7.0 that removed all output.
New in version 8.0: Added the update_min_steps parameter.
Changed in version 4.0: Added the color parameter. Added the update method to the object.
New in version 2.0.
click.clear() Clears the terminal screen. This will have the effect of clearing the whole visible space of the terminal and moving the cursor to the top left. This does not do anything if not connected to a terminal.
New in version 2.0.
None
click.style(text, fg=None, bg=None, bold=None, dim=None, underline=None, overline=None, italic=None, blink=None, reverse=None, strikethrough=None, reset=True) Styles a text with ANSI styles and returns the new string. By default the styling is self contained which means that at the end of the string a reset code is issued. This can be prevented by passing reset=False.
Examples:
click.echo(click.style('Hello World!', fg='green'))
click.echo(click.style('ATTENTION!', blink=True))
click.echo(click.style('Some things', reverse=True, fg='cyan'))
click.echo(click.style('More colors', fg=(255, 12, 128), bg=117))
Supported color names:
black (might be a gray)redgreenyellow (might be an orange)bluemagentacyanwhite (might be light gray)bright_blackbright_redbright_greenbright_yellowbright_bluebright_magentabright_cyanbright_whitereset (reset the color code only)If the terminal supports it, color may also be specified as:
See https://en.wikipedia.org/wiki/ANSI_color and https://gist.github.com/XVilka/8346728 for more information.
Changed in version 8.0: A non-string message is converted to a string.
Changed in version 8.0: Added support for 256 and RGB color codes.
Changed in version 8.0: Added the strikethrough, italic, and overline parameters.
Changed in version 7.0: Added support for bright colors.
New in version 2.0.
click.unstyle(text) Removes ANSI styling information from a string. Usually it’s not necessary to use this function as Click’s echo function will automatically remove styling if necessary.
New in version 2.0.
click.secho(message=None, file=None, nl=True, err=False, color=None, **styles) This function combines echo() and style() into one call. As such the following two calls are the same:
click.secho('Hello World!', fg='green')
click.echo(click.style('Hello World!', fg='green'))
All keyword arguments are forwarded to the underlying functions depending on which one they go with.
Non-string types will be converted to str. However, bytes are passed directly to echo() without applying style. If you want to style bytes that represent text, call bytes.decode() first.
Changed in version 8.0: A non-string message is converted to a string. Bytes are passed through without style applied.
New in version 2.0.
click.edit(text=None, editor=None, env=None, require_save=True, extension='.txt', filename=None) Edits the given text in the defined editor. If an editor is given (should be the full path to the executable but the regular operating system search path is used for finding the executable) it overrides the detected editor. Optionally, some environment variables can be used. If the editor is closed without changes, None is returned. In case a file is edited directly the return value is always None and require_save and extension are ignored.
If the editor cannot be opened a UsageError is raised.
Note for Windows: to simplify cross-platform usage, the newlines are automatically converted from POSIX to Windows and vice versa. As such, the message here will have \n as newline markers.
None..txt but changing this might change syntax highlighting.AnyStr | None
click.launch(url, wait=False, locate=False) This function launches the given URL (or filename) in the default viewer application for this file type. If this is an executable, it might launch the executable in a new session. The return value is the exit code of the launched application. Usually, 0 indicates success.
Examples:
click.launch('https://click.palletsprojects.com/')
click.launch('/my/downloaded/file', locate=True)
New in version 2.0.
xdg-open on Linux does not block.True then instead of launching the application associated with the URL it will attempt to launch a file manager with the file located. This might have weird effects if the URL does not point to the filesystem.click.getchar(echo=False) Fetches a single character from the terminal and returns it. This will always return a unicode character and under certain rare circumstances this might return more than one character. The situations which more than one character is returned is when for whatever reason multiple characters end up in the terminal buffer or standard input was not actually a terminal.
Note that this will always read from the terminal, even if something is piped into the standard input.
Note for Windows: in rare cases when typing non-ASCII characters, this function might wait for a second character and then return both at once. This is because certain Unicode characters look like special-key markers.
New in version 2.0.
click.pause(info=None, err=False) This command stops execution and waits for the user to press any key to continue. This is similar to the Windows batch “pause” command. If the program is not run through a terminal, this command will instead do nothing.
New in version 4.0: Added the err parameter.
New in version 2.0.
click.get_binary_stream(name) Returns a system stream for byte processing.
name (te.Literal['stdin', 'stdout', 'stderr']) – the name of the stream to open. Valid names are 'stdin', 'stdout' and 'stderr'
click.get_text_stream(name, encoding=None, errors='strict') Returns a system stream for text processing. This usually returns a wrapped stream around a binary stream returned from get_binary_stream() but it also can take shortcuts for already correctly configured streams.
click.open_file(filename, mode='r', encoding=None, errors='strict', lazy=False, atomic=False) Open a file, with extra behavior to handle '-' to indicate a standard stream, lazy open on write, and atomic write. Similar to the behavior of the File param type.
If '-' is given to open stdout or stdin, the stream is wrapped so that using it in a context manager will not close it. This makes it possible to use the function without accidentally closing a standard stream:
with open_file(filename) as f:
...
'-' for stdin/stdout.New in version 3.0.
click.get_app_dir(app_name, roaming=True, force_posix=False) Returns the config folder for the application. The default behavior is to return whatever is most appropriate for the operating system.
To give you an idea, for an app called "Foo Bar", something like the following folders could be returned:
~/Library/Application Support/Foo Bar
~/.foo-bar
~/.config/foo-bar
~/.foo-bar
C:\Users\<user>\AppData\Roaming\Foo Bar
C:\Users\<user>\AppData\Local\Foo Bar
New in version 2.0.
True then on any POSIX system the folder will be stored in the home folder with a leading dot instead of the XDG config home or darwin’s application support folder.click.format_filename(filename, shorten=False) Format a filename as a string for display. Ensures the filename can be displayed by replacing any invalid bytes or surrogate escapes in the name with the replacement character �.
Invalid bytes or surrogate escapes will raise an error when written to a stream with errors="strict". This will typically happen with stdout when the locale is something like en_GB.UTF-8.
Many scenarios are safe to write surrogates though, due to PEP 538 and PEP 540, including:
stderr, which uses errors="backslashreplace".LANG=C.UTF-8, C, or POSIX. Python opens stdout and stderr with errors="surrogateescape".LANG/LC_* are set. Python assumes LANG=C.UTF-8.PYTHONUTF8=1 or -X utf8. Python opens stdout and stderr with errors="surrogateescape".class click.BaseCommand(name, context_settings=None) The base command implements the minimal API contract of commands. Most code will never use this as it does not implement a lot of useful functionality but it can act as the direct subclass of alternative parsing methods that do not depend on the Click parser.
For instance, this can be used to bridge Click and other systems like argparse or docopt.
Because base commands do not implement a lot of the API that other parts of Click take for granted, they are not supported for all operations. For instance, they cannot be used with the decorators usually and they have no built-in callback system.
Changed in version 2.0: Added the context_settings parameter.
context_class alias of Context
allow_extra_args = False the default for the Context.allow_extra_args flag.
allow_interspersed_args = True the default for the Context.allow_interspersed_args flag.
ignore_unknown_options = False the default for the Context.ignore_unknown_options flag.
name the name the command thinks it has. Upon registering a command on a Group the group will default the command name with this information. You should instead use the Context's info_name attribute.
context_settings: MutableMapping[str, Any] an optional dictionary with defaults passed to the context.
to_info_dict(ctx) Gather information that could be useful for a tool generating user-facing documentation. This traverses the entire structure below this command.
Use click.Context.to_info_dict() to traverse the entire CLI structure.
New in version 8.0.
make_context(info_name, args, parent=None, **extra) This function when given an info name and arguments will kick off the parsing and create a new Context. It does not invoke the actual command callback though.
To quickly customize the context class used without overriding this method, set the context_class attribute.
Changed in version 8.0: Added the context_class attribute.
parse_args(ctx, args) Given a context and a list of arguments this creates the parser and parses the arguments, then modifies the context as necessary. This is automatically invoked by make_context().
invoke(ctx) Given a context, this invokes the command. The default implementation is raising a not implemented error.
shell_complete(ctx, incomplete) Return a list of completions for the incomplete value. Looks at the names of chained multi-commands.
Any command could be part of a chained multi-command, so sibling commands are valid at any point during command completion. Other command classes will return more completions.
New in version 8.0.
main(args: Sequence[str] | None = None, prog_name: str | None = None, complete_var: str | None = None, standalone_mode: te.Literal[True] = True, **extra: Any) → te.NoReturn This is the way to invoke a script with all the bells and whistles as a command line application. This will always terminate the application after a call. If this is not wanted, SystemExit needs to be caught.
This method is also available by directly calling the instance of a Command.
sys.argv[1:] is used.sys.argv[0]."_<prog_name>_COMPLETE" with prog_name in uppercase.False they will be propagated to the caller and the return value of this function is the return value of invoke().Context for more information.Changed in version 8.0.1: Added the windows_expand_args parameter to allow disabling command line arg expansion on Windows.
Changed in version 8.0: When taking arguments from sys.argv on Windows, glob patterns, user dir, and env vars are expanded.
Changed in version 3.0: Added the standalone_mode parameter.
class click.Command(name, context_settings=None, callback=None, params=None, help=None, epilog=None, short_help=None, options_metavar='[OPTIONS]', add_help_option=True, no_args_is_help=False, hidden=False, deprecated=False) Commands are the basic building block of command line interfaces in Click. A basic command handles command line parsing and might dispatch more parsing to commands nested below it.
Option or Argument objects.--help option. This can be disabled by this parameter.--help as argument if no arguments are passedChanged in version 8.1: help, epilog, and short_help are stored unprocessed, all formatting is done when outputting help text, not at init, and is done even if not using the @command decorator.
Changed in version 8.0: Added a repr showing the command name.
Changed in version 7.1: Added the no_args_is_help parameter.
Changed in version 2.0: Added the context_settings parameter.
callback the callback to execute when the command fires. This might be None in which case nothing happens.
params: List[Parameter] the list of parameters for this command in the order they should show up in the help page and execute. Eager parameters will automatically be handled before non eager ones.
to_info_dict(ctx) Gather information that could be useful for a tool generating user-facing documentation. This traverses the entire structure below this command.
Use click.Context.to_info_dict() to traverse the entire CLI structure.
New in version 8.0.
get_usage(ctx) Formats the usage line into a string and returns it.
Calls format_usage() internally.
format_usage(ctx, formatter) Writes the usage line into the formatter.
This is a low-level method called by get_usage().
None
collect_usage_pieces(ctx) Returns all the pieces that go into the usage line and returns it as a list of strings.
get_help_option_names(ctx) Returns the names for the help option.
get_help_option(ctx) Returns the help option object.
make_parser(ctx) Creates the underlying option parser for this command.
ctx (Context) –
get_help(ctx) Formats the help into a string and returns it.
Calls format_help() internally.
get_short_help_str(limit=45) Gets short help for the command or makes it by shortening the long help string.
format_help(ctx, formatter) Writes the help into the formatter if it exists.
This is a low-level method called by get_help().
This calls the following methods:
None
format_help_text(ctx, formatter) Writes the help text to the formatter if it exists.
None
format_options(ctx, formatter) Writes all the options into the formatter if they exist.
None
format_epilog(ctx, formatter) Writes the epilog into the formatter if it exists.
None
parse_args(ctx, args) Given a context and a list of arguments this creates the parser and parses the arguments, then modifies the context as necessary. This is automatically invoked by make_context().
invoke(ctx) Given a context, this invokes the attached callback (if it exists) in the right way.
shell_complete(ctx, incomplete) Return a list of completions for the incomplete value. Looks at the names of options and chained multi-commands.
New in version 8.0.
class click.MultiCommand(name=None, invoke_without_command=False, no_args_is_help=None, subcommand_metavar=None, chain=False, result_callback=None, **attrs) A multi command is the basic implementation of a command that dispatches to subcommands. The most common version is the Group.
invoke_without_command is disabled or disabled if it’s enabled. If enabled this will add --help as argument if no arguments are passed.True chaining of multiple subcommands is enabled. This restricts the form of commands in that they cannot have optional arguments but it allows multiple commands to be chained together.result_callback() decorator.Command.allow_extra_args = True the default for the Context.allow_extra_args flag.
allow_interspersed_args = False the default for the Context.allow_interspersed_args flag.
to_info_dict(ctx) Gather information that could be useful for a tool generating user-facing documentation. This traverses the entire structure below this command.
Use click.Context.to_info_dict() to traverse the entire CLI structure.
New in version 8.0.
collect_usage_pieces(ctx) Returns all the pieces that go into the usage line and returns it as a list of strings.
format_options(ctx, formatter) Writes all the options into the formatter if they exist.
None
result_callback(replace=False) Adds a result callback to the command. By default if a result callback is already registered this will chain them but this can be disabled with the replace parameter. The result callback is invoked with the return value of the subcommand (or the list of return values from all subcommands if chaining is enabled) as well as the parameters as they would be passed to the main callback.
Example:
@click.group()
@click.option('-i', '--input', default=23)
def cli(input):
return 42
@cli.result_callback()
def process_result(result, input):
return result + input
replace (bool) – if set to True an already existing result callback will be removed.
Callable[[F], F]
Changed in version 8.0: Renamed from resultcallback.
New in version 3.0.
format_commands(ctx, formatter) Extra format methods for multi methods that adds all the commands after the options.
None
parse_args(ctx, args) Given a context and a list of arguments this creates the parser and parses the arguments, then modifies the context as necessary. This is automatically invoked by make_context().
invoke(ctx) Given a context, this invokes the attached callback (if it exists) in the right way.
get_command(ctx, cmd_name) Given a context and a command name, this returns a Command object if it exists or returns None.
list_commands(ctx) Returns a list of subcommand names in the order they should appear.
shell_complete(ctx, incomplete) Return a list of completions for the incomplete value. Looks at the names of options, subcommands, and chained multi-commands.
New in version 8.0.
class click.Group(name=None, commands=None, **attrs) A group allows a command to have subcommands attached. This is the most common way to implement nesting in Click.
Command objects. Can also be a list of Command, which will use Command.name to create the dict.MultiCommand, Command, and BaseCommand.Changed in version 8.0: The commands argument can be a list of command objects.
command_class: Type[Command] | None = None If set, this is used by the group’s command() decorator as the default Command class. This is useful to make all subcommands use a custom command class.
New in version 8.0.
group_class: Type[Group] | Type[type] | None = None If set, this is used by the group’s group() decorator as the default Group class. This is useful to make all subgroups use a custom group class.
If set to the special value type (literally group_class = type), this group’s class will be used as the default class. This makes a custom group class continue to make custom groups.
New in version 8.0.
commands: MutableMapping[str, Command] The registered subcommands by their exported names.
add_command(cmd, name=None) Registers another Command with this group. If the name is not provided, the name of the command is used.
command(__func: Callable[[...], Any]) → Command A shortcut decorator for declaring and attaching a command to the group. This takes the same arguments as command() and immediately registers the created command with this group by calling add_command().
To customize the command class used, set the command_class attribute.
Changed in version 8.1: This decorator can be applied without parentheses.
Changed in version 8.0: Added the command_class attribute.
group(__func: Callable[[...], Any]) → Group A shortcut decorator for declaring and attaching a group to the group. This takes the same arguments as group() and immediately registers the created group with this group by calling add_command().
To customize the group class used, set the group_class attribute.
Changed in version 8.1: This decorator can be applied without parentheses.
Changed in version 8.0: Added the group_class attribute.
get_command(ctx, cmd_name) Given a context and a command name, this returns a Command object if it exists or returns None.
class click.CommandCollection(name=None, sources=None, **attrs) A command collection is a multi command that merges multiple multi commands together into one. This is a straightforward implementation that accepts a list of different multi commands as sources and provides all the commands for each of them.
See MultiCommand and Command for the description of name and attrs.
sources: List[MultiCommand] The list of registered multi commands.
add_source(multi_cmd) Adds a new multi command to the chain dispatcher.
multi_cmd (MultiCommand) –
None
get_command(ctx, cmd_name) Given a context and a command name, this returns a Command object if it exists or returns None.
class click.Parameter(param_decls=None, type=None, required=False, default=None, callback=None, nargs=None, multiple=False, metavar=None, expose_value=True, is_eager=False, envvar=None, shell_complete=None) A parameter to a command comes in two versions: they are either Options or Arguments. Other subclasses are currently not supported by design as some of the internals for parsing are intentionally not finalized.
Some settings are supported by both options and arguments.
ParamType or a Python type. The latter is converted into the former automatically if supported.f(ctx, param, value) and must return the value. It is called for all sources, including prompts.1 the return value is a tuple instead of single value. The default for nargs is 1 (except if the type is a tuple, then it’s the arity of the tuple). If nargs=-1, all remaining parameters are collected.True then the value is passed onwards to the command callback and stored on the context, otherwise it’s skipped.ctx, param, incomplete and must return a list of CompletionItem or a list of strings.Changed in version 8.0: process_value validates required parameters and bounded nargs, and invokes the parameter callback before returning the value. This allows the callback to validate prompts. full_process_value is removed.
Changed in version 8.0: autocompletion is renamed to shell_complete and has new semantics described above. The old name is deprecated and will be removed in 8.1, until then it will be wrapped to match the new requirements.
Changed in version 8.0: For multiple=True, nargs>1, the default must be a list of tuples.
Changed in version 8.0: Setting a default is no longer required for nargs>1, it will default to None. multiple=True or nargs=-1 will default to ().
Changed in version 7.1: Empty environment variables are ignored rather than taking the empty string value. This makes it possible for scripts to clear variables if they can’t unset them.
Changed in version 2.0: Changed signature for parameter callback to also be passed the parameter. The old callback format will still work, but it will raise a warning to give you a chance to migrate the code easier.
to_info_dict() Gather information that could be useful for a tool generating user-facing documentation.
Use click.Context.to_info_dict() to traverse the entire CLI structure.
New in version 8.0.
property human_readable_name: str Returns the human readable name of this parameter. This is the same as the name for options, but the metavar for arguments.
get_default(ctx: Context, call: te.Literal[True] = True) → Any | None Get the default for the parameter. Tries Context.lookup_default() first, then the local default.
Changed in version 8.0.2: Type casting is no longer performed when getting a default.
Changed in version 8.0.1: Type casting can fail in resilient parsing mode. Invalid defaults will not prevent showing help text.
Changed in version 8.0: Looks at ctx.default_map first.
Changed in version 8.0: Added the call parameter.
type_cast_value(ctx, value) Convert and validate a value against the option’s type, multiple, and nargs.
get_error_hint(ctx) Get a stringified version of the param for use in error messages to indicate which param caused the error.
shell_complete(ctx, incomplete) Return a list of completions for the incomplete value. If a shell_complete function was given during init, it is used. Otherwise, the type shell_complete() function is used.
New in version 8.0.
class click.Option(param_decls=None, show_default=None, prompt=False, confirmation_prompt=False, prompt_required=True, hide_input=False, is_flag=None, flag_value=None, multiple=False, count=False, allow_from_autoenv=True, type=None, help=None, hidden=False, show_choices=True, show_envvar=False, **attrs) Options are usually optional values on the command line and have some extra features that arguments don’t have.
All other parameters are passed onwards to the parameter constructor.
Context.show_default is True. If this value is a string, it shows that string in parentheses instead of the actual value. This is particularly useful for dynamic options. For single option boolean flags, the default remains hidden if its value is False.True or a non empty string then the user will be prompted for input. If set to True the prompt will be the option name capitalized.True to customize the message.False, the user will be prompted for input only when the option was specified as a flag without a value.True then the input on the prompt will be hidden from the user. This is useful for password input.True then the argument is accepted multiple times and recorded. This is similar to nargs in how it works but supports arbitrary number of arguments.Parameter.Changed in version 8.1.0: Help text indentation is cleaned here instead of only in the @option decorator.
Changed in version 8.1.0: The show_default parameter overrides Context.show_default.
Changed in version 8.1.0: The default of a single option boolean flag is not shown if the default value is False.
Changed in version 8.0.1: type is detected from flag_value if given.
class click.Argument(param_decls, required=None, **attrs) Arguments are positional parameters to a command. They generally provide fewer features than options but can have infinite nargs and are required by default.
All parameters are passed onwards to the constructor of Parameter.
class click.Context(command, parent=None, info_name=None, obj=None, auto_envvar_prefix=None, default_map=None, terminal_width=None, max_content_width=None, resilient_parsing=False, allow_extra_args=None, allow_interspersed_args=None, ignore_unknown_options=None, help_option_names=None, token_normalize_func=None, color=None, show_default=None) The context is a special internal object that holds state relevant for the script execution at every single level. It’s normally invisible to commands unless they opt-in to getting access to it.
The context is useful as it can pass internal objects around and can control special execution features such as reading data from environment variables.
A context can be used as context manager in which case it will call close() on teardown.
None then reading from environment variables is disabled. This does not affect manually set environment variables which are always read.True then extra arguments at the end will not raise an error and will be kept on the context. The default is to inherit from the command.False then options and arguments cannot be mixed. The default is to inherit from the command.['--help'].Command.show_default overrides this default for the specific command.Changed in version 8.1: The show_default parameter is overridden by Command.show_default, instead of the other way around.
Changed in version 8.0: The show_default parameter defaults to the value from the parent context.
Changed in version 7.1: Added the show_default parameter.
Changed in version 4.0: Added the color, ignore_unknown_options, and max_content_width parameters.
Changed in version 3.0: Added the allow_extra_args and allow_interspersed_args parameters.
Changed in version 2.0: Added the resilient_parsing, help_option_names, and token_normalize_func parameters.
formatter_class alias of HelpFormatter
parent the parent context or None if none exists.
command the Command for this context.
info_name the descriptive information name
params: Dict[str, Any] Map of parameter names to their parsed values. Parameters with expose_value=False are not stored.
args: List[str] the leftover arguments.
protected_args: List[str] protected arguments. These are arguments that are prepended to args when certain parsing scenarios are encountered but must be never propagated to another arguments. This is used to implement nested parsing.
obj: Any the user object stored.
invoked_subcommand: str | None This flag indicates if a subcommand is going to be executed. A group callback can use this information to figure out if it’s being executed directly or because the execution flow passes onwards to a subcommand. By default it’s None, but it can be the name of the subcommand to execute.
If chaining is enabled this will be set to '*' in case any commands are executed. It is however not possible to figure out which ones. If you require this knowledge you should use a result_callback().
terminal_width: int | None The width of the terminal (None is autodetection).
max_content_width: int | None The maximum width of formatted content (None implies a sensible default which is 80 for most things).
allow_extra_args Indicates if the context allows extra args or if it should fail on parsing.
New in version 3.0.
allow_interspersed_args: bool Indicates if the context allows mixing of arguments and options or not.
New in version 3.0.
ignore_unknown_options: bool Instructs click to ignore options that a command does not understand and will store it on the context for later processing. This is primarily useful for situations where you want to call into external programs. Generally this pattern is strongly discouraged because it’s not possibly to losslessly forward all arguments.
New in version 4.0.
help_option_names: List[str] The names for the help options.
token_normalize_func: Callable[[str], str] | None An optional normalization function for tokens. This is options, choices, commands etc.
resilient_parsing: bool Indicates if resilient parsing is enabled. In that case Click will do its best to not cause any failures and default values will be ignored. Useful for completion.
color: bool | None Controls if styling output is wanted or not.
show_default: bool | None Show option default values when formatting help text.
to_info_dict() Gather information that could be useful for a tool generating user-facing documentation. This traverses the entire CLI structure.
with Context(cli) as ctx:
info = ctx.to_info_dict()
New in version 8.0.
scope(cleanup=True) This helper method can be used with the context object to promote it to the current thread local (see get_current_context()). The default behavior of this is to invoke the cleanup functions which can be disabled by setting cleanup to False. The cleanup functions are typically used for things such as closing file handles.
If the cleanup is intended the context object can also be directly used as a context manager.
Example usage:
with ctx.scope():
assert get_current_context() is ctx
This is equivalent:
with ctx:
assert get_current_context() is ctx
New in version 5.0.
cleanup (bool) – controls if the cleanup functions should be run or not. The default is to run these functions. In some situations the context only wants to be temporarily pushed in which case this can be disabled. Nested pushes automatically defer the cleanup.
property meta: Dict[str, Any] This is a dictionary which is shared with all the contexts that are nested. It exists so that click utilities can store some state here if they need to. It is however the responsibility of that code to manage this dictionary well.
The keys are supposed to be unique dotted strings. For instance module paths are a good choice for it. What is stored in there is irrelevant for the operation of click. However what is important is that code that places data here adheres to the general semantics of the system.
Example usage:
LANG_KEY = f'{__name__}.lang'
def set_language(value):
ctx = get_current_context()
ctx.meta[LANG_KEY] = value
def get_language():
return get_current_context().meta.get(LANG_KEY, 'en_US')
New in version 5.0.
make_formatter() Creates the HelpFormatter for the help and usage output.
To quickly customize the formatter class used without overriding this method, set the formatter_class attribute.
Changed in version 8.0: Added the formatter_class attribute.
with_resource(context_manager) Register a resource as if it were used in a with statement. The resource will be cleaned up when the context is popped.
Uses contextlib.ExitStack.enter_context(). It calls the resource’s __enter__() method and returns the result. When the context is popped, it closes the stack, which calls the resource’s __exit__() method.
To register a cleanup function for something that isn’t a context manager, use call_on_close(). Or use something from contextlib to turn it into a context manager first.
@click.group()
@click.option("--name")
@click.pass_context
def cli(ctx):
ctx.obj = ctx.with_resource(connect_db(name))
context_manager (ContextManager[V]) – The context manager to enter.
Whatever context_manager.__enter__() returns.
V
New in version 8.0.
call_on_close(f) Register a function to be called when the context tears down.
This can be used to close resources opened during the script execution. Resources that support Python’s context manager protocol which would be used in a with statement should be registered with with_resource() instead.
close() Invoke all close callbacks registered with call_on_close(), and exit all context managers entered with with_resource().
None
property command_path: str The computed command path. This is used for the usage information on the help page. It’s automatically created by combining the info names of the chain of contexts to the root.
find_root() Finds the outermost context.
find_object(object_type) Finds the closest object of a given type.
object_type (Type[V]) –
V | None
ensure_object(object_type) Like find_object() but sets the innermost object to a new instance of object_type if it does not exist.
object_type (Type[V]) –
V
lookup_default(name: str, call: te.Literal[True] = True) → Any | None Get the default for a parameter from default_map.
Changed in version 8.0: Added the call parameter.
fail(message) Aborts the execution of the program with a specific error message.
message (str) – the error message to fail with.
te.NoReturn
abort() Aborts the script.
te.NoReturn
exit(code=0) Exits the application with a given exit code.
code (int) –
te.NoReturn
get_usage() Helper method to get formatted usage string for the current context and command.
get_help() Helper method to get formatted help page for the current context and command.
invoke(__callback: Callable[[...], V], *args: Any, **kwargs: Any) → V Invokes a command callback in exactly the way it expects. There are two ways to invoke this method:
Note that before Click 3.2 keyword arguments were not properly filled in against the intention of this code and no context was created. For more information about this change and why it was done in a bugfix release see Upgrading to 3.2.
forward(_Context__cmd, *args, **kwargs) Similar to invoke() but fills in default keyword arguments from the current context if the other command expects it. This cannot invoke callbacks directly, only other commands.
Changed in version 8.0: All kwargs are tracked in params so they will be passed if forward is called at multiple levels.
set_parameter_source(name, source) Set the source of a parameter. This indicates the location from which the value of the parameter was obtained.
ParameterSource.None
get_parameter_source(name) Get the source of a parameter. This indicates the location from which the value of the parameter was obtained.
This can be useful for determining when a user specified a value on the command line that is the same as the default value. It will be DEFAULT only if the value was actually taken from the default.
name (str) – The name of the parameter.
Changed in version 8.0: Returns None if the parameter was not provided from any source.
click.get_current_context(silent: te.Literal[False] = False) → Context Returns the current click context. This can be used as a way to access the current context object from anywhere. This is a more implicit alternative to the pass_context() decorator. This function is primarily useful for helpers such as echo() which might be interested in changing its behavior based on the current context.
To push the current context, Context.scope() can be used.
New in version 5.0.
silent – if set to True the return value is None if no context is available. The default behavior is to raise a RuntimeError.
class click.core.ParameterSource(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None) This is an Enum that indicates the source of a parameter’s value.
Use click.Context.get_parameter_source() to get the source for a parameter by name.
Changed in version 8.0: Use Enum and drop the validate method.
Changed in version 8.0: Added the PROMPT value.
COMMANDLINE = 1 The value was provided by the command line args.
ENVIRONMENT = 2 The value was provided with an environment variable.
DEFAULT = 3 Used the default specified by the parameter.
DEFAULT_MAP = 4 Used a default provided by Context.default_map.
PROMPT = 5 Used a prompt to confirm a default or provide a value.
click.STRING = STRING click.INT = INT click.FLOAT = FLOAT click.BOOL = BOOL click.UUID = UUID click.UNPROCESSED = UNPROCESSED class click.File(mode='r', encoding=None, errors='strict', lazy=None, atomic=False) Declares a parameter to be a file for reading or writing. The file is automatically closed once the context tears down (after the command finished working).
Files can be opened for reading or writing. The special value - indicates stdin or stdout depending on the mode.
By default, the file is opened for reading text data, but it can also be opened in binary mode or for writing. The encoding parameter can be used to force a specific encoding.
The lazy flag controls if the file should be opened immediately or upon first IO. The default is to be non-lazy for standard input and output streams as well as files opened for reading, lazy otherwise. When opening a file lazily for reading, it is still opened temporarily for validation, but will not be held open until first IO. lazy is mainly useful when opening for writing to avoid creating the file until it is needed.
Starting with Click 2.0, files can also be opened atomically in which case all writes go into a separate file in the same folder and upon completion the file will be moved over to the original location. This is useful if a file regularly read by other users is modified.
See File Arguments for more information.
class click.Path(exists=False, file_okay=True, dir_okay=True, writable=False, readable=True, resolve_path=False, allow_dash=False, path_type=None, executable=False) The Path type is similar to the File type, but returns the filename instead of an open file. Various checks can be enabled to validate the type of file and permissions.
True, and the file does not exist, then all further checks are silently skipped.~ is not expanded, as this is supposed to be done by the shell only.open_file() to handle opening this value.None, keep Python’s default, which is str. Useful to convert to pathlib.Path.Changed in version 8.1: Added the executable parameter.
Changed in version 8.0: Allow passing path_type=pathlib.Path.
Changed in version 6.0: Added the allow_dash parameter.
class click.Choice(choices, case_sensitive=True) The choice type allows a value to be checked against a fixed set of supported values. All of these values have to be strings.
You should only pass a list or tuple of choices. Other iterables (like generators) may lead to surprising results.
The resulting value will always be one of the originally passed choices regardless of case_sensitive or any ctx.token_normalize_func being specified.
See Choice Options for an example.
class click.IntRange(min=None, max=None, min_open=False, max_open=False, clamp=False) Restrict an click.INT value to a range of accepted values. See Range Options.
If min or max are not passed, any value is accepted in that direction. If min_open or max_open are enabled, the corresponding boundary is not included in the range.
If clamp is enabled, a value outside the range is clamped to the boundary instead of failing.
Changed in version 8.0: Added the min_open and max_open parameters.
class click.FloatRange(min=None, max=None, min_open=False, max_open=False, clamp=False) Restrict a click.FLOAT value to a range of accepted values. See Range Options.
If min or max are not passed, any value is accepted in that direction. If min_open or max_open are enabled, the corresponding boundary is not included in the range.
If clamp is enabled, a value outside the range is clamped to the boundary instead of failing. This is not supported if either boundary is marked open.
Changed in version 8.0: Added the min_open and max_open parameters.
class click.DateTime(formats=None) The DateTime type converts date strings into datetime objects.
The format strings which are checked are configurable, but default to some common (non-timezone aware) ISO 8601 formats.
When specifying DateTime formats, you should only pass a list or a tuple. Other iterables, like generators, may lead to surprising results.
The format strings are processed using datetime.strptime, and this consequently defines the format strings which are allowed.
Parsing is tried using each format, in order, and the first format which parses successfully is used.
class click.Tuple(types) The default behavior of Click is to apply a type on a value directly. This works well in most cases, except for when nargs is set to a fixed count and different types should be used for different items. In this case the Tuple type can be used. This type can only be used if nargs is set to a fixed number.
For more information see Tuples as Multi Value Options.
This can be selected by using a Python tuple literal as a type.
class click.ParamType Represents the type of a parameter. Validates and converts values from the command line or Python into the correct type.
To implement a custom type, subclass and implement at least the following:
name class attribute must be set.None must return None. This is already implemented by default.convert() must convert string values to the correct type.convert() must accept values that are already the correct type.ctx and param arguments are None. This can occur when converting prompt input.name: str the descriptive name of this type
envvar_list_splitter: ClassVar[str | None] = None if a list of this type is expected and the value is pulled from a string environment variable, this is what splits it up. None means any whitespace. For all parameters the general rule is that whitespace splits them up. The exception are paths and files which are split by os.path.pathsep by default (“:” on Unix and “;” on Windows).
to_info_dict() Gather information that could be useful for a tool generating user-facing documentation.
Use click.Context.to_info_dict() to traverse the entire CLI structure.
New in version 8.0.
get_metavar(param) Returns the metavar default for this param if it provides one.
get_missing_message(param) Optionally might return extra information about a missing parameter.
New in version 2.0.
convert(value, param, ctx) Convert the value to the correct type. This is not called if the value is None (the missing value).
This must accept string values from the command line, as well as values that are already the correct type. It may also convert other compatible types.
The param and ctx arguments may be None in certain situations, such as when converting prompt input.
If the value cannot be converted, call fail() with a descriptive message.
split_envvar_value(rv) Given a value from an environment variable this splits it up into small chunks depending on the defined envvar list splitter.
If the splitter is set to None, which means that whitespace splits, then leading and trailing whitespace is ignored. Otherwise, leading and trailing splitters usually lead to empty items being included.
fail(message, param=None, ctx=None) Helper method to fail with an invalid value message.
shell_complete(ctx, param, incomplete) Return a list of CompletionItem objects for the incomplete value. Most types do not provide completions, but some do, and this allows custom types to provide custom completions as well.
New in version 8.0.
exception click.ClickException(message) An exception that Click can handle and show to the user.
message (str) –
None
exception click.Abort An internal signalling exception that signals Click to abort.
exception click.UsageError(message, ctx=None) An internal exception that signals a usage error. This typically aborts any further handling.
exception click.BadParameter(message, ctx=None, param=None, param_hint=None) An exception that formats out a standardized error message for a bad parameter. This is useful when thrown from a callback or type as Click will attach contextual information to it (for instance, which parameter it is).
New in version 2.0.
param in cases where custom validation should happen. If it is a string it’s used as such, if it’s a list then each item is quoted and separated.None
exception click.FileError(filename, hint=None) Raised if a file cannot be opened.
exception click.NoSuchOption(option_name, message=None, possibilities=None, ctx=None) Raised if click attempted to handle an option that does not exist.
New in version 4.0.
exception click.BadOptionUsage(option_name, message, ctx=None) Raised if an option is generally supplied but the use of the option was incorrect. This is for instance raised if the number of arguments for an option is not correct.
New in version 4.0.
exception click.BadArgumentUsage(message, ctx=None) Raised if an argument is generally supplied but the use of the argument was incorrect. This is for instance raised if the number of values for an argument is not correct.
New in version 6.0.
class click.HelpFormatter(indent_increment=2, width=None, max_width=None) This class helps with formatting text-based help pages. It’s usually just needed for very special internal cases, but it’s also exposed so that developers can write their own fancy outputs.
At present, it always writes into memory.
write(string) Writes a unicode string into the internal buffer.
string (str) –
None
indent() Increases the indentation.
None
dedent() Decreases the indentation.
None
write_usage(prog, args='', prefix=None) Writes a usage line into the buffer.
write_heading(heading) Writes a heading into the buffer.
heading (str) –
None
write_paragraph() Writes a paragraph into the buffer.
None
write_text(text) Writes re-indented text into the buffer. This rewraps and preserves paragraphs.
text (str) –
None
write_dl(rows, col_max=30, col_spacing=2) Writes a definition list into the buffer. This is how options and commands are usually formatted.
section(name) Helpful context manager that writes a paragraph, a heading, and the indents.
indentation() A context manager that increases the indentation.
Iterator[None]
getvalue() Returns the buffer contents.
click.wrap_text(text, width=78, initial_indent='', subsequent_indent='', preserve_paragraphs=False) A helper function that intelligently wraps text. By default, it assumes that it operates on a single paragraph of text but if the preserve_paragraphs parameter is provided it will intelligently handle paragraphs (defined by two empty lines).
If paragraphs are handled, a paragraph can be prefixed with an empty line containing the \b character (\x08) to indicate that no rewrapping should happen in that block.
class click.OptionParser(ctx=None) The option parser is an internal class that is ultimately used to parse options and arguments. It’s modelled after optparse and brings a similar but vastly simplified API. It should generally not be used directly as the high level Click classes wrap it for you.
It’s not nearly as extensible as optparse or argparse as it does not implement features that are implemented on a higher level (such as types or defaults).
ctx The Context for this parser. This might be None for some advanced use cases.
allow_interspersed_args: bool This controls how the parser deals with interspersed arguments. If this is set to False, the parser will stop on the first non-option. Click uses this to implement nested subcommands safely.
ignore_unknown_options: bool This tells the parser how to deal with unknown options. By default it will error out (which is sensible), but there is a second mode where it will ignore it and continue processing after shifting all the unknown options into the resulting args.
add_option(obj, opts, dest, action=None, nargs=1, const=None) Adds a new option named dest to the parser. The destination is not inferred (unlike with optparse) and needs to be explicitly provided. Action can be any of store, store_const, append, append_const or count.
The obj can be used to identify the option in the order list that is returned from the parser.
add_argument(obj, dest, nargs=1) Adds a positional argument named dest to the parser.
The obj can be used to identify the option in the order list that is returned from the parser.
parse_args(args) Parses positional arguments and returns (values, args, order) for the parsed options and arguments as well as the leftover arguments if there are any. The order is a list of objects as they appear on the command line. If arguments appear multiple times they will be memorized multiple times as well.
See Shell Completion for information about enabling and customizing Click’s shell completion system.
class click.shell_completion.CompletionItem(value, type='plain', help=None, **kwargs) Represents a completion value and metadata about the value. The default metadata is type to indicate special shell handling, and help if a shell supports showing a help string next to the value.
Arbitrary parameters can be passed when creating the object, and accessed using item.attr. If an attribute wasn’t passed, accessing it returns None.
"dir" and "file".class click.shell_completion.ShellComplete(cli, ctx_args, prog_name, complete_var) Base class for providing shell completion support. A subclass for a given shell will override attributes and methods to implement the completion instructions (source and complete).
New in version 8.0.
name: ClassVar[str] Name to register the shell as with add_completion_class(). This is used in completion instructions ({name}_source and {name}_complete).
source_template: ClassVar[str] Completion script template formatted by source(). This must be provided by subclasses.
property func_name: str The name of the shell function defined by the completion script.
source_vars() Vars for formatting source_template.
By default this provides complete_func, complete_var, and prog_name.
source() Produce the shell script that defines the completion function. By default this %-style formats source_template with the dict returned by source_vars().
get_completion_args() Use the env vars defined by the shell script to return a tuple of args, incomplete. This must be implemented by subclasses.
get_completions(args, incomplete) Determine the context and last complete command or parameter from the complete args. Call that object’s shell_complete method to get the completions for the incomplete value.
format_completion(item) Format a completion item into the form recognized by the shell script. This must be implemented by subclasses.
item (CompletionItem) – Completion item to format.
complete() Produce the completion data to send back to the shell.
By default this calls get_completion_args(), gets the completions, then calls format_completion() for each completion.
click.shell_completion.add_completion_class(cls, name=None) Register a ShellComplete subclass under the given name. The name will be provided by the completion instruction environment variable during completion.
name attribute.ShellCompleteType
class click.testing.CliRunner(charset='utf-8', env=None, echo_stdin=False, mix_stderr=True) The CLI runner provides functionality to invoke a Click command line script for unittesting purposes in a isolated environment. This only works in single-threaded systems without any concurrency as it changes the global interpreter state.
True, then reading from stdin writes to stdout. This is useful for showing examples in some circumstances. Note that regular prompts will automatically echo the input.False, then stdout and stderr are preserved as independent streams. This is useful for Unix-philosophy apps that have predictable stdout and noisy stderr, such that each may be measured independentlyget_default_prog_name(cli) Given a command object it will return the default program name for it. The default is the name attribute or "root" if not set.
cli (BaseCommand) –
make_env(overrides=None) Returns the environment overrides for invoking a script.
isolation(input=None, env=None, color=False) A context manager that sets up the isolation for invoking of a command line tool. This sets up stdin with the given input data and os.environ with the overrides from the given dictionary. This also rebinds some internals in Click to be mocked (like the prompt functionality).
This is automatically done in the invoke() method.
Changed in version 8.0: stderr is opened with errors="backslashreplace" instead of the default "strict".
Changed in version 4.0: Added the color parameter.
invoke(cli, args=None, input=None, env=None, catch_exceptions=True, color=False, **extra) Invokes a command in an isolated environment. The arguments are forwarded directly to the command line script, the extra keyword arguments are passed to the main() function of the command.
This returns a Result object.
shlex.split().sys.stdin.SystemExit.main().Changed in version 8.0: The result object has the return_value attribute with the value returned from the invoked command.
Changed in version 4.0: Added the color parameter.
Changed in version 3.0: Added the catch_exceptions parameter.
Changed in version 3.0: The result object has the exc_info attribute with the traceback if available.
isolated_filesystem(temp_dir=None) A context manager that creates a temporary directory and changes the current working directory to it. This isolates tests that affect the contents of the CWD to prevent them from interfering with each other.
temp_dir (str | PathLike[str] | None) – Create the temporary directory under this directory. If given, the created directory is not removed when exiting.
Changed in version 8.0: Added the temp_dir parameter.
class click.testing.Result(runner, stdout_bytes, stderr_bytes, return_value, exit_code, exception, exc_info=None) Holds the captured result of an invoked CLI script.
runner The runner that created the result
stdout_bytes The standard output as bytes.
stderr_bytes The standard error as bytes, or None if not available
return_value The value returned from the invoked command.
New in version 8.0.
exit_code The exit code as integer.
exception The exception that happened if one did.
exc_info The traceback
property output: str The (standard) output as unicode string.
property stdout: str The standard output as unicode string.
property stderr: str The standard error as unicode string.
© Copyright 2014 Pallets.
Licensed under the BSD 3-Clause License.
We are not supported nor endorsed by Pallets.
https://click.palletsprojects.com/en/8.1.x/api/