15.5 optparse 模块—— 命令行选项的解析器
description(default:None)
注意:从2.7版本后不再使用:optparse模块不推荐使用,python不再更新该模块,后续的发展将推荐使用argparse模块。
支持python2.3及以上版本
optparse模块比旧的getopt模块具有更方便、更灵活、功能更强大的解析命令行选项的库。optparse使用一种更加
声明式的命令行解析风格:你创建一个OptionParser实例,填充选项,并解析命令行。optparse允许用户指定选项,使用传统的GNU/POSIX语法,此外它还会自动生成使用和帮助信息。
下面是使用optparse的简单脚本的例子(exam1.py):
代码 |
from
optparse
import
OptionParser
def
main():
parser = OptionParser()
parser.add_option(
"-f"
,
"--file"
, dest=
"filename"
,help=
"write report to FILE"
, metavar=
"FILE"
)
parser.add_option(
"-q"
,
"--quiet"
,action=
"store_false"
, dest=
"verbose"
, default=
True
,help=
"don't print status messages to stdout"
)
(options, args) = parser.parse_args()
if
__name__ ==
'__main__'
:
main()
|
结果: | ----examp1.py -h
Usage: exam1.py [options]
Options:
-h, --help show this help message and exit
-f FILE, --file=FILE write report to FILE
-q, --quiet don't print status messages to stdout
|
optparse解析命令行:它会基于用户提供的命令行值,通过parse_args()返回选项对象的属性集合。parse_args()的返回值中,option.filename的值是“outfile”,option.verbose的只是False。optparse支持长的选线和短的选项,允许短选项合并在一起,并允许选项以多种方式联系它们的参数。因此下面的例子都相当于上面的例子:
代码 |
#增加两行代码
print
options.filename
print
options.verbose
|
结果 |
----examp1.py -f outfile -q
outfile
False
|
15.5.1.背景
optparse的设计思路是鼓励创建简单明了符合传统命令行接口的程序。为此,它仅支持最常见的常规下使用的unix命令行语法和语义。如果你不熟悉这些约定,通过阅读本节内容去了解他们。
15.5.1.1.术语
参数(argument)
在命令行里输入字符串,并通过shell执行execl()或execv()。在Python中,参数是sys.argv[1:]的元素(sys.argv[0]是正在执行程序的名称)。Unix shell也使用术语“word”。它是偶尔可取的能够替代sys.argv[1:]之外的一个参数列表,所以你可以将“argument”当作为“sys.argv[1:]的元素,或其他提供的一些可替换sys.argv[1:]的列表” 。
选项(option)
一个参数用来提供额外的信息来指导或定制程序的执行。有许多不同的语法选项;传统的Unix语法是一个连字符(“-”)在跟一个字母,例如-x或-f。同时,传统的Unix语法允许多个选项被合并成一个单一的参数,如-x -f相当于xf。GNU项目引进'--'跟一个连字分割符单词,如:--file 或--dry-run。这些都只是optparse提供的两个选项语法。
其他的一些选项语法如下:
* 连字符后面跟着几个字母,如-pf(这不是多个选项合并成一个参数)
* 连字符后面跟一个整词,如-file(在技术这相当于以前的语法,但它们通常不出现在相同的程序中)
* 加号后面跟一个字母或者几个字母,或一个单词,如+f,+rgb
* 一个斜杠后跟一个字母,或几个字母,或一个此,如/f,/file
这些选项语法optparse不支持并且永远不会。这是经过深思熟虑的:前三个在任何环境中都是非标准的,最后一个只会让你觉得是针对VMS,MS-DOS或Windows系统的。
选项参数(option argument)
跟在选项后的参数是与选项密切相关的,并被来自参数列表的选项使用。对于optparse而言,选项参数可以是在一个单独的来自选项的参数:
-f foo --file foo |
或包含在参数中:
-ffoo --file=foo |
通常情况下,一个给定的选项有一个参数或没有。很多人想要一个“可选的选项参数”功能,这意味着一些选项可以有参数或没有。这是有争议的,因为它会使得解析模棱两可:如果-a 有一个可选项的参数,而-b是另一个选项,那我们如何解析-ab?由于这种模棱两可,optparse不支持此功能。
位置参数(positional argument)
它是参数列表中选项解析后的剩下的东西,即在解析选项和它们的参数后,它会从参数列表中删除。
必需选项(required option)
选项必须出现在命令行上;注意,"必需选项"这个词在英语中是自相矛盾的。optparse不阻止你实现必需选项,但是不会给你提供太多帮助。
例如:考虑这个假想的命令行:
prog -v --report /tmp/report.txt foo bar |
-v 和--report都是选项,假设--report有一个参数/tmp/report.txt是选项参数,foo和bar都是位置参数。
15.5.1.2.选项是什么?
选项是用于提供额外的信息来调整或定制程序的执行。如果还是不清楚,选项通常是可选的。程序也应该能够在没有任何选项下也能很好的运行。(从Unix或GNU工具集中随机选择一个程序。它可以运行在没有任何选项下,仍然有意义吗?主要的例外是find、tar和dd——所有这些突变体我们都适当地批评他们的非标准语法和令人困惑的接口)。
很多人希望他们的程序有“必需选项”。考虑一下。如果是必需的,那就是不可选的。如果有信息,那你的程序绝对需要才能成功运行,那这就是位置参数了。
这里有一个良好命令行交互设计的例子,考虑不起眼的cp工具,它用于复制文件的。如果你试图复制文件并且没有提供目的地和至少一个来源,那它将没有多大意义。因此,如果你不带参数运行它,cp会执行失败。然而,它有一个灵活的、有用的语法,不需要任何选项:
cp SOURCE DEST cp SOURCE ... DEST-DIR |
你可以考虑的更远。大多数cp实现提供一堆选项调整如何复制文件:可以是保护模式和修改时间,避免符号链接,覆盖现有文件前的询问等等。但这都不会偏离cp的核心使命,那就是复制一个文件到另一个,或几个文件到另一个目录。
15.5.1.4.位置参数是什么?
位置参数的信息是你的程序运行绝对和积极需要的。
一个良好的用户交互接口应该尽可能减少绝对要求。如果你的程序只有满足17个不同的信息才能成功运行,那么大多数人都会在程序成功运行之前就放弃或走开了,至于如何从用户那里获得信息一点都不重要了。这是否适用于用户接口是命令行,配置文件、或GUI:如果你对你的用户提出许多要求,大多数人都会放弃的。
简而言之,尽量减少用户提供必需信息——尽可能用合理的默认值。当然,你也要让你的程序相当灵活。这就是选项。再次,无论是条目配置文件、“首选项”对话框GUI部件或者是命令行选项,当你的选项实现的越多,你的程序越灵活,程序的实现也会变得越复杂。当然太灵活也有缺点,用户会淹没在太多的选项中,并且代码也会变得难以维护。
15.5.2.教程
optparse非常灵活和强大,在大多数情况下我们可以直接使用。本节讨论的代码模式使用于任何常见的基于optparse的程序。
首先,你需要导入Optparse类;然后,在主程序中,创建一个OptionParese实例:
from
optparse
import
OptionParser
parser = OptionParser()
|
然后你可以开始定义选项了。基本的语法是:
parser.add_option(opt_str, ..., attr=value, ...) |
每个选项都有一个或多个选项字符串,如 -f 或 --file 和几个选项属性用于告诉optparse当在命令行中遇到选项是你期望声明和它该做什么。
通常,每个选项都有一个短选项和一个长选项字符串,例如:
parser.add_option("-f", "--file", ...) |
你可以自由的定义多个短选项和多个长选项(包括零),但至少有一个选项。
选项字符串传递给add_option()作为有效的标签用于选项定义的调用。为简便起见,我们经常指的是在命令行上遇到一个选项;实际上,optparse遇到选项字符串并去查找选项。
一旦你定义了所有的选项,就通知optparse解析你的命令行程序:
(options, args) = parser.parse_args()
|
(如果你喜欢,你可以自定义一个参数列表用于
parse_args(),但一般没必要怎么做;默认情况下参数列表使用的是
sys.argv[1:])。)
parse_args()返回两个值:
* options,一个对象包含所有选项的值,如,如果-
-file接受一个字符串参数,那么
option.file 将是用户提供的文件名,如果用户没有提供选项值那它就是None.
*args,位置参数列表解析后剩下的选项参数
本教程仅覆盖四个最重要的选项属性:
action,
type,
dest(destination)和
help.其中,
action是最基本的。
15.5.2.1.选项行为的理解
Actions告诉optparse当在命令行上遇到选项时应该做什么。在optparse中有一组固定操作硬编码的行为;添加新的行为属于optparse的高级扩展中。大多行为是告诉optparse存储一个值到某些变量中——例如,在命令行中输入字符串并存储到一个选项属性中。
如果你不指定一个选项行为,optparse的选项默认是
store。
15.5.2.2.存储行为
大多数选项行为是
store,他告诉optparse采取下一个参数(或当前参数的其余部分)存储,确保它是正确的类型,并将其存储到你选择的目的地。
例如:
parser.add_option(
"-f"
,
"--file"
,
action=
"store"
, type=
"string"
, dest=
"filename"
)
|
现在让我们做一个假的命令行,看optparse如何解析:
args = ["-f", "foo.txt"] (options, args) = parser.parse_args(args) |
当oprparse看到字符创-f选项后,它就会寻找下一个参数foo.txt并将其存储到选项中。所以,调用parse_args()后,option.filename的值就是“foo.txt”。
optparse支持的选项有int和float型。下面是一个选项,期望获取整数参数:
parser.add_option("-n", type="int", dest="num") |
注意:这个选项没有长字符串选项,这完全是允许的。同样,没有明确的行为那么它默认的就是
store。
让我们解析另一个仿造的命令行。这一个,我们将参数和选项放在一起:因为-n42和-n 42是一样的,代码如下:
(options, args) = parser.parse_args(["-n42"]) print options.num |
打印的值:42
如果不指定类型,
optparse默认类型是
string。结合默认行为
store,这意味着我们的第一个例子可以很短:
parser.add_option("-f", "--file", dest="filename") |
如果你不提供一个目标,
optparse会从选项字符串找出一个合理的默认选择:如果第一个长选项字符串
--foo-bar,那么它就是默认目标。如果没有长选项那短选项
-f就作为默认目标。
optparse还包括内置long和complex类型。增加类型在optparse的扩展章节中。
15.5.2.3.处理布尔选项(flag)
Flag 选项——特定的选项被设置为真或假的行为是相当普遍的。optparse支持两独立的行为
store_true和
store_false.例如,你有一个verbose标志可以用-v打开和-q关闭:
parser.add_option("-v", action="store_true", dest="verbose") parser.add_option("-q", action="store_false", dest="verbose") |
这里我们有两个不同选项却拥有相同的目标,这是完全没问题的。(他只是意味着当你设置默认值必须小心一点——见下文。)
当optparse在命令行上遇到-v时,option.verbose将被设置为
True;当遇到-q时,option.verbose将被设置为
False。
15.5.2.4.其他行为
optparse还支持其他行为:
“store_const”
存储常量值
“append”
将选项的参数增加到列表中
“count”
增加一个计数器
“callback”
调用一个指定的函数
这些都在参数指南章节中,参考章节“回调选项”。
15.5.2.5.默认值
上面所有的例子都涉及到设置变量("destinnation"),这些变量命令行选项中都是能看到的。如果这些选项看不到会发生什么呢?若我们没有提供任何默认值,它们都将设置为
None。通常这都是没问题的,但有时你想要控制的更多。
optparse允许你为每个目标提供一个默认值,这是在解析命令行之前分配的。
首先,考虑下面verbose/quite的例子。如果我们想要optparse将verbose设置为True,除非看不到
-q选项,那么我们可以这样做:
parser.add_option("-v", action="store_true", dest="verbose", default=True) parser.add_option("-q", action="store_false", dest="verbose") |
由于默认选项只适用于destination选项,而不是任何特定选项,那么这两个选项应用于相同的destination中, 与下面的方式是完全等价的 :
parser.add_option("-v", action="store_true", dest="verbose") parser.add_option("-q", action="store_false", dest="verbose", default=True) |
考虑下面这个例子:
parser.add_option(
"-v"
, action=
"store_true"
, dest=
"verbose"
,default=
True
)
parser.add_option(
"-q"
,
"--quiet"
,action=
"store_false"
, dest=
"verbose"
,default=
False
)
|
再次,verbose的默认值将是True:最后一个默认值将是destination的有效默认值。
清晰的指定默认值的方式是调用OptionParser的set_defaults()方法,你可以在调用parse_args()方法之前的任何时候设置默认值:
parser.set_defaults(verbose=True) parser.add_option(...) (options, args) = parser.parse_args() |
和之前一样,最后一个值对于默认选项才是有效的。为了清楚起见,不要用两个方式设置默认值,而只选某一种方式来设置默认值。
15.5.2.6.生成帮助信息
optparse能够自动生成帮助和使用文本,这对于创建用户友好的命令行接口非常有用。你所要做的只是给每个选项提供一个帮助值,并为你的整个程序选择一个简短的使用信息。这里有一个OptionParser填充用户友好(记录)选项:
from
optparse
import
OptionParser
usage =
"usage: %prog [options] arg1 arg2"
parser = OptionParser(usage=usage)
parser.add_option(
"-v"
,
"--verbose"
,
action=
"store_true"
, dest=
"verbose"
, default=
True
,
help=
"make lots of noise [default]"
)
parser.add_option(
"-q"
,
"--quiet"
,
action=
"store_false"
, dest=
"verbose"
,
help=
"be vewwy quiet (I'm hunting wabbits )"
)
parser.add_option(
"-f"
,
"--filename"
,
metavar=
"FILE"
, help=
"write output to FILE"
)
parser.add_option(
"-m"
,
"--mode"
,
default=
"intermediate"
,
help=
"interaction mode: novice, intermediate, "
"or expert [default: %default]"
)
(options, args) = parser.parse_args()
|
如果optparse在命令行上遇到-h或--help选项,或者你仅调用parser.print_help(),它会将信息打印到标准输出上:
Usage: exam2.py [options] arg1 arg2
Options:
-h, --help show this help message and exit
-v, --verbose make lots of noise [default]
-q, --quiet be vewwy quiet (I'm hunting wabbits)
-f FILE, --filename=FILE
write output to FILE
-m MODE, --mode=MODE interaction mode: novice, intermediate, or expert
[default: intermediate]
|
(如果帮助输触发了帮助选项,optparse会在打印帮助文本后退出。)
有很多其他事情能够帮助optparse生成最好的帮助信息:
*脚本定义自己的用法信息:
usage =
"usage: %prog [options] arg1 arg2"
|
optparse扩展%prog通过使用字符串的当前程序的名称,如
os.path.basename(sys.argv[0])。在详细选项的帮助之前打印扩展的字符串。
*如果你不提供一个usage字符串,optparse使用一个普通且合理的默认值:“
Usage: %prog [options]”,如果你的脚本不采取任何位置参数的话,使用默认的就可以了。选项的值直接显示与自动生成的帮助信息中,例如:用于“mode”选项的帮助信息:
-m MODE, --mode=MODE
|
这里,“MODE”被称为变化变量:它表示用户通过-m/--mode所提供的额外参数。默认情况下,optparse将目标变量名转化为大写,并使用变化变量。有时,这不是你想要的。例如,--filename选项显示地设置metvar="FILE",会自动生成选项描述信息。
|
这里重要的不仅仅是节省空间,尽管:使用变化变量FILE来手动写帮助文本,并为用户提供线索用于在使用半格式化语法-f FILE和正式的语法描述“write output to FILE”之间建立连接。这是一个简单且有效的方法,让你的帮助文档对于终端用户更清晰和更有用。
在2.4的新版本中:在帮助字符中,选项中有一个默认值可以包括%default——optparse通过选项默认值的str()来替换它。如果一个选项没有默认值(或默认值是None),%default扩展成none。
15.5.2.6.1.分组选项
当处理很多选项时,为了便于帮助信息输出可以将它们分组。一个OptionParser可以包含几个选项组,每个组可以包含几个选项。
选项组使用的类是
OptionGroup:
类
optparse.OptionGroup(parser,title,description=None)
where:
*
parser是
OptionParser实例插入到组中的
*
title是组的标题
*
description,optional是组的长描述信息
OptionGroup继承自
OptionContainer(如
OptionParser),所以可以用
add_option()方法将选项添加到组中。
一旦声明所有的选项,就会通过
OptionParser的方法
add_option_group()添加组到前面定义的解析器中。
继续前一节中定义的解析器,很容易添加
OptionGroup到解析器中:
group = OptionGroup(parser,
"Dangerous Options"
,
"Caution: use these options at your own risk. "
"It is believed that some of them bite."
)
group.add_option(
"-g"
, action=
"store_true"
, help=
"Group option."
)
parser.add_option_group (group)
|
运行结果如下:
Usage: exam3.py [options] arg1 arg2
Options:
-h, --help show this help message and exit
-v, --verbose make lots of noise [default]
-q, --quiet be vewwy quiet (I'm hunting wabbits)
-f FILE, --filename=FILE
write output to FILE
-m MODE, --mode=MODE interaction mode: novice, intermediate, or expert
[default: intermediate]
Dangerous Options:
Caution: use these options at your own risk. It is believed that some
of them bite.
-g Group option.
|
更完整的示例会涉及到多个组:扩展前面的例子:
group = OptionGroup(parser,
"Dangerous Options"
,
"Caution: use these options at your own risk. "
"It is believed that some of them bite."
)
group.add_option(
"-g"
, action=
"store_true"
, help=
"Group option."
)
parser.add_option_group(group )
group = OptionGroup(parser,
"Debug Options"
)
group.add_option(
"-d"
,
"--debug"
, action=
"store_true"
,
help=
"Print debug information"
)
group.add_option(
"-s"
,
"-- sql"
, action=
"store_true"
,
help=
"Print all SQL statements executed"
)
group.add_option(
"-e"
, action=
"store_true"
, help=
"Print every action done"
)
parser.add_option_group(group )
|
结果如下:
Usage: exam3.py [options] arg1 arg2
Options:
-h, --help show this help message and exit
-v, --verbose make lots of noise [default]
-q, --quiet be vewwy quiet (I'm hunting wabbits)
-f FILE, --filename=FILE
write output to FILE
-m MODE, --mode=MODE interaction mode: novice, intermediate, or expert
[default: intermediate]
Dangerous Options:
Caution: use these options at your own risk. It is believed that some
of them bite.
-g Group option.
Debug Options:
-d, --debug Print debug information
-s, --sql Print all SQL statements executed
-e Print every action done
|
、另一个有趣的方法,特别是当需要对选项组编程使用时:
|
返回OptionGroup的标题或 长描述信息
15.5.2.7.打印版本字符串
类似于简洁的用法字符串,optparse也可为你的程序打印版本字符串。你需要提供字符串用于OptionParser的版本参数:
parser = OptionParser(usage="%prog [-f] [-q]", version="%prog 1.0") |
就像在用法中扩展%prog。除此之外,可以包含任何你喜欢的版本信息。当你使用它时,
optparse自动为你的解析器增加
--version选项。如果在命令行中遇到这个选项,将会显示版本字符串(通过替代%prog),将其输出到标准输出并退出程序。
例如,如果你调用/usr/bin/foo:
$ /usr/bin/foo --version foo 1.0 |
一下两种方法可以用来打印和获取
version字符串:
OptionParser.print_version(file=none)
将当前程序的版本信息(
self.version)打印到文件中(默认是
stdout)。正如
print_usage(),在
self.version中的任何
%prog都将会替换成当前程序的名字。如果self.version是空的或未定义则什么都不做。
OptionParser.get_version()
类似于print_version()但是返回版本字符串而不是打印它。
15.5.2.8.optparser如何处理错误
Optparser担心的有两类错误:程序员错误和用户错误。程序员错误通常是指错误的调用OptionParser.add_option(),如,无效选项字符串、未知的选项属性、缺少选项属性等等。这些都可以用平常的方式处理:即引发异常(optparser.OptionError或TypeError)和直接让程序崩溃。
处理用户的错误跟重要,因为不管你的代码如何稳定它们都会发生的。optparse可以自动检测用户错误,比如坏的选项参数(如-n 4x , -n选项需要一个整数参数 ),缺少参数(-n在命令行末端,-n需要一个任意类型的参数)。同时,你可以通过OptionParser.error()通知应用程序定义的错误的情况。
(options, args) = parser.parse_args()[...]if options.a and options.b: parser.error("options -a and -b are mutually exclusive") |
在这两种情况下,optparse用相同的方式处理错误:它打印程序用法信息和错误信息到错误状态2的标准错误并退出程序。
考虑上面第一个例子,当用户传递4x而选项需要一个整数的情况:
$ /usr/bin/foo -n 4x Usage: foo [options] foo: error: option -n: invalid integer value: '4x' |
或者,用户没有传递任何值:
$ /usr/bin/foo -n Usage: foo [options] foo: error: -n option requires an argument |
optparse生成的错误消息总是关注选项涉及的错误;确保你的应用程序代码中调用OptionParser.error()也做同样的事。
如果optparse的默认错误处理行为不适合你的需要,那么你需要子类Optinparser并重载exit()或error()方法。
15.5.2.9.所有的内容综合起来
下面是一个基于optparse的脚本:
Created on 2015年1月28日
@author: pan
'''
from
optparse
import
OptionParser
from
optparse
import
OptionGroup
usage =
"usage: %prog [
options
] arg1 arg2"
parser = OptionParser(usage=usage)
parser.add_option(
"-v"
,
"--verbose"
,
action=
"store_true"
, dest=
"verbose"
, default=
True
,
help=
"make lots of noise [default]"
)
parser.add_option(
"-q"
,
"--quiet"
,
action=
"store_false"
, dest=
"verbose"
,
help=
"be vewwy quiet (I'm hunting wabbits )"
)
parser.add_option(
"-f"
,
"--filename"
,
metavar=
"FILE"
, help=
"write output to FILE"
)
parser.add_option(
"-m"
,
"--mode"
,
default=
"intermediate"
,
help=
"interaction mode: novice, intermediate, "
"or expert [default: %default]"
)
group = OptionGroup(parser,
"Dangerous Options"
,
"Caution: use these options at your own risk. "
"It is believed that some of them bite."
)
group.add_option(
"-g"
, action=
"store_true"
, help=
"Group option."
)
parser.add_option_group(group)
group = OptionGroup(parser,
"Debug Options"
)
group.add_option(
"-d"
,
"--debug"
, action=
"store_true"
,
help=
"Print debug information"
)
group.add_option(
"-s"
,
"--sql"
, action=
"store_true"
,
help=
"Print all SQL statements executed"
)
group.add_option(
"-e"
, action=
"store_true"
, help=
"Print every action done"
)
parser.add_option_group(group)
(options, args) = parser.parse_args()
|
15.5.3.参考指南
15.5.3.1. 创建解析器
第一步用optparser创建OptionParser实例。
类optparser.
OptionParser(...)
OptionParser构造函数没有必要的参数,但有许多可选的关键参数。你应该通过他们传递关键参数,即不依赖于参数声明的顺序。
usage(默认:"
%prog [options]")
当你的程序运行不正确或带有帮助选项是将会打印用法摘要。当
optparser打印使用字符串时,它会将
%prog扩展成
os.path.basename(sys.argv[0])(或
prog变成你传递的关键参数)。为了避免使用消息,你可以传递一个特殊的值
optparse.SUPPRESS_USAGE。
option_list(default:[])
用Option对象的列表来填充解析器。任何在standard_option_list(一个类属性,可以由OptionParser子类设置)中的选项之后都会添加到option_list的选项中,但是在版本和帮助选项之前。弃用:创建解析器后使用add_option()代替。
option_class(
default:optparse.Option)
当用add_option()添加选项到解析器中使用该类
version(default:none)
当用户提供了版本选项时就打印版本字符串。如果你为
version提供了一个真实的值,optparse会自动添加一个版本选项使用单个选项字符串
--version。扩展子串
%prog就像
usage一样
。
conflict_handler(default:"error")
当向解析中添加的选项与选项发生冲突,指定该做什么;详见“选项之间的冲突”
当向解析中添加的选项与选项发生冲突,指定该做什么;详见“选项之间的冲突”
description(default:None)
一段文字简要概述你的程序。optparse重新排版这段文字以适用于当前终端宽度并当用户请求版主时打印它(usage之后,但是在选项列表之前)。
formatter(default:a new IndentedHelpFormatter)
optparse.HelpFormatter实例将用于打印帮助文本。
optparse为此提供了两个具体类:
IndentedHelpFormatter和TitleHelpFormatter。
add_help_option(default:True)
如果为真,
optparse会向解析器中添加一个帮助选项(带有选项字符串
-h和
--help)。
prog
在
usage和
version中使用扩展的
%prog字符串,而不是
os.path.basename(sys.argv[0])。
epilog(default:None)
选项帮助后打印一段帮助文本。
15.5.3.2.填充解析器
有几种方式填充解析器的选项。首选的方法是使用OptionParser.add_option(),正如教程章节中所展示的。可以用以下两种方式中的一个调用add_option():
*通过一个选项实例(如make_option()的返回值)
*make_option()接受任意组合的位置参数和关键字参数(即选择构造函数),并为你创造选项实例。
另一个选择是通过传递预先构建选项实例的列表到OptionParser的构造函数中。如:
option_list = [ make_option("-f", "--filename", action="store", type="string", dest="filename"), make_option("-q", "--quiet", action="store_false", dest="verbose"), ]parser = OptionParser(option_list=option_list) |
(
make_option()通过工厂方式创建选项实例;目前是一个选项构造函数的别名。optparse在未来版本中可能将选项分成几个类,make_option()可选择正确的类实例化。不能直接实例化选项。)
15.5.3.3.定义选项
每个选项实例表示一组同义的命令行选项字符串,如-f和--file。你可以指定任意数量的短或长选项字符串,但是必须指定至少一个整体选项字符串。
典型的创建选项实例的方式是用
OptionParser的
add_option()方法。
OptionParser.add_option(opt_str[,..],attr=value,...)
仅用一个短选项字符串定义选项:
|
仅用一个长选项字符串定义选项:
|
关键参数定义新选项对象的属性。最重要的选项属性是行为,并且它在很大程度上决定了其他属性的相关性和需求。如果你传递不相关的属性或未需求的属性,optparse将会在你的程序中生成一个OptionError异常。
选项的行为决定了当在命令行上遇到选项是optparse应该做什么。标准选项是硬编码到optparse中的:
"store"
存储选项参数(默认)
“store_const”
存储常量值
“store_true”
存储“真”值
“store_false”
存储“假”值
“append”
添加这个选项参数到列表中
“append_const”
添加常量值到列表中
“count”
添加一个计数器
“callback”
调用指定函数
“help”
打印用法信息包括所有的选项和包括它们的文档
(如果你提供一个行为,默认就是“store”。你也可以这个行为提供类型和目标属性;详见选项行为)
如你所见, 大多数行为涉及到存储或更新某个值。optparse总是创建一个特殊对象,通常称为选项调用(者恰好是
optparse.Value的实例)。选项参数(各种其他值)被作为对象属性存储,通过
dest(目的)选项属性。
例如:当你调用
parser.parser_args() |
optparse的第一件事就是创建
options对象:
options = Values() |
解析器中一个选项定义如下:
parser.add_option("-f", "--file", action="store", type="string", dest="filename") |
命令行被解析成如下行为:
-f foo -f foo --file=foo --file foo |
然后,当解析看到选项后,等价于
options.filename = "foo" |
type和dest选项属性和action一样是很重要的属性,但是action是唯一一个有意义的选项。
15.5.3.4.选项属性
一下选项属性可作为关键参数传递给OptionParser.add_option()。如果你传递的选项属性与特定选项不相关,或不是选项所要求的,optparse会引发OptionErrror异常。
Option.
action
(默认值:“store”)
决定命令行上ptparse选项的行为;可用的选项文档参考:
15.5.3.5
Option.
type
(默认值:“string”)
选项的期望类型(如,"string"或“int”);可用的选项文档参考:15.5.3.6
Option.
dest
(默认值:源于选项字符串)
如果选项的行为意味着写入或修改某个值,该属性会告诉optparse写到哪儿:dest命名Options对象的属性,optparse构建该属性并解析命令行。
Option.
default
如果选项在命令行上没看到,就是使用选项目的的值,参见
OptionParser.set_default().
Option
.nargs
(默认值:1)
有多少类型参数,
type应该使用此选项。if >1 ,optparse将值以元组的方式存储到
dest中。
Option
.const
行为用于存储常量值,常量存储
Option
.choices
用于选项类型
“choice”,用户可从字符串列表中选择
。
option.
callback
选项的行为
“callback”,看到选项是随时调用。关于具体回调参数传递可参见选项回调章节(Option Callbacks)。
Option.callback_args
Option.callback_kwargs
四个标准回调参数后,将额外的位置和关键参数传递给回调方法。
Option.
help
帮助文本打印这个选项列出的所有可用的选项后,当用户提供一个帮助选项(如:--
help)。如果没有提供帮助文本,选项将会没有可列出的帮助文本。隐藏此选项,使用特殊的值optparse.SUPPRESS_HELP。
Option.
metavar
(默认值:源于选项字符串)
打印帮助文本时选项参数的替身。参见教程章节的例子。
15.5.3.5.标准选项行为
各个选项都有略微不同的需求和影响。大多数行为都有些相关选项属性可用于指定指导optparse的行为;几个必需的属性,任何行为使用的时候都需要指定。
*“
store”[相关:
type,
dest,
nargs,
choices]
选项后需要跟一个参数,并根据type的值转换并存储仅dest中。如果
nargs>1,命令行中的多个参数被使用;所有的参数都根据type类型进行转换并以tuple存储到dest中。参见标准选项类型章节。
如果选择支持(list或tuple字符串),默认类型是“
choice”.
如果
type不支持,默认类型是“
string”
如果dest不支持,optparse将会从第一个选项长字符串派生一个目的地(如:--foo-bar使用foo-bar)。如果没有长选项,就会使用段选项的第一个字符串(如:-f使用f)。
例如:
|
命令行的解析如下:
-f foo.txt -p 1 -3.5 4 -fbar.tx |
optparse将设置:
option.f = "foo.txt" option.point = (1.0 ,-3.5 ,4.0) option.f = "bar.txt" |
*“store_const”[需求:const;相关:dest]
const值存储到
dest中
例如:
parser.add_option(
"-q"
,
"--quiet"
,
action=
"store_const"
, const=
0
, dest=
"verbose"
)
parser.add_option(
"-v"
,
"--verbose"
,
action=
"store_const"
, const=
1
, dest=
"verbose"
)
parser.add_option(
"--noisy"
,
action=
"store_const"
, const=
2
, dest=
"verbose"
|
如果是--noisy,optpares将会设置:
option.verbose = 2 |
*"store_true"[相关:dest]
“store_const”特指,存储‘真’值到dest中
*“store_falst”[相关:dest]
与“store_false”类似,但存储的是‘假’值
例如:
parser.add_option(
"--clobber"
, action=
"store_true"
, dest=
"clobber"
)
parser.add_option(
"--no-clobber"
, action=
"store_false"
, dest=
"clobber"
)
|
*"append"[相关:type,dest,nargs,choices]
选项后必须跟一个参数,并添加到dest列表中。如果dest没有提供默认值,当首次在命令行上遇到选项会自动创建一个空列表。如果nargs>1,多个参数被使用,并且nargs的tuple长度被增加到dest中。
type和dest的默认值和"store"一样。
例如:
parser.add_option(
"-t"
,
"--tracks"
, action=
"append"
, type=
"int "
)
|
如命令行中输入 -t3 ,optparse相当于在做:
options.tracks = [] options.tracks.append(int("3")) |
如果,后面有一个 --tracks=4,那么会做:
options.tracks.append(int("3")) |
*"append_const"[需求:const; 相关:dest]
类似”
store_const“,但是
const值被增加到dest中;正如”
append“一样,
dest默认值是
None,选项首次遇到会创建空列表。
*"count"[相关:dest]
在dest中增加整数存储。如果没提供默认值,dest在首次增加时被设置为零。
例如:
parser.add_option(
"-v"
, action=
"count"
, dest=
"verbosity"
)
|
在命令行上首次遇到-v,optparse相当于在做:
options.verbosity = 0 options.verbosity += 1 |
后随的每一个-v的结果:
options.verbosity += 1 |
*"callback"[需求:callback 相关:type,nargs,callback_args,callback_kwargs]
callback调用指定函数,如下:
|
详见
选项调用(option callbacks)章节
*"help"
为当前解析器的所有选项打印一个完整的帮助信息。帮助信息的构建来自于OptionParser的构造函数和每个选项的帮助字符串。 如果选项没有提供帮助信息,它将任然被列在帮助信息中。如完全忽略一个选项,使用特殊值optparse.SUPPRESS_HELP。
optparse自动添加一个
help选项到OptionParses,所有你通常不需要创建。
例如:
from
optparse
import
OptionParser, SUPPRESS_HELP
# usually, a help option is added automatically, but that can
# be suppressed using the add_help_option argument
parser = OptionParser(add_help_option=
False
)
parser.add_option(
"-h"
,
"--help"
, action=
"help"
)
parser.add_option(
"-v"
, action=
"store_true"
, dest=
"verbose"
,
help=
"Be moderately verbose"
)
parser.add_option(
"--file"
, dest=
"filename"
,
help=
"Input file to read data from"
)
parser.add_option(
"--secret"
, help=SUPPRESS_HELP)
|
如果你在命令行中输入-h或--help,则会打印如下信息:
Usage: exam4.py [options]
Options:
-h, --help
-v Be moderately verbose
--file=FILENAME Input file to read data from
|
打印完帮助信息后,进程会调用sys.exit(0)
*”version“
OptionParser支持打印版本号输出并退出。版本号实际上通过OptionParser的print_version()方法格式和打印的。一般适用于OptionParser构造函数的版本参数提供,正如help选项一样,以也不需要创建版本选项,因为会在你需要的时候自动创建。
15.5.3.6.标准选项类型
optparse内置六个选项类型:“string”、“int”、“long”、“choice”、“float”和“complex”。如果你需要新的选项类型,可参考optparse扩展章节。
string选项参数不用检查和转换:命令行中的文本以原值存储到目的中(或传给回调函数中)。
整数参数(类型“int”或“long”)按如下方式解析:
*如果数字以0x开头,则以16进制解析
*如果数字以0开头,则以8进制解析
*如果数字以0b开头,则以二进制解析
*其他方式,数字都以10进制解析
转换是通过调用基于参数(2,8,10,16)的int()或long()方法。如果失败了,optparse将会传一个有用的错误信息。
“float”和“complex”选项参数直接使用float()和complex()转换,且有相同的错误处理。
“choice”选项是“string”选项的一个子类型。choices选项属性(字符串序列)定义了选项参数允许的集合。optparse.check_choice()比较用户支持的选项,相反如果主列表中有无效的字符串则会生成OptionValueError错误。
15.5.3.7.参数解析
创建并填充一个OptionParser的全部意义在于调用parse_args()方法:
(options, args) = parser.parse_args(args=None,values=None) |
参数输入:
args
参数列表的处理(默认值:sys.argv[1:])
values
optparse.Values对象存储选项参数(默认:新的Values实例)——如果已经存在对象,选项默认不初始化它。
返回值:
options
对象传递的Valuse值或optparse.optparse创建Valuse实例。
args
所有选项处理后剩下的位置参数。
最常见的用法是不提供关键字参数。如果提供Values,将会重复调用setattr()修改值(大约每个选项参数存储到一个选项目的中)并返回parse_args()。
如果parse_args()的参数列表遇到任何错误,它将会调用OptionParser的error()方法并返回一个合适的用户终止的错误信息。总将以状态2退出进程(传统unix的退出状态码)。
15.5.3.8.查询和控制选项解析器
可以定制解析器的默认行为,也可以拆开选项解析器。OptionParser提供了几个方法帮助你:
OptionParser.disable_interspersed_args()
在第一非选项上设置停止解析。例如,如果-a和-b都是不带参数的简单选项,optparse通常接受这种语法:
prog -a arg1 -b arg2 |
等同于:
prog -a -b arg1 arg2 |
为禁用这个特性,可调用disable_interspersed_args().恢复传统的Unix语法,遇到第一个非选项参数解析就停止。
如果有一个命令处理器运行另一个命令选项,那么你要确保你在使用时不会感到困惑。例如,每个命令都可能有不同的选项设置。
OptionParser.enable_interspersed_args()
在第一个非非选项上设置解析停止,并允许点缀带有命令参数的开关。这是默认行为。
OptionParser.get_option(opt_str)
返回使用选项字符串opt_str的Option实例,或None如果没有选项字符串。
OptionParser.has_option(opt_str)
返回真,如果OptionParse的opt_str中有选项(er,-q或--verbose)
OptionParser.remove_option(opt_str)
如果OptionParser中选项对应opt_str,那就移出该选项呢。如果选项还涉及到其他选项,那其它选项都将无效。如果opt_str不包含任何其他属于OptionParser的选项,则生成ValueError。