选项

通过 option() 装饰器可以给命令增加选项。通过配置参数来控制不同的选项。Click 中的选项不同于 位置参数。

基本的值选项

最基本的选项是值选项。这种类型的选项接受一个是值得参数。如果没有指定值的类型，那么将使用默认类型 STRING。默认情况下，参数的名称为第一个长选项，如果没有长选项则为第一个短选项。

  1. @click.command()
  2. @click.option('--n', default=1)
  3. def dots(n):
  4.     click.echo('.' * n)

在命令行中运行:

  1. $ dots --n=2
  2. ..

这上述例子中选项值的类型是 INT，因为值的默认值为数字。

多个值的选项

有时候，你需要有多个值得选项。这种选项只支持固定数量的参数。通过 nargs 参数来配置。多个值将被放入一个元组（tuple）中。

  1. @click.command()
  2. @click.option('--pos', nargs=2, type=float)
  3. def findme(pos):
  4.     click.echo('%s / %s' % pos)

在命令行中运行:

  1. $ findme --pos 2.0 3.0
  2. 2.0 / 3.0

使用元组（tuple）代替多个值的选项

4.0 新版功能.

正如你所看到的，使用 nargs 来设置一个每个值都是数字的选项，得到的元组（tuple）中都是一样的数字类型。这可能不是你想要的。通常情况下，你希望元组中包含不同类型的值。你可以直接使用下列的特殊元组达成目的：

  1. @click.command()
  2. @click.option('--item', type=(unicode, int))
  3. def putitem(item):
  4.     click.echo('name=%s id=%d' % item)

在命令行中运行:

  1. $ putitem --item peter 1338
  2. name=peter id=1338

使用元组的选项，nargs 会根据元组的长度自动生成，同时自动使用 click.Tuple。以下列子可等价表达上述例子：

  1. @click.command()
  2. @click.option('--item', nargs=2, type=click.Tuple([unicode, int]))
  3. def putitem(item):
  4.     click.echo('name=%s id=%d' % item)

多个选项

和 nargs 类似，有时候可能会需要一个参数传递多次，同时记录每次的值而不是只记录最后一个值。比如，git commit -m foo -m bar 会记录两行 commit 信息：foo 和 bar。这个功能可以通过 multiple 参数实现：

例如:

  1. @click.command()
  2. @click.option('--message', '-m', multiple=True)
  3. def commit(message):
  4.     click.echo('\n'.join(message))

在命令行中运行:

  1. $ commit -m foo -m bar
  2. foo
  3. bar

计数

在一些非常罕见的情况下，使用重复的选项来计数是很有意思的。例如：

  1. @click.command()
  2. @click.option('-v', '--verbose', count=True)
  3. def log(verbose):
  4.     click.echo('Verbosity: %s' % verbose)

在命令行中运行:

  1. $ log -vvv
  2. Verbosity: 3

布尔值标记

布尔值标记用于开启或关闭选项。可以通过以 / 分割的两个标记来实现开启或关闭选项。（如果 / 在一个选项名中，Click 会自动识别其为布尔值标记，隐式默认 is_flag=True）。Click 希望你能提供一个开启和关闭标记然后设置默认值。

例如:

  1. import sys
  2.  
  3. @click.command()
  4. @click.option('--shout/--no-shout', default=False)
  5. def info(shout):
  6.     rv = sys.platform
  7.     if shout:
  8.         rv = rv.upper() + '!!!!111'
  9.     click.echo(rv)

在命令行中运行:

  1. $ info --shout
  2. LINUX2!!!!111
  3. $ info --no-shout
  4. linux2

如果你实在不想要一个关闭标记，你只需要定义开启标记，然后手动设置它为标记。

  1. import sys
  2.  
  3. @click.command()
  4. @click.option('--shout', is_flag=True)
  5. def info(shout):
  6.     rv = sys.platform
  7.     if shout:
  8.         rv = rv.upper() + '!!!!111'
  9.     click.echo(rv)

在命令行中运行:

  1. $ info --shout
  2. LINUX2!!!!111

提示：如果 / 已经包含在你的选项名中（比如说如果你使用 Windows 风格的参数 / 是字符串的前缀），你可以使用 ; 来代替 /。

  1. @click.command()
  2. @click.option('/debug;/no-debug')
  3. def log(debug):
  4.     click.echo('debug=%s' % debug)
  5.  
  6. if __name__ == '__main__':
  7.     log()

