当你想实现一个命令行程序时，或许第一个想到的是用 Python 来实现。比如 CentOS 上大名鼎鼎的包管理工具 yum 就是基于 Python 实现的。

而 Python 的世界中有很多命令行库，每个库都各具特色。但我们往往不知道其背后的设计理念，也因此在选择时感到迷茫。这些库的作者为何在重复造轮子，他是从哪个角度来考虑，来让命令行库“演变”到一个新的更好用的形态。

为了能够更加直观地感受到命令行库的设计理念，在此之前，我们不妨设计一个名为 calc 的命令行程序，它能：

• 支持 echo 子命令，对输入的字符串做处理来输出
  • 若不提供任何选项，则输出原始内容
  • 若提供 --lower 选项，则输出小写字符串
  • 若提供 --upper 选项，则输出大写字符串
• 支持 eval 子命令，针对输入调用 Python 的 eval 函数，将结果输出（作为示例，我们不考虑安全性问题）

argparse

argparse 作为 Python 的标准库，可能会是你想到第一个命令行库。

argparse 的设计理念就是提供给开发者最细粒度的控制。换句话说，你需要告诉它必不可少的细节，比如参数的类型是什么，处理参数的动作是怎样的。

在 argparse 的世界中，需要：

• 设置解析器，作为后续定义参数和解析命令行的基础。如果要实现子命令，则还要设置子解析器。
• 定义参数，包括名称、类型、动作、帮助等。其中的动作是指对于此参数的初步处理，是直接存下来，还是作为布尔值，亦或是追加到列表中等等
• 解析参数
• 根据参数编写业务逻辑

以下示例是基于 argparse 的 calc 程序：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51

import argparse


def echo_text(args):
    if args.lower:
        print(args.text.lower())
    elif args.upper:
        print(args.text.upper())
    else:
        print(args.text)


def eval_expression(args):
    print(eval(args.expression))


# 1. 设置解析器
parser = argparse.ArgumentParser(description='Calculator Program.')
subparsers = parser.add_subparsers()

# 2. 定义参数
# 2.1 echo 子命令
# echo 子解析器
echo_parser = subparsers.add_parser(
    'echo', help='Echo input text in multiple forms')
# 添加位置参数 text
echo_parser.add_argument('text', help='Input text')
# --lower/--upper 互斥，需要设置互斥组
echo_group = echo_parser.add_mutually_exclusive_group()
# 添加选项参数 --lower/--upper，这里action的作用就是将之变为布尔变量
echo_parser.add_argument('--lower', action='store_true', help='Lower input text')
echo_parser.add_argument('--upper', action='store_true', help='Upper input text')
# 设置此命令的处理函数
echo_parser.set_defaults(handle=echo_text)

# eval 子解析器
eval_parser = subparsers.add_parser(
    'eval', help='Eval input expression and return result')
# 添加位置参数 expression
eval_parser.add_argument('expression', help='Expression to eval')
# 设置此命令的处理函数
eval_parser.set_defaults(handle=eval_expression)

# 3. 解析参数
args = parser.parse_args(['echo', '--upper', 'Hello, World'])
print(args)  # 结果：Namespace(lower=True, text='Hello, World', upper=False)
# args = parser.parse_args(['eval', '1+2*3'])
# print(args)  # 结果：Namespace(expression='1+2*3')

# 4. 业务逻辑处理
args.handle(args)

从上述示例可以看到，要实现子命令，对应地需要添加子解析器。然后最为关键的就是要定义参数，需要通过 add_argument 很明确地告诉 argparse 参数长什么样，需要怎么处理：

• 它是位置参数 text/expression，还是选项参数 --lower/--upper
• 若是选项参数，是否互斥
• 参数的是存成什么形式，比如 action='store_true' 表示存成布尔
• 子命令的响应函数

通过 argparse 实现的整个过程是很计算机思维的，且比较冗长。其优点是灵活，所有的功能都涵盖到了；但缺点则是将定义和处理割裂，尤其在程序功能复杂时会愈加凌乱和不直观，难以理解和维护。

docopt

有人喜欢 argparse 这样命令式的写法，就会有人喜欢声明式的写法。而 docopt 恰巧这就是这样一个命令行库。设计它的初衷就是对于熟悉命令行程序帮助信息的开发者来说，直接通过编写帮助信息来描述整个命令行参数定义的元信息会是更加简单快捷的方式。这种声明式的语法描述某种程度上会比过程式地定义参数来的更加简单和直观。

在 docopt 的世界中，需要：

• 定义接口描述/帮助信息，这一步是它的特色和重点
• 解析参数，获得一个字典
• 根据参数编写业务逻辑

以下示例是基于 docopt 的 calc 程序：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

# 1. 定义接口描述/帮助信息
"""Calculator Program.

Usage:
  calc echo [--lower | --upper] <text>
  calc eval <expression>

Commands:
  echo          Echo input text in multiple forms
  eval          Eval input expression and return result

Options:
  -h --help     Show help
  --lower       Lower input text
  --upper       Upper input text
"""
from docopt import docopt


def echo_text(args):
    if args['--lower']:
        print(args['<text>'].lower())
    elif args['--upper']:
        print(args['<text>'].upper())
    else:
        print(args['<text>'])


def eval_expression(args):
    print(eval(args['<expression>']))


# 2. 解析命令行
args = docopt(__doc__, argv=['echo', '--upper', 'Hello, World'])
# 结果：{'--lower': False, '--upper': True, '<expression>': None, '<text>': 'Hello, World', 'echo': True, 'eval': False}
print(args)

# 3. 业务逻辑
if args['echo']:
    echo_text(args)
elif args['eval']:
    eval_expression(args)

从上述示例可以看到，我们通过文档字符串 __doc__ 定义了接口描述，这和 argparse 中 一系列参数定义的行为是等价的，然后 docopt 便会根据这个元信息把命令行参数转换为一个字典。业务逻辑中就需要对这个字典进行处理。

相比于 argparse：

• 对于较为复杂的命令，命令和参数元信息的定义上 docopt 会更加简单
• 在业务逻辑的处理上，argparse 在一些简单参数的处理上会更加便捷，且命令和处理函数之间可以方便路由（比如示例中的情形）；相对来说 docopt 转换为字典后就把所有处理交给业务逻辑的方式会更加复杂

click

不论是 argparse 还是 docopt，元信息的定义和处理都是割裂开的。而命令行程序本质上是定义参数并对参数进行处理，而处理参数的逻辑一定是与所定义的参数有关联的。那可不可以用函数和装饰器来实现处理参数逻辑与定义参数的关联呢？click 正好就是以这种使用方式来设计的。

装饰器这样一个优雅的语法糖是元信息定义和处理逻辑之间的绝妙胶水，从而暗示了两者的路有关系。对比于前两个命令行库的路由实现着实优雅了不少。

在 click 的世界中：

• 通过装饰器定义命令和参数的元信息
• 使用此装饰器装饰处理函数

对，就是这么简单。

以下示例是基于 click 的 calc 程序：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

import sys
import click

sys.argv = ['calc', 'echo', '--upper', 'Hello, World']


@click.group(help='Calculator Program.')
def cli():
    pass

# 2. 定义参数
@cli.command(name='echo', help='Echo input text in multiple forms')
@click.argument('text')
@click.option('--lower', is_flag=True, help='Lower input text')
@click.option('--upper', is_flag=True, help='Upper input text')
# 1. 业务逻辑
def echo_text(text, lower, upper):
    if lower:
        print(text.lower())
    elif upper:
        print(text.upper())
    else:
        print(text)


@cli.command(name='eval', help='Eval input expression and return result')
@click.argument('expression')
def eval_expression(expression):
    print(eval(expression))


cli()

从上述示例可以看到，元信息定义和处理逻辑无缝绑定在一起，能够直观地看出对应的参数会如何处理，这个优势在有大量参数需要处理时显得尤为突出。在处理函数中，接收到不再是像 argparse 或 docopt 中的一个包含所有参数的变量，而是具体的参数变量，这让处理逻辑在参数使用上也变得更加简便。

此外，click 还内置了很多实用工具和增强能力，如参数自动补全、分页支持、颜色、进度条等功能，能够有效提升开发效率。

fire

虽然前面三个库已经足够强大，但是仍然会有人认为不够简单。是否还有进一步简化的空间呢？如果只是定义函数，是否能让框架推测出参数元信息呢？理论上还真是可以。

fire 用一种面向广义对象的方式来玩转命令行，这种对象可以是类、函数、字典、列表等，它更加灵活，也更加简单。你都不需要定义参数类型，fire 会根据输入和参数默认值来自动判断，这无疑进一步简化了实现过程。

在 fire 的世界中，定义 Python 对象就够了。

以下示例是基于 fire 的 calc 程序：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

import sys
import fire

sys.argv = ['calc', 'echo', '"Hello, World"', '--upper']

# 业务逻辑
# 类中有几个方法，就意味着命令行程序有几个同名命令
class Calc:
    # text 没有任何默认值，视为位置参数
    # lower/upper 有布尔类型的默认值，视为选项参数 --lower/--upper，
    # 且指定了为 True，不指定 False
    def echo(self, text, lower=False, upper=False):
        """Echo input text in multiple forms"""
        if lower:
            print(text.lower())
        elif upper:
            print(text.upper())
        else:
            print(text)

    def eval(self, expression):
        """Eval input expression and return result"""
        print(eval(expression))


fire.Fire(Calc)

从上面的示例可以看出，使用 fire 足够的简单，一切都是根据约定来进行推断，包括支持哪些命令，每个命令接受的什么参数和选项。这种方式可以说是足够的 Pythonic，相比于 click，fire 把命令行参数的定义和函数参数的定义融为了一体。通过它，我们真的就只用关注业务逻辑。

不过简单往往也意味着对于复杂需求的捉襟见肘。仅仅通过默认值来推导命令行参数所能表达的情况是有限的，比如互斥选项、位置参数的类型限定都无法通过框架来表达，而只能由业务逻辑去判断。

typer

那么该如何在保持像 fire 这样简单实现的方式下，增强参数元信息的表达能力呢？既然默认参数的能力有限，那么如果使用 Python 3 的类型注解呢？

typer 站在 click 巨人的肩膀上，借助 Python 3 类型注解的特性，既满足了简单直观编写的需要，又达到了应对复杂场景的目的，可谓是现代化的命令行库。

在 typer 的世界中，也是直接编写业务逻辑，和 fire 稍稍不同的点是使用了类型注解和默认值来表达参数元信息定义。

以下示例是基于 typer 的 calc 程序：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

import sys
import typer

sys.argv = ['calc', 'echo', '"Hello, World"', '--upper']
cli = typer.Typer(help='Calculator Program.')


# 定义命令 echo，及处理函数
# text 无默认值，视为位置参数，类型为字符串
# lower/upper 类型为 bool，默认值为 False，视为选项 --lower/--upper，
# 且指定了为 True，不指定 False
@cli.command(name='echo')
def echo_text(text: str, lower: bool = False, upper: bool = False):
    """Echo input text in multiple forms"""
    if lower:
        print(text.lower())
    elif upper:
        print(text.upper())
    else:
        print(text)


# 定义命令 eval，及处理函数
# expression 无默认值，视为位置参数，类型为字符串
@cli.command(name='eval')
def eval_expression(expression: str):
    """Eval input expression and return result"""
    print(eval(expression))


cli()

