optparse

2.3版本的新功能。

自2.7版弃用：该optparse模块已弃用，不会进一步开发; 发展将继续与argparse模块。

源代码： Liby / optparse.p

optparse是比旧getopt模块更方便，灵活且功能强大的库，用于解析命令行选项。optparse使用更具说明性的命令行解析风格：您创建一个实例OptionParser，使用选项填充它，并解析命令行。optparse允许用户使用传统的GNU / POSIX语法指定选项，并且还为您生成使用情况和帮助信息。

以下是optparse一个简单脚本中使用的示例：

使用这几行代码，您的脚本的用户现在可以在命令行上执行“通常的事情”，例如：

在分析命令行时，根据用户提供的命令行值optparse设置options返回的对象的属性parse_args()。当parse_args()从解析此命令行返回，options.filename将"outfile"和options.verbose会False。optparse支持长期和短期期权，允许短期期权合并在一起，并允许期权以各种方式与其参数相关联。因此，以下命令行全部等同于上述示例：

另外，用户可以运行其中的一个

和optparse会打印出脚本选项的简要摘要：

yourscript 的值在运行时确定（通常来自sys.argv[0]）。

1.背景

optparse明确地设计用于鼓励使用直接的常规命令行界面创建程序。为此，它只支持Unix下常用的最常用的命令行语法和语义。如果您不熟悉这些惯例，请阅读本节以熟悉它们。

1.1. 术语

论据

在命令行上输入的字符串，并通过 shell 传递给execl()或execv()。在Python中，参数是元素sys.argv[1:]（sys.argv[0]是正在执行的程序的名称）。Unix shell也使用术语“单词”。

偶尔需要用一个参数列表来代替sys.argv[1:]，所以你应该将“参数”理解为“ sys.argv[1:]作为替代的一个元素或其他列表sys.argv[1:]”。

选项

用于提供额外信息来引导或定制程序执行的参数。选项有许多不同的语法; 传统的Unix语法是一个连字符（“ - ”），后跟单个字母，例如-x或-F。另外，传统的Unix语法允许将多个选项合并为一个参数，例如-x -F等同于-xF。引入的GNU项目--后跟一系列连字符分隔的单词，例如--file或--dry-run。这是唯一提供的两种选项语法optparse。

世界已经看到的一些其他选项语法包括：

• 一个连字符后面几个字母，例如-pf（这是不一样的多个选项合并为一个参数）

• 一个连字符后跟一个单词，例如-file（这在技术上等同于前面的语法，但它们通常不会在同一个程序中看到）

• 一个加号后跟单个字母，或几个字母或一个单词，例如+f，+rgb

• 斜杠后跟一个字母，或几个字母，或一个字，例如/f，/file

这些选项语法不受支持optparse，并且它们永远不会。这是故意的：前三个在任何环境下都是非标准的，如果你专门针对VMS，MS-DOS和/或Windows，最后一个是唯一有意义的。

选项参数

一个选项后面的参数与该选项密切相关，并且在该选项时从参数列表中消耗。与optparse，选项参数可能会在他们的选项单独的参数：

或者包含在相同的论点中：

通常情况下，给定的选项需要参数或不参与。很多人都希望有一个“可选的选项参数”功能，这意味着如果他们看到它，某些选项将会有一个参数，如果它们不参与则不会。这是有点争议的，因为它使解析模糊：如果-a采取可选参数，并且-b完全是另一种选择，我们如何解释-ab？由于这种模糊性，optparse不支持此功能。

在选项被解析后，即在选项及其参数已被解析并从参数list.required optionan选项中删除之后，在参数列表中剩余的位置参数。必须在命令行上提供选项; 请注意，“必需的选项”一词在英语中是自相矛盾的。optparse并不妨碍你实现所需的选项，但也不会给你太多的帮助。

例如，考虑这个假设的命令行：

-v和--report都是选择。假设只有--report一个参数，report.txt是一个选项参数。foo并且bar是位置参数。

1.2 有什么选择？

选项用于提供额外的信息来调整或定制程序的执行。如果不清楚，选项通常是可选的。一个程序应该能够运行得很好，没有任何选择。（选择从Unix或GNU工具集的随机程序，它可以运行，而完全不带任何选项，仍然有意义吗？主要的例外是find，tar和dd-所有这些都已经正确地批评自己的非标准语法突变oddballs和令人困惑的界面。）

很多人希望他们的计划有“必需的选择”。想想看。如果它是必需的，那么它不是可选的！如果你的程序为了成功运行而需要绝对的信息，那就是位置参数。

作为良好的命令行界面设计的例子，考虑cp复制文件的谦虚工具。尝试复制文件时没有提供目的地和至少一个源文件没有多大意义。因此，cp如果你没有参数运行它就会失败。但是，它有一个灵活有用的语法，根本不需要任何选项：

你可以得到相当远的那一点。大多数cp实现提供了一系列选项来精确调整文件的复制方式：您可以保留模式和修改时间，避免遵循符号链接，在重新打开现有文件之前询问等等。但是这些都不会干扰核心任务cp，即将一个文件复制到另一个文件，或将多个文件复制到另一个目录

1.3. 什么是位置参数？

位置参数适用于您的程序完全需要运行的那些信息。