在 6.0 版更改.

如果你想定义一个别名作为第二个选项名，你需要开头空格消除格式化字符串时的歧义：

例如:

  1. import sys
  2.  
  3. @click.command()
  4. @click.option('--shout/--no-shout', ' /-S', default=False)
  5. def info(shout):
  6.     rv = sys.platform
  7.     if shout:
  8.         rv = rv.upper() + '!!!!111'
  9.     click.echo(rv)
  1. $ info --help
  2. Usage: info [OPTIONS]
  3.  
  4. Options:
  5.   --shout / -S, --no-shout
  6.   --help                    Show this message and exit.

功能开关

另一种布尔值标记，同时也是功能开关。通过对多个选项设置同一个参数名，同时设置一个标记来实现。提示通过提供 flag_value 参数，Click 会自动隐式设置 is_flag=True。

设置一个默认值为 True 的默认标记。

  1. import sys
  2.  
  3. @click.command()
  4. @click.option('--upper', 'transformation', flag_value='upper',
  5.               default=True)
  6. @click.option('--lower', 'transformation', flag_value='lower')
  7. def info(transformation):
  8.     click.echo(getattr(sys.platform, transformation)())

在命令行中运行:

  1. $ info --upper
  2. LINUX2
  3. $ info --lower
  4. linux2
  5. $ info
  6. LINUX2

选择选项

有时候你想要一个值为某个列表内的某一个的参数。这种情况下，你可以使用 Choice 类型。它可以实例化一个包含有效值的列表。

例如:

  1. @click.command()
  2. @click.option('--hash-type', type=click.Choice(['md5', 'sha1']))
  3. def digest(hash_type):
  4.     click.echo(hash_type)

运行如下:

  1. $ digest --hash-type=md5
  2. md5
  3.  
  4. $ digest --hash-type=foo
  5. Usage: digest [OPTIONS]
  6.  
  7. Error: Invalid value for "--hash-type": invalid choice: foo. (choose from md5, sha1)
  8.  
  9. $ digest --help
  10. Usage: digest [OPTIONS]
  11.  
  12. Options:
  13.   --hash-type [md5|sha1]
  14.   --help                  Show this message and exit.

提示

有时候，你想通过命令行输入没有提供的参数。通过定义一个 prompt 参数可以实现这个功能。

例如:

  1. @click.command()
  2. @click.option('--name', prompt=True)
  3. def hello(name):
  4.     click.echo('Hello %s!' % name)

运行如下:

  1. $ hello --name=John
  2. Hello John!
  3. $ hello
  4. Name: John
  5. Hello John!

如果你不喜欢默认的提示信息，你可以自己定义：

  1. @click.command()
  2. @click.option('--name', prompt='Your name please')
  3. def hello(name):
  4.     click.echo('Hello %s!' % name)

运行如下:

  1. $ hello
  2. Your name please: John
  3. Hello John!

密码提示

Click 也支持隐藏输入信息和确认，这在输入密码时非常有用：

  1. @click.command()
  2. @click.option('--password', prompt=True, hide_input=True,
  3.               confirmation_prompt=True)
  4. def encrypt(password):
  5.     click.echo('Encrypting password to %s' % password.encode('rot13'))

运行如下:

  1. $ encrypt
  2. Password: 
  3. Repeat for confirmation: 
  4. Encrypting password to frperg

因为这种情况非常普遍，因此你可以直接用 password_option() 装饰器取代：

  1. @click.command()
  2. @click.password_option()
  3. def encrypt(password):
  4.     click.echo('Encrypting password to %s' % password.encode('rot13'))

提示时获取动态的默认值

上下文中的 auto_envvar_prefix 和 default_map 选项允许程序从环境变量或者配置文件中读取选项的值。不过这会覆盖提示机制，你将不能够自主输入选项的值。

如果你想要用户自己设置默认值，同时如果命令行没有获取该选项的值仍然使用提示进行输入，你可以提供一个可供调用的默认值。比如说从环境变量中获取一个默认值：

  1. @click.command()
  2. @click.option('--username', prompt=True,
  3.               default=lambda: os.environ.get('USER', ''))
  4. def hello(username):
  5.     print("Hello,", username)

回调选项和优先选项

有时候，你想要一个参数去完整地改变程序运行流程。比如，你想要一个 —version 参数去打印出程序的版本然后退出。