从上面的示例可以看出，相比于 click，它免去了参数元信息的繁琐定义，取而代之的是类型注解；相比于 fire，它的元信息定义能力则大大增强，可以通过指定默认值为 typer.Option 或 typer.Argument 来进一步扩展参数和选项的语义。可以说是，typer 达到了简单与灵活的完美平衡。

横向对比

最后，我们横向对比下 argparse、docopt、click、fire、typer 库的各项功能和特点：

Python 的命令行库种类繁多、各具特色，它们并非是重复造轮子的产物，其背后的思想值得学习。结合横向对比的总结，可以选择出符合使用场景的库。如果几个库都符合，那么就选择你所偏爱的风格。

相关文章

• Python 命令行之旅：初探 argparse
• Python 命令行之旅：深入 argparse（一）
• Python 命令行之旅：深入 argparse（二）
• Python 命令行之旅：使用 argparse 实现 git 命令
• Python 命令行之旅：初探 docopt
• Python 命令行之旅：深入 docopt
• Python 命令行之旅：使用 docopt 实现 git 命令
• Python 命令行之旅：初探 click
• Python 命令行之旅：深入 click（一）
• Python 命令行之旅：深入 click（二）
• Python 命令行之旅：深入 click（三）
• Python 命令行之旅：深入 click（四）
• Python 命令行之旅：使用 click 实现 git 命令
• Python 命令行之旅：初探 fire
• Python 命令行之旅：深入 fire（一）
• Python 命令行之旅：深入 fire（二）
• Python 命令行之旅：使用 fire 实现 git 命令
• Python 命令行之旅：argparse、docopt、click 和 fire 总结篇
• Python 命令行大乱斗

最近做云服务 API 测试项目的过程中，发现某些时候会大批量调用 API，从而导致限流的报错。在遇到这种报错时，传统的重试策略是每隔一段时间重试一次。但由于是固定的时间重试一次，重试时又会有大量的请求在同一时刻涌入，会不断地造成限流。

这让我回想起两年前在查阅Celery Task 文档的时候发现可以为任务设置 retry_backoff 的经历，它让任务在失败时以 指数退避 的方式进行重试。那么指数退避究竟是什么样的呢？

二、指数退避

根据 wiki 上对 Exponential backoff 的说明，指数退避是一种通过反馈，成倍地降低某个过程的速率，以逐渐找到合适速率的算法。

在以太网中，该算法通常用于冲突后的调度重传。根据时隙和重传尝试次数来决定延迟重传。

在 c 次碰撞后（比如请求失败），会选择 0 和 $2^c-1$ 之间的随机值作为时隙的数量。

• 对于第 1 次碰撞来说，每个发送者将会等待 0 或 1 个时隙进行发送。
• 而在第 2 次碰撞后，发送者将会等待 0 到 3（ 由 $2^2-1$ 计算得到）个时隙进行发送。
• 而在第 3 次碰撞后，发送者将会等待 0 到 7（ 由 $2^3-1$ 计算得到）个时隙进行发送。
• 以此类推……

随着重传次数的增加，延迟的程度也会指数增长。

说的通俗点，每次重试的时间间隔都是上一次的两倍。

三、指数退避的期望值

考虑到退避时间的均匀分布，退避时间的数学期望是所有可能性的平均值。也就是说，在 c 次冲突之后，退避时隙数量在 [0,1，...，N] 中，其中 $N=2^c-1$ ，则退避时间的数学期望（以时隙为单位）是

$$E(c)=\frac{1}{N+1}\sum_{i=0}^{N}{i}=\frac{1}{N+1}\frac{N(N+1)}{2}=\frac{N}{2}=\frac{2^c-1}{2}$$

那么对于前面讲到的例子来说：

• 第 1 次碰撞后，退避时间期望为 $E(1)=\frac{2^1-1}{2}=0.5$
• 第 2 次碰撞后，退避时间期望为 $E(2)=\frac{2^2-1}{2}=1.5$
• 第 3 次碰撞后，退避时间期望为 $E(3)=\frac{2^3-1}{2}=3.5$

四、指数退避的应用

4.1 Celery 中的指数退避算法

来看下 celery/utils/time.py 中获取指数退避时间的函数：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

def get_exponential_backoff_interval(
    factor,
    retries,
    maximum,
    full_jitter=False
):
    """Calculate the exponential backoff wait time."""
    # Will be zero if factor equals 0
    countdown = factor * (2 ** retries)
    # Full jitter according to
    # https://www.awsarchitectureblog.com/2015/03/backoff.html
    if full_jitter:
        countdown = random.randrange(countdown + 1)
    # Adjust according to maximum wait time and account for negative values.
    return max(0, min(maximum, countdown))

这里 factor 是退避系数，作用于整体的退避时间。而 retries 则对应于上文的 c（也就是碰撞次数）。核心内容 countdown = factor * (2 ** retries) 和上文提到的指数退避算法思路一致。
在此基础上，可以将 full_jitter 设置为 True，含义是对退避时间做一个“抖动”，以具有一定的随机性。最后呢，则是限定给定值不能超过最大值 maximum，以避免无限长的等待时间。不过一旦取最大的退避时间，也就可能导致多个任务同时再次执行。更多见 Task.retry_jitter 。

4.2 《UNIX 环境高级编程》中的连接示例

在 《UNIX 环境高级编程》（第 3 版）的 16.4 章节中，也有一个使用指数退避来建立连接的示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

#include "apue.h"
#include <sys/socket.h>

#define MAXSLEEP 128

int connect_retry(int domain, int type, int protocol,
                  const struct sockaddr *addr, socklen_t alen)
{
    int numsec, fd;

    /*
    * 使用指数退避尝试连接
    */
    for (numsec = 1; numsec < MAXSLEEP; numsec <<= 1)
    {
        if (fd = socket(domain, type, protocol) < 0)
            return (-1);
        if (connect(fd, addr, alen) == 0)
        {
            /*
            * 连接接受
            */
            return (fd);
        }
        close(fd);

        /*
        * 延迟后重试
        */
        if (numsec <= MAXSLEEP / 2)
            sleep(numsec);
    }
    return (-1);
}

如果连接失败，进程会休眠一小段时间（numsec），然后进入下次循环再次尝试。每次循环休眠时间是上一次的 2 倍，直到最大延迟 1 分多钟，之后便不再重试。

总结

回到开头的问题，在遇到限流错误的时候，通过指数退避算法进行重试，我们可以最大程度地避免再次限流。相比于固定时间重试，指数退避加入了时间放大性和随机性，从而变得更加“智能”。至此，我们再也不用担心限流让整个测试程序运行中断了~

就在本周，字典合并特性（PEP 584）的提交被合入了 CPython 的主干分支，并在 2020-02-26 发布了 Python 3.9.0a4 预览版本。

那什么是字典合并操作符呢？在回答这个问题前，我们不妨回忆下集合的合并操作。当我们想要对两个结合做合并操作时，会怎么做呢？

1
2
3
4
5
6
7

>>> s1 = {1, 2}
>>> s2 = {2, 3}
>>> s1 | s2  # s1 和 s2 取并集，生成新的集合；与 s1.union(s2) 等价
{1, 2, 3}
>>> s1 |= s2 # s1 和 s2 取并集，并更新到 s1 上；与 s1.update(s2) 等价
>>> s1
{1, 2, 3}

类似地，我们希望 Python 中的字典能像集合一样，使用 | 和 |= 作为合并操作符，以解决我们在过去合并字典时感受到的“痛苦”，于是就有了 PEP 584。

今天就想和大家聊聊这个提案，不仅是要了解字典合并操作符的前世今生，更是要学习提案作者以及参与者是如何对引入一个新特性的思考，辩证性地分析利弊，最终确定引入。最后还想和大家分享下在 CPython 层面是如何实现的。

二、背景

在平时使用 Python 的过程中，我们有时会需要合并字典。目前合并字典有多种方式，它们或多或少都有些缺点。

2.1 dict.update

d1.update(d2) 确实能合并两个字典，但它是在修改d1的基础上进行。如果我们想要合并成一个新的字典，没有一个直接使用表达式的方式，而需要借助临时变量进行：

1
2

e = d1.copy()
e.update(d2)

2.2 {d1, d2}

字典解包可以将两个字典合并为一个新的字典，但看起来有些丑陋，并且不能让人显而易见地看出这是在合并字典。

{**d1, **d2} 还会忽略映射类型，并始终返回字典类型。

2.3 collections.ChainMap

ChainMap 很少有人知道，它也可以用作合并字典。但和前面合并方式相反，在合并两个字典时，第一个字典的键会覆盖第二个字典的相同键。

此外，由于 ChainMap 是对入参字典的封装，这意味着写入 ChainMap 会修改原始字典：

1
2
3
4
5
6
7
8
9

>>> from collections import ChainMap
>>> d1 = {'a':1}
>>> d2 = {'a':2}
>>> merged = ChainMap(d1, d2)
>>> merged['a']     # d1['a'] 会覆盖 d2['a']
1
>>> merged['a'] = 3 # 实际等同于 d1['a'] = 3
>>> d1
{'a': 3}

2.4 dict(d1, **d2)

这是一种鲜为人知的合并字典的“巧妙方法”，但如果字典的键不是字符串，它就不能有效工作了：

1
2
3
4
5
6

>>> d1 = {'a': 1}
>>> d2 = {2: 2}
>>> dict(d1, **d2)
Traceback (most recent call last):
  ...
TypeError: keywords must be strings

三、原理

新操作符同 dict.update 方法的关系，就和列表连接（+）、扩展（+=）操作符同 list.extend 方法的关系一样。需要注意的是，这和集合中 |/|= 操作符同 set.update 的关系稍有不同。作者明确了允许就地运算符接受更广泛的类型（就像 list 那样）是一种更有用的设计，并且限制二进制操作符的操作数类型（就像 list 那样）将有助于避免由复杂的隐式类型转换引起的错误被吞掉。

1
2
3
4
5
6
7
8

>>> l1 = [1, 2]
>>> l1 + (3,) # 限制操作数的类型，不是列表就报错
Traceback (most recent call last)
...
TypeError: can only concatenate list (not "tuple") to list
>>> l1 += (3,) # 允许就地运算符接受更广泛的类型（如元组）
>>> l1
[1, 2, 3]

当合并字典发生键冲突时，以最右边的值为准。这和现存的字典类似操作相符，比如：

1
2
3
4
5

{'a': 1, 'a': 2} # 2 覆盖 1
{**d, **e}       # e覆盖d中相同键所对应的值
d.update(e)      # e覆盖d中相同键所对应的值
d[k] = v         # v 覆盖原有值
{k: v for x in (d, e) for (k, v) in x.items()} # e覆盖d中相同键所对应的值

四、规范

字典合并会返回一个新字典，该字典由左操作数与右操作数合并而成，每个操作数必须是 dict（或 dict 子类的实例）。如果两个操作数中都出现一个键，则最后出现的值（即来自右侧操作数的值）将会覆盖：

1
2
3
4
5
6

>>> d = {'spam': 1, 'eggs': 2, 'cheese': 3}
>>> e = {'cheese': 'cheddar', 'aardvark': 'Ethel'}
>>> d | e
{'spam': 1, 'eggs': 2, 'cheese': 'cheddar', 'aardvark': 'Ethel'}
>>> e | d # 不符合交换律，左右互换操作数会得到不同的结果
{'aardvark': 'Ethel', 'spam': 1, 'eggs': 2, 'cheese': 3}

扩展赋值版本的就地操作：

1
2
3