一个好的用户界面应该尽可能少的绝对要求。如果你的程序需要17个不同的信息，以成功运行，它没有多大关系如何你从用户大多数人的信息会放弃走开他们成功地运行该程序之前。无论用户界面是命令行，配置文件还是GUI：这都适用：如果您对用户提出了许多要求，他们中的大多数都会放弃。

简而言之，尽量减少用户绝对需要提供的信息量 - 尽可能使用合理的默认值。当然，你也想让你的程序合理灵活。这是什么选择。同样，无论它们是配置文件中的条目，GUI的“首选项”对话框中的小部件还是命令行选项，您实现的选项越多，程序的灵活性越高，以及更复杂其实施成为。当然，太多的灵活性也有缺点。太多的选项可能压倒用户，使你的代码难以维护。

2.教程

虽然optparse相当灵活且功能强大，但在大多数情况下使用也很简单。本节介绍任何optparse基于程序的通用代码模式。

首先，您需要导入OptionParser类; 然后，在主程序的早期，创建一个OptionParser实例：

然后你可以开始定义选项。基本的语法是：

每个选项都有一个或多个选项字符串（例如-f或）--file，以及几个选项属性，它们告诉optparse我们期望什么，以及在命令行中遇到该选项时该做什么。

通常，每个选项将有一个短选项字符串和一个长选项字符串，例如：

只要至少有一个选项字符串，您可以自由定义尽可能多的短选项字符串和尽可能多的长选项字符串（包括零）。

传递给的选项字符串OptionParser.add_option()对于由该调用定义的选项是有效的标签。为简洁起见，我们经常会提到在命令行上遇到一个选项 ; 在现实中，optparse遇到选项字符串并从中查找选项。

一旦定义了所有选项，optparse就要指示解析程序的命令行：

（如果你喜欢，你可以传递一个自定义参数列表parse_args()，但这很少有必要：默认情况下它使用sys.argv[1:]。）

parse_args() 返回两个值：

• options，一个包含所有选项值的对象 - 例如，如果--file使用单个字符串参数，options.file则将是由用户提供的文件名，或者None如果用户没有提供该选项

• args，解析选项后剩余的位置参数列表

本教程部分仅涉及四个最重要的选项属性：action，type，dest（目标），和help。其中，action最根本的是。

2.1. 了解选项操作

optparse当命令行遇到选项时，操作会告诉您该做什么。有一组固定的操作被硬编码到optparse; 添加新操作是扩展optparse一节中介绍的高级主题。大多数操作都告诉optparse将某个值存储在某个变量中 - 例如，从命令行取一个字符串并将其存储在一个属性中options。

如果您未指定选项操作，则optparse默认为store。

2.2. 商店行为

最常见的选项动作是store，它告诉optparse采取下一个参数（或当前参数的其余部分），确保它是正确的类型，并将其存储到您选择的目的地。

例如：

现在让我们编一个假的命令行并要求optparse解析它：

当optparse看到选项字符串时-f，它会消耗下一个参数foo.txt，并存储它options.filename。所以，在此之后parse_args()，options.filename是"foo.txt"。

受支持的其他一些选项类型optparse是int和float。这是一个期望有一个整数参数的选项：

请注意，此选项没有长选项字符串，这是完全可以接受的。此外，没有明确的行动，因为默认是store。

我们来解析另一个虚假的命令行。这一次，我们会将选项参数与选项对齐：因为-n42（一个参数）等同于-n 42（两个参数），所以代码

将打印42。

如果您不指定类型，则optparse假定string。结合默认动作这一事实store，这意味着我们的第一个示例可以缩短很多：

如果您不提供目的地，则optparse根据选项字符串计算合理的默认值：如果第一个长选项字符串是--foo-bar，则默认目的地是foo_bar。如果没有长选项字符串，请optparse查看第一个短选项字符串：-fis 的默认目的地f。

optparse还包括内置long和complex类型。扩展optparse一节介绍了添加类型。

2.3. 处理布尔（标志）选项

标志选项 - 当一个特定的选项被看到时，将一个变量设置为真或假 - 很常见。optparse通过两个独立的行动支持他们，store_true和store_false。例如，您可能有一个verbose打开-v和关闭的标志-q：

在这里，我们有两个不同的选项与相同的目的地，这是完全正确的。（这只是意味着您在设置默认值时必须小心 - 请参阅下文。）

当optparse遇到-v命令行时，它设置options.verbose为True; 当它遇到时-q，options.verbose被设置为False。

2.4. 其他行为

其他一些支持的操作optparse是：

"store_const"存储常量值"append"将此选项的参数附加到列表中"count"通过"callback"调用指定函数来增加计数器

这些在参考指南，参考指南和选项回调部分中有介绍。

2.5. 默认值

以上所有示例都涉及在某些命令行选项可见时设置某个变量（“目标”）。如果这些选项从未见过会发生什么？由于我们没有提供任何默认值，它们都设置为None。这通常很好，但有时你想要更多的控制。optparse可以为每个目标提供一个默认值，该值在解析命令行之前分配。

首先，考虑冗长/安静的例子。如果我们想要optparse设置verbose为True除非-q被看到，那么我们可以这样做：

由于默认值适用于目标而不是任何特定的选项，并且这两个选项碰巧具有相同的目标，所以这完全等同：

考虑这个：

同样，缺省值verbose将为True：为任何特定目标提供的最后一个缺省值是重要的。

指定默认值的更清晰的set_defaults()方法是OptionParser 的方法，您可以在调用之前随时调用该方法parse_args()：