提示：—version 参数功能真正地实现是依靠 Click 中的 click.version_option()。下面的代码只是做一个简单的展示。

在下面你例子中，你需要明白两个概念：优先参数和回调。优先参数会比其他参数优先处理，回调是参数被处理后将调用回调函数。在优先需要一个参数时优先运行是很必须要的。比如，如果 —version 运行前需要 —foo 参数，你需要让它优于 —version 运行。详细信息请查看 回调评估顺序。

回调是有当前上下文 Context 和值两个参数的函数。上下文提供退出程序和访问其他已经生成的参数的有用功能。

下面是一个 —version 的简单例子:

  1. def print_version(ctx, param, value):
  2.     if not value or ctx.resilient_parsing:
  3.         return
  4.     click.echo('Version 1.0')
  5.     ctx.exit()
  6.  
  7. @click.command()
  8. @click.option('--version', is_flag=True, callback=print_version,
  9.               expose_value=False, is_eager=True)
  10. def hello():
  11.     click.echo('Hello World!')

expose_value 参数可以避免没有用的 version 参数传入回调函数中。如果没有设置它，一个布尔值将传入 hello 脚本中。resilient_parsing 用于在 Click 想在不影响整个程序运行的前提下解析命令行。这个例子中我将退出程序，什么也不做。

如下所示:

  1. $ hello
  2. Hello World!
  3. $ hello --version
  4. Version 1.0

Callback Signature Changes

In Click 2.0 the signature for callbacks changed. For moreinformation about these changes see Upgrading to 2.0.

Yes 参数

对于一些危险的操作，询问用户是否继续是一个明智的选择。通过添加一个布尔值 —yes 标记就可以实现，用户如果不提供它，就会得到提示。

  1. def abort_if_false(ctx, param, value):
  2.     if not value:
  3.         ctx.abort()
  4.  
  5. @click.command()
  6. @click.option('--yes', is_flag=True, callback=abort_if_false,
  7.               expose_value=False,
  8.               prompt='Are you sure you want to drop the db?')
  9. def dropdb():
  10.     click.echo('Dropped all tables!')

在命令行中运行:

  1. $ dropdb
  2. Are you sure you want to drop the db? [y/N]: n
  3. Aborted!
  4. $ dropdb --yes
  5. Dropped all tables!

因为这样的组合很常见，所以你可以用 confirmation_option() 装饰器来实现：

  1. @click.command()
  2. @click.confirmation_option(prompt='Are you sure you want to drop the db?')
  3. def dropdb():
  4.     click.echo('Dropped all tables!')

Callback Signature Changes

In Click 2.0 the signature for callbacks changed. For moreinformation about these changes see Upgrading to 2.0.

从环境变量中获取值

Click 有一个非常有用的特性，除了接收常规的参数外它可以从环境变量中接收参数。这个功能可以让工具更容易自动化。比如，你可能想要通过 —config 参数获取配置文件，同时又想支持通过提供 TOOL_CONFIG=hello.cfg 键值对来获取配置文件。

Click 通过两种方式实现这种需求。一种是去自动创建选项所需的环境变量。开启这个功能需要在脚本运行时使用 auto_envvar_prefix 参数。每个命令和参数将被添加为以下划线分割的大写变量。如果你有一个叫做 foo 的子命令，它有一个叫 bar 的选项，且有一个叫 MY_TOOL 的前缀，那么变量名就叫 MY_TOOL_FOO_BAR。

用例:

  1. @click.command()
  2. @click.option('--username')
  3. def greet(username):
  4.     click.echo('Hello %s!' % username)
  5.  
  6. if __name__ == '__main__':
  7.     greet(auto_envvar_prefix='GREETER')

在命令行中运行:

  1. $ export GREETER_USERNAME=john
  2. $ greet
  3. Hello john!

另一种是通过在选项中定义环境变量的名字来手工从特定的环境变量中获取值。

用例:

  1. @click.command()
  2. @click.option('--username', envvar='USERNAME')
  3. def greet(username):
  4.     click.echo('Hello %s!' % username)
  5.  
  6. if __name__ == '__main__':
  7.     greet()

在命令行中运行:

  1. $ export USERNAME=john
  2. $ greet
  3. Hello john!

在这个例子中，也可以使用列表，列表中的第一个值将被选用。

从环境变量中获取多个值