>>> d |= e # 将 e 更新到 d 中
>>> d
{'spam': 1, 'eggs': 2, 'cheese': 'cheddar', 'aardvark': 'Ethel'}

扩展赋值的行为和字典的 update 方法完全一样，它还支持任何实现了映射协议（更确切地说是实现了 keys 和 __getitem__ 方法）或键值对迭代对象。所以：

1
2
3
4
5
6
7
8

>>> d | [('spam', 999)]   # “原理”章节中提到限制操作数的类型，不是字典或字典子类就报错
Traceback (most recent call last):
  ...
TypeError: can only merge dict (not "list") to dict

>>> d |= [('spam', 999)]  # “原理”章节中提到允许就地运算符接受更广泛的类型，其行为和 update 一样，接受键值对迭代对象
>>> d
{'eggs': 2, 'cheese': 'cheddar', 'aardvark': 'Ethel', 'spam': 999}

五、主流观点

5.1 字典合并不符合交换律

合并是符合交换律的，但是字典联合却没有（d | e != e | d）。

回应

Python 中有过不符合交换律的合并先例：

1
2
3
4

>>> {0} | {False}
{0}
>>> {False} | {0}
{False}

上述结果虽然是相等的，但是本质是不同的。通常来说，a | b 和 b | a 并不相同。

5.2 字典合并并不高效

类似管道写法使用多次字典合并并不高效，比如 d | e | f | g | h 会创建和销毁三个临时映射。

回应

这种问题在序列级联时同样会出现。

序列级联的每一次合并都会使序列中的元素总数增加，最终会带来 O(N^2) 的性能开销。而字典合并有可能会有重复键，因此临时映射的大小并不会如此快速地增长。

正如我们很少将大量的列表或元组连接在一起一样，PEP的作者任务合并大量的字典也是少见情况。若是确实有这样的诉求，那么最好使用显式的循环和就地合并：

1
2
3

new = {}
for d in many_dicts:
    new |= d

5.3 字典合并是有损的

字典合并可能会丢失数据（相同键的值可能消失），其他形式的合并并不会。

回应

作者并不觉得这种有损是一个问题。此外，dict.update 也会发生这种情况，但并不会丢弃键，这其实是符合预期的。只不过是现在使用的不是 update 而是 |。

如果从不可逆的角度考虑，其他类型的合并也是有损的。假设 a | b 的结果是365，那么 a 和 b 是多少却不得而知。

5.4 只有一种方法达到目的

字典合并不符合“Only One Way”的禅宗。

回应

其实并没有这样的禅宗。“Only One Way”起源于很早之前Perl社区对Python的诽谤。

5.5 超过一种方法达到目的

好吧，禅宗并没有说“Only One Way To Do It”。但是它明确禁止“超过一种方法达到目的”。

回应

并没有这样的禁止。Python 之禅仅表达了对“仅一种显而易见的方式”的偏爱。

1
2

There should be one-- and preferably only one --obvious way to do
it.

它的重点是应该有一种明显的方式达到目的。对于字典更新操作来说，我们可能希望至少执行两个不同的操作：

• 就地更新字典：显而易见的方式是使用 update() 方法。如果此提案被接受，|= 扩展赋值操作符也将等效，但这是扩展赋值如何定义的副作用。选择哪种取决于使用者口味。
• 合并两个现存的字典到新字典中：此提案中显而易见的方法是使用 | 合并操作符。

实际上，Python 里经常违反对“仅一种方式”的偏爱。例如，每个 for 循环都可以重写为 while 循环；每个 if 块都可以写为 if/else 块。列表、集合和字典推导都可以用生成器表达式代替。列表提供了不少于五种方法来实现级联：

• 级联操作符：a + b
• 就地级联操作符：a + = b
• 切片分配：a[len(a):] = b
• 序列解压缩：[*a, *b]
• 扩展方法：a.extend(b)

我们不能太教条主义，不能因为它违反了“仅一种方式”就非常严格的拒绝有用的功能。

5.6 字典合并让代码更难理解

字典合并让人们更难理解代码的含义。为了解释该异议，而不是具体引用任何人的话：“在看到 spam | eggs，如果不知道 spam 和 eggs 是什么，根本就不知道这个表达式的作用”。

回应

这确实如此，即使没有该提案，| 操作符的现状也是如此：

• 对于 int/bool 是按位或
• 对于 set/forzenset 是并集
• 还可能是任何其他的重载操作

添加字典合并看起来并不会让理解代码变得更困难。确定 spam 和 eggs 是映射类型并不比确定是集合还是整数要花更多的工作。其实良好的命名约定将会有助于改善情况：

1
2
3

flags |= WRITEABLE  # 可能就是数字的按位或
DO_NOT_RUN = WEEKENDS | HOLIDAYS  # 可能就是集合合并
settings = DEFAULT_SETTINGS | user_settings | workspace_settings  # 可能就是字典合并

5.7 参考下完整的集合API

字典和集合很相似，应该要支持集合所支持的操作符：|、&、^ 和 -。

回应

也许后续会有PEP来专门说明这些操作符如何用于字典。简单来说：

把集合的对称差集（^）操作用在字典上面是显而易见且自然。比如：

1
2

>>> d1 = {"spam": 1, "eggs": 2}
>>> d2 = {"ham": 3, "eggs": 4}

对于 d1 和 d2 对称差集，我们期望 d1 ^ d2 应该是 {"spam": 1, "ham": 3}

把集合的差集（-）操作用在字典上面也是显而易见和自然的。比如 d1 和 d2 的差集，我们期望：

• d1 - d2 为 {"spam": 1}
• d2 - d1 为 {"ham": 3}

把集合的交集（&）操作用在字典上面就有些问题了。虽然很容易确定两个字典中键的交集，但是如何处理键所对应的值就比较模糊。不难看出 d1 和 d2 的共同键是 eggs，如果我们遵循“后者胜出”的一致性原则，那么值就是 4。

六、已拒绝的观点

PEP 584 提案中罗列了很多已拒绝的观点，比如使用 + 来合并字典；在合并字典时也合并值类型为列表的值等等。这些观点都非常有意思，被拒绝的理由也同样有说服力。限于篇幅的原因不再进一步展开，感兴趣的可以阅读 https://www.python.org/dev/peps/pep-0584/#id34。

七、实现

7.1 纯 Python 实现

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

def __or__(self, other):
    if not isinstance(other, dict):
        return NotImplemented
    new = dict(self)
    new.update(other)
    return new

def __ror__(self, other):
    if not isinstance(other, dict):
        return NotImplemented
    new = dict(other)
    new.update(self)
    return new

def __ior__(self, other):
    dict.update(self, other)
    return self

纯 Python 实现并不复杂，我们只需让 dict 实现几个魔法方法：

• __or__ 和 __ror__ 魔法方法对应于 | 操作符，__or__ 表示对象在操作符左侧，__ror__ 表示对象在操作符右侧。实现就是根据左侧操作数生成一个新字典，再把右侧操作数更新到新字典中，并返回新字典。
• __ior__ 魔法方法对应于 |= 操作符，将右侧操作数更新到自身即可。

7.2 CPython 实现

CPython 中字典合并的详细实现可见此 PR： https://github.com/python/cpython/pull/12088/files 。

最核心的实现如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

// 实现字典合并生成新字典的逻辑，对应于 | 操作符
static PyObject *
dict_or(PyObject *self, PyObject *other)
{
    if (!PyDict_Check(self) || !PyDict_Check(other)) {
        Py_RETURN_NOTIMPLEMENTED;
    }
    PyObject *new = PyDict_Copy(self);
    if (new == NULL) {
        return NULL;
    }
    if (dict_update_arg(new, other)) {
        Py_DECREF(new); // 减少引用计数
        return NULL;
    }
    return new;
}

// 实现字典就地合并逻辑，对应于 |= 操作符
static PyObject *
dict_ior(PyObject *self, PyObject *other)
{
    if (dict_update_arg(self, other)) {
        return NULL;
    }
    Py_INCREF(self); // 增加引用计数
    return self;
}

CPython 的实现逻辑和纯Python实现几乎一样，唯独需要注意的就是引用计数的问题，这关系到对象的垃圾回收。

八、总结

PEP 584 是一个非常精彩的提案，引入 | 和 |= 操作符用作字典合并，看似是一个比较简单的功能，但所要考虑的情况却不少。不仅需要说明这个提案的背景，目前有哪些方式可以达到目的，它们有哪些痛点；还要考虑对既有类型引入操作符所带来的各种影响，对开发者提出的质疑和顾虑进行思考和解决。整个提案所涉及到的方法论、思考维度、知识点都非常值得学习。

对使用者来说，合并字典将会变得更加方便。在提案的最后，作者给出了许多第三方库在合并字典时采用新方式编写的例子，可谓是简洁了不少。详见 https://www.python.org/dev/peps/pep-0584/#id50 。

昨天发现了一款非常不错的云系统架构原型图制作库 Diagrams，通过它，我们便可以使用代码的方式绘制诸如阿里云、AWS、Azure、K8S 等系统架构原型图。

相比于在 UI 上对各种图标进行拖拽和调整，这种方式更符合我们程序员的使用习惯。

本文不仅要介绍下这个库，也想说说我是如何参与到这个库中以支持阿里云资源。

二、安装

Diagrams 使用 Graphviz 来渲染图表，在安装 diagrams 之前需要先安装 Graphviz。

macOS 用户（如果使用 Homebrew）可以使用 brew install graphviz 的方式来安装 Graphviz。

安装 diagrams 的方式有多种，通过 pip、pipenv 和 poetry 均可：

1
2
3
4
5
6
7
8

# 使用 pip (pip3)
$ pip install diagrams

# 使用 pipenv
$ pipenv install diagrams

# 使用 poetry
$ poetry add diagrams

三、快速开始

1
2
3
4
5
6
7
8

# diagram.py
from diagrams import Diagram
from diagrams.alibabacloud.network import SLB
from diagrams.alibabacloud.compute import ECS
from diagrams.alibabacloud.database import RDS

with Diagram("Web Service", show=False):
    SLB("lb") >> ECS("web") >> RDS("userdb")

执行后，就能生成如下架构图：

1

$ python diagram.py

四、指南

Diagrams 库非常容易掌握，我们仅需要掌握三个概念就能轻松绘制云系统架构图：

• Diagram：这是表示图的最主要的对象，代表一个架构图
• Node：表示一个节点或系统组件，比如快速开始中的SLB、ECS和RDS都是架构图中的节点
• Cluster：表示集群或分组，可将多个节点放到一个集群中

4.1 图 Diagram

使用 Diagram 类来创建图环境上下文，使用 with 语法来使用这个上下文。Diagram 的第一个参数是会被用作架构图的名称以及输出的图片文件名（转换为小写+下划线）。

1
2
3
4
5

from diagrams import Diagram
from diagrams.aws.compute import EC2

with Diagram("Simple Diagram"):
    EC2("web")

运行上述代码，会生成一个包含 EC2 节点的架构图，并存放在当前的 simple_diagram.png 中。

Diagram 类还支持如下参数：

• outformat：指定输出图片的类型，默认是 png，可以是 png、jpg、svg 和 pdf
• show：指定是否显示图片，默认是 False
• graph_attr、node_attr 和 edge_attr：指定 Graphviz 属性选项，用来控制图、点、线的样式，详情查看 参考链接

4.2 节点 Node

目前，Diagrams 支持五类云资源节点，分别是 AWS、Azure、AlibabaCloud、GCP 和 K8S。

节点之间的关系使用操作符来表示，分别是：

