如何编写完美的 Python 命令行程序?

2019 年 1 月 19 日 CSDN

这篇文章将教你如何编写完美的 Python 命令行程序,提高团队的生产力,让大家的工作更舒适。

作者 | Yannick Wolff

译者 | 弯月

责编 | 屠敏

出品 | CSDN(ID:CSDNNews)

作为 Python 开发者,我们经常要编写命令行程序。比如在我的数据科学项目中,我要从命令行运行脚本来训练模型,以及计算算法的准确率等。

因此,更方便更易用的脚本能够很好地提高生产力,特别是在有多个开发者从事同一个项目的场合下。

因此,我建议你遵循以下四条规则:

  1. 尽可能提供默认参数值

  2. 所有错误情况必须处理(例如,参数缺失,类型错误,找不到文件)

  3. 所有参数和选项必须有文档

  4. 不是立即完成的任务应当显示进度条


举个简单的例子


我们把这些规则应用到一个具体的例子上。这个脚本可以使用凯撒加密法加密和解密消息。

假设已经有个写好的 encrypt 函数(实现如下),我们需要创建一个简单的脚本,用来加密和解密消息。我们希望让用户通过命令行参数选择加密模式(默认)和解密模式,并选择一个秘钥(默认为 1)。

def encrypt(plaintext, key):
    cyphertext = ''
    for character in plaintext:
        if character.isalpha():
            number = ord(character)
            number += key
            if character.isupper():
                if number > ord('Z'):
                    number -= 26
                elif number < ord('A'):
                    number += 26
            elif character.islower():
                if number > ord('z'):
                    number -= 26
                elif number < ord('a'):
                    number += 26
            character = chr(number)
        cyphertext += character

    return cyphertext


我们的脚本需要做的第一件事就是获取命令行参数的值。当我搜索“python command line arguments”时,出现的第一个结果是关于sys.argv的,所以我们来试试这个方法……


“初学者”的方法


sys.argv 是个列表,包含用户在运行脚本时输入的所有参数(包括脚本名自身)。

例如,如果我输入:

python caesar_script.py --key 23 --decrypt my secret message
pb vhfuhw phvvdjh


该列表将包含:

['caesar_script.py', '--key', '23', '--decrypt', 'my', 'secret', 'message'] 


因此只需遍历该参数列表,找到'--key'(或'-k')以得到秘钥值,找到'--decrypt'以设置解密模式(实际上只需要使用秘钥的反转作为秘钥即可)。

最后我们的脚本大致如下:

import sys

from caesar_encryption import encrypt