和以前一样，为给定选项目标指定的最后一个值是计数的值。为了清楚起见，请尝试使用一种方法或另一种设置默认值，而不是两种。

2.6. 生成帮助

optparse自动生成帮助和使用文本的能力对于创建用户友好的命令行界面非常有用。您所要做的就是help为每个选项提供一个值，并为整个程序提供一个简短的用法信息。这里有一个OptionParser，它提供了用户友好（记录）的选项：

如果在命令行上或者在命令行上optparse遇到，或者只是调用，则会将以下内容输出到标准输出：-h--helpparser.print_help()

（如果帮助输出由帮助选项触发，则optparse在打印帮助文本后退出。）

这里有很多事情可以帮助您optparse产生最好的帮助信息：

• the script defines its own usage message: usage = "usage: %prog options arg1 arg2" optparse expands %prog in the usage string to the name of the current program, i.e. os.path.basename(sys.argv[0]). The expanded string is then printed before the detailed option help. If you don’t supply a usage string, optparse uses a bland but sensible default: "Usage: %prog [options]", which is fine if your script doesn’t take any positional arguments.

• 每个选项都定义了一个帮助字符串，并且不用担心换行问题 - optparse照顾换行和帮助输出看起来不错。

• 带值的选项在自动生成的帮助消息中指示了这一事实，例如“模式”选项：

-m MODE, --mode=MODE

这里，“MODE”被称为元变量：它代表用户预期提供给-m/的参数--mode。默认情况下，optparse将目标变量名称转换为大写，并将其用于元变量。有时，这不是你想要的 - 例如，该--filename选项显式设置metavar="FILE"，导致这个自动生成的选项描述：

-f FILE, --filename=FILE

不过这不仅仅是节省空间很重要：手动编写的帮助文本使用元变量FILE来暗示用户，因为在半形式语法-f FILE和非正式语义描述“将输出写入FILE” 之间存在关联。这是一种简单而有效的方式，可以使您的帮助文本对最终用户更加清晰和有用。

版本2.4中的新功能：具有默认值的选项可以包含%default在帮助字符串中 - optparse将其替换str()为选项的默认值。如果选项没有默认值（或默认值为None），则%default展开为none。

2.6.1. 分组选项

在处理多种选项时，将这些选项分组以更好地帮助输出是很方便的。一个OptionParser可以包含多个选项组，每个选项组可以包含多个选项。

选项组使用该类获得OptionGroup：

class optparse.OptionGroup(parser, title, description=None)

哪里

• 解析器是该OptionParser组将要执行的实例

• 标题是组标题

• 描述，可选，是对该组的长描述

OptionGroup继承自OptionContainer（like OptionParser），因此该add_option()方法可用于向该组添加选项。

一旦声明了所有选项，使用该OptionParser方法add_option_group()将该组添加到先前定义的解析器中。

继续上一节中定义的解析器，将OptionGroup解析器添加到解析器很容易：

这将导致以下帮助输出：

更完整的示例可能涉及使用多个组：仍然扩展前面的示例：

导致以下输出：

另一个有趣的方法，特别是使用选项组进行编程时：

OptionParser.get_option_group(opt_str)

返回OptionGroup短或长选项字符串opt_str（例如'-o'或'--option'）所属的。如果没有这样的OptionGroup回报None。

2.7. 打印版本字符串

与简短的使用字符串类似，optparse也可以为您的程序打印一个版本字符串。您必须提供字符串作为versionOptionParser 的参数：

%prog就像它在扩大一样usage。除此之外，version可以包含任何你喜欢的东西。当您提供它时，会optparse自动--version为您的解析器添加一个选项。如果在命令行中遇到此选项，它会扩展您的version字符串（通过替换%prog），将其输出到stdout并退出。

例如，如果您的脚本被调用/usr/bin/foo：

以下两种方法可用于打印和获取version字符串：

OptionParser.print_version(file=None)

将当前程序（self.version）的版本信息打印到文件（默认stdout）。与之一样print_usage()，任何%progin的出现都self.version被替换为当前程序的名称。如果self.version是空的或未定义的，什么也不做。

OptionParser.get_version()

print_version()与之相同，但返回版本字符串而不是打印它。

2.8. 如何optparse处理错误

有两大类错误optparse需要担心：程序员错误和用户错误。程序员错误通常是错误的调用OptionParser.add_option()，例如无效的选项字符串，未知的选项属性，缺少的选项属性等。这些问题以常规方式处理：引发异常（optparse.OptionError或者TypeError）并让程序崩溃。

处理用户错误更为重要，因为无论您的代码如何稳定，它们都会保证发生。optparse可以自动检测一些用户错误，例如错误的选项参数（传递-n 4xwhere -n获取整数参数），缺少参数（-n在命令行末尾，其中-n接受任何类型的参数）。此外，您可以调用OptionParser.error()以指示应用程序定义的错误条件：

在任何一种情况下，都optparse以相同的方式处理错误：它将程序的使用消息和错误消息打印到标准错误，并以错误状态2退出。

考虑上面的第一个例子，用户传递4x给一个带有整数的选项：

或者，用户无法传递任何值的地方：

optparse生成的错误消息始终注意提及错误中涉及的选项; OptionParser.error()从应用程序代码调用时一定要这样做。

如果optparse的默认错误处理行为不能满足您的需求，您需要继承OptionParser并覆盖其exit()和/或error()方法。