• >>：左节点指向右节点
• <<：右节点指向左节点
• -：节点互相连接，没有方向

以下是一个例子：

1
2
3
4
5
6
7
8
9
10

from diagrams import Diagram
from diagrams.aws.compute import EC2
from diagrams.aws.database import RDS
from diagrams.aws.network import ELB
from diagrams.aws.storage import S3

with Diagram("Web Services", show=False):
    ELB("lb") >> EC2("web") >> RDS("userdb") >> S3("store")
    ELB("lb") >> EC2("web") >> RDS("userdb") << EC2("stat")
    (ELB("lb") >> EC2("web")) - EC2("web") >> RDS("userdb")

Diagrams 不仅支持单个节点的关系建立，还支持一组节点和其他节点的关系建立，使用 list 来表示一组节点。示例如下：

1
2
3
4
5
6
7
8
9
10
11

from diagrams import Diagram
from diagrams.aws.compute import EC2
from diagrams.aws.database import RDS
from diagrams.aws.network import ELB

with Diagram("Grouped Workers", show=False, direction="TB"):
    ELB("lb") >> [EC2("worker1"),
                  EC2("worker2"),
                  EC2("worker3"),
                  EC2("worker4"),
                  EC2("worker5")] >> RDS("events")

4.3 集群/组 Cluster

当我们需要在架构图上表示几个节点属于一个集群时，就要用到 Cluster。和 Diagram 的使用方式类似，它也是一个上下文管理器，使用 with 语法。
示例如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

from diagrams import Cluster, Diagram
from diagrams.aws.compute import ECS
from diagrams.aws.database import RDS
from diagrams.aws.network import Route53

with Diagram("Simple Web Service with DB Cluster", show=False):
    dns = Route53("dns")
    web = ECS("service")

    with Cluster("DB Cluster"):
        db_master = RDS("master")
        db_master - [RDS("slave1"),
                     RDS("slave2")]

    dns >> web >> db_master

Diagrams 还支持嵌套集群，只需嵌套使用 with Cluster() 即可：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

from diagrams import Cluster, Diagram
from diagrams.aws.compute import ECS, EKS, Lambda
from diagrams.aws.database import Redshift
from diagrams.aws.integration import SQS
from diagrams.aws.storage import S3

with Diagram("Event Processing", show=False):
    source = EKS("k8s source")

    with Cluster("Event Flows"):
        with Cluster("Event Workers"):
            workers = [ECS("worker1"),
                       ECS("worker2"),
                       ECS("worker3")]

        queue = SQS("event queue")

        with Cluster("Processing"):
            handlers = [Lambda("proc1"),
                        Lambda("proc2"),
                        Lambda("proc3")]

    store = S3("events store")
    dw = Redshift("analytics")

    source >> workers >> queue >> handlers
    handlers >> store
    handlers >> dw

五、我是如何贡献代码

看到 Diagrams 库时，我感到很兴奋。我们画示意图无外乎两种，一种是通过UI来画，一种是通过DSL来制作。在流程图、时序图方面，PlantUML 是我很喜欢的 DSL，然而在云系统架构图方面，过去确实没发现相关的库，直到看到了 Diagrams。

在我看到 Diagrams 时，它还只是支持 AWS、Azure、GCP 和 K8S，我心想怎么能没有阿里云呢？这么好的库我岂不是用不了了。既然如此，不如自己动手，丰衣足食吧。阅读 Diagrams 的代码，会发现写的还真不错，代码清晰简单，还提供了完善的脚手架。

对于它所支持的云供应商（比如 AWS），当我们想更新里面的资源时，只需要在 resources/aws 文件夹中更新资源图片，然后执行 ./autogen.sh 即可。./autogen.sh 会对 resources/ 做这么几件事：

• 将特定云供应商的 svg 图片转换为 png
• 将特定云供应商的图片调整为圆角图片
• 自动生成节点类代码
• 自动生成文档
• 使用 black 格式化自动生成的代码

对于它所不支持的云供应商（比如 AlibabaCloud），则要先修改脚手架和配置文件以支持新的云供应商，然后遵循上面的方法即可。具体改动内容可见 此 PR。

参与一个开源项目其实就是这么简单，当你发现满足不了你的需求时，就阅读它的源码以了解实现原理，然后再自己动手实现需求，最后就是向作者提个 PR。

在近半年的 Python 命令行旅程中，我们依次学习了 argparse、docopt、click 和 fire 库的特点和用法，逐步了解到 Python 命令行库的设计哲学与演变。
本文作为本次旅程的终点，希望从一个更高的视角对这些库进行横向对比，总结它们的异同点和使用场景，以期在应对不同场景时能够分析利弊，选择合适的库为己所用。

1
2

本系列文章默认使用 Python 3 作为解释器进行讲解。
若你仍在使用 Python 2，请注意两者之间语法和库的使用差异哦~

二、设计理念

在讨论各个库的设计理念之前，我们先设计一个计算器程序，其实这个例子在 argparse 库的第一篇讲解中出现过，也就是：

• 命令行程序接受一个位置参数，它能出现多次，且是数字
• 默认情况下，命令行程序会求出给定的一串数字的最大值
• 如果指定了选项参数 --sum，那么就会将求出给定的一串数字的和

希望从各个库实现该例子的代码中能进一步体会它们的设计理念。

2.1、argparse

argparse 的设计理念就是提供给你最细粒度的控制，你需要详细地告诉它参数是选项参数还是位置参数、参数值的类型是什么、该参数的处理动作是怎样的。
总之，它就像是一个没有智能分析能力的初代机器人，你需要告诉它明确的信息，它才会根据给定的信息去帮助你做事情。

以下示例为 argparse 实现的 计算器程序：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

import argparse

# 1. 设置解析器
parser = argparse.ArgumentParser(description='Calculator Program.')

# 2. 定义参数
# 添加位置参数 nums，在帮助信息中显示为 num
# 其类型为 int，且支持输入多个，且至少需要提供一个
parser.add_argument('nums',  metavar='num', type=int, nargs='+',
                    help='a num for the accumulator')
# 添加选项参数 --sum，该参数被 parser 解析后所对应的属性名为 accumulate
# 若不提供 --sum，默认值为 max 函数，否则为 sum 函数
parser.add_argument('--sum', dest='accumulate', action='store_const',
                    const=sum, default=max,
                    help='sum the nums (default: find the max)')


# 3. 解析参数
args = parser.parse_args(['--sum', '1', '2', '3'])
print(args) # 结果：Namespace(accumulate=<built-in function sum>, nums=[1, 2, 3])

# 4. 业务逻辑
result = args.accumulate(args.nums)
print(result)  # 基于上文的 ['--sum', '1', '2', '3'] 参数，accumulate 为 sum 函数，其结果为 6

从上述示例可以看到，我们需要通过 add_argument 很明确地告诉 argparse 参数长什么样：

• 它是位置参数 nums，还是选项参数 --sum
• 它的类型是什么，比如 type=int 表示类型是 int
• 这个参数能重复出现几次，比如 nargs='+' 表示至少提供 1 个
• 参数的是存什么的，比如 action='store_const' 表示存常量

然后它才根据给定的这些元信息来解析命令行参数（也就是示例中的 ['--sum', '1', '2', '3']）。

这是很计算机的思维，虽然冗长，但也带来了灵活性。

2.2、docopt

从 argparse 的理念可以看出，它是命令式的。这时候 docopt 另辟蹊径，声明式是不是也可以？一个命令行程序的帮助信息其实已然包含了这个命令行的完整元信息，那不就可以通过定义帮助信息来定义命令行？docopt 就是基于这样的想法去设计的。

声明式的好处在于只要你掌握了声明式的语法，那么定义命令行的元信息就会很简单。

以下示例为 docopt 实现的 计算器程序：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

# 1. 定义接口描述/帮助信息
"""Calculator Program.

Usage:
  calculator.py [--sum] <num>...
  calculator.py (-h | --help)

Options:
  -h --help     Show help.
  --sum         Sum the nums (default: find the max).
"""

from docopt import docopt

# 2. 解析命令行
arguments = docopt(__doc__, options_first=True, argv=['--sum', '1', '2', '3'])
print(arguments) # 结果：{'--help': False, '--sum': True, '<num>': ['1', '2', '3']}

# 3. 业务逻辑
nums = (int(num) for num in arguments['<num>'])

if arguments['--sum']:
    result = sum(nums)
else:
    result = max(nums)

print(result) # 基于上文的 ['--sum', '1', '2', '3'] 参数，处理函数为 sum 函数，其结果为 6

从上述示例可以看到，我们通过 __doc__ 定义了接口描述，这和 argparse 中 add_argument 是等价的，然后 docopt 便会根据这个元信息把命令行参数转换为一个字典。业务逻辑中就需要对这个字典进行处理。

对比与 argparse：

• 对于更为复杂的命令程序，元信息的定义上 docopt 会更加简单
• 然而在业务逻辑的处理上，由于 argparse 在一些简单参数的处理上会更加便捷（比如示例中的情形），相对来说 docopt 转换为字典后就把所有处理交给业务逻辑的方式会更加复杂

2.3、click

命令行程序本质上是定义参数和处理参数，而处理参数的逻辑一定是与所定义的参数有关联的。那可不可以用函数和装饰器来实现处理参数逻辑与定义参数的关联呢？而 click 正好就是以这种使用方式来设计的。

click 使用装饰器的好处就在于用装饰器优雅的语法将参数定义和处理逻辑整合在一起，从而暗示了路由关系。相比于 argparse 和 docopt 需要自行对解析后的参数来做路由关系，简单了不少。

以下示例为 click 实现的 计算器程序：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

import sys
import click

sys.argv = ['calculator.py', '--sum', '1', '2', '3']

# 2. 定义参数
@click.command()
@click.argument('nums', nargs=-1, type=int)
@click.option('--sum', 'use_sum', is_flag=True, help='sum the nums (default: find the max)')
# 1. 业务逻辑
def calculator(nums, use_sum):
    """Calculator Program."""
    print(nums, use_sum) # 输出：(1, 2, 3) True
    if use_sum:
        result = sum(nums)
    else:
        result = max(nums)

    print(result) # 基于上文的 ['--sum', '1', '2', '3'] 参数，处理函数为 sum 函数，其结果为 6

calculator()

从上述示例可以看出，参数和对应的处理逻辑非常好地绑定在了一起，看上去就很直观，使得我们可以明确了解参数会怎么处理，这在有大量参数时显得尤为重要，这边是 click 相比于 argparse 和 docopt 最明显的优势。

此外，click 还内置了很多实用工具和额外能力，比如说 Bash 补全、颜色、分页支持、进度条等诸多实用功能，可谓是如虎添翼。

2.4、fire

fire 则是用一种面向广义对象的方式来玩转命令行，这种对象可以是类、函数、字典、列表等，它更加灵活，也更加简单。你都不需要定义参数类型，fire 会根据输入和参数默认值来自动判断，这无疑进一步简化了实现过程。

以下示例为 click 实现的 计算器程序：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

import sys
import fire

sys.argv = ['calculator.py', '1', '2', '3', '--sum']

builtin_sum = sum

# 1. 业务逻辑
# sum=False，暗示它是一个选项参数 --sum，不提供的时候为 False
# *nums 暗示它是一个能提供任意数量的位置参数
def calculator(sum=False, *nums):
    """Calculator Program."""
    print(sum, nums) # 输出：True (1, 2, 3)
    if sum:
        result = builtin_sum(nums)
    else:
        result = max(nums)

    print(result) # 基于上文的 ['1', '2', '3', '--sum'] 参数，处理函数为 sum 函数，其结果为 6