def caesar():
    key = 1
    is_error = False

    for index, arg in enumerate(sys.argv):
        if arg in ['--key''-k'and len(sys.argv) > index + 1:
            key = int(sys.argv[index + 1])
            del sys.argv[index]
            del sys.argv[index]
            break

    for index, arg in enumerate(sys.argv):
        if arg in ['--encrypt''-e']:
            del sys.argv[index]
            break
        if arg in ['--decrypt''-d']:
            key = -key
            del sys.argv[index]
            break

    if len(sys.argv) == 1:
        is_error = True
    else:
        for arg in sys.argv:
            if arg.startswith('-'):
                is_error = True

    if is_error:
        print(f'Usage: python {sys.argv[0]} [ --key <key> ] [ --encrypt|decrypt ] <text>')
    else:
        print(encrypt(' '.join(sys.argv[1:]), key))

if __name__ == '__main__':
    caesar()


这个脚本遵循了一些我们前面推荐的规则:

  1. 支持默认秘钥和默认模式

  2. 基本的错误处理(没有提供输入文本的情况,以及提供了无法识别的参数的情况)

  3. 出错时或者不带任何参数调用脚本时会显示文档:

python caesar_script_using_sys_argv.py
Usagepython caesar.py [ --key <key> ] [ --encrypt|decrypt ] <text>

但是,这个凯撒加密法脚本太长了(39 行,其中甚至还没包括加密代码本身),而且很难读懂。

解析命令行参数应该还有更好的办法……


试试 argparse?


argparse 是 Python 用来解析命令行参数的标准库。

我们来看看用 argparse 怎样编写凯撒加密的脚本:

import argparse

from caesar_encryption import encrypt


def caesar():
    parser 
= argparse.ArgumentParser()
    group = parser.add_mutually_exclusive_group()
    group.add_argument('-e''--encrypt', action='store_true')
    group.add_argument('-d''--decrypt', action='store_true')
    parser.add_argument('text', nargs='*')
    parser.add_argument('-k''--key', type=intdefault=1)
    args = parser.parse_args()

    text_string = ' '.join(args.text)
    key = args.key
    if args.decrypt:
        key = -key
    cyphertext = encrypt(text_string, key)
    print(cyphertext)

if __name__ == '__main__':
    caesar()


这段代码也遵循了上述规则,而且与前面的手工编写的脚本相比,可以提供更准确的文档,以及更具有交互性的错误处理:

python caesar_script_using_argparse.py --encode My message

usagecaesar_script_using_argparse.py [-h] [-e | -d] [-k KEY] [text [text ...]]
caesar_script_using_argparse.pyerrorunrecognized arguments--encode
python caesar_script_using_argparse.py --help

usagecaesar_script_using_argparse.py [-h] [-e | -d] [-k KEY] [text [text ...]]


positional arguments:
  text
optional arguments:
  -h, --help         show this help message and exit
  -e, --encrypt
  -d, --decrypt
  -k KEY, --key KEY


但是,仔细看了这段代码后,我发现(虽然有点主观)函数开头的几行(从7行到13行)定义了参数,但定义方式并不太优雅:它太臃肿了,而且完全是程式化的。应该有更描述性、更简洁的方法。


click 能做得更好!


幸运的是,有个 Python 库能提供与 argparse 同样的功能(甚至还能提供更多),它的代码风格更优雅。这个库的名字叫 click。

这里是凯撒加密脚本的第三版,使用了 click:

import click

from caesar_encryption import encrypt

@click.command()
@click.argument('text', nargs=-1)
@click.option('--decrypt/--encrypt''-d/-e')
@click.option('--key''-k'default=1)
def caesar(text, decrypt, key):
    text_string = ' '.join(text)
    if decrypt:
        key = -key
    cyphertext = encrypt(text_string, key)
    click.echo(cyphertext)

if __name__ == '__main__':
    caesar()


注意现在参数和选项都在修饰器里定义,定义好的参数直接作为函数参数提供。

我来解释一下上面代码中的一些地方:

  • 脚本参数定义中的nargs参数指定了该参数期待的单词的数目(一个用引号括起来的字符串算一个单词)。默认值是1。这里nargs=-1允许接收任意数目的单词。

  • --encrypt/--decrypt这种写法可以定义完全互斥的选项(类似于argparse中的add_mutually_exclusive_group函数),它将产生一个布尔型参数。

  • click.echo是该库提供的一个工具函数,它的功能与print相同,但兼容Python 2和Python 3,还有一些其他功能(如处理颜色等)。


添加一些隐秘性


这个脚本的参数(被加密的消息)应当是最高机密。而我们却要求用户直接在终端里输入文本,使得这些文本被记录在命令历史中,这不是很讽刺吗?

解决方法之一就是使用隐藏的提示。或者可以从输入文件中读取文本,对于较长的文本来说更实际一些。或者可以干脆让用户选择。

输出也一样:用户可以保存到文件中,也可以输出到终端。这样就得到了凯撒脚本的最后一个版本:

import click

from caesar_encryption import encrypt

@click.command()
@click.option(
    '--input_file',
    type=click.File('r'),
    help='File in which there is the text you want to encrypt/decrypt.'
         'If not provided, a prompt will allow you to type the input text.',
)
@click.option(
    '--output_file',
    type=click.File('w'),
    help='File in which the encrypted / decrypted text will be written.'
         'If not provided, the output text will just be printed.',
)
@click.option(
    '--decrypt/--encrypt',
    '-d/-e',
    help='Whether you want to encrypt the input text or decrypt it.'
)
@click.option(
    '--key',
    '-k',
    default=1,
    help='The numeric key to use for the caesar encryption / decryption.'
)
def caesar(input_file, output_file, decrypt, key):
    if input_file:
        text = input_file.read()
    else:
        text = click.prompt('Enter a text', hide_input=not decrypt)
    if decrypt:
        key = -key
    cyphertext = encrypt(textkey)
    if output_file:
        output_file.write(cyphertext)
    else:
        click.echo(cyphertext)

if __name__ == '__main__':
    caesar()

这个版本有什么新东西吗?

  • 首先,注意到我给每个参数选项都加了个help参数。由于脚本变得复杂了,help参数可以给脚本的行为添加一些文档。运行结果如下:

> python caesar_script_v2.py --help
Usage: caesar_script_v2.py [OPTIONS]
Options:
  --input_file FILENAME          File in which there is the text you want to encrypt/decrypt. If not provided, a prompt will allow you to type the input text.
  --output_file FILENAME         File in which the encrypted/decrypted text will be written. If not provided, the output text will just be printed.
  -d, --decrypt / -e, --encrypt  Whether you want to encrypt the input text or decrypt it.
  -k, --key INTEGER              The numeric key to use for the caesar encryption / decryption.
  --help                         Show this message and exit.
  • 两个新的参数:input_file 和 output_file,类型均为 click.File。该库能够用正确的模式打开文件,处理可能的错误,再执行函数。例如:

> python caesar_script_v2.py --decrypt --input_file wrong_file.txt
Usage: caesar_script_v2.py [OPTIONS]
Error: Invalid value for "--input_file": Could not open file: wrong_file.txt: No such file or directory
  • 正像help文本中解释的那样,如果没有提供input_file,就使用click.promp让用户直接在提示符下输入文本,在加密模式下这些文本是隐藏的。如下所示:

> python caesar_script_v2.py --encrypt --key 2
Enter a text: **************
yyy.ukectc.eqo


破解密文!


现在设想你是个黑客:你要解密一个用凯撒加密过的密文,但你不知道秘钥是什么。

最简单的策略就是用所有可能的秘钥调用解密函数 25 次,阅读解密结果,看看哪个是合理的。

但你很聪明,而且也很懒,所以你想让整个过程自动化。确定解密后的 25 个文本哪个最可能是原始文本的方法之一,就是统计所有这些文本中的英文单词的个数。这可以使用 PyEnchant 模块实现:

import click
import enchant

from caesar_encryption import encrypt

@click.command()
@click.option(
    '--input_file',
    type=click.File('r'),
    required=True,
)
@click.option(
    '--output_file',
    type=click.File('w'),
    required=True,
)
def caesar_breaker(input_file, output_file):
    cyphertext = input_file.read()
    english_dictionnary = enchant.Dict("en_US")
    max_number_of_english_words = 0
    for key in range(26):
        plaintext = encrypt(cyphertext, -key)
        number_of_english_words = 0
        for word in plaintext.split(' '):
            if word and english_dictionnary.check(word):
                number_of_english_words += 1
        if number_of_english_words > max_number_of_english_words:
            max_number_of_english_words = number_of_english_words
            best_plaintext = plaintext
            best_key = key
    click.echo(f'The most likely encryption key is {best_key}. It gives the following plaintext:\n\n{best_plaintext[:1000]}...')
    output_file.write(best_plaintext)

if __name__ == '__main__':
    caesar_breaker()

貌似运行得很不错,但别忘了,好的命令行程序还有个规则需要遵守:

4.A 不是立即完成的任务应当显示进度条。

示例中的文本包含10^4个单词,因此该脚本需要大约5秒才能解密。这很正常,因为它需要检查所有25个秘钥,每个秘钥都要检查10^4个单词是否出现在英文字典中。

假设你要解密的文本包括10^5个但IC,那么就要花费50秒才能输出结果,用户可能会非常着急。

因此我建议这种任务一定要显示进度条。特别是,显示进度条还非常容易实现。

下面是个显示进度条的例子:

import click
import enchant

from tqdm import tqdm

from caesar_encryption import encrypt

@click.command()
@click.option(
    '--input_file',
    type=click.File('r'),
    required=True,
)
@click.option(
    '--output_file',
    type=click.File('w'),
    required=True,
)
def caesar_breaker(input_file, output_file):
    cyphertext = input_file.read()
    english_dictionnary = enchant.Dict("en_US")
    best_number_of_english_words = 0
    for key in tqdm(range(26)):
        plaintext = encrypt(cyphertext, -key)
        number_of_english_words = 0
        for word in plaintext.split(' '):
            if word and english_dictionnary.check(word):
                number_of_english_words += 1
        if number_of_english_words > best_number_of_english_words:
            best_number_of_english_words = number_of_english_words
            best_plaintext = plaintext
            best_key = key
    click.echo(f'The most likely encryption key is {best_key}. It gives the following plaintext:\n\n{best_plaintext[:1000]}...')
    output_file.write(best_plaintext)

if __name__ == '__main__':
    caesar_breaker()

你发现区别了吗?可能不太好找,因为区别真的很小,只有四个字母:tqdm。

tqdm 是 Python 库的名字,也是它包含的类的名字。只需用它包裹一个可迭代的东西,就能显示出进度条:

for key in tqdm(range(26)):

这样就能显示出非常漂亮的进度条。我都不敢相信这是真的。

另外,click也提供类似的显示进度条的工具(click.progress_bar),但我觉得它的外观不太容易懂,而且要写的代码也多一些。

我希望这篇文章能让你在改进开发者的体验上多花点时间。

原文:https://blog.sicara.com/perfect-python-command-line-interfaces-7d5d4efad6a2

作者:Yannick Wolff,Sicara 的数据科学家。

本文为 CSDN 翻译,如需转载,请注明来源出处。

 热 文 推 荐 

☞ MongoDB 凉了?

☞ 和 C++ 相比,我为什么要选择 Rust 来开发软件?

☞ 如何设计一个实用的线程池?

“对不起,你的离职是我的错!”

 Gartner的预言:通向混合IT之旅

☞ 阿里“菜鸟”AI?

☞ 刚刚!华为又被美国盯上了!

☞ 心疼!能为程序员男友做些什么吗?

print_r('点个好看吧!');
var_dump('点个好看吧!');
NSLog(@"点个好看吧!");
System.out.println("点个好看吧!");
console.log("点个好看吧!");
print("点个好看吧!");
printf("点个好看吧!");
cout << "点个好看吧!" << endl;
Console.WriteLine("点个好看吧!");
fmt.Println("点个好看吧!");
Response.Write("点个好看吧!");
alert("点个好看吧!")
echo "点个好看吧!"

点击“阅读原文”,打开 CSDN App 阅读更贴心!

喜欢就点击“好看”吧


登录查看更多
5

相关内容

Python是一种面向对象的解释型计算机程序设计语言,在设计中注重代码的可读性,同时也是一种功能强大的通用型语言。
【2020新书】实战R语言4,323页pdf
专知会员服务
97+阅读 · 2020年7月1日
【实用书】学习用Python编写代码进行数据分析,103页pdf
专知会员服务
188+阅读 · 2020年6月29日
【实用书】Python机器学习Scikit-Learn应用指南,247页pdf
专知会员服务
255+阅读 · 2020年6月10日
专知会员服务
165+阅读 · 2020年6月4日
【干货书】机器学习Python实战教程,366页pdf
专知会员服务
329+阅读 · 2020年3月17日
用 Python 开发 Excel 宏脚本的神器
私募工场
26+阅读 · 2019年9月8日
一个牛逼的 Python 调试工具
机器学习算法与Python学习
15+阅读 · 2019年4月30日
GitHub 热门:别再用 print 输出来调试代码了
Python开发者
27+阅读 · 2019年4月24日
百闻不如一码!手把手教你用Python搭一个Transformer
大数据文摘
18+阅读 · 2019年4月22日
实战 | 用Python做图像处理(三)
七月在线实验室
15+阅读 · 2018年5月29日
实战 | 用Python做图像处理(二)
七月在线实验室
17+阅读 · 2018年5月25日
用Python调用百度OCR接口实例
数据挖掘入门与实战
16+阅读 · 2018年1月29日
如何运用Python建一个聊天机器人?
七月在线实验室
17+阅读 · 2018年1月23日
教你用Python来玩跳一跳
七月在线实验室
6+阅读 · 2018年1月2日
用python和Tesseract实现光学字符识别(OCR)
Python程序员
7+阅读 · 2017年7月18日
Arxiv
29+阅读 · 2020年3月16日
A Comprehensive Survey on Transfer Learning
Arxiv
117+阅读 · 2019年11月7日
Object detection on aerial imagery using CenterNet
Arxiv
6+阅读 · 2019年8月22日
Deep Learning for Generic Object Detection: A Survey
Arxiv
13+阅读 · 2018年9月6日
A Survey on Deep Transfer Learning
Arxiv
11+阅读 · 2018年8月6日
Arxiv
7+阅读 · 2018年6月19日
VIP会员
相关VIP内容
【2020新书】实战R语言4,323页pdf
专知会员服务
97+阅读 · 2020年7月1日
【实用书】学习用Python编写代码进行数据分析,103页pdf
专知会员服务
188+阅读 · 2020年6月29日
【实用书】Python机器学习Scikit-Learn应用指南,247页pdf
专知会员服务
255+阅读 · 2020年6月10日
专知会员服务
165+阅读 · 2020年6月4日
【干货书】机器学习Python实战教程,366页pdf
专知会员服务
329+阅读 · 2020年3月17日
相关资讯
用 Python 开发 Excel 宏脚本的神器
私募工场
26+阅读 · 2019年9月8日
一个牛逼的 Python 调试工具
机器学习算法与Python学习
15+阅读 · 2019年4月30日
GitHub 热门:别再用 print 输出来调试代码了
Python开发者
27+阅读 · 2019年4月24日
百闻不如一码!手把手教你用Python搭一个Transformer
大数据文摘
18+阅读 · 2019年4月22日
实战 | 用Python做图像处理(三)
七月在线实验室
15+阅读 · 2018年5月29日
实战 | 用Python做图像处理(二)
七月在线实验室
17+阅读 · 2018年5月25日
用Python调用百度OCR接口实例
数据挖掘入门与实战
16+阅读 · 2018年1月29日
如何运用Python建一个聊天机器人?
七月在线实验室
17+阅读 · 2018年1月23日
教你用Python来玩跳一跳
七月在线实验室
6+阅读 · 2018年1月2日
用python和Tesseract实现光学字符识别(OCR)
Python程序员
7+阅读 · 2017年7月18日
Top
微信扫码咨询专知VIP会员