Parameters

Click supports only two types of parameters for scripts (by design): options and arguments.

Options

  • Are optional.

  • Recommended to use for everything except subcommands, urls, or files.

  • Can take a fixed number of arguments. The default is 1. They may be specified multiple times using Multiple Options.

  • Are fully documented by the help page.

  • Have automatic prompting for missing input.

  • Can act as flags (boolean or otherwise).

  • Can be pulled from environment variables.

Arguments

  • Are optional with in reason, but not entirely so.

  • Recommended to use for subcommands, urls, or files.

  • Can take an arbitrary number of arguments.

  • Are not fully documented by the help page since they may be too specific to be automatically documented. For more see Documenting Arguments.

  • Can be pulled from environment variables but only explicitly named ones. For more see Environment Variables.

Parameter Names

Parameters (options and arguments) have a name that will be used as the Python argument name when calling the decorated function with values.

@click.command()
@click.argument('filename')
@click.option('-t', '--times', type=int)
def multi_echo(filename, times):
    """Print value filename multiple times."""
    for x in range(times):
        click.echo(filename)

In the above example the argument’s name is filename. The name must match the python arg name. To provide a different name for use in help text, see Truncating Help Texts. The option’s names are -t and --times. More names are available for options and are covered in Options.

And what it looks like when run:

$ multi_echo --times=3 index.txt
index.txt
index.txt
index.txt

Parameter Types

The supported parameter types are:

str / click.STRING:

The default parameter type which indicates unicode strings.

int / click.INT:

A parameter that only accepts integers.

float / click.FLOAT:

A parameter that only accepts floating point values.

bool / click.BOOL:

A parameter that accepts boolean values. This is automatically used for boolean flags. The string values “1”, “true”, “t”, “yes”, “y”, and “on” convert to True. “0”, “false”, “f”, “no”, “n”, and “off” convert to False.

click.UUID:

A parameter that accepts UUID values. This is not automatically guessed but represented as uuid.UUID.

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.

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.

Changelog

Changed in version 2.0: Added the atomic parameter.

Parameters:

  • mode (str)

  • encoding (str | None)

  • errors (str | None)

  • lazy (bool | None)

  • atomic (bool)

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.

Parameters:

  • exists (bool) – The file or directory needs to exist for the value to be valid. If this is not set to True, and the file does not exist, then all further checks are silently skipped.

  • file_okay (bool) – Allow a file as a value.

  • dir_okay (bool) – Allow a directory as a value.

  • readable (bool) – if true, a readable check is performed.

  • writable (bool) – if true, a writable check is performed.

  • executable (bool) – if true, an executable check is performed.

  • resolve_path (bool) – Make the value absolute and resolve any symlinks. A ~ is not expanded, as this is supposed to be done by the shell only.

  • allow_dash (bool) – Allow a single dash as a value, which indicates a standard stream (but does not open it). Use open_file() to handle opening this value.

  • path_type (Type[Any] | None) – Convert the incoming path value to this type. If None, keep Python’s default, which is str. Useful to convert to pathlib.Path.

Changed in version 8.1: Added the executable parameter.

Changelog

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.

Parameters:

  • case_sensitive (bool) – Set to false to make choices case insensitive. Defaults to true.

  • choices (Sequence[str])

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.

Changelog

Changed in version 8.0: Added the min_open and max_open parameters.

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.

Changelog

Changed in version 8.0: Added the min_open and max_open parameters.

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.

Parameters:

formats (Sequence[str] | None) – A list or tuple of date format strings, in the order in which they should be tried. Defaults to '%Y-%m-%d', '%Y-%m-%dT%H:%M:%S', '%Y-%m-%d %H:%M:%S'.

How to Implement Custom Types

To implement a custom type, you need to subclass the ParamType class. For simple cases, passing a Python function that fails with a ValueError is also supported, though discouraged. Override the convert() method to convert the value from a string to the correct type.

The following code implements an integer type that accepts hex and octal numbers in addition to normal integers, and converts them into regular integers.

import click

class BasedIntParamType(click.ParamType):
    name = "integer"

    def convert(self, value, param, ctx):
        if isinstance(value, int):
            return value

        try:
            if value[:2].lower() == "0x":
                return int(value[2:], 16)
            elif value[:1] == "0":
                return int(value, 8)
            return int(value, 10)
        except ValueError:
            self.fail(f"{value!r} is not a valid integer", param, ctx)

BASED_INT = BasedIntParamType()

The name attribute is optional and is used for documentation. Call fail() if conversion fails. The param and ctx arguments may be None in some cases such as prompts.

Values from user input or the command line will be strings, but default values and Python arguments may already be the correct type. The custom type should check at the top if the value is already valid and pass it through to support those cases.