fire.Fire(calculator)

从上述示例可以看出，fire 提供的方式无疑是最简单、并且最 Pythonic 的了。我们只需关注业务逻辑，而命令行参数的定义则和函数参数的定义融为了一体。

不过，有利自然也有弊，比如 nums 并没有说是什么类型，也就意味着输入字符串’abc’也是合法的，这就意味着一个严格的命令行程序必须在自己的业务逻辑中来对期望的类型进行约束。

三、横向对比

最后，我们横向对比下argparse、docopt、click 和 fire 库的各项功能和特点：

Python 的命令行库种类繁多、各具特色。结合上面的总结，可以选择出符合使用场景的库，如果几个库都符合，那么就根据你更偏爱的风格来选择。这些库都很优秀，其背后的思想很是值得我们学习和扩展。

相关文章

• Python 命令行之旅：初探 argparse
• Python 命令行之旅：深入 argparse（一）
• Python 命令行之旅：深入 argparse（二）
• Python 命令行之旅：使用 argparse 实现 git 命令
• Python 命令行之旅：初探 docopt
• Python 命令行之旅：深入 docopt
• Python 命令行之旅：使用 docopt 实现 git 命令
• Python 命令行之旅：初探 click
• Python 命令行之旅：深入 click（一）
• Python 命令行之旅：深入 click（二）
• Python 命令行之旅：深入 click（三）
• Python 命令行之旅：深入 click（四）
• Python 命令行之旅：使用 click 实现 git 命令
• Python 命令行之旅：初探 fire
• Python 命令行之旅：深入 fire（一）
• Python 命令行之旅：深入 fire（二）
• Python 命令行之旅：使用 fire 实现 git 命令
• Python 命令行之旅：argparse、docopt、click 和 fire 总结篇
• Python 命令行大乱斗

2019 年底开始蔓延的新型肺炎疫情牵动人心，作为个体，我们力所能及的就是尽量待在家中少出门。

看到一些朋友叫设计同学帮忙给自己的头像戴上口罩，作为技术人，心想一定还有更多人有这样的诉求，不如开发一个简单的程序来实现这个需求，也算是帮助设计姐姐减少工作量。

于是花了些时间，写了一个叫做 face-mask 的命令行工具，能够轻松的给图片中的人像戴上口罩，而且口罩的方向和大小都是适应人脸的哦~

使用

安装 face-mask

确保 Python 版本在 3.6 及以上

1

pip install face-mask

使用 face-mask

直接指定图片路径即可为图片中的人像戴上口罩，并会生成一个新的图片（额外有 -with-mask 后缀）：

1

face-mask /path/to/face/picture

通过指定 --show 选项，还可以使用默认图片查看器打开新生成的图片：

1

face-mask /path/to/face/picture --show

效果

给一个人戴上口罩

给多个人戴上口罩

给动漫人物戴上口罩

实现

思路

要想实现上面的效果，我们应该怎么做？不妨这么想：

• 首先是识别出人的鼻子(nose_bridge)和脸轮廓(chin)
• 通过脸轮廓确定出脸左点（chin_left_point）、脸底点（chin_bottom_point）和脸右点（chin_right_point）
• 由鼻子和脸底点确定口罩大小的高度、中心线
• 将口罩左右平均分为两个部分
  • 调整左口罩大小，宽度为脸左点到中心线的距离
  • 调整右口罩大小，宽度为脸右点到中心线的距离
  • 合并左右口罩为新口罩
• 旋转新口罩，角度为中心线相对于 y 轴的旋转角
• 将新口罩放在原图适当位置

关于人脸识别，可以使用 face_recognition 库进行识别。

关于图像处理，可以使用 Pillow 库进行处理。

代码

有了思路之后，实现就是件相对轻松的事情。不过对库的熟悉和图片的变换计算可能要花些时间。

详细的代码请阅读 face-mask。这里仅说明下最核心的步骤。

人脸识别

1
2
3
4

import face_recognition

face_image_np = face_recognition.load_image_file('/path/to/face/picture')
face_landmarks = face_recognition.face_landmarks(face_image_np)

借助 face_recognition 库可以轻松的识别出人像，最终得到的 face_landmarks 是一个列表，里面的每个 face_landmark 都表示一个人像数据。

face_landmark 是一个字典，其中的键表示人像特征，值表示该特征的点的列表。比如：

• 键 nose_bridge 表示鼻梁
• 键 chin 表示脸颊

我们需要根据每个 face_landmark，给对应的头像戴上口罩。

获得鼻子和脸颊的特征点

1
2
3
4
5
6
7
8
9
10
11
12

import numpy as np