2.9. 把它放在一起

以下是optparse基于脚本的脚本通常的样子：

3.参考指南

3.1. 创建解析器

使用的第一步optparse是创建一个OptionParser实例。

class optparse.OptionParser(...)

OptionParser构造函数没有必需的参数，但有许多可选的关键字参数。您应该始终将它们作为关键字参数传递，即不要依赖声明参数的顺序。

usage (default: "%prog [options]")The usage summary to print when your program is run incorrectly or with a help option. When optparse prints the usage string, it expands %prog to os.path.basename(sys.argv[0]) (or to prog if you passed that keyword argument). To suppress a usage message, pass the special value optparse.SUPPRESS_USAGE.option_list (default: [])A list of Option objects to populate the parser with. The options in option_list are added after any options in standard_option_list (a class attribute that may be set by OptionParser subclasses), but before any version or help options. Deprecated; use add_option() after creating the parser instead.option_class (default: optparse.Option)Class to use when adding options to the parser in add_option().version (default: None)A version string to print when the user supplies a version option. If you supply a true value for version, optparse automatically adds a version option with the single option string --version. The substring %prog is expanded the same as for usage.conflict_handler (default: "error")Specifies what to do when options with conflicting option strings are added to the parser; see section Conflicts between options.description (default: None)A paragraph of text giving a brief overview of your program. optparse reformats this paragraph to fit the current terminal width and prints it when the user requests help (after usage, but before the list of options).formatter (default: a new IndentedHelpFormatter)An instance of optparse.HelpFormatter that will be used for printing help text. optparse provides two concrete classes for this purpose: IndentedHelpFormatter and TitledHelpFormatter.add_help_option (default: True)If true, optparse will add a help option (with option strings -h and --help) to the parser.progThe string to use when expanding %prog in usage and version instead of os.path.basename(sys.argv[0]).epilog (default: None)A paragraph of help text to print after the option help.

3.2. 填充解析器

有几种方法可以用选项填充解析器。首选方法是使用OptionParser.add_option()，如教程部分所示。add_option()可以通过以下两种方式之一进行调用：

• 传递一个Option实例（如返回的那样make_option()）

• 传递它可以接受的位置参数和关键字参数的任意组合make_option()（即选项构造函数），它将为您创建Option实例

另一种方法是将预先构建的Option实例列表传递给OptionParser构造函数，如下所示：

（make_option()是用于创建Option实例的工厂函数;目前它是Option构造函数的别名，将来的版本optparse可能会将Option拆分为多个类，make_option()并将选择正确的类实例化，不要直接实例化选项。

3.3. 定义选项

每个选项实例代表一组同义的命令行选项字符串，例如-f和--file。您可以指定任意数量的短或长选项字符串，但必须至少指定一个总体选项字符串。

创建Option实例的规范方法是使用add_option()方法OptionParser。

OptionParser.add_option(option)OptionParser.add_option(*opt_str, attr=value, ...)

要用一个简短的选项字符串来定义一个选项：

并且只用一个很长的选项字符串来定义一个选项：

关键字参数定义了新的Option对象的属性。最重要的选项属性是action，它很大程度上决定了哪些其他属性是相关或需要的。如果您传递不相关的选项属性或未能通过所需属性，optparse则会引发一个OptionError异常来解释您的错误。

选项的动作决定了optparse它在命令行中遇到此选项时会发生什么。硬编码的标准选项操作optparse是：

"store"存储此选项的参数（默认）"store_const"存储常量值"store_true"存储真值"store_false"存储错误值"append"将此选项的参数"append_const"附加到列表将常数值附加到列表"count"通过"callback"调用指定函数增加计数器"help"打印包含所有选项和他们的文档

（如果您不提供操作，则默认为"store"。对于此操作，您还可以提供操作type和dest选项属性;请参阅标准选项操作。）

如您所见，大多数操作都涉及在某处存储或更新值。optparse总是为此创建一个特殊对象，通常称为options（它恰好是一个实例optparse.Values）。根据dest（目标）选项属性，选项参数（以及其他各种值）被存储为该对象的属性。

例如，当你打电话

首先要做的optparse是创建options对象：

如果此解析器中的某个选项是使用定义的

并且正在解析的命令行包含以下任一项：

那么optparse，看到这个选项，就会做相当于

在type和dest选项属性几乎一样重要action，但是action是唯一一个有意义的所有选项。

3.4. 选项属性

以下选项属性可以作为关键字参数传递给OptionParser.add_option()。如果传递与特定选项无关的选项属性，或者未能传递必需的选项属性，则会optparse引发OptionError。

Option.action

（默认值："store"）

确定optparse在命令行中显示此选项时的行为; 可用的选项在这里记录。

Option.type

（默认值："string"）

该选项期望的参数类型（例如"string"或"int"）; 在这里记录可用的选项类型。

Option.dest

（默认：从选项字符串派生）

如果该选项的操作意味着在某处写入或修改了某个值，optparse则会告诉写入它的位置：dest命名在分析命令行时构建的options对象的属性optparse。

Option.default

如果该选项未在命令行中显示，则用于此选项目标的值。另见OptionParser.set_defaults()。

Option.nargs

（默认值：1）

当看到这个选项时，应该消耗多少种type类型的参数。如果> 1，optparse将存储值的元组dest。

Option.const

对于存储常量值的操作，要存储的常量值。

Option.choices