由于选项可以接收多个值，从环境变量中获取多个值（字符串）稍微复杂一些。Click 通过定义 type同时 multiple 和 nargs 的值需要为 1 以外的值，Click 会运行 ParamType.split_envvar_value()方法来进行分隔。

默认情况下所有的 type 都将使用空格来分割。但是 File 和 Path type 是例外，它们两个都遵守操作系统的路径分割规则。在 Linux 和 OS X 的 Unix系统上，通过 (:) 分割，在 Windows 系统上，通过 (;) 分割。

用例:

  1. @click.command()
  2. @click.option('paths', '--path', envvar='PATHS', multiple=True,
  3.               type=click.Path())
  4. def perform(paths):
  5.     for path in paths:
  6.         click.echo(path)
  7.  
  8. if __name__ == '__main__':
  9.     perform()

在命令行中运行:

  1. $ export PATHS=./foo/bar:./test
  2. $ perform
  3. ./foo/bar
  4. ./test

其他前缀参数

Click 能够使用除了 - 以外进行分割的前缀参数。如果你想处理有斜杠 / 或其他类似的参数，这个特性将非常有用。注意一般情况下强烈不推荐使用，因为 Click 想要开发者尽可能地保持 POSIX 语法。但是在一些特定情况下，这个特性是很有用的：

  1. @click.command()
  2. @click.option('+w/-w')
  3. def chmod(w):
  4.     click.echo('writable=%s' % w)
  5.  
  6. if __name__ == '__main__':
  7.     chmod()

在命令行中运行:

  1. $ chmod +w
  2. writable=True
  3. $ chmod -w
  4. writable=False

注意如果你想使用 / 作为前缀字符，如果你想要使用布尔值标记，你需要使用 ; 分隔符替换 /:

  1. @click.command()
  2. @click.option('/debug;/no-debug')
  3. def log(debug):
  4.     click.echo('debug=%s' % debug)
  5.  
  6. if __name__ == '__main__':
  7.     log()

范围选项

使用 IntRange type 可以获得一个特殊的方法，它和 INT type 有点像，它的值被限定在一个特定的范围内（包含两端的值）。它有两种模式：

  • 默认模式（非强制模式），如果值不在区间范围内将会引发一个错误。
  • 强制模式，如果值不在区间范围内，将会强制选取一个区间临近值。也就是说如果区间是 0-5，值为 10 则选取 5，值为 -1 则选取 0。
    例如:
  1. @click.command()
  2. @click.option('--count', type=click.IntRange(0, 20, clamp=True))
  3. @click.option('--digit', type=click.IntRange(0, 10))
  4. def repeat(count, digit):
  5.     click.echo(str(digit) * count)
  6.  
  7. if __name__ == '__main__':
  8.     repeat()

在命令行中运行:

  1. $ repeat --count=1000 --digit=5
  2. 55555555555555555555
  3. $ repeat --count=1000 --digit=12
  4. Usage: repeat [OPTIONS]
  5.  
  6. Error: Invalid value for "--digit": 12 is not in the valid range of 0 to 10.

如果区间的一端为 None，这意味着这一端将不限制。

使用回调函数进行验证

在 2.0 版更改.

如果你想自定义验证逻辑，你可以在回调参数中做这些事。回调方法中既可以改变值又可以在验证失败时抛出错误。

在 Click 1.0 中，你需要抛出 UsageError 错误，但是从 Click 2.0 开始，你也可以抛出 BadParameter 错误，这个错误增加了一些优点，它会自动格式化包含参数名的错误信息。

例如:

  1. def validate_rolls(ctx, param, value):
  2.     try:
  3.         rolls, dice = map(int, value.split('d', 2))
  4.         return (dice, rolls)
  5.     except ValueError:
  6.         raise click.BadParameter('rolls need to be in format NdM')
  7.  
  8. @click.command()
  9. @click.option('--rolls', callback=validate_rolls, default='1d6')
  10. def roll(rolls):
  11.     click.echo('Rolling a %d-sided dice %d time(s)' % rolls)
  12.  
  13. if __name__ == '__main__':
  14.     roll()

在命令行中运行:

  1. $ roll --rolls=42
  2. Usage: roll [OPTIONS]
  3.  
  4. Error: Invalid value for "--rolls": rolls need to be in format NdM
  5.  
  6. $ roll --rolls=2d12
  7. Rolling a 12-sided dice 2 time(s)