nose_bridge = face_landmark['nose_bridge']
nose_point = nose_bridge[len(nose_bridge) * 1 // 4]
nose_v = np.array(nose_point)

chin = face_landmark['chin']
chin_len = len(chin)
chin_bottom_point = chin[chin_len // 2]
chin_bottom_v = np.array(chin_bottom_point)
chin_left_point = chin[chin_len // 8]
chin_right_point = chin[chin_len * 7 // 8]

通过上述代码，我们获得了：

• 表示上鼻梁的一个点 nose_point
• 表示脸左点 chin_left_point
• 表示脸右点 chin_right_point
• 表示脸底点 chin_bottom_point

拆分、缩放和合并口罩

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

from PIL import Image

_face_img = Image.fromarray(face_image_np)
_mask_img = Image.open('/path/to/mask/picture')

# split mask and resize
width = _mask_img.width
height = _mask_img.height
width_ratio = 1.2
new_height = int(np.linalg.norm(nose_v - chin_bottom_v))

# left
mask_left_img = _mask_img.crop((0, 0, width // 2, height))
mask_left_width = get_distance_from_point_to_line(chin_left_point, nose_point, chin_bottom_point)
mask_left_width = int(mask_left_width * width_ratio)
mask_left_img = mask_left_img.resize((mask_left_width, new_height))

# right
mask_right_img = _mask_img.crop((width // 2, 0, width, height))
mask_right_width = get_distance_from_point_to_line(chin_right_point, nose_point, chin_bottom_point)
mask_right_width = int(mask_right_width * width_ratio)
mask_right_img = mask_right_img.resize((mask_right_width, new_height))

# merge mask
size = (mask_left_img.width + mask_right_img.width, new_height)
mask_img = Image.new('RGBA', size)
mask_img.paste(mask_left_img, (0, 0), mask_left_img)
mask_img.paste(mask_right_img, (mask_left_img.width, 0), mask_right_img)

上述代码主要做了如下内容：

• 将口罩左右平均分为两个部分
• 调整左口罩大小，宽度为脸左点到中心线的距离 * 宽度系数 1.2
• 调整右口罩大小，宽度为脸右点到中心线的距离 * 宽度系数 1.2
• 合并左右口罩为新口罩

get_distance_from_point_to_line 用来获取一个点到一条线的距离，具体实现可看源代码。

width_ratio 是宽度系数，用来适当扩大口罩。原因我们是根据脸颊的宽度计算口罩的宽度，但口罩是待在耳朵上的，真实宽度应该要更宽。

旋转口罩、并放到原图适当位置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

# rotate mask
angle = np.arctan2(chin_bottom_point[1] - nose_point[1], chin_bottom_point[0] - nose_point[0])
rotated_mask_img = mask_img.rotate(angle, expand=True)

# calculate mask location
center_x = (nose_point[0] + chin_bottom_point[0]) // 2
center_y = (nose_point[1] + chin_bottom_point[1]) // 2

offset = mask_img.width // 2 - mask_left_img.width
radian = angle * np.pi / 180
box_x = center_x + int(offset * np.cos(radian)) - rotated_mask_img.width // 2
box_y = center_y + int(offset * np.sin(radian)) - rotated_mask_img.height // 2

# add mask
_face_img.paste(mask_img, (box_x, box_y), mask_img)

上述代码主要做了如下内容：

• 旋转新口罩，角度为中心线相对于 y 轴的旋转角
• 计算口罩应该放置的坐标
• 将新口罩放在原图的计算出的坐标下

最后就是将新图片保存到本地路径，代码不再展示。

总结

我们借助 face_recognition 库可以轻松的识别出人像，然后根据脸颊的宽度和鼻梁位置计算出口罩的大小、方向和位置，并最终生成出戴上口罩的图片。整个过程并不复杂，但在坐标计算上要格外小心，如此，我们便打造了一个短小精悍的“自动戴上口罩”程序！

Python 的 “is” 和 “==” 想必大家都不陌生，我们在比较变量和字面量时常常用到它们，可是它们的区别在哪里？什么情况下该用 is？什么情况下该用 ==？这成了不少人心中的困惑。

当我们判断一个变量是否为 None 时，通常会用 is:

1
2
3
4
5
6

>>> a = None
>>> a is None
True
>>> b = 1
>>> b is None
False

而当我们判断一个变量是否为字面量（比如某个数值）时，通常会用 ==:

1
2
3
4
5

>>> a = 0
>>> a == 0
True
>>> a == 1
False

要想解决上面的疑惑，我们首先需要搞明白 is 和 == 是什么。

“is” 和 “==” 是什么

is 用来检查身份（identity）的同一性，即两个变量是否指向同一个对象。

== 用来检查值的相等性（equality），即两个变量的值是否相等。

身份的同一性同时也意味值的相等性，既然两个都指向同一个对象，那值就肯定相等。但是反之则不是。

__eq__ 魔法方法

既然 == 是用来检查值的相等性，那么两个对象的值比较究竟是怎么进行的？

对于基本类型的对象的值比较，我们很容易理解。比如列表对象 [1, 2, 3] 的值比较就是比较列表的长度和列表中每个元素的值。

但是对于自定义的对象，该如何进行值比较？这里就涉及到了 __eq__(self, other) 魔法方法，我们可以通过该方法来实现对象的 == 逻辑。比如：

1
2
3
4
5
6
7
8
9
10
11

>>> class Foo(object):
...   def __eq__(self, other):
...     return True
...
>>> foo = Foo()
>>> foo == 1
True
>>> foo == None
True
>>> foo is None
False

在上面的示例中，我们定义了 Foo 类，并实现了 __eq__(self, other) 方法，它永远返回 True，也就意味着和任何对象做值比较（==）结果都是 True。而当它做同一性比较时，比如和 None 比较，由于不是同一个对象，所以返回 False。

场景示例

示例一：指向同一个对象的变量比较

1
2
3
4
5
6

>>> a = [1, 2, 3]
>>> b = a  # b 指向 a，a 指向 [1, 2, 3]，所以 b 指向同一个 [1, 2, 3]
>>> b is a
True
>>> b == a
True

在上述示例中 a 和 b 均指向同一个列表对象 [1, 2, 3]，所以对它们使用 is 和 ==，结果都是 True。

示例二：指向不同对象（但值相同）的变量比较

1
2
3
4
5
6

>>> a = [1, 2, 3]
>>> b = a[:]  # b 复制了一份 a 所指向的列表，产生新的 [1, 2, 3]
>>> b is a
False
>>> b == a
True

在上述示例中，由于 b 指向的是 a 的副本，也就是说 a 和 b 指向两个不同的对象，所以对它们使用 is 的结果是 False。但由于值相等，使用 == 的结果就是 True。

示例三：指向字面量的变量比较

1
2
3
4
5
6
7
8
9
10
11
12
13
14

>>> a = 256
>>> b = 256  # 和 a 指向同一字面量 256
>>> a is b  # 表明指向同一对象
True
>>> a == b
True
>>>
>>> a = 257
>>> b = 257
>>> a == b
True
>>> a is b  # 表明指向不同对象
False
>>>

通常来说，两个变量指向字面量，它们的比较应该使用 ==，而非 is，否则就可能有类似上述示例中的困惑。

在 Python 的交互解释器中，把可能频繁使用的整数对象规定在范围 [-5, 256] 之间，当它们创建好后就会被缓存下来。但凡是需要再用到它们时，就会从缓存中取，而不是重新创建对象。

• 当 a 和 b 都指向同一个字面量 256 时，a is b 返回 True。这是因为声明 b = 256 时，256 整数对象是从缓存中取的，而非重新创建，所以 a 和 b 指向同一个整数对象。
• 当 a 和 b 都指向同一个字面量 257 时，a is b 返回 False。这是因为声明 b = 257 时，257 整数对象没被缓存，是重新创建的，所以 a 和 b 指向不同的整数对象。

同理，如果字面量是字符串，结果也类似。

1
2
3
4
5
6
7
8
9
10
11
12

>>> a = 'python.org'
>>> b = 'python.org'
>>> a is b
False
>>> a == b
True
>>> a = 'pythonorg'
>>> b = 'pythonorg'
>>> a is b
True
>>> a == b
True

Python 3.8 引入 is 比较字面量时报 SyntaxWarning

鉴于使用 is 比较字面量其实是不正确的，在 Python 3.8 的 release notes 中，引入如下内容：

The compiler now produces a SyntaxWarning when identity checks (is and is not) are used with certain types of literals (e.g. strings, numbers). These can often work by accident in CPython, but are not guaranteed by the language spec. The warning advises users to use equality tests (== and !=) instead. (Contributed by Serhiy Storchaka in bpo-34850.)

因此，当我们使用 is 去比较数字、字符串等字面量时，就会报 SyntaxWarning：

1
2
3
4
5

>>> x = 200
>>> x is 200
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
SyntaxWarning: "is" with a literal. Did you mean "=="?

总结

说了这么多，其实我们只需要记住如下两点：

• 当要比较值是否相等时，请用 ==。
• 当要比较是否是同一个对象时，请用 is。

本周没有新鲜事儿。

好文共赏

2020 年后的软件开发人员趋势

Python 进度条 tqdm 示例

进度条是程序开发中一个不可获取的功能，网上关于 Python 进度条库 tqdm 的示例说的并不友好，本文将深入浅出地带你如何使用 tqdm 实现进度条功能。

为什么 Python 3.8 给 “is” 打印 SyntaxWarning？

对比 Python、Go 和 C++ 的 N 皇后问题

Python 当前是机器学习领域的主导语言，但经常因执行某些任务的速度慢而受到批评。在本文中，我们使用著名的 N 皇后难题作为基准，来说明一旦使用 Numba 编译器进行编译，它就可以在执行速度上与 C 和 Go 竞争，同时还可以非常快速地制作原型。

使用 codemod 将 unittest 断言转换为 Python 断言

大型代码库需要持续维护，但是更改分布在多个文件中的代码既费时又麻烦。本文展示了如何通过 codemod 借助抽象语法树来重构 Python 代码——相比于基本的正则和搜索替换，控制粒度要更细。

Python 游戏框架指南

在本循序渐进的教程中，您将学习如何使用 arcade，一种现代的 Python 框架，制作具有引人入胜的图形和声音的游戏。 Arcade 是针对 Python 3.6 及更高版本而构建的面向对象的库，为您提供了一套现代的工具，可提供出色的 Python 游戏体验。

编写多语言脚本

Python 和 Ruby 的语法有些相似，您能否想出一个在两种语言中均有效的程序？

高效使用 MatPlotlib

我已经花了一些时间来学习 Python 可视化的一些工具以及如何将其与 matplotlib 一起使用，我开始将 matplotlib 视为必不可少的工具。 这篇文章将展示我如何使用 matplotlib 并为用户入门提供一些建议。

科学计算 Python：使用 SciPy 进行优化

了解 SciPy 生态系统及与 SciPy 库的区别。您将学习如何使用 Anaconda 或 pip 安装 SciPy，并查看其一些模块。 然后您将重点关注使用 SciPy 中的群集和优化功能的示例。

open() 和 CPython 的意外结果

滥用 Python 的 open()， 以及 CPython 的 GC 和 UNIX 语言的互相作用，可能会导致意外结果。

找点 Python 的乐子

编写混乱的代码，除了可以获得乐趣，也是绝佳的学习体验。

改善代码的 5 个重构建议

编写安全的 repr()

赞视频

Python 中的基本数据类型

在本课程中，您将学习 Python 内置的基本数据类型，例如数字、字符串和布尔值，以及 Python 内置函数的概览。

酷开源

pypistats

PyPI 下载统计。

Sentry

实时日志记录和聚合服务端。

celery

基于分布式消息的异步任务队列。

SaltStack

基础设施自动化和管理系统。

Paramiko

SSHv2 协议的 Python (2.6+, 3.3+) 实现，同时提供客户端和服务端功能。

DiskCache

使用 SQLite 和文件作为后端缓存，比 memcached 和 redis 的查询都要快。

tmuxp

💻 基于 libtmux 的 tmux 会话管理器。

sql2json

运行查询并将结果转换为 json 的 Python 工具。

python-hunter

一个灵活的代码追踪工具。

CrossHair

用于 Python 的静态分析工具，模糊了测试系统和类型系统之间的界限。

speck

将图像渲染为一组连续的（水平或垂直）像素线。

在前面三篇介绍 fire 的文章中，我们全面了解了 fire 强大而不失简洁的能力。按照惯例，我们要像使用 argparse、docopt 和 click 一样使用 fire 来实现 git 命令。

本文的关注点并不在 git 的各种命令是如何实现的，而是怎么使用 fire 去打造一个实用命令行程序，代码结构是怎样的。因此，和 git 相关的操作，将会使用 gitpython 库来简单实现。

为了让没读过 使用 xxx 实现 git 命令（xxx 指 argparse、docopt 和 click） 的小伙伴也能读明白本文，我们仍会对 git 常用命令和 gitpython 做一个简单介绍。

1
2

本系列文章默认使用 Python 3 作为解释器进行讲解。
若你仍在使用 Python 2，请注意两者之间语法和库的使用差异哦~

二、git 常用命令

当你写好一段代码或增删一些文件后，会用如下命令查看文件状态：

1

git status

确认文件状态后，会用如下命令将的一个或多个文件（夹）添加到暂存区：

1

git add [pathspec [pathspec ...]]

然后使用如下命令提交信息：

1

git commit -m "your commit message"

最后使用如下命令将提交推送到远程仓库：

1

git push

我们将使用 fire 和 gitpython 库来实现这 4 个子命令。

三、关于 gitpython

gitpython 是一个和 git 仓库交互的 Python 第三方库。
我们将借用它的能力来实现真正的 git 逻辑。

安装：

1

pip install gitpython

四、思考

在实现前，我们不妨先思考下会用到 fire 的哪些功能？整个程序的结构是怎样的？

fire

git 的 4 个子命令的实现其实对应于四个函数，我们可以都放到一个类中，实现四个实例方法。
而对于 git add 命令，需要接受任意个参数，在实例方法中用 *pathspecs 参数来表达。
对于 git commit 命令，需要接受 -m 选项，在实例方法中用 m 参数来表达。

程序结构

程序结构上：

• 实例化 Git 对象，供全局使用
• 在 GitCli 类中定义四个命令对应的实例方法 status、add、commit、push

则基本结构如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

import os
import fire
from git.cmd import Git

git = Git(os.getcwd())

class GitCli:
    def status(self):
        """
        处理 status 命令
        """
        pass

    def add(self, *pathspecs):
        """
        处理 add 命令
        """
        pass

    def commit(self, m):
        """
        处理 -m <msg> 命令
        """
        pass

    def push(self):
        """
        处理 push 命令
        """
        pass


if __name__ == '__main__':
    fire.Fire(GitCli())

下面我们将一步步地实现我们的 git 程序。

五、实现

假定我们在 fire-git.py 文件中实现我们的 git 程序。

5.1 status 子命令

status 子命令不接受任何参数和选项，因此 status 方法无需任何入参。

1
2
3
4
5
6
7
8

class GitCli:
    def status(self):
        """
        处理 status 命令
        """
        cmd = ['git', 'status']
        output = git.execute(cmd)
        return output

不难看出，我们最后调用了真正的 git status 来实现，并打印了输出。

5.2 add 子命令

add 子命令相对于 status 子命令，需要接受任意个 pathspec 参数，因此 add 方法需要增加 *pathspecs 入参。
fire 最终传入的是一个元组，我们需要将其转换成 list 以便后续处理。

1
2
3
4
5
6
7
8

class GitCli:
    def add(self, *pathspecs):
        """
        处理 add 命令
        """
        cmd = ['git', 'add'] + list(pathspecs)
        output = git.execute(cmd)
        return output

当我们执行 python3 fire-git.py add --help 时，结果如下：

1
2
3
4
5
6
7
8
9
10
11
12
13

INFO: Showing help with the command 'fire-git.py add -- --help'.

NAME
    fire-git.py add - 处理 add 命令

SYNOPSIS
    fire-git.py add [PATHSPECS]...

DESCRIPTION
    处理 add 命令

POSITIONAL ARGUMENTS
    PATHSPECS

5.3 commit 子命令

commit 子命令相对于 status 子命令，需要接受 -m 选项，因此 commit 方法需要增加 m 入参。

1
2
3
4
5
6
7
8

class GitCli:
    def commit(self, m):
        """
        处理 -m <msg> 命令
        """
        cmd = ['git', 'commit', '-m', m]
        output = git.execute(cmd)
        return output

5.4 push 子命令

push 子命令同 status 子命令一样，不接受任何参数和选项，因此 push 方法无需任何入参。

1
2
3
4
5
6
7
8

class GitCli:
    def push(self):
        """
        处理 push 命令
        """
        cmd = ['git', 'push']
        output = git.execute(cmd)
        return output

至此，我们就实现了一个简单的 git 命令行，使用 python fire-git.py status 便可查询项目状态。

非常方便的是，每个命令函数的 docstring 都将作为这个命令的帮助信息，因此，当我们执行 python3 fire-git.py --help 会自动生成如下帮助内容：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

INFO: Showing help with the command 'fire-git.py -- --help'.

NAME
    fire-git.py

SYNOPSIS
    fire-git.py COMMAND

COMMANDS
    COMMAND is one of the following:

     add
       处理 add 命令

     commit
       处理 -m <msg> 命令

     push
       处理 push 命令

     status
       处理 status 命令

想看整个源码，请戳 fire-git.py 。

六、小结

本文简单介绍了日常工作中常用的 git 命令，然后提出实现它的思路，最终一步步地使用 fire 和 gitpython 实现了 git 程序。

对比 argparse、docopt 和 click 的实现版本，你会发现使用 fire 来实现是最简单的：

• 相较于 argparse，子解析器、参数类型什么的统统不需要关心
• 相较于 docopt，参数解析和命令调用处理也不需要关心
• 相较于 click，装饰器所定义的命令行参数信息也必须要关心

无疑，fire 把能简化的都简化了，简直就是懒人福音。

关于 fire 的讲解将告一段落，回顾下 fire 的至简之道，你会深爱上它。这也体现出了 Python 之美。

现在，你已学会了四个特点各异的主流命令行解析库的使用了，再也不需要为命令行程序的实现而烦恼了。

什么，你为要使用哪一个库而发愁？在下一篇也是最后一篇文章中，我们将对这些库做一个横向对比，以对什么场景下使用什么样的命令行库了然于胸~

相关文章

• Python 命令行之旅：初探 argparse
• Python 命令行之旅：深入 argparse（一）
• Python 命令行之旅：深入 argparse（二）
• Python 命令行之旅：使用 argparse 实现 git 命令
• Python 命令行之旅：初探 docopt
• Python 命令行之旅：深入 docopt
• Python 命令行之旅：使用 docopt 实现 git 命令
• Python 命令行之旅：初探 click
• Python 命令行之旅：深入 click（一）
• Python 命令行之旅：深入 click（二）
• Python 命令行之旅：深入 click（三）
• Python 命令行之旅：深入 click（四）
• Python 命令行之旅：使用 click 实现 git 命令
• Python 命令行之旅：初探 fire
• Python 命令行之旅：深入 fire（一）
• Python 命令行之旅：深入 fire（二）
• Python 命令行之旅：使用 fire 实现 git 命令
• Python 命令行之旅：argparse、docopt、click 和 fire 总结篇
• Python 命令行大乱斗

Python 2 已退休

老爹 Guido van Rossum 退出 Python 指导委员会

好文共赏

Python 类型注解

本文将全面介绍 mypy，通过许多示例演示了这种类型检查器的语法和功能。

Flask8 规则

Flake8 中的所有规则的说明和示例。

在 Python 中使用 Rust 变得简单

对于需要性能提升的计算密集型任务，可以由 Rust 来实现逻辑，然后在 Python 中调用。本文将介绍如何实现这个过程。

借助 NASA 图片和 Python 制作月亮视频

手把手教你如果通过 Python 和数张 NASA 的月亮图片制作月亮视频。

让 Python 程序闪电般迅速

讨厌 Python 的人总是说，他们不想使用它的原因之一是它很慢。 嗯，特定的程序（无论使用何种编程语言）是快还是慢，很大程度上取决于编写该程序的开发人员以及编写优化的快速的程序的技能和能力。 因此，让我们证明一些人是错误的，让我们看看如何改善 Python 程序的性能并使它们真正更快！

如何将 Flask 与 gevent 一起使用（uWSGI 和 Gunicorn 版本）

创建异步 Flask 应用程序，并在 Nginx 反向代理后面使用 uWSGI 或 Gunicorn 来运行它。

使用 Jupyter 开发机器人

这篇文章展示了 Jupyter 生态系统中可用的工具，在 Jupyter Notebooks 中构建高级可视化并使用 Voilá 转换为独立的 Web 应用程序，以及如何将这些应用程序部署到机器人云中。

我没有感受到 async 的压力

如今异步风靡一时，异步 Python、异步 Rust、Go、Node、.NET，选择您喜欢的生态系统，它有些异步操作。这种异步操作的工作原理在很大程度上取决于语言的生态系统和运行时，但总体而言，它具有一些不错的好处。这使事情变得非常简单：异步等待（await）可能需要一些时间才能完成的操作。它是如此简单，以至于创造了无数新的方法来“打击”人。我要讨论的是在系统超载之前您还没有意识到自己可能采坑的情况，也就是背压管理。在协议设计中，的一个相关术语叫做流量控制。

Python 之禅的思考

Python 计时器功能：监视代码的三种方法

了解如何使用 Python 计时器功能来监视程序的运行速度。您将使用类、上下文管理器和装饰器来测量程序的运行时间。 您将了解每种方法的优点以及在特定情况下可以使用的方法。

开源迁移的困扰

Flask 的创建者介绍了 Python 2 到 3 的迁移以及 Python 社区如何处理过渡。有趣的内容！

赞视频

Python 老爹在牛津联盟的访谈

Numba 让 Python 快上 1000 倍!

在此视频中，我介绍了您需要了解的有关 Numba 的最低要求，Numba 是针对 Python 和 Numpy 子集的即时编译器。 该视频的前半部分做了基本介绍，并着重介绍了人们在使用 Numba 时常犯的一些错误。后半部分提出了一个现实世界中的模拟问题，在单线程和多线程情况下，使用 Numba 最多可加速 1000 倍。最后给出一个“阅读清单”作为结尾，以了解有关 Numba 的更多信息。

酷开源

Saleor

使用 Python、GraphQL、Django 和 ReactJS 构建的模块化、高性能的电子商务网站。

Peewee

一个小巧、富有表现力的 ORM —— 支持 PostgreSQL、MySQL 和 SQLite。

Poetry

让 Python 的依赖项管理和打包变得容易。

django-split-settings

将 Django 设置分散到多个文件和目录中，能够轻松覆盖和修改设置。

GINO

GINO 递归定义为 GINO Is Not ORM，是一个基于 asyncio 和 SQLAlchemy core 的轻量级异步 Python ORM 框架，目前（2020 年初）仅支持 asyncpg 一种引擎。

QuTiP

Python 中的量子工具箱。

ObsPy

用于处理地震数据的 Python 框架。

Kornia

PyTorch 的开源可区分计算机视觉库。

Typer

基于 Python 类型注解的 CLI 库，能够简单地创建 CLI 程序。

klaxon

从终端或 Python 程序中发送 Mac OS 通知。

ffmpeg-python

FFmpeg 的 Python 绑定，支持复杂的过滤

Traffic-Signal-Violation-Detection-System

使用 YOLOv3 和 Tkinter 实现的基于计算机视觉的交通信号违规检测系统。

pylightxl

轻量级、零依赖、最简功能的 excel 读/写 Python 库。

XSS Finder

大型、高级的跨站点脚本扫描程序。

Magic Wormhole

安全地将内容从一台计算机转移到另一台计算机上。

在上一篇文章中我们介绍了 fire 的子命令、嵌套命令和属性访问等内容，今天我们将继续深入了解 fire 的其他功能。

1
2

本系列文章默认使用 Python 3 作为解释器进行讲解。
若你仍在使用 Python 2，请注意两者之间语法和库的使用差异哦~

二、功能

2.1 最简命令实现

在上一节中，我们介绍了只要定义一个函数就可以实现命令行程序。比如：

1
2
3
4
5
6
7
8
9
10

import fire

def english():
  return 'Hello, fire!'

def chinese():
  return '你好，fire！'

if __name__ == '__main__':
  fire.Fire()

但这还不是最简单的实现方式，fire 甚至允许你通过定义变量的方式来实现命令行！
上面的例子可以写成下面这种形式：

1
2
3
4
5
6
7

import fire

english = 'Hello, fire!'
chinese = '你好，fire！'

if __name__ == '__main__':
  fire.Fire()

2.2 链式调用

在 Fire CLI 中，你可以通过链式调用不断地对上一个结果进行处理。

想做到这一点也很简单，就是在实例方法中返回 self 即可。

在下面的示例中，我们实现了一个简单的四则运算命令，可链式调用 add、sub、mul 和 div。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

import fire

class Calculator:

  def __init__(self):
    self.result = 0
    self.express = '0'

  def __str__(self):
    return f'{self.express} = {self.result}'

  def add(self, x):
    self.result += x
    self.express = f'{self.express}+{x}'
    return self

  def sub(self, x):
    self.result -= x
    self.express = f'{self.express}-{x}'
    return self

  def mul(self, x):
    self.result *= x
    self.express = f'({self.express})*{x}'
    return self

  def div(self, x):
    self.result /= x
    self.express = f'({self.express})/{x}'
    return self

if __name__ == '__main__':
  fire.Fire(Calculator)

上述代码中的 add、sub、mul、div 分别对应加、减、乘、除的逻辑，每个方法都接受 x 参数作为参与运算的数字，返回值均为 self，这样就可以无限次地链式调用。在命令行中链式调用结束后，会最终调用到 __str__ 方法将结果打印出来。

其中，__str__ 在 fire 中用来完成自定义序列化。如果不提供这个方法，在链式调用完成后将会打印帮助内容。

比如，我们可以这么调用：

1
2
3
4
5

$ python calculator.py add 1 sub 2 mul 3 div 4
((+1-2)*3)/4 = -0.75

$ python calculator.py add 1 sub 2 mul 3 div 4 add 4 sub 3 mul 2 div 1
((((0+1-2)*3)/4+4-3)*2)/1 = 0.5

2.3 位置参数和选项参数

通过前面的介绍我们也都清楚了在 fire 中不必显式的定义位置参数或选项参数。

通过下面的例子，我们将细化两类参数的使用：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

import fire

class Building(object):

  def __init__(self, name, stories=1):
    self.name = name
    self.stories = stories

  def __str__(self):
    return f'name: {self.name}, stories: {self.stories}'

  def climb_stairs(self, stairs_per_story=10):
    yield self.name
    for story in range(self.stories):
      for stair in range(1, stairs_per_story):
        yield stair
      yield 'Phew!'
    yield 'Done!'

if __name__ == '__main__':
  fire.Fire(Building)

• 构造函数中定义的参数（如 name 和 stories）在命令行中仅为选项参数（如 --name 和 --stories）。我们可以这么调用：

1

$ python example.py --name="Sherrerd Hall" --stories=3

• 构造函数中定义的参数可在命令中放于任意位置。比如下面两个调用都是可以的：

1
2

$ python example.py --name="Sherrerd Hall" climb-stairs --stairs-per-story 10
$ python example.py climb-stairs --stairs-per-story 10 --name="Sherrerd Hall"

• 构造函数和普通方法中定义的默认参数（如 stories），在命令行中是可选的。我们可以这么调用：

1

$ python example.py --name="Sherrerd Hall"

• 普通方法中定义的参数（如 stairs_per_story）在命令行中即可以是位置参数，也可以是选项参数。我们可以这么调用：

1
2
3
4

# 作为位置参数
$ python example.py --name="Sherrerd Hall" climb_stairs 10
# 作为选项参数
$ python example.py --name="Sherrerd Hall" climb_stairs --stairs_per_story=10

• 选项参数中的横杠（-）和下划线（_）是等价的。因此也可以这么调用：

1
2

# 作为选项参数
$ python example.py --name="Sherrerd Hall" climb_stairs --stairs-per-story=10

此外，fire 还支持在函数中定义 *args 和 **kwargs。

1
2
3
4
5
6
7
8
9
10
11

import fire

def fargs(*args):
  return str(args)


def fkwargs(**kwargs):
  return str(kwargs)

if __name__ == '__main__':
  fire.Fire()

• 函数中的 *args 在命令行中为位置参数。我们可以这么调用：

1

$ python example.py fargs a b c

• 函数中的 **kwargs 在命令行中为选项参数。我们可以这么调用：

1

$ python example.py fargs --a a1 --b b1 --c c1

• 通过分隔符 - 可显式告知分隔符后的为子命令，而非命令的参数。且看下面的示例：

1
2
3
4
5
6
7

# 没有使用分隔符，upper 被作为位置参数
$ python example.py fargs a b c upper
('a', 'b', 'c', 'upper')

# 使用了分隔符，upper 被作为子命令
$ python example.py fargs a b c - upper
('A', 'B', 'C')

• 通过 fire 内置的 --separator 可以自定义分隔符，此选项参数需要跟在单独的 -- 后面：

1
2

$ python example.py a b c X upper -- --separator=X
('A', 'B', 'C')

2.4 参数类型

在 fire 中，参数的类型由其值决定，通过下面的简单代码，我们可以看到给不同的值时，fire会解析为什么类型：

1
2

import fire
fire.Fire(lambda obj: type(obj).__name__)

1
2
3
4
5
6
7
8
9
10
11
12
13
14

$ python example.py 10
int
$ python example.py 10.0
float
$ python example.py hello
str
$ python example.py '(1,2)'
tuple
$ python example.py [1,2]
list
$ python example.py True
bool
$ python example.py {name: David}
dict

如果想传递字符串形式的数字，那就需要小心引号了，要么把引号引起来，要么转义引号：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

# 数字 10
$ python example.py 10
int
# 没有对引号处理，仍然是数字10
$ python example.py "10"
int
# 把引号引起来，所以是字符串“10”
$ python example.py '"10"'
str
# 另一种把引号引起来的形式
$ python example.py "'10'"
str
# 转义引号
$ python example.py \"10\"
str

考虑下更复杂的场景，如果传递的是字典，在字典中有字符串，那么也是要小心引号的：

1
2
3
4
5
6
7
8
9
10
11
12

# 推荐做法
$ python example.py '{"name": "David Bieber"}'
dict
# 也是可以的
$ python example.py {"name":'"David Bieber"'}
dict
# 错误，会被解析为字符串
$ python example.py {"name":"David Bieber"}
str
# 错误，不会作为单个参数（因为中间有空格），报错
$ python example.py {"name": "David Bieber"}
<error>

如果值为 True 或 False 将为视为布尔值，fire 还支持通过 --name 将 name 设为 True，或通过 --noname 将 name 设为 False：

1
2
3
4
5
6
7
8

$ python example.py --obj=True
bool
$ python example.py --obj=False
bool
$ python example.py --obj
bool
$ python example.py --noobj
bool

2.5 Fire 内置选项参数

Fire 内置了一些选项参数，以帮助我们更容易地使用命令行程序。若想使用内置的选项功能，需要将选项参数跟在 -- 后，在上文中，我们介绍了 --separator 参数，除了它，fire 还支持以下选项参数：

• command -- --help 列出详细的帮助信息
• command -- --interactive 进入交互式模式
• command -- --completion [shell] 生成 CLI 程序的自动补全脚本，以支持自动补全
• command -- --trace 获取命令的 Fire 追踪以了解调用 Fire 后究竟发生了什么
• command -- --verbose 获取包含私有成员在内的详情

三、小结

fire 让命令行程序的实现变得特别简单，本文着重介绍了它的链式调用、选项参数、位置参数、参数类型以及内置选项参数。fire 的概念并不多，真正践行了“把简单留给他人，把复杂留给自己”的理念。

fire 的介绍就告一段落，它绝对会是你编写命令行程序的一大利器。在下一篇文章中，我们依然会通过实现一个简单的 git 程序来进行 fire 的实战。

相关文章

• Python 命令行之旅：初探 argparse
• Python 命令行之旅：深入 argparse（一）
• Python 命令行之旅：深入 argparse（二）
• Python 命令行之旅：使用 argparse 实现 git 命令
• Python 命令行之旅：初探 docopt
• Python 命令行之旅：深入 docopt
• Python 命令行之旅：使用 docopt 实现 git 命令
• Python 命令行之旅：初探 click
• Python 命令行之旅：深入 click（一）
• Python 命令行之旅：深入 click（二）
• Python 命令行之旅：深入 click（三）
• Python 命令行之旅：深入 click（四）
• Python 命令行之旅：使用 click 实现 git 命令
• Python 命令行之旅：初探 fire
• Python 命令行之旅：深入 fire（一）
• Python 命令行之旅：深入 fire（二）
• Python 命令行之旅：使用 fire 实现 git 命令
• Python 命令行之旅：argparse、docopt、click 和 fire 总结篇
• Python 命令行大乱斗

本周没有新鲜事儿~

好文共赏

ASGI 简介：异步 Python Web 生态系统的出现

如果您认为 Python 已陷入数据科学领域，请再考虑一遍！有了 async 特性，Python Web 开发又回来了，这很令人兴奋。

2020 年发布 Python 应用程序的 12 种趋势替代方案

2019 年 Python 生态中最流行的主题之一是打包和分发。 随着一年的结束，我想总结一下我们目前可用于分发 Python 应用程序的方式，其中一些也适用于任何语言。

通过 NumPy、SciPy 和 Pandas 玩转相关性

了解什么是相关性以及如何使用 Python 计算相关性。本文将介绍使用 SciPy、NumPy 和 Pandas 相关方法来计算三个不同的相关系数，还会介绍如何使用 Matplotlib 可视化数据、回归线和相关矩阵。

Python 性能技巧

各类提升 Python 程序性能的技巧。

如何让 Python 等待

对于许多类型的应用程序，有时需要暂停程序的运行，直到发生某些外部情况为止。 我们需要找出一种让脚本等待的方法，这要想正确地做起来并不像听起来那样简单！在本文中，我将向您展示几种不同的等待方式。 我将在所有示例中使用 Python，这个概念也适用于所有编程语言。

使用 PyHamcrest 进行精确的单元测试

Hamcrest 是一个 Python 框架，旨在使测试断言更易于编写和更加精确。

Python import 语句权威指南

如何在 Python 2 和 3 中解决常见的导入问题。

将 Raspberry Pi 4 设置为 iPad Pro 的开发机器

为了 ML 模型服务，将 Flask 移植到 FastAPI

Flask 因其简单性而是一个非常流行的 Web 框架，用于在 Python 中构建 REST API，尤其是服务于机器学习模型。 在本文中，我们将学习如何迁移到更新的 FastAPI 框架，以利用类型检查和异步编程的优势。

全栈 NLP：构建和部署端到端虚假新闻分类器

这是一个有关构建 NLP 文本分类 Web 应用程序并将其部署到生产环境的教程。

视频搜索引擎—我的计算机视觉之旅

制作视频很容易，但是谁会有时间观看所有视频？我想出一个视频搜索引擎，用来查找想要的瞬间，并提供了原型。

一个简单的 Web 服务是如何工作的

非常简单的 Python：处理文件

关于文件处理，基本用法和坑都在这里。

赞视频

Python 字典迭代：高级技巧

字典是 Python 中最重要和有用的数据结构，能帮助解决各类问题。本课程将带你深入了解如何迭代字典。

使用 Python 在终端中绘制动画圣诞树

做了一个圣诞节特别的编程项目 —— 制作在终端上运行的动画圣诞树。 有时编程可能很有趣，就比如这个。

酷开源

nlp-recipes

自然语言处理的最佳实践和示例。

assembly

基于 Flask 的 Pythonic OOP Web 框架。

PrettyErrors

让 Python 的异常输出变得更优雅。

typical

快速、简单、正确的利用 Python 3 类型注解的数据校验库。

labelme

Python 的图像多边形注释（多边形、矩形、圆形、直线、点和图像级标记注释）。

Checkov

Checkov 是用于基础结构即代码的静态代码分析工具。它扫描使用 Terraform 设置的云基础架构，检测安全性和合规性错误配置。

NewsPie

一个由 Flask 构建并由 News API 支持的简约新闻聚合器。

pix-to-xls

一个可以将图像转换为 excel 彩色单元格的简单工具。

Silver

masscan 速度很快、nmap 可以提取软件指纹、而 vulners 是一个巨大的漏洞数据库。Silver 是一个允许完整使用这些程序能力的前端，它可以通过解析数据、生成并行进程、缓存漏洞数据来进行更快的扫描，且不止于此。

apispec

可插拔的 API 规范生成器，目前支持 OpenAPI 规范（又称 Swagger 规范）。

arcade

易于使用的用于创建 2D 街机游戏的 Python 库。

在第一篇“初探 fire”的文章中，我们初步掌握了使用 fire 的简单步骤，了解了它 Pythonic 的用法。

今天我们将深入了解 fire 的子命令、嵌套命令和属性访问功能。

1
2

本系列文章默认使用 Python 3 作为解释器进行讲解。
若你仍在使用 Python 2，请注意两者之间语法和库的使用差异哦~

二、功能

2.1 子命令

使用 fire 实现子命令有多种方式：

2.1.1 定义若干函数，使用 fire.Fire()

实现子命令最简单的方式就是定义若干个函数，每个函数名隐式就是子命令名称，然后调用 fire.Fire() 变将当前模块所有的函数解析为对应的子命令的处理函数。

1
2
3
4
5
6
7
8
9
10

import fire

def add(x, y):
  return x + y

def multiply(x, y):
  return x * y

if __name__ == '__main__':
  fire.Fire()

然后我们就可以在命令行中这么调用：

1
2
3
4

$ python example.py add 10 20
30
$ python example.py multiply 10 20
200

关于如何识别参数类型，比如上述 add 10 20 中 10 和 20 是作为数字而非字符串，我们会在下篇文章的参数解析章节中进行讲解。

2.1.2 定义若干函数，使用 fire.Fire()

在 2.1.1 的版本中，会把所有函数都当做是子命令。有时我们可能只想把部分函数当做子命令，或者是希望子命令名称和函数名称不一样。这个时候我们就可以通过字典对象显式地告诉 fire。

字典对象的形式为 {'子命令名称': 函数}，比如前面的示例中，我们希望最终的子命令为 add 和 mul，那么就可以这么写：

1
2
3
4

fire.Fire({
  'add': add,
  'mul': multiply,
})

然后我们就可以在命令行中这么调用：

1
2
3
4

$ python example.py add 10 20
30
$ python example.py mul 10 20
200

2.1.3 定义类和方法，使用 fire.Fire(

定义类和方法的这种方式我们在上一篇文章中介绍过，它和定义函数的方式基本相同，只不过是用类的方式来组织。

然后将类实例化，并把实例化的对象多为 fire.Fire 的入参：

1
2
3
4
5
6
7
8
9
10
11
12
13

import fire

class Calculator(object):

  def add(self, x, y):
    return x + y

  def multiply(self, x, y):
    return x * y

if __name__ == '__main__':
  calculator = Calculator()
  fire.Fire(calculator)

2.1.4 定义类和方法，使用 fire.Fire()

和 2.1.3 中的唯一不同点是把类而非实例对象作为 fire.Fire 的入参：

1

fire.Fire(Calculator)

传递类和实例对象的基本作用是一样的，但传递类还有一个额外的特性：如果构造函数中定义了参数，那么这些参数都会作为整个命令行程序的选项参数。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

import fire

class BrokenCalculator(object):

  def __init__(self, offset=1):
      self._offset = offset

  def add(self, x, y):
    return x + y + self._offset

  def multiply(self, x, y):
    return x * y + self._offset

if __name__ == '__main__':
  fire.Fire(BrokenCalculator)

查看帮助命令有：

1
2
3
4
5
6
7
8
9
10
11

$ python example.py --help
INFO: Showing help with the command 'example.py -- --help'.

NAME
    example.py

SYNOPSIS
    example.py <flags>

FLAGS
    --offset=OFFSET

由此可见构造函数 BrokenCalculator.__init__(self, offset=1) 中的 offset 自动转换为了命令行中的全局选项参数 --offset，且默认值为 1。

我们可以在命令行中这么调用：

1
2
3
4
5
6
7
8

$ python example.py add 10 20
31
$ python example.py multiply 10 20
201
$ python example.py add 10 20 --offset=0
30
$ python example.py multiply 10 20 --offset=0
200

2.2 命令组/嵌套命令

想要实现嵌套命令，可将多个类组织起来，示例如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25