对于类型选项，"choice"用户可以从中选择字符串列表。

Option.callback

对于具有操作的选项，"callback"可以在看到此选项时调用可调用的选项。有关传递给可调用参数的参数的详细信息，请参见选项回调一节。

Option.callback_argsOption.callback_kwargs

在四个标准回调参数后callback传递的附加位置和关键字参数。

Option.help

在用户提供help选项（如--help）后列出所有可用选项时，可以为此选项打印帮助文本。如果没有提供帮助文本，该选项将被列出而没有帮助文本。要隐藏此选项，请使用特殊值optparse.SUPPRESS_HELP。

Option.metavar

（默认：从选项字符串派生）

在打印帮助文本时，可以使用选项参数。有关示例，请参见教程部分。

3.5. 标准选项操作

各种选择行动都有稍微不同的要求和影响。大多数行为都有几个相关的选项属性，您可以指定它们来指导optparse行为; 有几个需要属性，您必须为使用该操作的任何选项指定属性。

• "store"[相关：type，dest，nargs，choices该选项必须跟随一个参数，它是根据转换为值type，并存储在dest。如果nargs> 1，将从命令行消耗多个参数; 全部将根据type并转换dest为一个元组进行转换。请参阅标准选项类型部分。如果choices提供（字符串的列表或元组），则类型默认为"choice"。如果type未提供，则默认为"string"。如果dest未提供，optparse则从第一个长选项字符串派生一个目标（例如，--foo-bar暗示foo_bar）。如果没有长选项字符串，optparse则从第一个短选项字符串（例如，-f暗示f）。例如：parser.add_option（“ - f”）parser.add_option（“ - p”，type =“float”，nargs = 3，dest =“point”）解析命令行-f foo.txt -p 1 -3.5 4 -fbar.txt optparse将设置options.f =“foo.txt”options.point =（1.0，-3.5，4.0）options.f =“bar.txt”

• "store_const" [required: const; relevant: 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被看到，optparse将会设置

options.verbose = 2

• "store_true"[相关：dest]一个特殊的情况下"store_const"存储真正的价值dest。

• "store_false" [relevant: dest]

像"store_true"，但存储一个虚假的价值。

示例：

parser.add_option("--clobber", action="store_true", dest="clobber") parser.add_option("--no-clobber", action="store_false", dest="clobber")

• "append" [relevant: type, dest, nargs, choices] The option must be followed by an argument, which is appended to the list in dest. If no default value for dest is supplied, an empty list is automatically created when optparse first encounters this option on the command-line. If nargs > 1, multiple arguments are consumed, and a tuple of length nargs is appended to dest. The defaults for type and dest are the same as for the "store" action. Example: parser.add_option("-t", "--tracks", action="append", type="int") If -t3 is seen on the command-line, optparse does the equivalent of: options.tracks = [] options.tracks.append(int("3")) If, a little later on, --tracks=4 is seen, it does: options.tracks.append(int("4")) The append action calls the append method on the current value of the option. This means that any default value specified must have an append method. It also means that if the default value is non-empty, the default elements will be present in the parsed value for the option, with any values from the command line appended after those default values:parser.add_option("--files", action="append", default='~/.mypkg/defaults') >>> opts, args = parser.parse_args('--files', 'overrides.mypkg') >>> opts.files '~/.mypkg/defaults', 'overrides.mypkg'

• "append_const" [required: const; relevant: dest]

像"store_const"，但const附加价值dest; 与之一样"append"，dest默认为None，并且在遇到第一次选项时自动创建一个空列表。

• "count" [relevant: dest] Increment the integer stored at dest. If no default value is supplied, dest is set to zero before being incremented the first time. Example: parser.add_option("-v", action="count", dest="verbosity") The first time -v is seen on the command line, optparse does the equivalent of: options.verbosity = 0 options.verbosity += 1 Every subsequent occurrence of -v results in options.verbosity += 1

• "callback" [required: callback; relevant: type, nargs, callback_args, callback_kwargs]

通过调用指定的函数callback，它被称为

func(option, opt_str, value, parser, *args, **kwargs)

更多细节请参见选项回调部分。

• "help" Prints a complete help message for all the options in the current option parser. The help message is constructed from the usage string passed to OptionParser’s constructor and the help string passed to every option. If no help string is supplied for an option, it will still be listed in the help message. To omit an option entirely, use the special value optparse.SUPPRESS_HELP. optparse automatically adds a help option to all OptionParsers, so you do not normally need to create one. Example: 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) If optparse sees either -h or --help on the command line, it will print something like the following help message to stdout (assuming sys.argv[0] is "foo.py"): Usage: foo.py options Options: -h, --help Show this help message and exit -v Be moderately verbose --file=FILENAME Input file to read data from After printing the help message, optparse terminates your process with sys.exit(0).

• "version"

将提供给OptionParser的版本号打印到标准输出并退出。版本号实际上是通过print_version()OptionParser 的方法格式化和打印的。通常只有在version参数提供给OptionParser构造函数时才有用。与help选项一样，您很少创建version选项，因为optparse在需要时自动添加选项。

3.6. 标准选项类型

optparse有六个内置选项类型："string"，"int"，"long"，"choice"，"float"和"complex"。如果您需要添加新的选项类型，请参阅扩展optparse部分。

字符串选项的参数不会以任何方式检查或转换：命令行上的文本按原样存储在目标中（或传递给回调函数）。

整数参数（类型"int"或"long"）被解析如下：

• 如果该号码开头0x，则将其解析为十六进制数字

• 如果数字以数字开头0，则将其解析为八进制数字

• 如果数字开头0b，它将被解析为一个二进制数字

• 否则，该数字将被解析为十进制数字

通过调用int()或long()使用适当的基地（2,8,10或16）完成转换。如果失败了，optparse尽管有更多有用的错误信息。

"float"和"complex"选项参数可以直接使用float()和进行转换complex()，具有类似的错误处理。

"choice"选项是选项的子类型"string"。该choices可选属性（字符串序列）定义了一组允许的选项参数。optparse.check_choice()将用户提供的选项参数与此主列表进行比较，并OptionValueError在发出无效字符串时引发。

3.7. 解析参数

创建和填充OptionParser的要点是调用它的parse_args()方法：

输入参数在哪里

args参数列表来处理（默认值：sys.argv[1:]）values一个optparse.Values对象存储选项参数中（默认：的新实例Values） -如果你给一个现有的对象，该选项默认不会在它初始化

和返回值是

options与传入的相同对象values，或optparseargs在所有选项处理完毕后由剩余位置参数创建的optparse.Values实例

最常见的用法是不提供关键字参数。如果您提供values，它将被重复setattr()调用修改（对于存储到选项目标的每个选项参数大致为一个）并返回parse_args()。

如果parse_args()在参数列表中遇到任何错误，它会error()用适当的最终用户错误消息调用OptionParser的方法。这最终会终止您的进程，退出状态为2（命令行错误的传统Unix退出状态）。

3.8. 查询和操作您的选项解析器

选项解析器的默认行为可以进行轻微的自定义，您也可以在选项解析器周围徘徊，看看有什么。OptionParser提供了几种方法来帮助你：

OptionParser.disable_interspersed_args()

将解析设置为在第一个非选项上停止。例如，如果-a和-b都是不带参数的简单选项，optparse通常会接受以下语法：

并认为它等同于

要禁用此功能，请致电disable_interspersed_args()。这恢复了传统的Unix语法，其中选项解析在第一个非选项参数中停止。

如果你有一个命令处理器运行另一个具有自己的选项的命令，并且你想确保这些选项不会感到困惑，请使用它。例如，每个命令可能有一组不同的选项。

OptionParser.enable_interspersed_args()

将解析设置为不停止第一个非选项，允许使用命令参数散布开关。这是默认行为。

OptionParser.get_option(opt_str)

使用选项字符串opt_str返回选项实例，或者None如果没有选项具有该选项字符串。

OptionParser.has_option(opt_str)

如果OptionParser有选项字符串opt_str（例如-q或--verbose），则返回true 。

OptionParser.remove_option(opt_str)

如果OptionParser具有与opt_str相对应的选项，则删除该选项。如果该选项提供了任何其他选项字符串，则所有这些选项字符串都将失效。如果opt_str不属于属于此的任何选项OptionParser，则引发ValueError。

3.9. 选项之间的冲突

如果您不小心，可以很容易地定义带有冲突选项字符串的选项：

（如果您已经使用一些标准选项定义了自己的OptionParser子类，则尤其如此。）

每次添加选项时，都会optparse检查与现有选项的冲突。如果它找到了，它会调用当前的冲突处理机制。您可以在构造函数中设置冲突处理机制：

或者单独调用：

可用的冲突处理程序是：

"error" (default)假设选项冲突是一个编程错误，并会引发OptionConflictError"resolve"解决选项冲突（见下文）

作为一个例子，让我们定义一个OptionParser智能地解决冲突并为其添加冲突的选项：

此时，optparse检测到以前添加的选项已在使用-n选项字符串。既然conflict_handler是这样"resolve"，它通过-n从早期选项的选项字符串列表中删除来解决这种情况。现在--dry-run是用户激活该选项的唯一方式。如果用户请求帮助，帮助信息将反映：

可以删除先前添加的选项的选项字符串，直到没有剩下的选项，并且用户无法从命令行调用该选项。在这种情况下，请optparse完全删除该选项，以便它不会显示在帮助文本或其他任何地方。继续使用我们现有的OptionParser：

此时，原始-n/ --dry-run选项不再可访问，因此optparse将其删除，留下以下帮助文本：

3.10. 清理

OptionParser实例有几个循环引用。这对Python的垃圾回收器来说不应该是个问题，但是你可能希望在完成之后通过调用destroy()你的OptionParser来明确地断开循环引用。这对于长时间运行的应用程序特别有用，可以从OptionParser访问大对象图。

3.11. 其他方法

OptionParser支持其他几种公共方法：

OptionParser.set_usage(usage)

根据上述关于usage构造函数关键字参数的规则设置用法字符串。通过None设置默认使用字符串; 用于optparse.SUPPRESS_USAGE抑制使用消息。

OptionParser.print_usage(file=None)

将当前程序的使用消息（self.usage）打印到文件（默认stdout）。字符串的任何出现%prog在self.usage被替换为当前程序的名称。如果self.usage是空的或没有定义，什么也不做。

OptionParser.get_usage()

与print_usage()使用字符串相同，但返回使用字符串而不是打印它。

OptionParser.set_defaults(dest=value, ...)

一次为多个选项目标设置默认值。使用set_defaults()是设置选项默认值的首选方式，因为多个选项可以共享相同的目标。例如，如果多个“模式”选项都设置相同的目的地，则其中任何一个都可以设置默认值，最后一个可以胜出：

为了避免这种混淆，请使用set_defaults()：

4.选项回调

当optparse内置动作和类型不足以满足您的需求时，您有两种选择：扩展optparse或定义回调选项。扩展optparse是更一般的，但对于很多简单情况来说却是矫枉过正的。通常一个简单的回调就是你所需要的。

定义回调选项有两个步骤：

• 使用该"callback"操作定义选项本身

• 写回调; 这是一个至少需要四个参数的函数（或方法），如下所述

4.1. 定义回调选项

与往常一样，定义回调选项的最简单方法是使用该OptionParser.add_option()方法。除此之外action，您必须指定的唯一选项属性是callback要调用的函数：

callback是一个函数（或其他可调用对象），因此您必须my_callback()在创建此回调选项时已经定义。在这种简单的情况下，optparse甚至不知道是否-c接受任何参数，这通常意味着该选项不会引用任何参数 - 只需-c在命令行上存在即可。但是，在某些情况下，您可能希望回调消耗任意数量的命令行参数。这是写回调变得棘手的地方; 本节稍后会介绍。

optparse总是将四个特定参数传递给您的回调函数，如果您通过callback_args和指定它们，它将只传递附加参数callback_kwargs。因此，最小回调函数签名是：

下面介绍回调的四个参数。

在定义回调选项时，您可以提供其他几个选项属性：

type具有其通常的含义：与"store"or或"append"action一样，它指示optparse消费一个参数并将其转换为type。但不是将转换后的值存储在任何地方，而是optparse将其传递给您的回调函数。nargs也有其通常的含义：如果它被提供并且> 1，optparse将消费nargs参数，每个参数都必须可转换为type。然后它将转换值的元组传递给您的回调。callback_args一个额外的位置参数元组传递给回调callback_kwargs一个额外的关键字参数字典传递给回调

4.2. 如何调用回调

所有的回调被调用如下：

哪里

option是调用回调的选项实例opt_str是在触发回调的命令行中看到的选项字符串。（如果使用了一个缩写long选项，opt_str它将是完整的，规范的选项字符串 - 例如，如果用户将--foo命令行作为缩写--foobar，那么opt_str将是"--foobar"。）value是在命令行中看到的此选项的参数。optparse只有type设定了才会期待论据; 类型value将是选项类型所暗示的类型。如果type这个选项是None（没有理由），那么value将是None。如果nargs> 1，value将是适当类型的值的元组。parser

是驱动整个事物的OptionParser实例，主要是有用的，因为您可以通过其实例属性访问其他有趣的数据：

parser.largs当前的剩余参数列表，即。已被使用但不是选项或选项参数的参数。随意修改parser.largs，例如添加更多参数。（这个列表将成为args第二个返回值parse_args()。）parser.rargs剩余参数的当前列表，即。同opt_str和value（如适用）去除，并且只参数如下他们仍然存在。随意修改parser.rargs，例如通过消耗更多参数。parser.values默认存储选项值的对象（optparse.OptionValues的实例）。这可以让回调使用与其余部分相同的机制optparse用于存储选项值; 你不需要混淆全局或封闭。您还可以访问或修改已在命令行中遇到的任何选项的值。args是通过callback_argsoption属性提供的任意位置参数的元组。kwargs是通过提供的任意关键字参数的字典callback_kwargs。

4.3. 在回调中引发错误

如果该选项或其参数有任何问题，则应该提高回调函数OptionValueError。optparse捕获此并终止程序，打印您提供给stderr的错误消息。您的信息应该清晰，简洁，准确，并提及有问题的选项。否则，用户将很难弄清楚他做错了什么。

4.4. 回调示例1：平凡的回调

下面是一个不带任何参数的回调选项的例子，并简单地记录下该选项：

当然，你可以用这个"store_true"动作来做到这一点。

4.5. 回调示例2：检查选项顺序

这里有一个稍微有趣的例子：记录下-a看到的事实，但如果它-b在命令行中出现，则会炸毁。

4.6. 回调示例3：检查选项顺序（概括）

如果你想为几个类似的选项重新使用这个回调-b函数（设置一个标志，但是如果已经被看到就炸毁），它需要一些工作：错误信息和它设置的标志必须被概括。

4.7. 回调示例4：检查任意条件

当然，您可以在其中放置任何条件 - 您不仅限于检查已定义选项的值。例如，如果您在月球满了时不应调用选项，则只需执行以下操作：

（这个定义is_moon_full()留给读者练习。）

4.8. 回调示例5：固定参数

当定义带有固定数量参数的回调选项时，情况会变得更有趣。指定回调选项需要参数类似于定义一个"store"或一个"append"选项：如果定义type，则该选项带有一个必须可转换为该类型的参数; 如果你进一步定义nargs，那么该选项需要nargs参数。

以下是一个模拟标准"store"动作的例子：

请注意，optparse需要消耗3个参数并将它们转换为整数; 你所要做的就是存储它们。（或者其他;显然你不需要回调这个例子。）

4.9. 回调示例6：可变参数

当你想要一个选项来获取可变数量的参数时，情况会变得多毛。对于这种情况，您必须编写回调optparse函数，因为它不提供任何内置功能。而且您必须处理optparse通常为您处理的常规Unix命令行解析的某些复杂问题。具体来说，回调应该执行裸--和-参数的传统规则：

• 无论是--或-可选项参数

• 裸露--（如果不是一些选项的参数）：停止命令行处理并放弃--

• 裸露-（如果不是某些选项的参数）：暂停命令行处理，但保留-（附加到parser.largs）

如果你想要一个带有可变数量参数的选项，那么需要考虑几个微妙棘手的问题。您选择的具体实现将基于您愿意为您的应用程序进行哪些权衡（这就是为什么optparse不直接支持这种事情的原因）。

尽管如此，下面是一个带有可变参数的选项的回调函数：

5.扩展optparse

由于optparse解释命令行选项的两个主要控制因素是每个选项的操作和类型，所以最可能的扩展方向是添加新操作和新类型。

5.1. 添加新的类型

要添加新的类型，你需要定义自己的子类optparse的Option类。这个类有几个定义optparse类型的属性：TYPES和TYPE_CHECKER。

Option.TYPES

类型名称的元组; 在你的子类中，只需定义一个TYPES基于标准元组的新元组。

Option.TYPE_CHECKER

字典映射类型名称到类型检查函数。类型检查函数具有以下签名：

option是一个Option实例，opt是一个选项字符串（例如-f），并且value是命令行中必须检查并转换为所需类型的字符串。check_mytype()应返回假设类型的对象mytype。类型检查函数返回的值将返回到返回的OptionValues实例中OptionParser.parse_args()，或作为value参数传递给回调函数。

如果遇到任何问题，您的类型检查功能应该升高OptionValueError如果遇到任何问题，您的类型检查功能应该升高。OptionValueError接受一个字符串参数，它被原样传递是OptionParser的error()方法，这反过来会预先考虑节目名称和字符串"error:"和结束处理之前打印一切到stderr。

下面是一个愚蠢的例子，演示了"complex"如何在命令行中添加一个选项类型来分析Python风格的复数。（这比以前更加恶劣，因为optparse1.3增加了对复杂数字的内置支持，但没关系。）

首先，必要的进口：

您需要首先定义类型检查器，因为它稍后会引用（在TYPE_CHECKER您的Option子类的类属性中）：

最后，Option子类：

（如果我们不做出copy()的Option.TYPE_CHECKER，我们最终会修改TYPE_CHECKER的属性optparse的选项类。这是Python的，没有什么可以阻止你做，除了良好的礼仪和常识。）

而已！现在您可以编写一个使用新选项类型optparse的脚本，就像其他任何基于脚本的脚本一样，除非您必须指示OptionParser使用MyOption而不是Option：

或者，您可以构建自己的选项列表并将其传递给OptionParser; 如果你不add_option()以上面的方式使用，你不需要告诉OptionParser使用哪个选项类：

5.2. 添加新的操作

添加新的动作有点棘手，因为您必须了解这个动作optparse有几个分类：

“存储”操作，导致optparse将值存储到当前OptionValues实例的属性; 这些选项需要为destOption构造函数提供一个属性。“typed”actionactions从命令行获取一个值，并期望它具有某种类型; 或者更确切地说，是一个可以转换成某种类型的字符串。这些选项需要typeOption构造函数的一个属性。

这些重叠的集合：一些默认的“店”的行动是"store"，"store_const"，"append"，和"count"，而默认的“类型化”行动"store"，"append"和"callback"。

当你添加一个动作时，你需要通过将其列入至少一个以下的Option类属性中进行分类（所有都是字符串列表）：

Option.ACTIONS

所有操作必须在操作中列出。

Option.STORE_ACTIONS

此处还列出了“商店”操作。

Option.TYPED_ACTIONS

此处列出了“键入”操作。

Option.ALWAYS_TYPED_ACTIONS

总是采用某种类型的操作（即其选项总是取值）在此处另行列出。这样做的唯一影响是optparse将默认类型，分配给"string"没有列出其操作的显式类型的选项ALWAYS_TYPED_ACTIONS。

为了实际执行您的新操作，您必须覆盖Option的take_action()方法并添加一个识别您的操作的案例。

例如，让我们添加一个"extend"动作。这与标准"append"动作类似，但不是从命令行获取单个值并将其附加到现有列表，而是使用"extend"逗号分隔的单个字符串取多个值，并用它们扩展现有列表。也就是说，如果--names是"extend"类型选项，则是"string"命令行

会导致一个列表

我们再次定义一个Option的子类：

说明的特点：

• "extend"双方预计，在命令行和重视的地方存储值，如此这般在这两个STORE_ACTIONS和TYPED_ACTIONS。

• 为了确保optparse将默认类型分配"string"给"extend"操作，我们也将"extend"操作放入ALWAYS_TYPED_ACTIONS。

• MyOption.take_action()只实现这一个新动作，并将控制权交给Option.take_action()标准optparse动作。

• values是optparse_parser.Values类的一个实例，它提供了非常有用的ensure_value()方法。ensure_value()实质上getattr()是安全阀; 它被称为

values.ensure_value(attr, value)

如果该attr属性values不存在或是None，则sure_value（）首先将其设置为value，然后返回'value。这对于像"extend"，，"append"和"count"所有这些操作非常方便，所有这些操作都将数据累加到一个变量中，并期望该变量具有某种类型（前两个是后者的整数）。使用ensure_value()意味着使用您的操作的脚本不必担心为有问题的选项目标设置默认值; 他们可以保留默认值，None并ensure_value()在需要时处理。