1666 lines
249 KiB
HTML
1666 lines
249 KiB
HTML
|
||
<!DOCTYPE html>
|
||
|
||
<html xmlns="http://www.w3.org/1999/xhtml" lang="zh_CN">
|
||
<head>
|
||
<meta charset="utf-8" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
|
||
|
||
<title>optparse --- 命令行选项的解析器 — Python 3.8.20 文档</title><meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||
|
||
<link rel="stylesheet" href="../_static/pydoctheme.css" type="text/css" />
|
||
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
|
||
|
||
<script id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
|
||
<script src="../_static/jquery.js"></script>
|
||
<script src="../_static/underscore.js"></script>
|
||
<script src="../_static/doctools.js"></script>
|
||
<script src="../_static/language_data.js"></script>
|
||
<script src="../_static/translations.js"></script>
|
||
|
||
<script src="../_static/sidebar.js"></script>
|
||
|
||
<link rel="search" type="application/opensearchdescription+xml"
|
||
title="在 Python 3.8.20 文档 中搜索"
|
||
href="../_static/opensearch.xml"/>
|
||
<link rel="author" title="关于这些文档" href="../about.html" />
|
||
<link rel="index" title="索引" href="../genindex.html" />
|
||
<link rel="search" title="搜索" href="../search.html" />
|
||
<link rel="copyright" title="版权所有" href="../copyright.html" />
|
||
<link rel="next" title="imp --- 访问 import 内部对象" href="imp.html" />
|
||
<link rel="prev" title="被取代的模块" href="superseded.html" />
|
||
<link rel="canonical" href="https://docs.python.org/3/library/optparse.html" />
|
||
|
||
|
||
|
||
|
||
|
||
<style>
|
||
@media only screen {
|
||
table.full-width-table {
|
||
width: 100%;
|
||
}
|
||
}
|
||
</style>
|
||
<link rel="shortcut icon" type="image/png" href="../_static/py.svg" />
|
||
<script type="text/javascript" src="../_static/copybutton.js"></script>
|
||
<script type="text/javascript" src="../_static/menu.js"></script>
|
||
|
||
</head>
|
||
<body>
|
||
<div class="mobile-nav">
|
||
<input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"
|
||
aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu" />
|
||
<label for="menuToggler" class="toggler__label">
|
||
<span></span>
|
||
</label>
|
||
<nav class="nav-content" role="navigation">
|
||
<a href="https://www.python.org/" class="nav-logo">
|
||
<img src="../_static/py.svg" alt="Logo"/>
|
||
</a>
|
||
<div class="version_switcher_placeholder"></div>
|
||
<form role="search" class="search" action="../search.html" method="get">
|
||
<svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">
|
||
<path fill-rule="nonzero"
|
||
d="M15.5 14h-.79l-.28-.27a6.5 6.5 0 001.48-5.34c-.47-2.78-2.79-5-5.59-5.34a6.505 6.505 0 00-7.27 7.27c.34 2.8 2.56 5.12 5.34 5.59a6.5 6.5 0 005.34-1.48l.27.28v.79l4.25 4.25c.41.41 1.08.41 1.49 0 .41-.41.41-1.08 0-1.49L15.5 14zm-6 0C7.01 14 5 11.99 5 9.5S7.01 5 9.5 5 14 7.01 14 9.5 11.99 14 9.5 14z" fill="#444"></path>
|
||
</svg>
|
||
<input type="text" name="q" aria-label="快速搜索"/>
|
||
<input type="submit" value="转向"/>
|
||
</form>
|
||
</nav>
|
||
<div class="menu-wrapper">
|
||
<nav class="menu" role="navigation" aria-label="main navigation">
|
||
<div class="language_switcher_placeholder"></div>
|
||
<h3><a href="../contents.html">目录</a></h3>
|
||
<ul>
|
||
<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code> --- 命令行选项的解析器</a><ul>
|
||
<li><a class="reference internal" href="#background">背景</a><ul>
|
||
<li><a class="reference internal" href="#terminology">术语</a></li>
|
||
<li><a class="reference internal" href="#what-are-options-for">选项的作用是什么？</a></li>
|
||
<li><a class="reference internal" href="#what-are-positional-arguments-for">位置参数有什么用？</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#tutorial">教程</a><ul>
|
||
<li><a class="reference internal" href="#understanding-option-actions">理解选项动作</a></li>
|
||
<li><a class="reference internal" href="#the-store-action">store 动作</a></li>
|
||
<li><a class="reference internal" href="#handling-boolean-flag-options">处理布尔值（旗标）选项</a></li>
|
||
<li><a class="reference internal" href="#other-actions">其他动作</a></li>
|
||
<li><a class="reference internal" href="#default-values">默认值</a></li>
|
||
<li><a class="reference internal" href="#generating-help">生成帮助</a><ul>
|
||
<li><a class="reference internal" href="#grouping-options">选项分组</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#printing-a-version-string">打印版本字符串</a></li>
|
||
<li><a class="reference internal" href="#how-optparse-handles-errors"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code> 如何处理错误handles errors</a></li>
|
||
<li><a class="reference internal" href="#putting-it-all-together">合并所有代码</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#reference-guide">参考指南</a><ul>
|
||
<li><a class="reference internal" href="#creating-the-parser">创建解析器</a></li>
|
||
<li><a class="reference internal" href="#populating-the-parser">填充解析器</a></li>
|
||
<li><a class="reference internal" href="#defining-options">定义选项</a></li>
|
||
<li><a class="reference internal" href="#option-attributes">选项属性</a></li>
|
||
<li><a class="reference internal" href="#standard-option-actions">标准选项动作</a></li>
|
||
<li><a class="reference internal" href="#standard-option-types">标准选项类型</a></li>
|
||
<li><a class="reference internal" href="#parsing-arguments">解析参数</a></li>
|
||
<li><a class="reference internal" href="#querying-and-manipulating-your-option-parser">查询和操纵你的选项解析器</a></li>
|
||
<li><a class="reference internal" href="#conflicts-between-options">选项之间的冲突</a></li>
|
||
<li><a class="reference internal" href="#cleanup">清理</a></li>
|
||
<li><a class="reference internal" href="#other-methods">其他方法</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#option-callbacks">选项回调</a><ul>
|
||
<li><a class="reference internal" href="#defining-a-callback-option">定义回调选项</a></li>
|
||
<li><a class="reference internal" href="#how-callbacks-are-called">回调应当如何调用</a></li>
|
||
<li><a class="reference internal" href="#raising-errors-in-a-callback">在回调中引发错误</a></li>
|
||
<li><a class="reference internal" href="#callback-example-1-trivial-callback">回调示例 1：最简回调</a></li>
|
||
<li><a class="reference internal" href="#callback-example-2-check-option-order">回调示例 2：检查选项顺序</a></li>
|
||
<li><a class="reference internal" href="#callback-example-3-check-option-order-generalized">回调示例 3：检查选项顺序（通用）</a></li>
|
||
<li><a class="reference internal" href="#callback-example-4-check-arbitrary-condition">回调示例 4：检查任意条件</a></li>
|
||
<li><a class="reference internal" href="#callback-example-5-fixed-arguments">回调示例 5：固定的参数</a></li>
|
||
<li><a class="reference internal" href="#callback-example-6-variable-arguments">回调示例 6：可变的参数</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#extending-optparse">扩展 <code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a><ul>
|
||
<li><a class="reference internal" href="#adding-new-types">添加新的类型</a></li>
|
||
<li><a class="reference internal" href="#adding-new-actions">添加新的动作</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
<h4>上一个主题</h4>
|
||
<p class="topless"><a href="superseded.html"
|
||
title="上一章">被取代的模块</a></p>
|
||
<h4>下一个主题</h4>
|
||
<p class="topless"><a href="imp.html"
|
||
title="下一章"><code class="xref py py-mod docutils literal notranslate"><span class="pre">imp</span></code> --- 访问 <span class="xref std std-ref">import</span> 内部对象</a></p>
|
||
<div role="note" aria-label="source link">
|
||
<h3>本页</h3>
|
||
<ul class="this-page-menu">
|
||
<li><a href="../bugs.html">报告 Bug</a></li>
|
||
<li>
|
||
<a href="https://github.com/python/cpython/blob/3.8/Doc/library/optparse.rst"
|
||
rel="nofollow">显示源代码
|
||
</a>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</nav>
|
||
</div>
|
||
</div>
|
||
|
||
<div id="outdated-warning" style="padding: .5em; text-align: center; background-color: #FFBABA; color: #6A0E0E;">
|
||
这个文档所针对的是一个已不再受支持的 Python 旧版本。
|
||
你应当升级版本，并阅读
|
||
<a href="/3/library/optparse.html"> Python 当前稳定版本的文档</a>.
|
||
</div>
|
||
|
||
<div class="related" role="navigation" aria-label="related navigation">
|
||
<h3>导航</h3>
|
||
<ul>
|
||
<li class="right" style="margin-right: 10px">
|
||
<a href="../genindex.html" title="总目录"
|
||
accesskey="I">索引</a></li>
|
||
<li class="right" >
|
||
<a href="../py-modindex.html" title="Python 模块索引"
|
||
>模块</a> |</li>
|
||
<li class="right" >
|
||
<a href="imp.html" title="imp --- 访问 import 内部对象"
|
||
accesskey="N">下一页</a> |</li>
|
||
<li class="right" >
|
||
<a href="superseded.html" title="被取代的模块"
|
||
accesskey="P">上一页</a> |</li>
|
||
|
||
<li><img src="../_static/py.svg" alt="python logo" style="vertical-align: middle; margin-top: -1px"/></li>
|
||
<li><a href="https://www.python.org/">Python</a> »</li>
|
||
<li class="switchers">
|
||
<div class="language_switcher_placeholder"></div>
|
||
<div class="version_switcher_placeholder"></div>
|
||
</li>
|
||
<li>
|
||
|
||
</li>
|
||
<li id="cpython-language-and-version">
|
||
<a href="../index.html">3.8.20 Documentation</a> »
|
||
</li>
|
||
|
||
<li class="nav-item nav-item-1"><a href="index.html" >Python 标准库</a> »</li>
|
||
<li class="nav-item nav-item-2"><a href="superseded.html" accesskey="U">被取代的模块</a> »</li>
|
||
<li class="right">
|
||
|
||
|
||
<div class="inline-search" role="search">
|
||
<form class="inline-search" action="../search.html" method="get">
|
||
<input placeholder="快速搜索" aria-label="快速搜索" type="text" name="q" />
|
||
<input type="submit" value="转向" />
|
||
<input type="hidden" name="check_keywords" value="yes" />
|
||
<input type="hidden" name="area" value="default" />
|
||
</form>
|
||
</div>
|
||
|
|
||
</li>
|
||
|
||
</ul>
|
||
</div>
|
||
|
||
<div class="document">
|
||
<div class="documentwrapper">
|
||
<div class="bodywrapper">
|
||
<div class="body" role="main">
|
||
|
||
<section id="module-optparse">
|
||
<span id="optparse-parser-for-command-line-options"></span><h1><a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> --- 命令行选项的解析器<a class="headerlink" href="#module-optparse" title="永久链接至标题">¶</a></h1>
|
||
<p><strong>源代码：</strong> <a class="reference external" href="https://github.com/python/cpython/tree/3.8/Lib/optparse.py">Lib/optparse.py</a></p>
|
||
<div class="deprecated">
|
||
<p><span class="versionmodified deprecated">3.2 版后已移除: </span><a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 模块已被弃用并且将不再继续开发；开发将转至 <a class="reference internal" href="argparse.html#module-argparse" title="argparse: Command-line option and argument parsing library."><code class="xref py py-mod docutils literal notranslate"><span class="pre">argparse</span></code></a> 模块进行。</p>
|
||
</div>
|
||
<hr class="docutils" />
|
||
<p><a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 是一个相比原有 <a class="reference internal" href="getopt.html#module-getopt" title="getopt: Portable parser for command line options; support both short and long option names."><code class="xref py py-mod docutils literal notranslate"><span class="pre">getopt</span></code></a> 模块更为方便、灵活和强大的命令行选项解析库。 <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 使用更为显明的命令行解析风格：创建一个 <a class="reference internal" href="#optparse.OptionParser" title="optparse.OptionParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">OptionParser</span></code></a> 的实例，向其中填充选项，然后解析命令行。 <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 允许用户以传统的 GNU/POSIX 语法来指定选项，并为你生成额外的用法和帮助消息。</p>
|
||
<p>下面是在一个简单脚本中使用 <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 的示例:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">optparse</span> <span class="kn">import</span> <span class="n">OptionParser</span>
|
||
<span class="o">...</span>
|
||
<span class="n">parser</span> <span class="o">=</span> <span class="n">OptionParser</span><span class="p">()</span>
|
||
<span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"-f"</span><span class="p">,</span> <span class="s2">"--file"</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s2">"filename"</span><span class="p">,</span>
|
||
<span class="n">help</span><span class="o">=</span><span class="s2">"write report to FILE"</span><span class="p">,</span> <span class="n">metavar</span><span class="o">=</span><span class="s2">"FILE"</span><span class="p">)</span>
|
||
<span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"-q"</span><span class="p">,</span> <span class="s2">"--quiet"</span><span class="p">,</span>
|
||
<span class="n">action</span><span class="o">=</span><span class="s2">"store_false"</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s2">"verbose"</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span>
|
||
<span class="n">help</span><span class="o">=</span><span class="s2">"don't print status messages to stdout"</span><span class="p">)</span>
|
||
|
||
<span class="p">(</span><span class="n">options</span><span class="p">,</span> <span class="n">args</span><span class="p">)</span> <span class="o">=</span> <span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">()</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>通过这几行代码，你的脚本的用户可以在命令行上完成“常见任务”，例如:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="o"><</span><span class="n">yourscript</span><span class="o">></span> <span class="o">--</span><span class="n">file</span><span class="o">=</span><span class="n">outfile</span> <span class="o">-</span><span class="n">q</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>在它解析命令行时，<a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 会根据用户提供的命令行值设置 <code class="xref py py-meth docutils literal notranslate"><span class="pre">parse_args()</span></code> 所返回的 <code class="docutils literal notranslate"><span class="pre">options</span></code> 对象的属性。 当 <code class="xref py py-meth docutils literal notranslate"><span class="pre">parse_args()</span></code> 从解析此命令行返回时，<code class="docutils literal notranslate"><span class="pre">options.filename</span></code> 将为 <code class="docutils literal notranslate"><span class="pre">"outfile"</span></code> 而 <code class="docutils literal notranslate"><span class="pre">options.verbose</span></code> 将为 <code class="docutils literal notranslate"><span class="pre">False</span></code>。 <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 支持长短两种形式的选项，允许多个短选项合并到一起，并允许选项以多种方式与其参数相关联。 因此，以下命令行均等价于以上示例:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="o"><</span><span class="n">yourscript</span><span class="o">></span> <span class="o">-</span><span class="n">f</span> <span class="n">outfile</span> <span class="o">--</span><span class="n">quiet</span>
|
||
<span class="o"><</span><span class="n">yourscript</span><span class="o">></span> <span class="o">--</span><span class="n">quiet</span> <span class="o">--</span><span class="n">file</span> <span class="n">outfile</span>
|
||
<span class="o"><</span><span class="n">yourscript</span><span class="o">></span> <span class="o">-</span><span class="n">q</span> <span class="o">-</span><span class="n">foutfile</span>
|
||
<span class="o"><</span><span class="n">yourscript</span><span class="o">></span> <span class="o">-</span><span class="n">qfoutfile</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>此外，用户还可以运行以下命令之一</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="o"><</span><span class="n">yourscript</span><span class="o">></span> <span class="o">-</span><span class="n">h</span>
|
||
<span class="o"><</span><span class="n">yourscript</span><span class="o">></span> <span class="o">--</span><span class="n">help</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>这样 <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 将打印出你的脚本的选项概要:</p>
|
||
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>Usage: <yourscript> [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
|
||
</pre></div>
|
||
</div>
|
||
<p>其中 <em>yourscript</em> 的值是在运行时确定的 (通常来自 <code class="docutils literal notranslate"><span class="pre">sys.argv[0]</span></code>)。</p>
|
||
<section id="background">
|
||
<span id="optparse-background"></span><h2>背景<a class="headerlink" href="#background" title="永久链接至标题">¶</a></h2>
|
||
<p><a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 被显式设计为鼓励创建带有简洁直观、符合惯例的命令行接口的程序。 为了这个目标，它仅支持最常见的命令行语法和在 Unix 下使用的规范语义。 如果你不熟悉这些惯例，请阅读本小节来使自己熟悉它们。</p>
|
||
<section id="terminology">
|
||
<span id="optparse-terminology"></span><h3>术语<a class="headerlink" href="#terminology" title="永久链接至标题">¶</a></h3>
|
||
<dl>
|
||
<dt>argument -- 参数</dt><dd><p>在命令行中输入的字符串，并会被 shell 传给 <code class="docutils literal notranslate"><span class="pre">execl()</span></code> 或 <code class="docutils literal notranslate"><span class="pre">execv()</span></code>。 在 Python 中，参数将是 <code class="docutils literal notranslate"><span class="pre">sys.argv[1:]</span></code> 的元素 (<code class="docutils literal notranslate"><span class="pre">sys.argv[0]</span></code> 是被执行的程序的名称)。 Unix shell 也使用术语 "word" 来指代参数。</p>
|
||
<p>有时替换 <code class="docutils literal notranslate"><span class="pre">sys.argv[1:]</span></code> 以外的参数列表也是必要的，所以你应当将 "参数" 当作是 "<code class="docutils literal notranslate"><span class="pre">sys.argv[1:]</span></code> 的一个元素，或者是作为 <code class="docutils literal notranslate"><span class="pre">sys.argv[1:]</span></code> 的替代的其他列表"。</p>
|
||
</dd>
|
||
<dt>选项</dt><dd><p>一个用来提供额外信息以指导或定制程序的执行的参数。 对于选项有许多不同的语法；传统的 Unix 语法是一个连字符 ("-") 后面跟单个字母，例如 <code class="docutils literal notranslate"><span class="pre">-x</span></code> 或 <code class="docutils literal notranslate"><span class="pre">-F</span></code>。 此外，传统的 Unix 语法允许将多个选项合并为一个参数，例如 <code class="docutils literal notranslate"><span class="pre">-x</span> <span class="pre">-F</span></code> 就等价于 <code class="docutils literal notranslate"><span class="pre">-xF</span></code>。 GNU 项目引入了 <code class="docutils literal notranslate"><span class="pre">--</span></code> 后面跟一串以连字符分隔的单词，例如 <code class="docutils literal notranslate"><span class="pre">--file</span></code> 或 <code class="docutils literal notranslate"><span class="pre">--dry-run</span></code>。 它们是 <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 所提供的仅有的两种选项语法。</p>
|
||
<p>存在于世上的其他一些选项语法包括:</p>
|
||
<ul class="simple">
|
||
<li><p>一个连字符后面跟几个字母，例如 <code class="docutils literal notranslate"><span class="pre">-pf</span></code> (这与多个选项合并成单个参数 <em>并不</em> 一样)</p></li>
|
||
<li><p>一个连字符后面跟一个完整单词，例如 <code class="docutils literal notranslate"><span class="pre">-file</span></code> (这在技术上等同于前面的语法，但它们通常不在同一个程序中出现)</p></li>
|
||
<li><p>一个加号后面跟一个字母，或几个字母，或一个单词，例如 <code class="docutils literal notranslate"><span class="pre">+f</span></code>, <code class="docutils literal notranslate"><span class="pre">+rgb</span></code></p></li>
|
||
<li><p>一个斜杠后面跟一个字母，或几个字母，或一个单词，例如 <code class="docutils literal notranslate"><span class="pre">/f</span></code>, <code class="docutils literal notranslate"><span class="pre">/file</span></code></p></li>
|
||
</ul>
|
||
<p>These option syntaxes are not supported by <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a>, and they never
|
||
will be. This is deliberate: the first three are non-standard on any
|
||
environment, and the last only makes sense if you're exclusively targeting
|
||
VMS, MS-DOS, and/or Windows.</p>
|
||
</dd>
|
||
<dt>可选参数:</dt><dd><p>一个跟在某个选项之后的参数，与该选项紧密相关，并会在该选项被消耗时从参数列表中被消耗。 使用 <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a>，选项参数可以是其对应选项以外的一个单独参数:</p>
|
||
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>-f foo
|
||
--file foo
|
||
</pre></div>
|
||
</div>
|
||
<p>或是包括在同一个参数中:</p>
|
||
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>-ffoo
|
||
--file=foo
|
||
</pre></div>
|
||
</div>
|
||
<p>通常，一个给定的选项将接受一个参数或是不接受。 许多人想要“可选的可选参数”特性，即某些选项将在看到特定参数时接受它，而如果没看到特定参数则不接受。 在某种程度上说这一特性是存在争议的，因它它将使解析发生歧义：如果 <code class="docutils literal notranslate"><span class="pre">-a</span></code> 接受一个可选参数而 <code class="docutils literal notranslate"><span class="pre">-b</span></code> 是完全不同的另一个选项，那我们该如何解读 <code class="docutils literal notranslate"><span class="pre">-ab</span></code> 呢？ 由于这会存在歧义，因此 <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 不支持这一特性。</p>
|
||
</dd>
|
||
<dt>positional argument -- 位置参数</dt><dd><p>在解析选项之后，即在选项及其参数解析完成并从参数列表中移除后参数列表中余下的内容。</p>
|
||
</dd>
|
||
<dt>必选选项</dt><dd><p>必须在命令行中提供的选项；请注意在英文中 "required option" 这个短语是自相矛盾的。 <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 不会阻止你实现必须选项，但也不会在这方面给你什么帮助。</p>
|
||
</dd>
|
||
</dl>
|
||
<p>例如，考虑这个假设的命令行:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">prog</span> <span class="o">-</span><span class="n">v</span> <span class="o">--</span><span class="n">report</span> <span class="n">report</span><span class="o">.</span><span class="n">txt</span> <span class="n">foo</span> <span class="n">bar</span>
|
||
</pre></div>
|
||
</div>
|
||
<p><code class="docutils literal notranslate"><span class="pre">-v</span></code> 和 <code class="docutils literal notranslate"><span class="pre">--report</span></code> 都是选项。 假定 <code class="docutils literal notranslate"><span class="pre">--report</span></code> 接受一个参数，<code class="docutils literal notranslate"><span class="pre">report.txt</span></code> 是一个选项参数。 <code class="docutils literal notranslate"><span class="pre">foo</span></code> 和 <code class="docutils literal notranslate"><span class="pre">bar</span></code> 是位置参数。</p>
|
||
</section>
|
||
<section id="what-are-options-for">
|
||
<span id="optparse-what-options-for"></span><h3>选项的作用是什么？<a class="headerlink" href="#what-are-options-for" title="永久链接至标题">¶</a></h3>
|
||
<p>选项被用来提供额外信息以便微调或定制程序的执行。 需要明确的一点是，选项通常都是 <em>可选的</em>。 一个程序应当能在没有设置任何选项的的情况下正常运行。 （从 Unix 或 GNU 工具集中随机挑选一个程序。 它是否能在未设置任何选项的情况下运行并且仍然得到有意义的结果？ 主要的例外有 <code class="docutils literal notranslate"><span class="pre">find</span></code>, <code class="docutils literal notranslate"><span class="pre">tar</span></code> 和 <code class="docutils literal notranslate"><span class="pre">dd</span></code> --- 它们都是些因为语法不标准和界面混乱而受到公正抨击的变异奇行种。）</p>
|
||
<p>有很多人希望他们的程序具有“必需选项”。 请再思考一下。 如果某个项是必需的，那么它就 <em>不是可选的</em>！ 如果你的程序必需要有某项信息才能成功运行，则它更适合作为位置参数。</p>
|
||
<p>作为良好的命令行界面设计的一个例子，请看基本的用于拷贝文件的 <code class="docutils literal notranslate"><span class="pre">cp</span></code> 工具。 试图拷贝文件而不提供一个目标和至少一个源是没有什么意义的。 因此，如果你不带参数地运行 <code class="docutils literal notranslate"><span class="pre">cp</span></code> 它将会报错。 不过，它具有一个完全不需要任何选项的灵活、易用的语法:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">cp</span> <span class="n">SOURCE</span> <span class="n">DEST</span>
|
||
<span class="n">cp</span> <span class="n">SOURCE</span> <span class="o">...</span> <span class="n">DEST</span><span class="o">-</span><span class="n">DIR</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>你只使用这个语法就能畅行无阻。 大多数 <code class="docutils literal notranslate"><span class="pre">cp</span></code> 实现还提供了许多精确调整文件拷贝方式的选项：你可以保留模式和修改时间，避免跟随符号链接，覆盖现有文件之前先询问，诸如此类。 但这些都不会破坏 <code class="docutils literal notranslate"><span class="pre">cp</span></code> 的核心任务，即将一个文件拷贝为另一个文件，或将多个文件拷贝到另一个目录。</p>
|
||
</section>
|
||
<section id="what-are-positional-arguments-for">
|
||
<span id="optparse-what-positional-arguments-for"></span><h3>位置参数有什么用？<a class="headerlink" href="#what-are-positional-arguments-for" title="永久链接至标题">¶</a></h3>
|
||
<p>位置参数是对于你的程序运行来说绝对、肯定需要的信息片段。</p>
|
||
<p>一个好的用户界面应当尽可能少地设置绝对必需提供的信息。 如果你的程序必需提供 17 项不同的信息片段才能成功运行，那么你要 <em>如何</em> 从用户获取这些信息将不是问题的关键 --- 大多数人会在他们成功运行此程序之前放弃并离开。 无论用户界面是命令行、配置文件还是 GUI 都一样适用：如果你对你的用户提出如此多的要求，它们大多将会直接放弃。</p>
|
||
<p>简而言之，请尽量最小化绝对要求用户提供的信息量 --- 只要有可能就使用合理的默认值。 当然，你希望程序足够灵活也是合理的。 这就是选项的作用。 同样，选项是配置文件中的条目，GUI 中的“首选项”对话框中的控件，还是命令行选项不是问题的关键 --- 你实现的选项越多，你的程序就越灵活，它的具体实现也会变得更为复杂。 当然，太大的灵活性也存在缺点；过多的选项会让用户更难掌握并使你的代码更难维护。</p>
|
||
</section>
|
||
</section>
|
||
<section id="tutorial">
|
||
<span id="optparse-tutorial"></span><h2>教程<a class="headerlink" href="#tutorial" title="永久链接至标题">¶</a></h2>
|
||
<p>虽然 <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 非常灵活和强大，但在大多数情况下它也很简明易用。 本小节介绍了任何基于 <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 的程序中常见的代码模式。</p>
|
||
<p>首先，你需要导入 OptionParser 类；然后在主程序的开头部分，创建一个 OptionParser 实例:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">optparse</span> <span class="kn">import</span> <span class="n">OptionParser</span>
|
||
<span class="o">...</span>
|
||
<span class="n">parser</span> <span class="o">=</span> <span class="n">OptionParser</span><span class="p">()</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>然后你可以开始定义选项。 基本语法如下:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="n">opt_str</span><span class="p">,</span> <span class="o">...</span><span class="p">,</span>
|
||
<span class="n">attr</span><span class="o">=</span><span class="n">value</span><span class="p">,</span> <span class="o">...</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>每个选项有一个或多个选项字符串，如 <code class="docutils literal notranslate"><span class="pre">-f</span></code> 或 <code class="docutils literal notranslate"><span class="pre">--file</span></code>，以及一些选项属性用来告诉 <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 当它在命令行中遇到该选项时将得到什么和需要做什么。</p>
|
||
<p>通常，每个选项都会有一个短选项字符串和一个长选项字符串，例如</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"-f"</span><span class="p">,</span> <span class="s2">"--file"</span><span class="p">,</span> <span class="o">...</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>你可以随你的喜好自由定义任意数量的短选项字符串和任意数量的长选项字符串（包括零个），只要总计至少有一个选项字符串。</p>
|
||
<p>传给 <a class="reference internal" href="#optparse.OptionParser.add_option" title="optparse.OptionParser.add_option"><code class="xref py py-meth docutils literal notranslate"><span class="pre">OptionParser.add_option()</span></code></a> 的选项字符串实际上是特定调用所定义的选项的标签。 为了表述简单，我们将经常会说在命令行中 <em>遇到一个选项</em>；而实际上，<a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 是遇到了 <em>选项字符串</em> 并根据它们来查找选项。</p>
|
||
<p>一旦你定义好所有的选项，即可指令 <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 来解析你的程序的命令行:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="p">(</span><span class="n">options</span><span class="p">,</span> <span class="n">args</span><span class="p">)</span> <span class="o">=</span> <span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">()</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>（如果你愿意，你可以将自定义的参数列表传给 <code class="xref py py-meth docutils literal notranslate"><span class="pre">parse_args()</span></code>，但很少有必要这样做：默认它将使用 <code class="docutils literal notranslate"><span class="pre">sys.argv[1:]</span></code>。）</p>
|
||
<p><code class="xref py py-meth docutils literal notranslate"><span class="pre">parse_args()</span></code> 返回两个值：</p>
|
||
<ul class="simple">
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">options</span></code>，一个包含你所有的选项的值的对象 --- 举例来说，如果 <code class="docutils literal notranslate"><span class="pre">--file</span></code> 接受一个字符串参数，则 <code class="docutils literal notranslate"><span class="pre">options.file</span></code> 将为用户所提供的文件名，或者如果用户未提供该选项则为 <code class="docutils literal notranslate"><span class="pre">None</span></code></p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">args</span></code>，由解析选项之后余下的位置参数组成的列表</p></li>
|
||
</ul>
|
||
<p>本教学章节只介绍了四个最重要的选项属性: <a class="reference internal" href="#optparse.Option.action" title="optparse.Option.action"><code class="xref py py-attr docutils literal notranslate"><span class="pre">action</span></code></a>, <a class="reference internal" href="#optparse.Option.type" title="optparse.Option.type"><code class="xref py py-attr docutils literal notranslate"><span class="pre">type</span></code></a>, <a class="reference internal" href="#optparse.Option.dest" title="optparse.Option.dest"><code class="xref py py-attr docutils literal notranslate"><span class="pre">dest</span></code></a> (destination) 和 <a class="reference internal" href="#optparse.Option.help" title="optparse.Option.help"><code class="xref py py-attr docutils literal notranslate"><span class="pre">help</span></code></a>。 其中，<a class="reference internal" href="#optparse.Option.action" title="optparse.Option.action"><code class="xref py py-attr docutils literal notranslate"><span class="pre">action</span></code></a> 是最基本的一个。</p>
|
||
<section id="understanding-option-actions">
|
||
<span id="optparse-understanding-option-actions"></span><h3>理解选项动作<a class="headerlink" href="#understanding-option-actions" title="永久链接至标题">¶</a></h3>
|
||
<p>动作是告诉 <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 当它在命令行中遇到某个选项时要做什么。 有一个固定的动作集被硬编码到 <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 内部；添加新的动作是将在 <a class="reference internal" href="#optparse-extending-optparse"><span class="std std-ref">扩展 optparse</span></a> 章节中介绍的进阶内容。 大多数动作都是告诉 <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 将特定的值存储到某个变量中 --- 例如，从命令行接收一个字符串并将其存储到 <code class="docutils literal notranslate"><span class="pre">options</span></code> 的某个选项中。</p>
|
||
<p>如果你没有指定一个选项动作，<a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 将默认选择 <code class="docutils literal notranslate"><span class="pre">store</span></code>。</p>
|
||
</section>
|
||
<section id="the-store-action">
|
||
<span id="optparse-store-action"></span><h3>store 动作<a class="headerlink" href="#the-store-action" title="永久链接至标题">¶</a></h3>
|
||
<p>最常用的选项动作是 <code class="docutils literal notranslate"><span class="pre">store</span></code>，它告诉 <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 接收下一个参数（或当前参数的剩余部分），确认其为正确的类型，并将其保存至你选择的目标。</p>
|
||
<p>例如：</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"-f"</span><span class="p">,</span> <span class="s2">"--file"</span><span class="p">,</span>
|
||
<span class="n">action</span><span class="o">=</span><span class="s2">"store"</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="s2">"string"</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s2">"filename"</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>现在让我们编一个虚假的命令行并让 <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 来解析它:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">args</span> <span class="o">=</span> <span class="p">[</span><span class="s2">"-f"</span><span class="p">,</span> <span class="s2">"foo.txt"</span><span class="p">]</span>
|
||
<span class="p">(</span><span class="n">options</span><span class="p">,</span> <span class="n">args</span><span class="p">)</span> <span class="o">=</span> <span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">(</span><span class="n">args</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>当 <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 看到选项字符串 <code class="docutils literal notranslate"><span class="pre">-f</span></code> 时，它将获取下一个参数 <code class="docutils literal notranslate"><span class="pre">foo.txt</span></code>，并将其保存到 <code class="docutils literal notranslate"><span class="pre">options.filename</span></code> 中。 因此，在这个对 <code class="xref py py-meth docutils literal notranslate"><span class="pre">parse_args()</span></code> 的调用之后，<code class="docutils literal notranslate"><span class="pre">options.filename</span></code> 将为 <code class="docutils literal notranslate"><span class="pre">"foo.txt"</span></code>。</p>
|
||
<p>受到 <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 支持的其他一些选项类型有 <code class="docutils literal notranslate"><span class="pre">int</span></code> 和 <code class="docutils literal notranslate"><span class="pre">float</span></code>。 下面是一个接受整数参数的选项:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"-n"</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="s2">"int"</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s2">"num"</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>请注意这个选项没有长选项字符串，这是完全可接受的。 而且，它也没有显式的动作，因为使用默认的 <code class="docutils literal notranslate"><span class="pre">store</span></code>。</p>
|
||
<p>让我们解析另一个虚假的命令行。 这一次，我们将让选项参数与选项紧贴在一起：因为 <code class="docutils literal notranslate"><span class="pre">-n42</span></code> (一个参数) 与 <code class="docutils literal notranslate"><span class="pre">-n</span> <span class="pre">42</span></code> (两个参数) 是等价的，以下代码</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="p">(</span><span class="n">options</span><span class="p">,</span> <span class="n">args</span><span class="p">)</span> <span class="o">=</span> <span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s2">"-n42"</span><span class="p">])</span>
|
||
<span class="nb">print</span><span class="p">(</span><span class="n">options</span><span class="o">.</span><span class="n">num</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>将会打印 <code class="docutils literal notranslate"><span class="pre">42</span></code>。</p>
|
||
<p>如果你没有指明类型，<a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 会假定类型为 <code class="docutils literal notranslate"><span class="pre">string</span></code>。 加上默认动作为 <code class="docutils literal notranslate"><span class="pre">store</span></code> 这一事实，意味着我们的第一个示例可以变得更加简短:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"-f"</span><span class="p">,</span> <span class="s2">"--file"</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s2">"filename"</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>如果你没有提供目标，<a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 会从选项字符串推断出一个合理的默认目标：如果第一个长选项字符串为 <code class="docutils literal notranslate"><span class="pre">--foo-bar</span></code>，则默认目标为 <code class="docutils literal notranslate"><span class="pre">foo_bar</span></code>。 如果没有长选项字符串，则 <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 会查找第一个短选项字符串：针对 <code class="docutils literal notranslate"><span class="pre">-f</span></code> 的默认目标将为 <code class="docutils literal notranslate"><span class="pre">f</span></code>。</p>
|
||
<p><a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 还包括了内置的 <code class="docutils literal notranslate"><span class="pre">complex</span></code> 类型。 添加类型的方式将在 <a class="reference internal" href="#optparse-extending-optparse"><span class="std std-ref">扩展 optparse</span></a> 一节中介绍。</p>
|
||
</section>
|
||
<section id="handling-boolean-flag-options">
|
||
<span id="optparse-handling-boolean-options"></span><h3>处理布尔值（旗标）选项<a class="headerlink" href="#handling-boolean-flag-options" title="永久链接至标题">¶</a></h3>
|
||
<p>旗标选项 --- 当看到特定选项时将某个变量设为真值或假值 --- 是相当常见的。 <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 通过两个单独的动作支持它们，<code class="docutils literal notranslate"><span class="pre">store_true</span></code> 和 <code class="docutils literal notranslate"><span class="pre">store_false</span></code>。 例如，你可能会有个 <code class="docutils literal notranslate"><span class="pre">verbose</span></code> 旗标将通过 <code class="docutils literal notranslate"><span class="pre">-v</span></code> 来启用并通过 <code class="docutils literal notranslate"><span class="pre">-q</span></code> 来禁用:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"-v"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"store_true"</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s2">"verbose"</span><span class="p">)</span>
|
||
<span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"-q"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"store_false"</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s2">"verbose"</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>这里我们有两个相同目标的不同选项，这是完全可行的。 （只是这意味着在设置默认值时你必须更加小心 --- 见下文所述。）</p>
|
||
<p>当 <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 在命令行中遇到 <code class="docutils literal notranslate"><span class="pre">-v</span></code> 时，它会将 <code class="docutils literal notranslate"><span class="pre">options.verbose</span></code> 设为 <code class="docutils literal notranslate"><span class="pre">True</span></code>；当它遇到 <code class="docutils literal notranslate"><span class="pre">-q</span></code> 时，则会将 <code class="docutils literal notranslate"><span class="pre">options.verbose</span></code> 设为 <code class="docutils literal notranslate"><span class="pre">False</span></code>。</p>
|
||
</section>
|
||
<section id="other-actions">
|
||
<span id="optparse-other-actions"></span><h3>其他动作<a class="headerlink" href="#other-actions" title="永久链接至标题">¶</a></h3>
|
||
<p>受到 <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 支持的其他动作还有:</p>
|
||
<dl class="simple">
|
||
<dt><code class="docutils literal notranslate"><span class="pre">"store_const"</span></code></dt><dd><p>store a constant value</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">"append"</span></code></dt><dd><p>将此选项的参数添加到一个列表</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">"count"</span></code></dt><dd><p>让指定的计数器加一</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">"callback"</span></code></dt><dd><p>调用指定函数</p>
|
||
</dd>
|
||
</dl>
|
||
<p>这些在 <a class="reference internal" href="#optparse-reference-guide"><span class="std std-ref">参考指南</span></a>，以及 <a class="reference internal" href="#optparse-option-callbacks"><span class="std std-ref">选项回调</span></a> 等章节中有说明。</p>
|
||
</section>
|
||
<section id="default-values">
|
||
<span id="optparse-default-values"></span><h3>默认值<a class="headerlink" href="#default-values" title="永久链接至标题">¶</a></h3>
|
||
<p>上述示例全都涉及当看到特定命令行选项时设置某些变量（即“目标”）的操作。 如果从未看到这些选项那么会发生什么叱？由于我们没有提供任何默认值，它们全都会被设为 <code class="docutils literal notranslate"><span class="pre">None</span></code>。 这通常是可以的，但有时你会想要更多的控制。 <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 允许你为每个目标提供默认值，它们将在解析命令行之前被赋值。</p>
|
||
<p>首先，考虑这个 verbose/quiet 示例。 如果我们希望 <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 将 <code class="docutils literal notranslate"><span class="pre">verbose</span></code> 设为 <code class="docutils literal notranslate"><span class="pre">True</span></code> 除非看到了 <code class="docutils literal notranslate"><span class="pre">-q</span></code>，那么我们可以这样做:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"-v"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"store_true"</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s2">"verbose"</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
|
||
<span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"-q"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"store_false"</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s2">"verbose"</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>由于默认值将应用到 <em>destination</em> 而不是任何特定选项，并且这两个选项正好具有相同的目标，因此这是完全等价的:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"-v"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"store_true"</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s2">"verbose"</span><span class="p">)</span>
|
||
<span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"-q"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"store_false"</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s2">"verbose"</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>考虑一下：</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"-v"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"store_true"</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s2">"verbose"</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span>
|
||
<span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"-q"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"store_false"</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s2">"verbose"</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>同样地，<code class="docutils literal notranslate"><span class="pre">verbose</span></code> 的默认值将为 <code class="docutils literal notranslate"><span class="pre">True</span></code>: 最终生效的将是最后提供给任何特定目标的默认值。</p>
|
||
<p>一种更清晰的默认值指定方式是使用 OptionParser 的 <code class="xref py py-meth docutils literal notranslate"><span class="pre">set_defaults()</span></code> 方法，你可以在调用 <code class="xref py py-meth docutils literal notranslate"><span class="pre">parse_args()</span></code> 之前的任何时候调用它:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">parser</span><span class="o">.</span><span class="n">set_defaults</span><span class="p">(</span><span class="n">verbose</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
|
||
<span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="o">...</span><span class="p">)</span>
|
||
<span class="p">(</span><span class="n">options</span><span class="p">,</span> <span class="n">args</span><span class="p">)</span> <span class="o">=</span> <span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">()</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>如前面一样，最终生效的将是最后为特定选项目标指定的值。 为清楚起见，请使用一种或另外一种设置默认值的方法，而不要同时使用。</p>
|
||
</section>
|
||
<section id="generating-help">
|
||
<span id="optparse-generating-help"></span><h3>生成帮助<a class="headerlink" href="#generating-help" title="永久链接至标题">¶</a></h3>
|
||
<p><a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 自动生成帮助和用法文本的功能适用于创建用户友好的命令行界面。 你所要做的只是为每个选项提供 <a class="reference internal" href="#optparse.Option.help" title="optparse.Option.help"><code class="xref py py-attr docutils literal notranslate"><span class="pre">help</span></code></a> 值，并可选项为你的整个程序提供一条简短的用法消息。 下面是一个填充了用户友好的（文档）选项的 OptionParser:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">usage</span> <span class="o">=</span> <span class="s2">"usage: %prog [options] arg1 arg2"</span>
|
||
<span class="n">parser</span> <span class="o">=</span> <span class="n">OptionParser</span><span class="p">(</span><span class="n">usage</span><span class="o">=</span><span class="n">usage</span><span class="p">)</span>
|
||
<span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"-v"</span><span class="p">,</span> <span class="s2">"--verbose"</span><span class="p">,</span>
|
||
<span class="n">action</span><span class="o">=</span><span class="s2">"store_true"</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s2">"verbose"</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span>
|
||
<span class="n">help</span><span class="o">=</span><span class="s2">"make lots of noise [default]"</span><span class="p">)</span>
|
||
<span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"-q"</span><span class="p">,</span> <span class="s2">"--quiet"</span><span class="p">,</span>
|
||
<span class="n">action</span><span class="o">=</span><span class="s2">"store_false"</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s2">"verbose"</span><span class="p">,</span>
|
||
<span class="n">help</span><span class="o">=</span><span class="s2">"be vewwy quiet (I'm hunting wabbits)"</span><span class="p">)</span>
|
||
<span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"-f"</span><span class="p">,</span> <span class="s2">"--filename"</span><span class="p">,</span>
|
||
<span class="n">metavar</span><span class="o">=</span><span class="s2">"FILE"</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s2">"write output to FILE"</span><span class="p">)</span>
|
||
<span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"-m"</span><span class="p">,</span> <span class="s2">"--mode"</span><span class="p">,</span>
|
||
<span class="n">default</span><span class="o">=</span><span class="s2">"intermediate"</span><span class="p">,</span>
|
||
<span class="n">help</span><span class="o">=</span><span class="s2">"interaction mode: novice, intermediate, "</span>
|
||
<span class="s2">"or expert [default: </span><span class="si">%d</span><span class="s2">efault]"</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>如果 <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 在命令行中遇到了 <code class="docutils literal notranslate"><span class="pre">-h</span></code> 或 <code class="docutils literal notranslate"><span class="pre">--help</span></code>，或者如果你调用了 <code class="xref py py-meth docutils literal notranslate"><span class="pre">parser.print_help()</span></code>，它会把以下内容打印到标准输出:</p>
|
||
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>Usage: <yourscript> [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]
|
||
</pre></div>
|
||
</div>
|
||
<p>（如果帮助输出是由 help 选项触发的，<a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 将在打印帮助文本之后退出。）</p>
|
||
<p>在这里为帮助 <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 生成尽可能好的帮助消息做了很多工作:</p>
|
||
<ul>
|
||
<li><p>该脚本定义了自己的用法消息:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">usage</span> <span class="o">=</span> <span class="s2">"usage: %prog [options] arg1 arg2"</span>
|
||
</pre></div>
|
||
</div>
|
||
<p><a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 会将用法字符串中的 <code class="docutils literal notranslate"><span class="pre">%prog</span></code> 扩展为当前程序的名称，即 <code class="docutils literal notranslate"><span class="pre">os.path.basename(sys.argv[0])</span></code>。 随后将在详细选项帮助之前打印这个经过扩展的字符串。</p>
|
||
<p>如果你未提供用法字符串，<a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 将使用一个直白而合理的默认值: <code class="docutils literal notranslate"><span class="pre">"Usage:</span> <span class="pre">%prog</span> <span class="pre">[options]"</span></code>，这在你的脚本不接受任何位置参数时是可以的。</p>
|
||
</li>
|
||
<li><p>每个选项都定义了帮助字符串，并且不用担心换行问题 --- <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 将负责执行换行并使帮助输出有良好的外观格式。</p></li>
|
||
<li><p>options that take a value indicate this fact in their automatically-generated
|
||
help message, e.g. for the "mode" option:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="o">-</span><span class="n">m</span> <span class="n">MODE</span><span class="p">,</span> <span class="o">--</span><span class="n">mode</span><span class="o">=</span><span class="n">MODE</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Here, "MODE" is called the meta-variable: it stands for the argument that the
|
||
user is expected to supply to <code class="docutils literal notranslate"><span class="pre">-m</span></code>/<code class="docutils literal notranslate"><span class="pre">--mode</span></code>. By default,
|
||
<a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> converts the destination variable name to uppercase and uses
|
||
that for the meta-variable. Sometimes, that's not what you want---for
|
||
example, the <code class="docutils literal notranslate"><span class="pre">--filename</span></code> option explicitly sets <code class="docutils literal notranslate"><span class="pre">metavar="FILE"</span></code>,
|
||
resulting in this automatically-generated option description:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="o">-</span><span class="n">f</span> <span class="n">FILE</span><span class="p">,</span> <span class="o">--</span><span class="n">filename</span><span class="o">=</span><span class="n">FILE</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>不过，这具有比节省一点空间更重要的作用：手动编写的帮助文本使用元变量 <code class="docutils literal notranslate"><span class="pre">FILE</span></code> 来提示用户在半正式的语法 <code class="docutils literal notranslate"><span class="pre">-f</span> <span class="pre">FILE</span></code> 和非正式的描述 "write output to FILE" 之间存在联系。 这是一种使你的帮助文本更清晰并对最终用户来说更易用的简单而有效的方式。</p>
|
||
</li>
|
||
<li><p>具有默认值的选项可以在帮助字符串中包括 <code class="docutils literal notranslate"><span class="pre">%default</span></code> --- <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 将用该选项的默认值的 <a class="reference internal" href="stdtypes.html#str" title="str"><code class="xref py py-func docutils literal notranslate"><span class="pre">str()</span></code></a> 来替代它。 如果一个选项没有默认值 (或默认值为 <code class="docutils literal notranslate"><span class="pre">None</span></code>)，则 <code class="docutils literal notranslate"><span class="pre">%default</span></code> 将被扩展为 <code class="docutils literal notranslate"><span class="pre">none</span></code>。</p></li>
|
||
</ul>
|
||
<section id="grouping-options">
|
||
<h4>选项分组<a class="headerlink" href="#grouping-options" title="永久链接至标题">¶</a></h4>
|
||
<p>在处理大量选项时，可以方便地将选项进行分组以提供更好的帮助输出。 <a class="reference internal" href="#optparse.OptionParser" title="optparse.OptionParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">OptionParser</span></code></a> 可以包含多个选项分组，每个分组可以包含多个选项。</p>
|
||
<p>选项分组是使用 <a class="reference internal" href="#optparse.OptionGroup" title="optparse.OptionGroup"><code class="xref py py-class docutils literal notranslate"><span class="pre">OptionGroup</span></code></a> 类来生成的:</p>
|
||
<dl class="class">
|
||
<dt id="optparse.OptionGroup">
|
||
<em class="property">class </em><code class="sig-prename descclassname">optparse.</code><code class="sig-name descname">OptionGroup</code><span class="sig-paren">(</span><em class="sig-param">parser</em>, <em class="sig-param">title</em>, <em class="sig-param">description=None</em><span class="sig-paren">)</span><a class="headerlink" href="#optparse.OptionGroup" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>其中</p>
|
||
<ul class="simple">
|
||
<li><p>parser 是分组将被插入的 <a class="reference internal" href="#optparse.OptionParser" title="optparse.OptionParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">OptionParser</span></code></a> 实例</p></li>
|
||
<li><p>title 是分组的标题</p></li>
|
||
<li><p>description，可选项，是分组的长描述文本</p></li>
|
||
</ul>
|
||
</dd></dl>
|
||
|
||
<p><a class="reference internal" href="#optparse.OptionGroup" title="optparse.OptionGroup"><code class="xref py py-class docutils literal notranslate"><span class="pre">OptionGroup</span></code></a> 继承自 <code class="xref py py-class docutils literal notranslate"><span class="pre">OptionContainer</span></code> (类似 <a class="reference internal" href="#optparse.OptionParser" title="optparse.OptionParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">OptionParser</span></code></a>) 因此 <code class="xref py py-meth docutils literal notranslate"><span class="pre">add_option()</span></code> 方法可被用来向分组添加选项。</p>
|
||
<p>一旦声明了所有选项，使用 <a class="reference internal" href="#optparse.OptionParser" title="optparse.OptionParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">OptionParser</span></code></a> 方法 <code class="xref py py-meth docutils literal notranslate"><span class="pre">add_option_group()</span></code> 即可将分组添加到之前定义的解析器。</p>
|
||
<p>继续使用前一节定义的解析器，很容易将 <a class="reference internal" href="#optparse.OptionGroup" title="optparse.OptionGroup"><code class="xref py py-class docutils literal notranslate"><span class="pre">OptionGroup</span></code></a> 添加到解析器中:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">group</span> <span class="o">=</span> <span class="n">OptionGroup</span><span class="p">(</span><span class="n">parser</span><span class="p">,</span> <span class="s2">"Dangerous Options"</span><span class="p">,</span>
|
||
<span class="s2">"Caution: use these options at your own risk. "</span>
|
||
<span class="s2">"It is believed that some of them bite."</span><span class="p">)</span>
|
||
<span class="n">group</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"-g"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"store_true"</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s2">"Group option."</span><span class="p">)</span>
|
||
<span class="n">parser</span><span class="o">.</span><span class="n">add_option_group</span><span class="p">(</span><span class="n">group</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>这将产生以下帮助输出:</p>
|
||
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>Usage: <yourscript> [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.
|
||
</pre></div>
|
||
</div>
|
||
<p>更完整一些的示例可能涉及使用多个分组：继续扩展之前的例子:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">group</span> <span class="o">=</span> <span class="n">OptionGroup</span><span class="p">(</span><span class="n">parser</span><span class="p">,</span> <span class="s2">"Dangerous Options"</span><span class="p">,</span>
|
||
<span class="s2">"Caution: use these options at your own risk. "</span>
|
||
<span class="s2">"It is believed that some of them bite."</span><span class="p">)</span>
|
||
<span class="n">group</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"-g"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"store_true"</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s2">"Group option."</span><span class="p">)</span>
|
||
<span class="n">parser</span><span class="o">.</span><span class="n">add_option_group</span><span class="p">(</span><span class="n">group</span><span class="p">)</span>
|
||
|
||
<span class="n">group</span> <span class="o">=</span> <span class="n">OptionGroup</span><span class="p">(</span><span class="n">parser</span><span class="p">,</span> <span class="s2">"Debug Options"</span><span class="p">)</span>
|
||
<span class="n">group</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"-d"</span><span class="p">,</span> <span class="s2">"--debug"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"store_true"</span><span class="p">,</span>
|
||
<span class="n">help</span><span class="o">=</span><span class="s2">"Print debug information"</span><span class="p">)</span>
|
||
<span class="n">group</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"-s"</span><span class="p">,</span> <span class="s2">"--sql"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"store_true"</span><span class="p">,</span>
|
||
<span class="n">help</span><span class="o">=</span><span class="s2">"Print all SQL statements executed"</span><span class="p">)</span>
|
||
<span class="n">group</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"-e"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"store_true"</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s2">"Print every action done"</span><span class="p">)</span>
|
||
<span class="n">parser</span><span class="o">.</span><span class="n">add_option_group</span><span class="p">(</span><span class="n">group</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>这会产生以下输出:</p>
|
||
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>Usage: <yourscript> [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
|
||
</pre></div>
|
||
</div>
|
||
<p>另一个有趣的方法，特别适合在编程处理选项分组时使用:</p>
|
||
<dl class="method">
|
||
<dt id="optparse.OptionParser.get_option_group">
|
||
<code class="sig-prename descclassname">OptionParser.</code><code class="sig-name descname">get_option_group</code><span class="sig-paren">(</span><em class="sig-param">opt_str</em><span class="sig-paren">)</span><a class="headerlink" href="#optparse.OptionParser.get_option_group" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>返回短或长选项字符串 <em>opt_str</em> (例如 <code class="docutils literal notranslate"><span class="pre">'-o'</span></code> 或 <code class="docutils literal notranslate"><span class="pre">'--option'</span></code>) 所属的 <a class="reference internal" href="#optparse.OptionGroup" title="optparse.OptionGroup"><code class="xref py py-class docutils literal notranslate"><span class="pre">OptionGroup</span></code></a>。 如果没有对应的 <a class="reference internal" href="#optparse.OptionGroup" title="optparse.OptionGroup"><code class="xref py py-class docutils literal notranslate"><span class="pre">OptionGroup</span></code></a>，则返回 <code class="docutils literal notranslate"><span class="pre">None</span></code>。</p>
|
||
</dd></dl>
|
||
|
||
</section>
|
||
</section>
|
||
<section id="printing-a-version-string">
|
||
<span id="optparse-printing-version-string"></span><h3>打印版本字符串<a class="headerlink" href="#printing-a-version-string" title="永久链接至标题">¶</a></h3>
|
||
<p>与简短用法字符串类似，<a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 还可以打印你的程序的版本字符串。 你必须将该字符串作为 <code class="docutils literal notranslate"><span class="pre">version</span></code> 参数提供给 OptionParser:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">parser</span> <span class="o">=</span> <span class="n">OptionParser</span><span class="p">(</span><span class="n">usage</span><span class="o">=</span><span class="s2">"%prog [-f] [-q]"</span><span class="p">,</span> <span class="n">version</span><span class="o">=</span><span class="s2">"%prog 1.0"</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p><code class="docutils literal notranslate"><span class="pre">%prog</span></code> 会像在 <code class="docutils literal notranslate"><span class="pre">usage</span></code> 中那样被扩展。 除了这一点，<code class="docutils literal notranslate"><span class="pre">version</span></code> 还可包含你想存放的任何东西。 当你提供它时，<a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 将自动向你的解析器添加一个 <code class="docutils literal notranslate"><span class="pre">--version</span></code> 选项。 如果它在命令行中遇到了该选项，它将扩展你的 <code class="docutils literal notranslate"><span class="pre">version</span></code> 字符串 (通过替换 <code class="docutils literal notranslate"><span class="pre">%prog</span></code>)，将其打印到标准输出，然后退出。</p>
|
||
<p>举例来说，如果你的脚本是 <code class="docutils literal notranslate"><span class="pre">/usr/bin/foo</span></code>:</p>
|
||
<div class="highlight-shell-session notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>/usr/bin/foo<span class="w"> </span>--version
|
||
<span class="go">foo 1.0</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>下列两个方法可被用来打印和获取 <code class="docutils literal notranslate"><span class="pre">version</span></code> 字符串:</p>
|
||
<dl class="method">
|
||
<dt id="optparse.OptionParser.print_version">
|
||
<code class="sig-prename descclassname">OptionParser.</code><code class="sig-name descname">print_version</code><span class="sig-paren">(</span><em class="sig-param">file=None</em><span class="sig-paren">)</span><a class="headerlink" href="#optparse.OptionParser.print_version" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>将当前程序的版本消息 (<code class="docutils literal notranslate"><span class="pre">self.version</span></code>) 打印到 <em>file</em> (默认为 stdout)。 就像 <a class="reference internal" href="#optparse.OptionParser.print_usage" title="optparse.OptionParser.print_usage"><code class="xref py py-meth docutils literal notranslate"><span class="pre">print_usage()</span></code></a> 一样，任何在 <code class="docutils literal notranslate"><span class="pre">self.version</span></code> 中出现的 <code class="docutils literal notranslate"><span class="pre">%prog</span></code> 将被替换为当前程序的名称。 如果 <code class="docutils literal notranslate"><span class="pre">self.version</span></code> 为空或未定义则不做任何操作。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="optparse.OptionParser.get_version">
|
||
<code class="sig-prename descclassname">OptionParser.</code><code class="sig-name descname">get_version</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#optparse.OptionParser.get_version" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>与 <a class="reference internal" href="#optparse.OptionParser.print_version" title="optparse.OptionParser.print_version"><code class="xref py py-meth docutils literal notranslate"><span class="pre">print_version()</span></code></a> 相似但是会返回版本字符串而不是打印它。</p>
|
||
</dd></dl>
|
||
|
||
</section>
|
||
<section id="how-optparse-handles-errors">
|
||
<span id="optparse-how-optparse-handles-errors"></span><h3><a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 如何处理错误handles errors<a class="headerlink" href="#how-optparse-handles-errors" title="永久链接至标题">¶</a></h3>
|
||
<p><a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 必须考虑两种宽泛的错误类：程序员错误和用户错误。 程序员错误通常是对 <a class="reference internal" href="#optparse.OptionParser.add_option" title="optparse.OptionParser.add_option"><code class="xref py py-func docutils literal notranslate"><span class="pre">OptionParser.add_option()</span></code></a> 的错误调用，例如无效的选项字符串，未知的选项属性，不存在的选项属性等等。 这些错误将以通常的方式来处理：引发一个异常 (或者是 <code class="xref py py-exc docutils literal notranslate"><span class="pre">optparse.OptionError</span></code> 或者是 <a class="reference internal" href="exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a>) 并让程序崩溃。</p>
|
||
<p>处理用户错误更为重要，因为无论你的代码有多稳定他们都肯定会发生。 <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 可以自动检测部分用户错误，例如不正确的选项参数（如传入 <code class="docutils literal notranslate"><span class="pre">-n</span> <span class="pre">4x</span></code> 而 <code class="docutils literal notranslate"><span class="pre">-n</span></code> 接受整数参数），缺少参数（如 <code class="docutils literal notranslate"><span class="pre">-n</span></code> 位于命令行的末尾，而 <code class="docutils literal notranslate"><span class="pre">-n</span></code> 接受任意类型的参数）。 并且，你可以调用 <code class="xref py py-func docutils literal notranslate"><span class="pre">OptionParser.error()</span></code> 来指明应用程序自定义的错误条件:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="p">(</span><span class="n">options</span><span class="p">,</span> <span class="n">args</span><span class="p">)</span> <span class="o">=</span> <span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">()</span>
|
||
<span class="o">...</span>
|
||
<span class="k">if</span> <span class="n">options</span><span class="o">.</span><span class="n">a</span> <span class="ow">and</span> <span class="n">options</span><span class="o">.</span><span class="n">b</span><span class="p">:</span>
|
||
<span class="n">parser</span><span class="o">.</span><span class="n">error</span><span class="p">(</span><span class="s2">"options -a and -b are mutually exclusive"</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>在两种情况下，<a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 都是以相同方式处理错误的：它会将程序的用法消息和错误消息打印到标准错误并附带错误状态 2 退出。</p>
|
||
<p>考虑上面的第一个示例，当用户向一个接受整数的选项传入了 <code class="docutils literal notranslate"><span class="pre">4x</span></code>:</p>
|
||
<div class="highlight-shell-session notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>/usr/bin/foo<span class="w"> </span>-n<span class="w"> </span>4x
|
||
<span class="go">Usage: foo [options]</span>
|
||
|
||
<span class="go">foo: error: option -n: invalid integer value: '4x'</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>或者，当用户未传入任何值:</p>
|
||
<div class="highlight-shell-session notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>/usr/bin/foo<span class="w"> </span>-n
|
||
<span class="go">Usage: foo [options]</span>
|
||
|
||
<span class="go">foo: error: -n option requires an argument</span>
|
||
</pre></div>
|
||
</div>
|
||
<p><a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 生成的错误消息总是会确保提示在错误中涉及的选项；请确保在从你的应用程序代码调用 <code class="xref py py-func docutils literal notranslate"><span class="pre">OptionParser.error()</span></code> 时也做同样的事。</p>
|
||
<p>如果 <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 的默认错误处理行为不适合你的需求，你需要子类化 OptionParser 并重写它的 <code class="xref py py-meth docutils literal notranslate"><span class="pre">exit()</span></code> 和/或 <code class="xref py py-meth docutils literal notranslate"><span class="pre">error()</span></code> 方法。</p>
|
||
</section>
|
||
<section id="putting-it-all-together">
|
||
<span id="optparse-putting-it-all-together"></span><h3>合并所有代码<a class="headerlink" href="#putting-it-all-together" title="永久链接至标题">¶</a></h3>
|
||
<p>下面是基于 <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 的脚本通常的结构:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">optparse</span> <span class="kn">import</span> <span class="n">OptionParser</span>
|
||
<span class="o">...</span>
|
||
<span class="k">def</span> <span class="nf">main</span><span class="p">():</span>
|
||
<span class="n">usage</span> <span class="o">=</span> <span class="s2">"usage: %prog [options] arg"</span>
|
||
<span class="n">parser</span> <span class="o">=</span> <span class="n">OptionParser</span><span class="p">(</span><span class="n">usage</span><span class="p">)</span>
|
||
<span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"-f"</span><span class="p">,</span> <span class="s2">"--file"</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s2">"filename"</span><span class="p">,</span>
|
||
<span class="n">help</span><span class="o">=</span><span class="s2">"read data from FILENAME"</span><span class="p">)</span>
|
||
<span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"-v"</span><span class="p">,</span> <span class="s2">"--verbose"</span><span class="p">,</span>
|
||
<span class="n">action</span><span class="o">=</span><span class="s2">"store_true"</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s2">"verbose"</span><span class="p">)</span>
|
||
<span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"-q"</span><span class="p">,</span> <span class="s2">"--quiet"</span><span class="p">,</span>
|
||
<span class="n">action</span><span class="o">=</span><span class="s2">"store_false"</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s2">"verbose"</span><span class="p">)</span>
|
||
<span class="o">...</span>
|
||
<span class="p">(</span><span class="n">options</span><span class="p">,</span> <span class="n">args</span><span class="p">)</span> <span class="o">=</span> <span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">()</span>
|
||
<span class="k">if</span> <span class="nb">len</span><span class="p">(</span><span class="n">args</span><span class="p">)</span> <span class="o">!=</span> <span class="mi">1</span><span class="p">:</span>
|
||
<span class="n">parser</span><span class="o">.</span><span class="n">error</span><span class="p">(</span><span class="s2">"incorrect number of arguments"</span><span class="p">)</span>
|
||
<span class="k">if</span> <span class="n">options</span><span class="o">.</span><span class="n">verbose</span><span class="p">:</span>
|
||
<span class="nb">print</span><span class="p">(</span><span class="s2">"reading </span><span class="si">%s</span><span class="s2">..."</span> <span class="o">%</span> <span class="n">options</span><span class="o">.</span><span class="n">filename</span><span class="p">)</span>
|
||
<span class="o">...</span>
|
||
|
||
<span class="k">if</span> <span class="vm">__name__</span> <span class="o">==</span> <span class="s2">"__main__"</span><span class="p">:</span>
|
||
<span class="n">main</span><span class="p">()</span>
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
</section>
|
||
<section id="reference-guide">
|
||
<span id="optparse-reference-guide"></span><h2>参考指南<a class="headerlink" href="#reference-guide" title="永久链接至标题">¶</a></h2>
|
||
<section id="creating-the-parser">
|
||
<span id="optparse-creating-parser"></span><h3>创建解析器<a class="headerlink" href="#creating-the-parser" title="永久链接至标题">¶</a></h3>
|
||
<p>使用 <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 的第一步是创建 OptionParser 实例。</p>
|
||
<dl class="class">
|
||
<dt id="optparse.OptionParser">
|
||
<em class="property">class </em><code class="sig-prename descclassname">optparse.</code><code class="sig-name descname">OptionParser</code><span class="sig-paren">(</span><em class="sig-param">...</em><span class="sig-paren">)</span><a class="headerlink" href="#optparse.OptionParser" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>OptionParser 构造器没有必需的参数，只有一些可选的关键字参数。 你应当始终以关键字参数形式传入它们，即不要依赖于声明参数所在位置的顺序。</p>
|
||
<dl class="simple">
|
||
<dt><code class="docutils literal notranslate"><span class="pre">usage</span></code> (默认: <code class="docutils literal notranslate"><span class="pre">"%prog</span> <span class="pre">[options]"</span></code>)</dt><dd><p>当你的程序不正确地运行或附带 help 选项运行时将打印的用法说明。 当 <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 打印用法字符串时，它会将 <code class="docutils literal notranslate"><span class="pre">%prog</span></code> 扩展为 <code class="docutils literal notranslate"><span class="pre">os.path.basename(sys.argv[0])</span></code> (或者如果你传入 <code class="docutils literal notranslate"><span class="pre">prog</span></code> 则为该关键字参数值)。 要屏蔽用法说明，请传入特殊值 <code class="xref py py-data docutils literal notranslate"><span class="pre">optparse.SUPPRESS_USAGE</span></code>。</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">option_list</span></code> (默认: <code class="docutils literal notranslate"><span class="pre">[]</span></code>)</dt><dd><p>一个用于填充解析器的由 Option 对象组成的列表。 <code class="docutils literal notranslate"><span class="pre">option_list</span></code> 中的选项将添加在 <code class="docutils literal notranslate"><span class="pre">standard_option_list</span></code> (一个可由 OptionParser 的子类设置的类属性) 中的任何选项之后，以及任何版本或帮助选项之前。 已被弃用；请改为在创建解析器之后使用 <a class="reference internal" href="#optparse.OptionParser.add_option" title="optparse.OptionParser.add_option"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add_option()</span></code></a>。</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">option_class</span></code> (默认: optparse.Option)</dt><dd><p>当在 <a class="reference internal" href="#optparse.OptionParser.add_option" title="optparse.OptionParser.add_option"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add_option()</span></code></a> 中向解析器添加选项时要使用的类。</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">version</span></code> (默认: <code class="docutils literal notranslate"><span class="pre">None</span></code>)</dt><dd><p>当用户提供了 version 选项时将会打印的版本字符串。 如果你为 <code class="docutils literal notranslate"><span class="pre">version</span></code> 提供真值，<a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 将自动添加单个选项字符串 <code class="docutils literal notranslate"><span class="pre">--version</span></code> 形式的 version 选项。 子字符串 <code class="docutils literal notranslate"><span class="pre">%prog</span></code> 会以与 <code class="docutils literal notranslate"><span class="pre">usage</span></code> 相同的方式扩展。</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">conflict_handler</span></code> (默认: <code class="docutils literal notranslate"><span class="pre">"error"</span></code>)</dt><dd><p>指定当有相互冲突的选项字符串的选项被添加到解析器时要如何做；参见 <a class="reference internal" href="#optparse-conflicts-between-options"><span class="std std-ref">选项之间的冲突</span></a> 一节。</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">description</span></code> (默认: <code class="docutils literal notranslate"><span class="pre">None</span></code>)</dt><dd><p>一段提供你的程序的简短介绍的文本。 <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 会重格式化段落以适合当前终端宽度并在用户请求帮助时打印其内容（在 <code class="docutils literal notranslate"><span class="pre">usage</span></code> 之后，选项列表之前）。</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">formatter</span></code> (默认: 一个新的 <code class="xref py py-class docutils literal notranslate"><span class="pre">IndentedHelpFormatter</span></code>)</dt><dd><p>一个将被用于打印帮助文本的 optparse.HelpFormatter 实例。 <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 为此目的提供了两个实体类: IndentedHelpFormatter 和 TitledHelpFormatter。</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">add_help_option</span></code> (默认: <code class="docutils literal notranslate"><span class="pre">True</span></code>)</dt><dd><p>如为真值，<a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 将向解析器添加一个 help 选项 (使用选项字符串 <code class="docutils literal notranslate"><span class="pre">-h</span></code> 和 <code class="docutils literal notranslate"><span class="pre">--help</span></code>)。</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">prog</span></code></dt><dd><p>当在 <code class="docutils literal notranslate"><span class="pre">usage</span></code> 和 <code class="docutils literal notranslate"><span class="pre">version</span></code> 中用于代替 <code class="docutils literal notranslate"><span class="pre">os.path.basename(sys.argv[0])</span></code> 来扩展 <code class="docutils literal notranslate"><span class="pre">%prog</span></code> 的字符串。</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">epilog</span></code> (默认: <code class="docutils literal notranslate"><span class="pre">None</span></code>)</dt><dd><p>一段将在选项帮助之后打印的帮助文本。</p>
|
||
</dd>
|
||
</dl>
|
||
</dd></dl>
|
||
|
||
</section>
|
||
<section id="populating-the-parser">
|
||
<span id="optparse-populating-parser"></span><h3>填充解析器<a class="headerlink" href="#populating-the-parser" title="永久链接至标题">¶</a></h3>
|
||
<p>有几种方式可以为解析器填充选项。 最推荐的方式是使用 <a class="reference internal" href="#optparse.OptionParser.add_option" title="optparse.OptionParser.add_option"><code class="xref py py-meth docutils literal notranslate"><span class="pre">OptionParser.add_option()</span></code></a>，如 <a class="reference internal" href="#optparse-tutorial"><span class="std std-ref">教程</span></a> 一节所演示的。 <code class="xref py py-meth docutils literal notranslate"><span class="pre">add_option()</span></code> 可以通过两种方式来调用:</p>
|
||
<ul class="simple">
|
||
<li><p>传入一个 Option 实例（即 <code class="xref py py-func docutils literal notranslate"><span class="pre">make_option()</span></code> 所返回的对象）</p></li>
|
||
<li><p>传入 <code class="xref py py-func docutils literal notranslate"><span class="pre">make_option()</span></code> 可接受的（即与 Option 构造器相同的）任意位置和关键字参数组合，它将为你创建 Option 实例</p></li>
|
||
</ul>
|
||
<p>另一种方式是将由预先构造的 Option 实例组成的列表传给 OptionParser 构造器，如下所示:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">option_list</span> <span class="o">=</span> <span class="p">[</span>
|
||
<span class="n">make_option</span><span class="p">(</span><span class="s2">"-f"</span><span class="p">,</span> <span class="s2">"--filename"</span><span class="p">,</span>
|
||
<span class="n">action</span><span class="o">=</span><span class="s2">"store"</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="s2">"string"</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s2">"filename"</span><span class="p">),</span>
|
||
<span class="n">make_option</span><span class="p">(</span><span class="s2">"-q"</span><span class="p">,</span> <span class="s2">"--quiet"</span><span class="p">,</span>
|
||
<span class="n">action</span><span class="o">=</span><span class="s2">"store_false"</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s2">"verbose"</span><span class="p">),</span>
|
||
<span class="p">]</span>
|
||
<span class="n">parser</span> <span class="o">=</span> <span class="n">OptionParser</span><span class="p">(</span><span class="n">option_list</span><span class="o">=</span><span class="n">option_list</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>(<code class="xref py py-func docutils literal notranslate"><span class="pre">make_option()</span></code> 是一个用于创建 Option 实例的工厂函数；目前它是 Option 构造器的一个别名。 未来的 <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 版本可能会将 Option 拆分为多个类，而 <code class="xref py py-func docutils literal notranslate"><span class="pre">make_option()</span></code> 将选择适当的类来实例化。 请不要直接实例化 Option。)</p>
|
||
</section>
|
||
<section id="defining-options">
|
||
<span id="optparse-defining-options"></span><h3>定义选项<a class="headerlink" href="#defining-options" title="永久链接至标题">¶</a></h3>
|
||
<p>每个 Option 实例代表一组同义的命令行选项字符串，例如 <code class="docutils literal notranslate"><span class="pre">-f</span></code> 和 <code class="docutils literal notranslate"><span class="pre">--file</span></code>。 你可以指定任意数量的短和长选项字符串，但你必须指定总计至少一个选项字符串。</p>
|
||
<p>创建 <code class="xref py py-class docutils literal notranslate"><span class="pre">Option</span></code> 的正规方式是使用 <a class="reference internal" href="#optparse.OptionParser" title="optparse.OptionParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">OptionParser</span></code></a> 的 <code class="xref py py-meth docutils literal notranslate"><span class="pre">add_option()</span></code> 方法。</p>
|
||
<dl class="method">
|
||
<dt id="optparse.OptionParser.add_option">
|
||
<code class="sig-prename descclassname">OptionParser.</code><code class="sig-name descname">add_option</code><span class="sig-paren">(</span><em class="sig-param">option</em><span class="sig-paren">)</span><a class="headerlink" href="#optparse.OptionParser.add_option" title="永久链接至目标">¶</a></dt>
|
||
<dt>
|
||
<code class="sig-prename descclassname">OptionParser.</code><code class="sig-name descname">add_option</code><span class="sig-paren">(</span><em class="sig-param">*opt_str</em>, <em class="sig-param">attr=value</em>, <em class="sig-param">...</em><span class="sig-paren">)</span></dt>
|
||
<dd><p>定义只有一个短选项字符串的选项:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"-f"</span><span class="p">,</span> <span class="n">attr</span><span class="o">=</span><span class="n">value</span><span class="p">,</span> <span class="o">...</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>以及定义只有一个长选项字符串的选项:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"--foo"</span><span class="p">,</span> <span class="n">attr</span><span class="o">=</span><span class="n">value</span><span class="p">,</span> <span class="o">...</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>该关键字参数定义新 Option 对象的属性。 最重要的选项属性是 <a class="reference internal" href="#optparse.Option.action" title="optparse.Option.action"><code class="xref py py-attr docutils literal notranslate"><span class="pre">action</span></code></a>，它主要负责确定其他的属性是相关的还是必须的。 如果你传入了不相关的选项属性，或是未能传入必须的属性，<a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 将引发一个 <code class="xref py py-exc docutils literal notranslate"><span class="pre">OptionError</span></code> 异常来说明你的错误。</p>
|
||
<p>选项的 <em>action</em> 决定当 <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 在命令行中遇到该选项时要做什么。 硬编码在 <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 中的标准选项动作有:</p>
|
||
<dl class="simple">
|
||
<dt><code class="docutils literal notranslate"><span class="pre">"store"</span></code></dt><dd><p>存储此选项的参数（默认）</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">"store_const"</span></code></dt><dd><p>store a constant value</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">"store_true"</span></code></dt><dd><p>存储 <code class="docutils literal notranslate"><span class="pre">True</span></code></p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">"store_false"</span></code></dt><dd><p>存储 <code class="docutils literal notranslate"><span class="pre">False</span></code></p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">"append"</span></code></dt><dd><p>将此选项的参数添加到一个列表</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">"append_const"</span></code></dt><dd><p>将常量值附加到列表</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">"count"</span></code></dt><dd><p>让指定的计数器加一</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">"callback"</span></code></dt><dd><p>调用指定函数</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">"help"</span></code></dt><dd><p>打印用法消息，包括所有选项和它们的文档</p>
|
||
</dd>
|
||
</dl>
|
||
<p>（如果你没有提供动作，则默认为 <code class="docutils literal notranslate"><span class="pre">"store"</span></code>。 对于此动作，你还可以提供 <a class="reference internal" href="#optparse.Option.type" title="optparse.Option.type"><code class="xref py py-attr docutils literal notranslate"><span class="pre">type</span></code></a> 和 <a class="reference internal" href="#optparse.Option.dest" title="optparse.Option.dest"><code class="xref py py-attr docutils literal notranslate"><span class="pre">dest</span></code></a> 选项属性；参见 <a class="reference internal" href="#optparse-standard-option-actions"><span class="std std-ref">标准选项动作</span></a>。）</p>
|
||
</dd></dl>
|
||
|
||
<p>如你所见，大多数动作都涉及在某处保存或更新一个值。 <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 总是会为此创建一个特殊对象，在习惯上命名为 <code class="docutils literal notranslate"><span class="pre">options</span></code> (它恰好是 <code class="xref py py-class docutils literal notranslate"><span class="pre">optparse.Values</span></code> 的实例)。 选项参数 (以及几种其他的值) 将根据 <a class="reference internal" href="#optparse.Option.dest" title="optparse.Option.dest"><code class="xref py py-attr docutils literal notranslate"><span class="pre">dest</span></code></a> (目标) 选项属性被保存为该对象的属性。</p>
|
||
<p>例如，当你调用</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">()</span>
|
||
</pre></div>
|
||
</div>
|
||
<p><a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 首先会做的一件事情是创建 <code class="docutils literal notranslate"><span class="pre">options</span></code> 对象:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">options</span> <span class="o">=</span> <span class="n">Values</span><span class="p">()</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>如果该解析器中的某个选项定义带有</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"-f"</span><span class="p">,</span> <span class="s2">"--file"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"store"</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="s2">"string"</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s2">"filename"</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>并且被解析的命令行包括以下任意一项:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="o">-</span><span class="n">ffoo</span>
|
||
<span class="o">-</span><span class="n">f</span> <span class="n">foo</span>
|
||
<span class="o">--</span><span class="n">file</span><span class="o">=</span><span class="n">foo</span>
|
||
<span class="o">--</span><span class="n">file</span> <span class="n">foo</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>那么 <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 在看到此选项时，将执行这样的操作</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">options</span><span class="o">.</span><span class="n">filename</span> <span class="o">=</span> <span class="s2">"foo"</span>
|
||
</pre></div>
|
||
</div>
|
||
<p><a class="reference internal" href="#optparse.Option.type" title="optparse.Option.type"><code class="xref py py-attr docutils literal notranslate"><span class="pre">type</span></code></a> 和 <a class="reference internal" href="#optparse.Option.dest" title="optparse.Option.dest"><code class="xref py py-attr docutils literal notranslate"><span class="pre">dest</span></code></a> 选项属性几乎与 <a class="reference internal" href="#optparse.Option.action" title="optparse.Option.action"><code class="xref py py-attr docutils literal notranslate"><span class="pre">action</span></code></a> 一样重要，但 <a class="reference internal" href="#optparse.Option.action" title="optparse.Option.action"><code class="xref py py-attr docutils literal notranslate"><span class="pre">action</span></code></a> 是唯一对 <em>所有</em> 选项都有意义的。</p>
|
||
</section>
|
||
<section id="option-attributes">
|
||
<span id="optparse-option-attributes"></span><h3>选项属性<a class="headerlink" href="#option-attributes" title="永久链接至标题">¶</a></h3>
|
||
<p>下列选项属性可以作为关键字参数传给 <a class="reference internal" href="#optparse.OptionParser.add_option" title="optparse.OptionParser.add_option"><code class="xref py py-meth docutils literal notranslate"><span class="pre">OptionParser.add_option()</span></code></a>。 如果你传入一个与特定选项无关的选项属性，或是未能传入必要的选项属性，<a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 将会引发 <code class="xref py py-exc docutils literal notranslate"><span class="pre">OptionError</span></code>。</p>
|
||
<dl class="attribute">
|
||
<dt id="optparse.Option.action">
|
||
<code class="sig-prename descclassname">Option.</code><code class="sig-name descname">action</code><a class="headerlink" href="#optparse.Option.action" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>(默认: <code class="docutils literal notranslate"><span class="pre">"store"</span></code>)</p>
|
||
<p>用于当在命令行中遇到此选项时确定 <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 的行为；可用的选项记录在 <a class="reference internal" href="#optparse-standard-option-actions"><span class="std std-ref">这里</span></a>。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="optparse.Option.type">
|
||
<code class="sig-prename descclassname">Option.</code><code class="sig-name descname">type</code><a class="headerlink" href="#optparse.Option.type" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>(默认: <code class="docutils literal notranslate"><span class="pre">"string"</span></code>)</p>
|
||
<p>此选项所接受的参数类型 (例如 <code class="docutils literal notranslate"><span class="pre">"string"</span></code> 或 <code class="docutils literal notranslate"><span class="pre">"int"</span></code>)；可用的选项类型记录在 <a class="reference internal" href="#optparse-standard-option-types"><span class="std std-ref">这里</span></a>。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="optparse.Option.dest">
|
||
<code class="sig-prename descclassname">Option.</code><code class="sig-name descname">dest</code><a class="headerlink" href="#optparse.Option.dest" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>(默认: 获取自选项字符串)</p>
|
||
<p>如果此选项的动作涉及在某处写入或修改一个值，该属性将告诉 <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 将它写入到哪里: <a class="reference internal" href="#optparse.Option.dest" title="optparse.Option.dest"><code class="xref py py-attr docutils literal notranslate"><span class="pre">dest</span></code></a> 指定 <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 在解析命令行时构建的 <code class="docutils literal notranslate"><span class="pre">options</span></code> 对象的某个属性。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="optparse.Option.default">
|
||
<code class="sig-prename descclassname">Option.</code><code class="sig-name descname">default</code><a class="headerlink" href="#optparse.Option.default" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>当未在命令行中遇到此选项时将被用作此选项的目标的值。 另请参阅 <a class="reference internal" href="#optparse.OptionParser.set_defaults" title="optparse.OptionParser.set_defaults"><code class="xref py py-meth docutils literal notranslate"><span class="pre">OptionParser.set_defaults()</span></code></a>。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="optparse.Option.nargs">
|
||
<code class="sig-prename descclassname">Option.</code><code class="sig-name descname">nargs</code><a class="headerlink" href="#optparse.Option.nargs" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>(默认: 1)</p>
|
||
<p>当遇到此选项时应当读取多少个 <a class="reference internal" href="#optparse.Option.type" title="optparse.Option.type"><code class="xref py py-attr docutils literal notranslate"><span class="pre">type</span></code></a> 类型的参数。 如果 > 1，<a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 会将由多个值组成的元组保存到 <a class="reference internal" href="#optparse.Option.dest" title="optparse.Option.dest"><code class="xref py py-attr docutils literal notranslate"><span class="pre">dest</span></code></a>。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="optparse.Option.const">
|
||
<code class="sig-prename descclassname">Option.</code><code class="sig-name descname">const</code><a class="headerlink" href="#optparse.Option.const" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>对于保存常量值的动作，指定要保存的常量值。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="optparse.Option.choices">
|
||
<code class="sig-prename descclassname">Option.</code><code class="sig-name descname">choices</code><a class="headerlink" href="#optparse.Option.choices" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>对于 <code class="docutils literal notranslate"><span class="pre">"choice"</span></code> 类型的选项，由用户可选择的字符串组成的列表。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="optparse.Option.callback">
|
||
<code class="sig-prename descclassname">Option.</code><code class="sig-name descname">callback</code><a class="headerlink" href="#optparse.Option.callback" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>对于使用 <code class="docutils literal notranslate"><span class="pre">"callback"</span></code> 动作的选项，当遇到此选项时要调用的可调用对象。 请参阅 <a class="reference internal" href="#optparse-option-callbacks"><span class="std std-ref">选项回调</span></a> 一节了解关于传给可调用对象的参数的详情。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="optparse.Option.callback_args">
|
||
<code class="sig-prename descclassname">Option.</code><code class="sig-name descname">callback_args</code><a class="headerlink" href="#optparse.Option.callback_args" title="永久链接至目标">¶</a></dt>
|
||
<dt id="optparse.Option.callback_kwargs">
|
||
<code class="sig-prename descclassname">Option.</code><code class="sig-name descname">callback_kwargs</code><a class="headerlink" href="#optparse.Option.callback_kwargs" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>将在四个标准回调参数之后传给 <code class="docutils literal notranslate"><span class="pre">callback</span></code> 的额外的位置和关键字参数。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="optparse.Option.help">
|
||
<code class="sig-prename descclassname">Option.</code><code class="sig-name descname">help</code><a class="headerlink" href="#optparse.Option.help" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>当用户提供 <a class="reference internal" href="#optparse.Option.help" title="optparse.Option.help"><code class="xref py py-attr docutils literal notranslate"><span class="pre">help</span></code></a> 选项 (例如 <code class="docutils literal notranslate"><span class="pre">--help</span></code>) 之后将在列出所有可用选项时针对此选项打印的帮助文本。 如果没有提供帮助文本，则列出选项时将不附带帮助文本。 要隐藏此选项，请使用特殊值 <code class="xref py py-data docutils literal notranslate"><span class="pre">optparse.SUPPRESS_HELP</span></code>。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="optparse.Option.metavar">
|
||
<code class="sig-prename descclassname">Option.</code><code class="sig-name descname">metavar</code><a class="headerlink" href="#optparse.Option.metavar" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>(默认: 获取自选项字符串)</p>
|
||
<p>当打印帮助文本时要使用的代表选项参数的名称。 请参阅 <a class="reference internal" href="#optparse-tutorial"><span class="std std-ref">教程</span></a> 一节查看相应示例。</p>
|
||
</dd></dl>
|
||
|
||
</section>
|
||
<section id="standard-option-actions">
|
||
<span id="optparse-standard-option-actions"></span><h3>标准选项动作<a class="headerlink" href="#standard-option-actions" title="永久链接至标题">¶</a></h3>
|
||
<p>各种选项动作具有略微不同的要求和效果。 大多数动作都具有几个可被你指定的独步选项属性用来控制 <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 的行为；少数还具有一些必需属性，你必须为任何使用该动作的选项指定这些属性。</p>
|
||
<ul>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">"store"</span></code> [关联: <a class="reference internal" href="#optparse.Option.type" title="optparse.Option.type"><code class="xref py py-attr docutils literal notranslate"><span class="pre">type</span></code></a>, <a class="reference internal" href="#optparse.Option.dest" title="optparse.Option.dest"><code class="xref py py-attr docutils literal notranslate"><span class="pre">dest</span></code></a>, <a class="reference internal" href="#optparse.Option.nargs" title="optparse.Option.nargs"><code class="xref py py-attr docutils literal notranslate"><span class="pre">nargs</span></code></a>, <a class="reference internal" href="#optparse.Option.choices" title="optparse.Option.choices"><code class="xref py py-attr docutils literal notranslate"><span class="pre">choices</span></code></a>]</p>
|
||
<p>该选项后必须跟一个参数，它将根据 <a class="reference internal" href="#optparse.Option.type" title="optparse.Option.type"><code class="xref py py-attr docutils literal notranslate"><span class="pre">type</span></code></a> 被转换为相应的值并保存至 <a class="reference internal" href="#optparse.Option.dest" title="optparse.Option.dest"><code class="xref py py-attr docutils literal notranslate"><span class="pre">dest</span></code></a>。 如果 <a class="reference internal" href="#optparse.Option.nargs" title="optparse.Option.nargs"><code class="xref py py-attr docutils literal notranslate"><span class="pre">nargs</span></code></a> > 1，则将从命令行读取多个参数；它们将全部根据 <a class="reference internal" href="#optparse.Option.type" title="optparse.Option.type"><code class="xref py py-attr docutils literal notranslate"><span class="pre">type</span></code></a> 被转换并以元组形式保存至 <a class="reference internal" href="#optparse.Option.dest" title="optparse.Option.dest"><code class="xref py py-attr docutils literal notranslate"><span class="pre">dest</span></code></a>。 参见 <a class="reference internal" href="#optparse-standard-option-types"><span class="std std-ref">标准选项类型</span></a> 一节。</p>
|
||
<p>如果提供了 <a class="reference internal" href="#optparse.Option.choices" title="optparse.Option.choices"><code class="xref py py-attr docutils literal notranslate"><span class="pre">choices</span></code></a> (由字符串组成的列表和元组)，则类型默认为 <code class="docutils literal notranslate"><span class="pre">"choice"</span></code>。</p>
|
||
<p>如果未提供 <a class="reference internal" href="#optparse.Option.type" title="optparse.Option.type"><code class="xref py py-attr docutils literal notranslate"><span class="pre">type</span></code></a>，则默认为 <code class="docutils literal notranslate"><span class="pre">"string"</span></code>。</p>
|
||
<p>如果未提供 <a class="reference internal" href="#optparse.Option.dest" title="optparse.Option.dest"><code class="xref py py-attr docutils literal notranslate"><span class="pre">dest</span></code></a>，则 <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 会从第一个长选项字符串派生出目标 (例如 <code class="docutils literal notranslate"><span class="pre">--foo-bar</span></code> 将对应 <code class="docutils literal notranslate"><span class="pre">foo_bar</span></code>)。 如果不存在长选项字符串，则 <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 会从第一个短选项字符串派生出目标 (例如 <code class="docutils literal notranslate"><span class="pre">-f</span></code> 将对应 <code class="docutils literal notranslate"><span class="pre">f</span></code>)。</p>
|
||
<p>示例:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"-f"</span><span class="p">)</span>
|
||
<span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"-p"</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="s2">"float"</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="mi">3</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s2">"point"</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>当它解析命令行</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="o">-</span><span class="n">f</span> <span class="n">foo</span><span class="o">.</span><span class="n">txt</span> <span class="o">-</span><span class="n">p</span> <span class="mi">1</span> <span class="o">-</span><span class="mf">3.5</span> <span class="mi">4</span> <span class="o">-</span><span class="n">fbar</span><span class="o">.</span><span class="n">txt</span>
|
||
</pre></div>
|
||
</div>
|
||
<p><a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 将设置</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">options</span><span class="o">.</span><span class="n">f</span> <span class="o">=</span> <span class="s2">"foo.txt"</span>
|
||
<span class="n">options</span><span class="o">.</span><span class="n">point</span> <span class="o">=</span> <span class="p">(</span><span class="mf">1.0</span><span class="p">,</span> <span class="o">-</span><span class="mf">3.5</span><span class="p">,</span> <span class="mf">4.0</span><span class="p">)</span>
|
||
<span class="n">options</span><span class="o">.</span><span class="n">f</span> <span class="o">=</span> <span class="s2">"bar.txt"</span>
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">"store_const"</span></code> [要求: <a class="reference internal" href="#optparse.Option.const" title="optparse.Option.const"><code class="xref py py-attr docutils literal notranslate"><span class="pre">const</span></code></a>; 关联: <a class="reference internal" href="#optparse.Option.dest" title="optparse.Option.dest"><code class="xref py py-attr docutils literal notranslate"><span class="pre">dest</span></code></a>]</p>
|
||
<p>值 <a class="reference internal" href="#optparse.Option.const" title="optparse.Option.const"><code class="xref py py-attr docutils literal notranslate"><span class="pre">const</span></code></a> 将存放到 <a class="reference internal" href="#optparse.Option.dest" title="optparse.Option.dest"><code class="xref py py-attr docutils literal notranslate"><span class="pre">dest</span></code></a> 中。</p>
|
||
<p>示例:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"-q"</span><span class="p">,</span> <span class="s2">"--quiet"</span><span class="p">,</span>
|
||
<span class="n">action</span><span class="o">=</span><span class="s2">"store_const"</span><span class="p">,</span> <span class="n">const</span><span class="o">=</span><span class="mi">0</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s2">"verbose"</span><span class="p">)</span>
|
||
<span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"-v"</span><span class="p">,</span> <span class="s2">"--verbose"</span><span class="p">,</span>
|
||
<span class="n">action</span><span class="o">=</span><span class="s2">"store_const"</span><span class="p">,</span> <span class="n">const</span><span class="o">=</span><span class="mi">1</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s2">"verbose"</span><span class="p">)</span>
|
||
<span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"--noisy"</span><span class="p">,</span>
|
||
<span class="n">action</span><span class="o">=</span><span class="s2">"store_const"</span><span class="p">,</span> <span class="n">const</span><span class="o">=</span><span class="mi">2</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s2">"verbose"</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>如果看到了 <code class="docutils literal notranslate"><span class="pre">--noisy</span></code>，<a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 将设置</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">options</span><span class="o">.</span><span class="n">verbose</span> <span class="o">=</span> <span class="mi">2</span>
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">"store_true"</span></code> [关联: <a class="reference internal" href="#optparse.Option.dest" title="optparse.Option.dest"><code class="xref py py-attr docutils literal notranslate"><span class="pre">dest</span></code></a>]</p>
|
||
<p>将 <code class="docutils literal notranslate"><span class="pre">True</span></code> 存放到 <a class="reference internal" href="#optparse.Option.dest" title="optparse.Option.dest"><code class="xref py py-attr docutils literal notranslate"><span class="pre">dest</span></code></a> 中的 <code class="docutils literal notranslate"><span class="pre">"store_const"</span></code> 的特例。</p>
|
||
</li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">"store_false"</span></code> [关联: <a class="reference internal" href="#optparse.Option.dest" title="optparse.Option.dest"><code class="xref py py-attr docutils literal notranslate"><span class="pre">dest</span></code></a>]</p>
|
||
<p>类似于 <code class="docutils literal notranslate"><span class="pre">"store_true"</span></code>，但是存放 <code class="docutils literal notranslate"><span class="pre">False</span></code>。</p>
|
||
<p>示例:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"--clobber"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"store_true"</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s2">"clobber"</span><span class="p">)</span>
|
||
<span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"--no-clobber"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"store_false"</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s2">"clobber"</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">"append"</span></code> [关联: <a class="reference internal" href="#optparse.Option.type" title="optparse.Option.type"><code class="xref py py-attr docutils literal notranslate"><span class="pre">type</span></code></a>, <a class="reference internal" href="#optparse.Option.dest" title="optparse.Option.dest"><code class="xref py py-attr docutils literal notranslate"><span class="pre">dest</span></code></a>, <a class="reference internal" href="#optparse.Option.nargs" title="optparse.Option.nargs"><code class="xref py py-attr docutils literal notranslate"><span class="pre">nargs</span></code></a>, <a class="reference internal" href="#optparse.Option.choices" title="optparse.Option.choices"><code class="xref py py-attr docutils literal notranslate"><span class="pre">choices</span></code></a>]</p>
|
||
<p>该选项必须跟一个参数，该参数将被添加到 <a class="reference internal" href="#optparse.Option.dest" title="optparse.Option.dest"><code class="xref py py-attr docutils literal notranslate"><span class="pre">dest</span></code></a> 的列表中。 如果未提供 <a class="reference internal" href="#optparse.Option.dest" title="optparse.Option.dest"><code class="xref py py-attr docutils literal notranslate"><span class="pre">dest</span></code></a> 的默认值，那么当 <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 首次在命令行中遇到该选项时将自动创建一个空列表。 如果 <a class="reference internal" href="#optparse.Option.nargs" title="optparse.Option.nargs"><code class="xref py py-attr docutils literal notranslate"><span class="pre">nargs</span></code></a> > 1，则会读取多个参数，并将一个长度为 <a class="reference internal" href="#optparse.Option.nargs" title="optparse.Option.nargs"><code class="xref py py-attr docutils literal notranslate"><span class="pre">nargs</span></code></a> 的元组添加到 <a class="reference internal" href="#optparse.Option.dest" title="optparse.Option.dest"><code class="xref py py-attr docutils literal notranslate"><span class="pre">dest</span></code></a>。</p>
|
||
<p><a class="reference internal" href="#optparse.Option.type" title="optparse.Option.type"><code class="xref py py-attr docutils literal notranslate"><span class="pre">type</span></code></a> 和 <a class="reference internal" href="#optparse.Option.dest" title="optparse.Option.dest"><code class="xref py py-attr docutils literal notranslate"><span class="pre">dest</span></code></a> 的默认值与 <code class="docutils literal notranslate"><span class="pre">"store"</span></code> 动作的相同。</p>
|
||
<p>示例:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"-t"</span><span class="p">,</span> <span class="s2">"--tracks"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"append"</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="s2">"int"</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>如果在命令行中遇到 <code class="docutils literal notranslate"><span class="pre">-t3</span></code>，<a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 将执行这样的操作:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">options</span><span class="o">.</span><span class="n">tracks</span> <span class="o">=</span> <span class="p">[]</span>
|
||
<span class="n">options</span><span class="o">.</span><span class="n">tracks</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="nb">int</span><span class="p">(</span><span class="s2">"3"</span><span class="p">))</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>如果，在稍后的时候，再遇到 <code class="docutils literal notranslate"><span class="pre">--tracks=4</span></code>，它将执行:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">options</span><span class="o">.</span><span class="n">tracks</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="nb">int</span><span class="p">(</span><span class="s2">"4"</span><span class="p">))</span>
|
||
</pre></div>
|
||
</div>
|
||
<p><code class="docutils literal notranslate"><span class="pre">append</span></code> 动作会在选项的当前值上调用 <code class="docutils literal notranslate"><span class="pre">append</span></code> 方法。 这意味着任何被指定的默认值必须具有 <code class="docutils literal notranslate"><span class="pre">append</span></code> 方法。 这还意味着如果默认值非空，则其中的默认元素将存在于选项的已解析值中，而任何来自命令行的值将被添加到这些默认值之后:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"--files"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"append"</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="p">[</span><span class="s1">'~/.mypkg/defaults'</span><span class="p">])</span>
|
||
<span class="gp">>>> </span><span class="n">opts</span><span class="p">,</span> <span class="n">args</span> <span class="o">=</span> <span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">([</span><span class="s1">'--files'</span><span class="p">,</span> <span class="s1">'overrides.mypkg'</span><span class="p">])</span>
|
||
<span class="gp">>>> </span><span class="n">opts</span><span class="o">.</span><span class="n">files</span>
|
||
<span class="go">['~/.mypkg/defaults', 'overrides.mypkg']</span>
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">"append_const"</span></code> [需要: <a class="reference internal" href="#optparse.Option.const" title="optparse.Option.const"><code class="xref py py-attr docutils literal notranslate"><span class="pre">const</span></code></a>; 关联: <a class="reference internal" href="#optparse.Option.dest" title="optparse.Option.dest"><code class="xref py py-attr docutils literal notranslate"><span class="pre">dest</span></code></a>]</p>
|
||
<p>与 <code class="docutils literal notranslate"><span class="pre">"store_const"</span></code> 类似，但 <a class="reference internal" href="#optparse.Option.const" title="optparse.Option.const"><code class="xref py py-attr docutils literal notranslate"><span class="pre">const</span></code></a> 值将被添加到 <a class="reference internal" href="#optparse.Option.dest" title="optparse.Option.dest"><code class="xref py py-attr docutils literal notranslate"><span class="pre">dest</span></code></a>；与 <code class="docutils literal notranslate"><span class="pre">"append"</span></code> 一样，<a class="reference internal" href="#optparse.Option.dest" title="optparse.Option.dest"><code class="xref py py-attr docutils literal notranslate"><span class="pre">dest</span></code></a> 默认为 <code class="docutils literal notranslate"><span class="pre">None</span></code>，并且当首次遇到该选项时将自动创建一个空列表。</p>
|
||
</li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">"count"</span></code> [关联: <a class="reference internal" href="#optparse.Option.dest" title="optparse.Option.dest"><code class="xref py py-attr docutils literal notranslate"><span class="pre">dest</span></code></a>]</p>
|
||
<p>对保存在 <a class="reference internal" href="#optparse.Option.dest" title="optparse.Option.dest"><code class="xref py py-attr docutils literal notranslate"><span class="pre">dest</span></code></a> 的整数执行递增。 如果未提供默认值，则 <a class="reference internal" href="#optparse.Option.dest" title="optparse.Option.dest"><code class="xref py py-attr docutils literal notranslate"><span class="pre">dest</span></code></a> 会在第一次执行递增之前被设为零。</p>
|
||
<p>示例:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"-v"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"count"</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s2">"verbosity"</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>第一次在命令行中看到 <code class="docutils literal notranslate"><span class="pre">-v</span></code> 时，<a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 将执行这样的操作:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">options</span><span class="o">.</span><span class="n">verbosity</span> <span class="o">=</span> <span class="mi">0</span>
|
||
<span class="n">options</span><span class="o">.</span><span class="n">verbosity</span> <span class="o">+=</span> <span class="mi">1</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>后续每次出现 <code class="docutils literal notranslate"><span class="pre">-v</span></code> 都将导致</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">options</span><span class="o">.</span><span class="n">verbosity</span> <span class="o">+=</span> <span class="mi">1</span>
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">"callback"</span></code> [需要: <a class="reference internal" href="#optparse.Option.callback" title="optparse.Option.callback"><code class="xref py py-attr docutils literal notranslate"><span class="pre">callback</span></code></a>; 关联: <a class="reference internal" href="#optparse.Option.type" title="optparse.Option.type"><code class="xref py py-attr docutils literal notranslate"><span class="pre">type</span></code></a>, <a class="reference internal" href="#optparse.Option.nargs" title="optparse.Option.nargs"><code class="xref py py-attr docutils literal notranslate"><span class="pre">nargs</span></code></a>, <a class="reference internal" href="#optparse.Option.callback_args" title="optparse.Option.callback_args"><code class="xref py py-attr docutils literal notranslate"><span class="pre">callback_args</span></code></a>, <a class="reference internal" href="#optparse.Option.callback_kwargs" title="optparse.Option.callback_kwargs"><code class="xref py py-attr docutils literal notranslate"><span class="pre">callback_kwargs</span></code></a>]</p>
|
||
<p>调用 <a class="reference internal" href="#optparse.Option.callback" title="optparse.Option.callback"><code class="xref py py-attr docutils literal notranslate"><span class="pre">callback</span></code></a> 所指定的函数，它将以如下形式被调用</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">func</span><span class="p">(</span><span class="n">option</span><span class="p">,</span> <span class="n">opt_str</span><span class="p">,</span> <span class="n">value</span><span class="p">,</span> <span class="n">parser</span><span class="p">,</span> <span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>请参阅 <a class="reference internal" href="#optparse-option-callbacks"><span class="std std-ref">选项回调</span></a> 一节了解详情。</p>
|
||
</li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">"help"</span></code></p>
|
||
<p>为当前选项解析器中所有的选项打印完整帮助消息。 该帮助消息是由传给 OptionParser 的构造器的 <code class="docutils literal notranslate"><span class="pre">usage</span></code> 字符串和传给每个选项的 <a class="reference internal" href="#optparse.Option.help" title="optparse.Option.help"><code class="xref py py-attr docutils literal notranslate"><span class="pre">help</span></code></a> 字符串构造而成的。</p>
|
||
<p>如果没有为某个选项提供 <a class="reference internal" href="#optparse.Option.help" title="optparse.Option.help"><code class="xref py py-attr docutils literal notranslate"><span class="pre">help</span></code></a> 字符串，它仍将在帮助消息中列出。 要完全略去某个选项，请使用特殊值 <code class="xref py py-data docutils literal notranslate"><span class="pre">optparse.SUPPRESS_HELP</span></code>。</p>
|
||
<p><a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 将自动为所有OptionParser 添加 <a class="reference internal" href="#optparse.Option.help" title="optparse.Option.help"><code class="xref py py-attr docutils literal notranslate"><span class="pre">help</span></code></a> 选项，因此你通常不需要创建选项。</p>
|
||
<p>示例:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">optparse</span> <span class="kn">import</span> <span class="n">OptionParser</span><span class="p">,</span> <span class="n">SUPPRESS_HELP</span>
|
||
|
||
<span class="c1"># usually, a help option is added automatically, but that can</span>
|
||
<span class="c1"># be suppressed using the add_help_option argument</span>
|
||
<span class="n">parser</span> <span class="o">=</span> <span class="n">OptionParser</span><span class="p">(</span><span class="n">add_help_option</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span>
|
||
|
||
<span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"-h"</span><span class="p">,</span> <span class="s2">"--help"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"help"</span><span class="p">)</span>
|
||
<span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"-v"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"store_true"</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s2">"verbose"</span><span class="p">,</span>
|
||
<span class="n">help</span><span class="o">=</span><span class="s2">"Be moderately verbose"</span><span class="p">)</span>
|
||
<span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"--file"</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s2">"filename"</span><span class="p">,</span>
|
||
<span class="n">help</span><span class="o">=</span><span class="s2">"Input file to read data from"</span><span class="p">)</span>
|
||
<span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"--secret"</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="n">SUPPRESS_HELP</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>如果 <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 在命令行中看到 <code class="docutils literal notranslate"><span class="pre">-h</span></code> 或 <code class="docutils literal notranslate"><span class="pre">--help</span></code>，它将将类似下面这样的帮助消息打印到 stdout (假设 <code class="docutils literal notranslate"><span class="pre">sys.argv[0]</span></code> 为 <code class="docutils literal notranslate"><span class="pre">"foo.py"</span></code>):</p>
|
||
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>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
|
||
</pre></div>
|
||
</div>
|
||
<p>在打印帮助消息之后，<a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 将使用 <code class="docutils literal notranslate"><span class="pre">sys.exit(0)</span></code> 来终结你的进程。</p>
|
||
</li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">"version"</span></code></p>
|
||
<p>将提供给 OptionParser 的版本号打印到 stdout 并退出。 该版本号实际上是由 OptionParser 的 <code class="docutils literal notranslate"><span class="pre">print_version()</span></code> 方法进行格式化并打印的。 这通常只在向 OptionParser 构造器提供了 <code class="docutils literal notranslate"><span class="pre">version</span></code> 参数时才有意义。 与 <a class="reference internal" href="#optparse.Option.help" title="optparse.Option.help"><code class="xref py py-attr docutils literal notranslate"><span class="pre">help</span></code></a> 选项类似，你很少会创建 <code class="docutils literal notranslate"><span class="pre">version</span></code> 选项，因为 <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 会在需要时自动添加它们。</p>
|
||
</li>
|
||
</ul>
|
||
</section>
|
||
<section id="standard-option-types">
|
||
<span id="optparse-standard-option-types"></span><h3>标准选项类型<a class="headerlink" href="#standard-option-types" title="永久链接至标题">¶</a></h3>
|
||
<p><a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 有五种内置选项类型: <code class="docutils literal notranslate"><span class="pre">"string"</span></code>, <code class="docutils literal notranslate"><span class="pre">"int"</span></code>, <code class="docutils literal notranslate"><span class="pre">"choice"</span></code>, <code class="docutils literal notranslate"><span class="pre">"float"</span></code> 和 <code class="docutils literal notranslate"><span class="pre">"complex"</span></code>。 如果你需要添加新的选项类型，请参阅 <a class="reference internal" href="#optparse-extending-optparse"><span class="std std-ref">扩展 optparse</span></a> 一节。</p>
|
||
<p>传给 string 类型选项的参数不会以任何方式进行检查或转换：命令行中的文本将被原样保存至目标（或传给回调）。</p>
|
||
<p>整数参数 (<code class="docutils literal notranslate"><span class="pre">"int"</span></code> 类型) 将以如下方式解析:</p>
|
||
<ul class="simple">
|
||
<li><p>如果数字开头为 <code class="docutils literal notranslate"><span class="pre">0x</span></code>，它将被解析为十六进制数</p></li>
|
||
<li><p>如果数字开头为 <code class="docutils literal notranslate"><span class="pre">0</span></code>，它将被解析为八进制数</p></li>
|
||
<li><p>如果数字开头为 <code class="docutils literal notranslate"><span class="pre">0b</span></code>，它将被解析为二进制数</p></li>
|
||
<li><p>在其他情况下，数字将被解析为十进制数</p></li>
|
||
</ul>
|
||
<p>转换操作是通过调用 <a class="reference internal" href="functions.html#int" title="int"><code class="xref py py-func docutils literal notranslate"><span class="pre">int()</span></code></a> 并传入适当的 base (2, 8, 10 或 16) 来完成的。 如果转换失败， <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 也将失败，但它会附带更有用的错误消息。</p>
|
||
<p><code class="docutils literal notranslate"><span class="pre">"float"</span></code> 和 <code class="docutils literal notranslate"><span class="pre">"complex"</span></code> 选项参数会直接通过 <a class="reference internal" href="functions.html#float" title="float"><code class="xref py py-func docutils literal notranslate"><span class="pre">float()</span></code></a> 和 <a class="reference internal" href="functions.html#complex" title="complex"><code class="xref py py-func docutils literal notranslate"><span class="pre">complex()</span></code></a> 来转换，使用类似的错误处理。</p>
|
||
<p><code class="docutils literal notranslate"><span class="pre">"choice"</span></code> 选项是 <code class="docutils literal notranslate"><span class="pre">"string"</span></code> 选项的子类型。 <a class="reference internal" href="#optparse.Option.choices" title="optparse.Option.choices"><code class="xref py py-attr docutils literal notranslate"><span class="pre">choices</span></code></a> 选项属性（由字符串组成的序列）定义了允许的选项参数的集合。 <code class="xref py py-func docutils literal notranslate"><span class="pre">optparse.check_choice()</span></code> 将用户提供的选项参数与这个主列表进行比较并会在给出无效的字符串时引发 <code class="xref py py-exc docutils literal notranslate"><span class="pre">OptionValueError</span></code>。</p>
|
||
</section>
|
||
<section id="parsing-arguments">
|
||
<span id="optparse-parsing-arguments"></span><h3>解析参数<a class="headerlink" href="#parsing-arguments" title="永久链接至标题">¶</a></h3>
|
||
<p>创建和填充 OptionParser 的基本目的是调用其 <code class="xref py py-meth docutils literal notranslate"><span class="pre">parse_args()</span></code> 方法:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="p">(</span><span class="n">options</span><span class="p">,</span> <span class="n">args</span><span class="p">)</span> <span class="o">=</span> <span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">(</span><span class="n">args</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">values</span><span class="o">=</span><span class="kc">None</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>输入参数的位置</p>
|
||
<dl class="simple">
|
||
<dt><code class="docutils literal notranslate"><span class="pre">args</span></code></dt><dd><p>要处理的参数列表 (默认: <code class="docutils literal notranslate"><span class="pre">sys.argv[1:]</span></code>)</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">values</span></code></dt><dd><p>要用于存储选项参数的 <code class="xref py py-class docutils literal notranslate"><span class="pre">optparse.Values</span></code> 对象 (默认：一个新的 <code class="xref py py-class docutils literal notranslate"><span class="pre">Values</span></code> 实例) -- 如果你给出一个现有对象，则不会基于它来初始化选项的默认值</p>
|
||
</dd>
|
||
</dl>
|
||
<p>返回值为</p>
|
||
<dl class="simple">
|
||
<dt><code class="docutils literal notranslate"><span class="pre">options</span></code></dt><dd><p>同一个对象将作为 <code class="docutils literal notranslate"><span class="pre">values</span></code>，或 <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 所创建的 optparse.Values 实例传入</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">args</span></code></dt><dd><p>在所有选项被处理完毕后余下的位置参数</p>
|
||
</dd>
|
||
</dl>
|
||
<p>最常见的用法是不提供任何关键字参数。 如果你提供了 <code class="docutils literal notranslate"><span class="pre">values</span></code>，它将通过重复的 <a class="reference internal" href="functions.html#setattr" title="setattr"><code class="xref py py-func docutils literal notranslate"><span class="pre">setattr()</span></code></a> 调用来修改（大致为每个存储到指定选项目标的选项参数调用一次）并由 <code class="xref py py-meth docutils literal notranslate"><span class="pre">parse_args()</span></code> 返回。</p>
|
||
<p>如果 <code class="xref py py-meth docutils literal notranslate"><span class="pre">parse_args()</span></code> 在参数列表中遇到任何错误，它将调用 OptionParser 的 <code class="xref py py-meth docutils literal notranslate"><span class="pre">error()</span></code> 方法并附带适当的最终用户错误消息。 这会完全终结你的进程并将退出状态设为 2 (传统的针对命令行错误的 Unix 退出状态)。</p>
|
||
</section>
|
||
<section id="querying-and-manipulating-your-option-parser">
|
||
<span id="optparse-querying-manipulating-option-parser"></span><h3>查询和操纵你的选项解析器<a class="headerlink" href="#querying-and-manipulating-your-option-parser" title="永久链接至标题">¶</a></h3>
|
||
<p>选项解析器的默认行为可被轻度地定制，并且你还可以调整你的选项解析器查看实际效果如何。 OptionParser 提供了一些方法来帮助你进行定制:</p>
|
||
<dl class="method">
|
||
<dt id="optparse.OptionParser.disable_interspersed_args">
|
||
<code class="sig-prename descclassname">OptionParser.</code><code class="sig-name descname">disable_interspersed_args</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#optparse.OptionParser.disable_interspersed_args" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>设置解析在第一个非选项处停止。 举例来说，如果 <code class="docutils literal notranslate"><span class="pre">-a</span></code> 和 <code class="docutils literal notranslate"><span class="pre">-b</span></code> 都是不接受参数的简单选项，则 <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 通常会接受这样的语法:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">prog</span> <span class="o">-</span><span class="n">a</span> <span class="n">arg1</span> <span class="o">-</span><span class="n">b</span> <span class="n">arg2</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>并会这样处理它</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">prog</span> <span class="o">-</span><span class="n">a</span> <span class="o">-</span><span class="n">b</span> <span class="n">arg1</span> <span class="n">arg2</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>要禁用此特性，则调用 <a class="reference internal" href="#optparse.OptionParser.disable_interspersed_args" title="optparse.OptionParser.disable_interspersed_args"><code class="xref py py-meth docutils literal notranslate"><span class="pre">disable_interspersed_args()</span></code></a>。 这将恢复传统的 Unix 语法，其中选项解析会在第一个非选项参数处停止。</p>
|
||
<p>如果你用一个命令处理程序来运行另一个拥有它自己的选项的命令而你希望参确保这些选项不会被混淆就可以使用此方法。 例如，每个命令可能具有不同的选项集合。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="optparse.OptionParser.enable_interspersed_args">
|
||
<code class="sig-prename descclassname">OptionParser.</code><code class="sig-name descname">enable_interspersed_args</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#optparse.OptionParser.enable_interspersed_args" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>设置解析不在第一个非选项处停止，允许多个命令行参数的插入相互切换。 这是默认的行为。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="optparse.OptionParser.get_option">
|
||
<code class="sig-prename descclassname">OptionParser.</code><code class="sig-name descname">get_option</code><span class="sig-paren">(</span><em class="sig-param">opt_str</em><span class="sig-paren">)</span><a class="headerlink" href="#optparse.OptionParser.get_option" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>返回具有选项字符串 <em>opt_str</em> 的的 Option 实例，或者如果不存在具有该选项字符串的选项则返回 <code class="docutils literal notranslate"><span class="pre">None</span></code>。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="optparse.OptionParser.has_option">
|
||
<code class="sig-prename descclassname">OptionParser.</code><code class="sig-name descname">has_option</code><span class="sig-paren">(</span><em class="sig-param">opt_str</em><span class="sig-paren">)</span><a class="headerlink" href="#optparse.OptionParser.has_option" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>如果 OptionParser 包含一个具有选项字符串 <em>opt_str</em> 的选项 (例如 <code class="docutils literal notranslate"><span class="pre">-q</span></code> 或 <code class="docutils literal notranslate"><span class="pre">--verbose</span></code>) 则返回 <code class="docutils literal notranslate"><span class="pre">True</span></code>。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="optparse.OptionParser.remove_option">
|
||
<code class="sig-prename descclassname">OptionParser.</code><code class="sig-name descname">remove_option</code><span class="sig-paren">(</span><em class="sig-param">opt_str</em><span class="sig-paren">)</span><a class="headerlink" href="#optparse.OptionParser.remove_option" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>如果 <a class="reference internal" href="#optparse.OptionParser" title="optparse.OptionParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">OptionParser</span></code></a> 包含一个对应于 <em>opt_str</em> 的选项，则移除该选项。 如果该选项提供了任何其他选项字符串，这些选项字符串将全部不可用。 如果 <em>opt_str</em> 不存在于任何属于此 <a class="reference internal" href="#optparse.OptionParser" title="optparse.OptionParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">OptionParser</span></code></a> 的选项之中，则会引发 <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a>。</p>
|
||
</dd></dl>
|
||
|
||
</section>
|
||
<section id="conflicts-between-options">
|
||
<span id="optparse-conflicts-between-options"></span><h3>选项之间的冲突<a class="headerlink" href="#conflicts-between-options" title="永久链接至标题">¶</a></h3>
|
||
<p>如果你不够小心，很容易会定义具有相互冲突的选项字符串的多个选项:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"-n"</span><span class="p">,</span> <span class="s2">"--dry-run"</span><span class="p">,</span> <span class="o">...</span><span class="p">)</span>
|
||
<span class="o">...</span>
|
||
<span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"-n"</span><span class="p">,</span> <span class="s2">"--noisy"</span><span class="p">,</span> <span class="o">...</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>（当你自定义具有某些标准选项的 OptionParser 时特别容易发生这种情况。）</p>
|
||
<p>每当你添加一个选项时，<a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 会检查它是否与现有选项冲突。 如果发现存在冲突，它将发起调用当前的冲突处理机制。 你可以选择在构造器中设置冲突处理机制:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">parser</span> <span class="o">=</span> <span class="n">OptionParser</span><span class="p">(</span><span class="o">...</span><span class="p">,</span> <span class="n">conflict_handler</span><span class="o">=</span><span class="n">handler</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>或是在单独调用中设置:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">parser</span><span class="o">.</span><span class="n">set_conflict_handler</span><span class="p">(</span><span class="n">handler</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>可用的冲突处理器有:</p>
|
||
<blockquote>
|
||
<div><dl class="simple">
|
||
<dt><code class="docutils literal notranslate"><span class="pre">"error"</span></code> (默认)</dt><dd><p>将选项冲突视为编程错误并引发 <code class="xref py py-exc docutils literal notranslate"><span class="pre">OptionConflictError</span></code></p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">"resolve"</span></code></dt><dd><p>智能地解决选项冲突（见下文）</p>
|
||
</dd>
|
||
</dl>
|
||
</div></blockquote>
|
||
<p>举例来说，让我们定义一个智能地解决冲突的 <a class="reference internal" href="#optparse.OptionParser" title="optparse.OptionParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">OptionParser</span></code></a> 并向其添加相互冲突的选项:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">parser</span> <span class="o">=</span> <span class="n">OptionParser</span><span class="p">(</span><span class="n">conflict_handler</span><span class="o">=</span><span class="s2">"resolve"</span><span class="p">)</span>
|
||
<span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"-n"</span><span class="p">,</span> <span class="s2">"--dry-run"</span><span class="p">,</span> <span class="o">...</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s2">"do no harm"</span><span class="p">)</span>
|
||
<span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"-n"</span><span class="p">,</span> <span class="s2">"--noisy"</span><span class="p">,</span> <span class="o">...</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s2">"be noisy"</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>At this point, <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> detects that a previously-added option is already
|
||
using the <code class="docutils literal notranslate"><span class="pre">-n</span></code> option string. Since <code class="docutils literal notranslate"><span class="pre">conflict_handler</span></code> is <code class="docutils literal notranslate"><span class="pre">"resolve"</span></code>,
|
||
it resolves the situation by removing <code class="docutils literal notranslate"><span class="pre">-n</span></code> from the earlier option's list of
|
||
option strings. Now <code class="docutils literal notranslate"><span class="pre">--dry-run</span></code> is the only way for the user to activate
|
||
that option. If the user asks for help, the help message will reflect that:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">Options</span><span class="p">:</span>
|
||
<span class="o">--</span><span class="n">dry</span><span class="o">-</span><span class="n">run</span> <span class="n">do</span> <span class="n">no</span> <span class="n">harm</span>
|
||
<span class="o">...</span>
|
||
<span class="o">-</span><span class="n">n</span><span class="p">,</span> <span class="o">--</span><span class="n">noisy</span> <span class="n">be</span> <span class="n">noisy</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>It's possible to whittle away the option strings for a previously-added option
|
||
until there are none left, and the user has no way of invoking that option from
|
||
the command-line. In that case, <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> removes that option completely,
|
||
so it doesn't show up in help text or anywhere else. Carrying on with our
|
||
existing OptionParser:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"--dry-run"</span><span class="p">,</span> <span class="o">...</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s2">"new dry-run option"</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>这时，原有的 <code class="docutils literal notranslate"><span class="pre">-n</span></code>/<code class="docutils literal notranslate"><span class="pre">--dry-run</span></code> 选项将不再可用，因此 <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 会将其移除，帮助文本将变成这样:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">Options</span><span class="p">:</span>
|
||
<span class="o">...</span>
|
||
<span class="o">-</span><span class="n">n</span><span class="p">,</span> <span class="o">--</span><span class="n">noisy</span> <span class="n">be</span> <span class="n">noisy</span>
|
||
<span class="o">--</span><span class="n">dry</span><span class="o">-</span><span class="n">run</span> <span class="n">new</span> <span class="n">dry</span><span class="o">-</span><span class="n">run</span> <span class="n">option</span>
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
<section id="cleanup">
|
||
<span id="optparse-cleanup"></span><h3>清理<a class="headerlink" href="#cleanup" title="永久链接至标题">¶</a></h3>
|
||
<p>OptionParser 实例存在一些循环引用。 这对 Python 的垃圾回收器来说应该不是问题，但你可能希望在你完成对 OptionParser 的使用后通过调用其 <code class="xref py py-meth docutils literal notranslate"><span class="pre">destroy()</span></code> 来显式地中断循环引用。 这在可以从你的 OptionParser 访问大型对象图的长期运行应用程序中特别有用。</p>
|
||
</section>
|
||
<section id="other-methods">
|
||
<span id="optparse-other-methods"></span><h3>其他方法<a class="headerlink" href="#other-methods" title="永久链接至标题">¶</a></h3>
|
||
<p>OptionParser 还支持其他一些公有方法:</p>
|
||
<dl class="method">
|
||
<dt id="optparse.OptionParser.set_usage">
|
||
<code class="sig-prename descclassname">OptionParser.</code><code class="sig-name descname">set_usage</code><span class="sig-paren">(</span><em class="sig-param">usage</em><span class="sig-paren">)</span><a class="headerlink" href="#optparse.OptionParser.set_usage" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>根据上述的规则为 <code class="docutils literal notranslate"><span class="pre">usage</span></code> 构造器关键字参数设置用法字符串。 传入 <code class="docutils literal notranslate"><span class="pre">None</span></code> 将设置默认的用法字符串；使用 <code class="xref py py-data docutils literal notranslate"><span class="pre">optparse.SUPPRESS_USAGE</span></code> 将屏蔽用法消息。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="optparse.OptionParser.print_usage">
|
||
<code class="sig-prename descclassname">OptionParser.</code><code class="sig-name descname">print_usage</code><span class="sig-paren">(</span><em class="sig-param">file=None</em><span class="sig-paren">)</span><a class="headerlink" href="#optparse.OptionParser.print_usage" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>将当前程序的用法消息 (<code class="docutils literal notranslate"><span class="pre">self.usage</span></code>) 打印到 <em>file</em> (默认为 stdout)。 出现在 <code class="docutils literal notranslate"><span class="pre">self.usage</span></code> 中的字符串 <code class="docutils literal notranslate"><span class="pre">%prog</span></code> 将全部被替换为当前程序的名称。 如果 <code class="docutils literal notranslate"><span class="pre">self.usage</span></code> 为空或未定义则不做任何事情。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="optparse.OptionParser.get_usage">
|
||
<code class="sig-prename descclassname">OptionParser.</code><code class="sig-name descname">get_usage</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#optparse.OptionParser.get_usage" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>与 <a class="reference internal" href="#optparse.OptionParser.print_usage" title="optparse.OptionParser.print_usage"><code class="xref py py-meth docutils literal notranslate"><span class="pre">print_usage()</span></code></a> 类似但是将返回用法字符串而不是打印它。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="optparse.OptionParser.set_defaults">
|
||
<code class="sig-prename descclassname">OptionParser.</code><code class="sig-name descname">set_defaults</code><span class="sig-paren">(</span><em class="sig-param">dest=value</em>, <em class="sig-param">...</em><span class="sig-paren">)</span><a class="headerlink" href="#optparse.OptionParser.set_defaults" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>一次性地为多个选项目标设置默认值。 使用 <a class="reference internal" href="#optparse.OptionParser.set_defaults" title="optparse.OptionParser.set_defaults"><code class="xref py py-meth docutils literal notranslate"><span class="pre">set_defaults()</span></code></a> 是为选项设置默认值的推荐方式同，因为多个选项可以共享同一个目标。 举例来说，如果几个 "mode" 选项全部设置了相同的目标，则它们中的任何一个都可以设置默认值，而最终生效的将是最后一次设置的默认值:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"--advanced"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"store_const"</span><span class="p">,</span>
|
||
<span class="n">dest</span><span class="o">=</span><span class="s2">"mode"</span><span class="p">,</span> <span class="n">const</span><span class="o">=</span><span class="s2">"advanced"</span><span class="p">,</span>
|
||
<span class="n">default</span><span class="o">=</span><span class="s2">"novice"</span><span class="p">)</span> <span class="c1"># overridden below</span>
|
||
<span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"--novice"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"store_const"</span><span class="p">,</span>
|
||
<span class="n">dest</span><span class="o">=</span><span class="s2">"mode"</span><span class="p">,</span> <span class="n">const</span><span class="o">=</span><span class="s2">"novice"</span><span class="p">,</span>
|
||
<span class="n">default</span><span class="o">=</span><span class="s2">"advanced"</span><span class="p">)</span> <span class="c1"># overrides above setting</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>为避免混淆，请使用 <a class="reference internal" href="#optparse.OptionParser.set_defaults" title="optparse.OptionParser.set_defaults"><code class="xref py py-meth docutils literal notranslate"><span class="pre">set_defaults()</span></code></a>:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">parser</span><span class="o">.</span><span class="n">set_defaults</span><span class="p">(</span><span class="n">mode</span><span class="o">=</span><span class="s2">"advanced"</span><span class="p">)</span>
|
||
<span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"--advanced"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"store_const"</span><span class="p">,</span>
|
||
<span class="n">dest</span><span class="o">=</span><span class="s2">"mode"</span><span class="p">,</span> <span class="n">const</span><span class="o">=</span><span class="s2">"advanced"</span><span class="p">)</span>
|
||
<span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"--novice"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"store_const"</span><span class="p">,</span>
|
||
<span class="n">dest</span><span class="o">=</span><span class="s2">"mode"</span><span class="p">,</span> <span class="n">const</span><span class="o">=</span><span class="s2">"novice"</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
</section>
|
||
</section>
|
||
<section id="option-callbacks">
|
||
<span id="optparse-option-callbacks"></span><h2>选项回调<a class="headerlink" href="#option-callbacks" title="永久链接至标题">¶</a></h2>
|
||
<p>当 <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 的内置动作和类型不能满足你的需要时，你有两个选择：扩展 <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 或定义一个回调选项。 扩展 <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 的方式更为通用，但对许多简单场景来说是大材小用了。 你所需要的往往只是一个简单的回调。</p>
|
||
<p>定义一个回调选项分为两步:</p>
|
||
<ul class="simple">
|
||
<li><p>使用 <code class="docutils literal notranslate"><span class="pre">"callback"</span></code> 动作定义选项本身</p></li>
|
||
<li><p>编写回调；它是一个接受至少四个参数的函数（或方法），如下所述</p></li>
|
||
</ul>
|
||
<section id="defining-a-callback-option">
|
||
<span id="optparse-defining-callback-option"></span><h3>定义回调选项<a class="headerlink" href="#defining-a-callback-option" title="永久链接至标题">¶</a></h3>
|
||
<p>一般来说，定义回调选项的最简单方式是使用 <a class="reference internal" href="#optparse.OptionParser.add_option" title="optparse.OptionParser.add_option"><code class="xref py py-meth docutils literal notranslate"><span class="pre">OptionParser.add_option()</span></code></a> 方法。 在 <a class="reference internal" href="#optparse.Option.action" title="optparse.Option.action"><code class="xref py py-attr docutils literal notranslate"><span class="pre">action</span></code></a> 之外，你必须指定的唯一选项属性是 <code class="docutils literal notranslate"><span class="pre">callback</span></code>，即要调用的函数:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"-c"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"callback"</span><span class="p">,</span> <span class="n">callback</span><span class="o">=</span><span class="n">my_callback</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p><code class="docutils literal notranslate"><span class="pre">callback</span></code> 是一个函数（或其他可调用对象），因此当你创建这个回调选项时你必须已经定义了 <code class="docutils literal notranslate"><span class="pre">my_callback()</span></code>。 在这个简单的例子中，<a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 甚至不知道 <code class="docutils literal notranslate"><span class="pre">-c</span></code> 是否接受任何参数，这通常意味着该选项不接受任何参数 --- 它需要知道的就是存在命令行参数 <code class="docutils literal notranslate"><span class="pre">-c</span></code>。 但是，在某些情况下，你可能希望你的回调接受任意数量的命令行参数。 这是编写回调的一个麻烦之处；本小节将稍后讲解这个问题。</p>
|
||
<p><a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 总是会向你的回调传递四个特定参数，它只会在你通过 <a class="reference internal" href="#optparse.Option.callback_args" title="optparse.Option.callback_args"><code class="xref py py-attr docutils literal notranslate"><span class="pre">callback_args</span></code></a> 和 <a class="reference internal" href="#optparse.Option.callback_kwargs" title="optparse.Option.callback_kwargs"><code class="xref py py-attr docutils literal notranslate"><span class="pre">callback_kwargs</span></code></a> 进行指定时才传入额外的参数。 因此，最小化的回调函数签名如下:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">my_callback</span><span class="p">(</span><span class="n">option</span><span class="p">,</span> <span class="n">opt</span><span class="p">,</span> <span class="n">value</span><span class="p">,</span> <span class="n">parser</span><span class="p">):</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>对传给回调的四个参数的说明见下文。</p>
|
||
<p>当你定义回调选项时还可以提供一些其他的选项属性:</p>
|
||
<dl class="simple">
|
||
<dt><a class="reference internal" href="#optparse.Option.type" title="optparse.Option.type"><code class="xref py py-attr docutils literal notranslate"><span class="pre">type</span></code></a></dt><dd><p>具有其通常的含义：与在 <code class="docutils literal notranslate"><span class="pre">"store"</span></code> 或 <code class="docutils literal notranslate"><span class="pre">"append"</span></code> 动作中一样，它指示 <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 读取一个参数并将其转换为 <a class="reference internal" href="#optparse.Option.type" title="optparse.Option.type"><code class="xref py py-attr docutils literal notranslate"><span class="pre">type</span></code></a>。 但是，<a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 并不会将所转换的值保存到某个地方，而是将其传给你的回调函数。</p>
|
||
</dd>
|
||
<dt><a class="reference internal" href="#optparse.Option.nargs" title="optparse.Option.nargs"><code class="xref py py-attr docutils literal notranslate"><span class="pre">nargs</span></code></a></dt><dd><p>同样具有其通常的含义：如果提供了该属性并且其值 > 1，<a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 将读取 <a class="reference internal" href="#optparse.Option.nargs" title="optparse.Option.nargs"><code class="xref py py-attr docutils literal notranslate"><span class="pre">nargs</span></code></a> 个参数，每个参数都必须可被转换为 <a class="reference internal" href="#optparse.Option.type" title="optparse.Option.type"><code class="xref py py-attr docutils literal notranslate"><span class="pre">type</span></code></a>。 随后它会将被转换值的元组传给你的回调。</p>
|
||
</dd>
|
||
<dt><a class="reference internal" href="#optparse.Option.callback_args" title="optparse.Option.callback_args"><code class="xref py py-attr docutils literal notranslate"><span class="pre">callback_args</span></code></a></dt><dd><p>一个要传给回调的由额外位置参数组成的元组</p>
|
||
</dd>
|
||
<dt><a class="reference internal" href="#optparse.Option.callback_kwargs" title="optparse.Option.callback_kwargs"><code class="xref py py-attr docutils literal notranslate"><span class="pre">callback_kwargs</span></code></a></dt><dd><p>一个要传给回调的由额外关键字参数组成的字典</p>
|
||
</dd>
|
||
</dl>
|
||
</section>
|
||
<section id="how-callbacks-are-called">
|
||
<span id="optparse-how-callbacks-called"></span><h3>回调应当如何调用<a class="headerlink" href="#how-callbacks-are-called" title="永久链接至标题">¶</a></h3>
|
||
<p>所有回调都将使用以下方式调用:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">func</span><span class="p">(</span><span class="n">option</span><span class="p">,</span> <span class="n">opt_str</span><span class="p">,</span> <span class="n">value</span><span class="p">,</span> <span class="n">parser</span><span class="p">,</span> <span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>其中</p>
|
||
<dl>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">option</span></code></dt><dd><p>是调用该回调的 Option 实例</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">opt_str</span></code></dt><dd><p>是在触发回调的命令行参数中出现的选项字符串。 （如果使用了长选项的缩写形式，则 <code class="docutils literal notranslate"><span class="pre">opt_str</span></code> 将为完整规范的选项字符串 --- 举例来说，如果用户在命令行中将 <code class="docutils literal notranslate"><span class="pre">--foo</span></code> 作为 <code class="docutils literal notranslate"><span class="pre">--foobar</span></code> 的缩写形式，则 <code class="docutils literal notranslate"><span class="pre">opt_str</span></code> 将为 <code class="docutils literal notranslate"><span class="pre">"--foobar"</span></code>。）</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">value</span></code></dt><dd><p>是在命令行中提供给该选项的参数。 <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 将只在设置了 <a class="reference internal" href="#optparse.Option.type" title="optparse.Option.type"><code class="xref py py-attr docutils literal notranslate"><span class="pre">type</span></code></a> 的时候才接受参数；<code class="docutils literal notranslate"><span class="pre">value</span></code> 将为该选项的类型所指定的类型。 如果该选项的 <a class="reference internal" href="#optparse.Option.type" title="optparse.Option.type"><code class="xref py py-attr docutils literal notranslate"><span class="pre">type</span></code></a> 为 <code class="docutils literal notranslate"><span class="pre">None</span></code> (不接受参数)，则 <code class="docutils literal notranslate"><span class="pre">value</span></code> 将为 <code class="docutils literal notranslate"><span class="pre">None</span></code>。 如果 <a class="reference internal" href="#optparse.Option.nargs" title="optparse.Option.nargs"><code class="xref py py-attr docutils literal notranslate"><span class="pre">nargs</span></code></a> > 1，则 <code class="docutils literal notranslate"><span class="pre">value</span></code> 将为由指定类型的值组成的元组。</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">parser</span></code></dt><dd><p>是驱动选项解析过程的 OptionParser 实例，主要作用在于你可以通过其实例属性访问其他一些相关数据:</p>
|
||
<dl class="simple">
|
||
<dt><code class="docutils literal notranslate"><span class="pre">parser.largs</span></code></dt><dd><p>当前的剩余参数列表，即已被读取但不属于选项或选项参数的参数。 可以任意修改 <code class="docutils literal notranslate"><span class="pre">parser.largs</span></code>，例如向其添加更多的参数。 （该列表将成为 <code class="docutils literal notranslate"><span class="pre">args</span></code>，即 <code class="xref py py-meth docutils literal notranslate"><span class="pre">parse_args()</span></code> 的第二个返回值。）</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">parser.rargs</span></code></dt><dd><p>当前的保留参数列表，即移除了 <code class="docutils literal notranslate"><span class="pre">opt_str</span></code> 和 <code class="docutils literal notranslate"><span class="pre">value</span></code> (如果可用)，并且只有在它们之后的参数才会被保留。 可以任意修改 <code class="docutils literal notranslate"><span class="pre">parser.rargs</span></code>，例如通过读取更多的参数。</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">parser.values</span></code></dt><dd><p>作为选项值默认保存位置的对象（一个 optparse.OptionValues 实例）。 这使得回调能使用与 <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 的其他部分相同的机制来保存选项值；你不需要手动处理全局变量或闭包。 你还可以访问或修改在命令行中遇到的任何选项的值。</p>
|
||
</dd>
|
||
</dl>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">args</span></code></dt><dd><p>是一个由通过 <a class="reference internal" href="#optparse.Option.callback_args" title="optparse.Option.callback_args"><code class="xref py py-attr docutils literal notranslate"><span class="pre">callback_args</span></code></a> 选项属性提供的任意位置参数组成的元组。</p>
|
||
</dd>
|
||
<dt><code class="docutils literal notranslate"><span class="pre">kwargs</span></code></dt><dd><p>是一个由通过 <a class="reference internal" href="#optparse.Option.callback_kwargs" title="optparse.Option.callback_kwargs"><code class="xref py py-attr docutils literal notranslate"><span class="pre">callback_kwargs</span></code></a> 提供的任意关键字参数组成的字典。</p>
|
||
</dd>
|
||
</dl>
|
||
</section>
|
||
<section id="raising-errors-in-a-callback">
|
||
<span id="optparse-raising-errors-in-callback"></span><h3>在回调中引发错误<a class="headerlink" href="#raising-errors-in-a-callback" title="永久链接至标题">¶</a></h3>
|
||
<p>如果选项或其参数存在任何问题则回调函数应当引发 <code class="xref py py-exc docutils literal notranslate"><span class="pre">OptionValueError</span></code>。 <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 将捕获该异常并终止程序，将你提供的错误消息打印到 stderr。 你的消息应当清晰、简洁、准确并指明出错的选项。 否则，用户将很难弄清楚自己做错了什么。</p>
|
||
</section>
|
||
<section id="callback-example-1-trivial-callback">
|
||
<span id="optparse-callback-example-1"></span><h3>回调示例 1：最简回调<a class="headerlink" href="#callback-example-1-trivial-callback" title="永久链接至标题">¶</a></h3>
|
||
<p>下面是一个不接受任何参数，只是简单地记录所遇见的选项的回调选项示例:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">record_foo_seen</span><span class="p">(</span><span class="n">option</span><span class="p">,</span> <span class="n">opt_str</span><span class="p">,</span> <span class="n">value</span><span class="p">,</span> <span class="n">parser</span><span class="p">):</span>
|
||
<span class="n">parser</span><span class="o">.</span><span class="n">values</span><span class="o">.</span><span class="n">saw_foo</span> <span class="o">=</span> <span class="kc">True</span>
|
||
|
||
<span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"--foo"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"callback"</span><span class="p">,</span> <span class="n">callback</span><span class="o">=</span><span class="n">record_foo_seen</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>当然，你也可以使用 <code class="docutils literal notranslate"><span class="pre">"store_true"</span></code> 动作做到这一点。</p>
|
||
</section>
|
||
<section id="callback-example-2-check-option-order">
|
||
<span id="optparse-callback-example-2"></span><h3>回调示例 2：检查选项顺序<a class="headerlink" href="#callback-example-2-check-option-order" title="永久链接至标题">¶</a></h3>
|
||
<p>下面是一个更有趣些的示例：当看到 <code class="docutils literal notranslate"><span class="pre">-a</span></code> 出现时将会记录，而如果它在命令行中出现于 <code class="docutils literal notranslate"><span class="pre">-b</span></code> 之后则将报告错误。</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">check_order</span><span class="p">(</span><span class="n">option</span><span class="p">,</span> <span class="n">opt_str</span><span class="p">,</span> <span class="n">value</span><span class="p">,</span> <span class="n">parser</span><span class="p">):</span>
|
||
<span class="k">if</span> <span class="n">parser</span><span class="o">.</span><span class="n">values</span><span class="o">.</span><span class="n">b</span><span class="p">:</span>
|
||
<span class="k">raise</span> <span class="n">OptionValueError</span><span class="p">(</span><span class="s2">"can't use -a after -b"</span><span class="p">)</span>
|
||
<span class="n">parser</span><span class="o">.</span><span class="n">values</span><span class="o">.</span><span class="n">a</span> <span class="o">=</span> <span class="mi">1</span>
|
||
<span class="o">...</span>
|
||
<span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"-a"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"callback"</span><span class="p">,</span> <span class="n">callback</span><span class="o">=</span><span class="n">check_order</span><span class="p">)</span>
|
||
<span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"-b"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"store_true"</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s2">"b"</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
<section id="callback-example-3-check-option-order-generalized">
|
||
<span id="optparse-callback-example-3"></span><h3>回调示例 3：检查选项顺序（通用）<a class="headerlink" href="#callback-example-3-check-option-order-generalized" title="永久链接至标题">¶</a></h3>
|
||
<p>如果你希望为多个类似的选项重用此回调（设置旗标，而在看到 <code class="docutils literal notranslate"><span class="pre">-b</span></code> 出现时触发），则需要一些额外工作：它设置的错误消息和旗标必须进行通用化。</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">check_order</span><span class="p">(</span><span class="n">option</span><span class="p">,</span> <span class="n">opt_str</span><span class="p">,</span> <span class="n">value</span><span class="p">,</span> <span class="n">parser</span><span class="p">):</span>
|
||
<span class="k">if</span> <span class="n">parser</span><span class="o">.</span><span class="n">values</span><span class="o">.</span><span class="n">b</span><span class="p">:</span>
|
||
<span class="k">raise</span> <span class="n">OptionValueError</span><span class="p">(</span><span class="s2">"can't use </span><span class="si">%s</span><span class="s2"> after -b"</span> <span class="o">%</span> <span class="n">opt_str</span><span class="p">)</span>
|
||
<span class="nb">setattr</span><span class="p">(</span><span class="n">parser</span><span class="o">.</span><span class="n">values</span><span class="p">,</span> <span class="n">option</span><span class="o">.</span><span class="n">dest</span><span class="p">,</span> <span class="mi">1</span><span class="p">)</span>
|
||
<span class="o">...</span>
|
||
<span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"-a"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"callback"</span><span class="p">,</span> <span class="n">callback</span><span class="o">=</span><span class="n">check_order</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s1">'a'</span><span class="p">)</span>
|
||
<span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"-b"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"store_true"</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s2">"b"</span><span class="p">)</span>
|
||
<span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"-c"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"callback"</span><span class="p">,</span> <span class="n">callback</span><span class="o">=</span><span class="n">check_order</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s1">'c'</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
<section id="callback-example-4-check-arbitrary-condition">
|
||
<span id="optparse-callback-example-4"></span><h3>回调示例 4：检查任意条件<a class="headerlink" href="#callback-example-4-check-arbitrary-condition" title="永久链接至标题">¶</a></h3>
|
||
<p>当然，你可以设置任何条件 --- 并不限于检查已定义选项的值。 举例来说，如果你有一个不应当在满月时被调用的选项，你就可以这样做:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">check_moon</span><span class="p">(</span><span class="n">option</span><span class="p">,</span> <span class="n">opt_str</span><span class="p">,</span> <span class="n">value</span><span class="p">,</span> <span class="n">parser</span><span class="p">):</span>
|
||
<span class="k">if</span> <span class="n">is_moon_full</span><span class="p">():</span>
|
||
<span class="k">raise</span> <span class="n">OptionValueError</span><span class="p">(</span><span class="s2">"</span><span class="si">%s</span><span class="s2"> option invalid when moon is full"</span>
|
||
<span class="o">%</span> <span class="n">opt_str</span><span class="p">)</span>
|
||
<span class="nb">setattr</span><span class="p">(</span><span class="n">parser</span><span class="o">.</span><span class="n">values</span><span class="p">,</span> <span class="n">option</span><span class="o">.</span><span class="n">dest</span><span class="p">,</span> <span class="mi">1</span><span class="p">)</span>
|
||
<span class="o">...</span>
|
||
<span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"--foo"</span><span class="p">,</span>
|
||
<span class="n">action</span><span class="o">=</span><span class="s2">"callback"</span><span class="p">,</span> <span class="n">callback</span><span class="o">=</span><span class="n">check_moon</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s2">"foo"</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>（定义 <code class="docutils literal notranslate"><span class="pre">is_moon_full()</span></code> 的任务将作为留给读者的练习。）</p>
|
||
</section>
|
||
<section id="callback-example-5-fixed-arguments">
|
||
<span id="optparse-callback-example-5"></span><h3>回调示例 5：固定的参数<a class="headerlink" href="#callback-example-5-fixed-arguments" title="永久链接至标题">¶</a></h3>
|
||
<p>当你定义接受固定数量参数的 callback 选项时情况会变得更有趣一点。 指定一个 callback 选项接受参数的操作类似于定义一个 <code class="docutils literal notranslate"><span class="pre">"store"</span></code> 或 <code class="docutils literal notranslate"><span class="pre">"append"</span></code> 选项：如果你定义 <a class="reference internal" href="#optparse.Option.type" title="optparse.Option.type"><code class="xref py py-attr docutils literal notranslate"><span class="pre">type</span></code></a>，那么该选项将接受一个必须可被转换为相应类型的参数；如果你进一步定义 <a class="reference internal" href="#optparse.Option.nargs" title="optparse.Option.nargs"><code class="xref py py-attr docutils literal notranslate"><span class="pre">nargs</span></code></a>，那么该选项将接受 <a class="reference internal" href="#optparse.Option.nargs" title="optparse.Option.nargs"><code class="xref py py-attr docutils literal notranslate"><span class="pre">nargs</span></code></a> 个参数。</p>
|
||
<p>下面是一个模拟了标准 <code class="docutils literal notranslate"><span class="pre">"store"</span></code> 动作的示例:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">store_value</span><span class="p">(</span><span class="n">option</span><span class="p">,</span> <span class="n">opt_str</span><span class="p">,</span> <span class="n">value</span><span class="p">,</span> <span class="n">parser</span><span class="p">):</span>
|
||
<span class="nb">setattr</span><span class="p">(</span><span class="n">parser</span><span class="o">.</span><span class="n">values</span><span class="p">,</span> <span class="n">option</span><span class="o">.</span><span class="n">dest</span><span class="p">,</span> <span class="n">value</span><span class="p">)</span>
|
||
<span class="o">...</span>
|
||
<span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"--foo"</span><span class="p">,</span>
|
||
<span class="n">action</span><span class="o">=</span><span class="s2">"callback"</span><span class="p">,</span> <span class="n">callback</span><span class="o">=</span><span class="n">store_value</span><span class="p">,</span>
|
||
<span class="nb">type</span><span class="o">=</span><span class="s2">"int"</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="mi">3</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s2">"foo"</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>请注意 <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 将为你读取 3 个参数并将它们转换为整数；你所要做的只是保存它们。 （或任何其他操作；对于这个示例显然你不需要使用回调。）</p>
|
||
</section>
|
||
<section id="callback-example-6-variable-arguments">
|
||
<span id="optparse-callback-example-6"></span><h3>回调示例 6：可变的参数<a class="headerlink" href="#callback-example-6-variable-arguments" title="永久链接至标题">¶</a></h3>
|
||
<p>当你想要一个选项接受可变数数量的参数时情况会变得更麻烦一点。 对于这种场景，你必须编写一个回调，因为 <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 没有为它提供任何内置的相应功能。 而你必须处理 <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 通常会为你处理的传统 Unix 命令行的某些细节问题。 特别地，回调应当实现单个 <code class="docutils literal notranslate"><span class="pre">--</span></code> 和 <code class="docutils literal notranslate"><span class="pre">-</span></code> 参数的惯例规则:</p>
|
||
<ul class="simple">
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">--</span></code> 或 <code class="docutils literal notranslate"><span class="pre">-</span></code> 都可以作为选项参数</p></li>
|
||
<li><p>单个 <code class="docutils literal notranslate"><span class="pre">--</span></code> (如果不是某个选项的参数): 停止命令行处理并丢弃该 <code class="docutils literal notranslate"><span class="pre">--</span></code></p></li>
|
||
<li><p>单个 <code class="docutils literal notranslate"><span class="pre">-</span></code> (如果不是某个选项的参数): 停止命令行处理但保留 <code class="docutils literal notranslate"><span class="pre">-</span></code> (将其添加到 <code class="docutils literal notranslate"><span class="pre">parser.largs</span></code>)</p></li>
|
||
</ul>
|
||
<p>如果你想要一个选项接受可变数量的参数，那么有几个微妙、棘手的问题需要考虑到。 你选择的具体实现将基于你的应用程序对于各方面利弊的权衡（这就是为什么 <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 没有直接支持这一功能）。</p>
|
||
<p>无论如何，下面是一个对于接受可变参数的选项的回调的尝试:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">vararg_callback</span><span class="p">(</span><span class="n">option</span><span class="p">,</span> <span class="n">opt_str</span><span class="p">,</span> <span class="n">value</span><span class="p">,</span> <span class="n">parser</span><span class="p">):</span>
|
||
<span class="k">assert</span> <span class="n">value</span> <span class="ow">is</span> <span class="kc">None</span>
|
||
<span class="n">value</span> <span class="o">=</span> <span class="p">[]</span>
|
||
|
||
<span class="k">def</span> <span class="nf">floatable</span><span class="p">(</span><span class="nb">str</span><span class="p">):</span>
|
||
<span class="k">try</span><span class="p">:</span>
|
||
<span class="nb">float</span><span class="p">(</span><span class="nb">str</span><span class="p">)</span>
|
||
<span class="k">return</span> <span class="kc">True</span>
|
||
<span class="k">except</span> <span class="ne">ValueError</span><span class="p">:</span>
|
||
<span class="k">return</span> <span class="kc">False</span>
|
||
|
||
<span class="k">for</span> <span class="n">arg</span> <span class="ow">in</span> <span class="n">parser</span><span class="o">.</span><span class="n">rargs</span><span class="p">:</span>
|
||
<span class="c1"># stop on --foo like options</span>
|
||
<span class="k">if</span> <span class="n">arg</span><span class="p">[:</span><span class="mi">2</span><span class="p">]</span> <span class="o">==</span> <span class="s2">"--"</span> <span class="ow">and</span> <span class="nb">len</span><span class="p">(</span><span class="n">arg</span><span class="p">)</span> <span class="o">></span> <span class="mi">2</span><span class="p">:</span>
|
||
<span class="k">break</span>
|
||
<span class="c1"># stop on -a, but not on -3 or -3.0</span>
|
||
<span class="k">if</span> <span class="n">arg</span><span class="p">[:</span><span class="mi">1</span><span class="p">]</span> <span class="o">==</span> <span class="s2">"-"</span> <span class="ow">and</span> <span class="nb">len</span><span class="p">(</span><span class="n">arg</span><span class="p">)</span> <span class="o">></span> <span class="mi">1</span> <span class="ow">and</span> <span class="ow">not</span> <span class="n">floatable</span><span class="p">(</span><span class="n">arg</span><span class="p">):</span>
|
||
<span class="k">break</span>
|
||
<span class="n">value</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">arg</span><span class="p">)</span>
|
||
|
||
<span class="k">del</span> <span class="n">parser</span><span class="o">.</span><span class="n">rargs</span><span class="p">[:</span><span class="nb">len</span><span class="p">(</span><span class="n">value</span><span class="p">)]</span>
|
||
<span class="nb">setattr</span><span class="p">(</span><span class="n">parser</span><span class="o">.</span><span class="n">values</span><span class="p">,</span> <span class="n">option</span><span class="o">.</span><span class="n">dest</span><span class="p">,</span> <span class="n">value</span><span class="p">)</span>
|
||
|
||
<span class="o">...</span>
|
||
<span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"-c"</span><span class="p">,</span> <span class="s2">"--callback"</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s2">"vararg_attr"</span><span class="p">,</span>
|
||
<span class="n">action</span><span class="o">=</span><span class="s2">"callback"</span><span class="p">,</span> <span class="n">callback</span><span class="o">=</span><span class="n">vararg_callback</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
</section>
|
||
<section id="extending-optparse">
|
||
<span id="optparse-extending-optparse"></span><h2>扩展 <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a><a class="headerlink" href="#extending-optparse" title="永久链接至标题">¶</a></h2>
|
||
<p>由于控制 <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 如何读取命令行选项的两个主要因子是每个选项的动作和类型，所以扩展最可能的方向就是添加新的动作和新的类型。</p>
|
||
<section id="adding-new-types">
|
||
<span id="optparse-adding-new-types"></span><h3>添加新的类型<a class="headerlink" href="#adding-new-types" title="永久链接至标题">¶</a></h3>
|
||
<p>要添加新的类型，你必须自定义 <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 的 <code class="xref py py-class docutils literal notranslate"><span class="pre">Option</span></code> 类的子类。 这个类包含几个用来定义 <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 的类型的属性: <a class="reference internal" href="#optparse.Option.TYPES" title="optparse.Option.TYPES"><code class="xref py py-attr docutils literal notranslate"><span class="pre">TYPES</span></code></a> 和 <a class="reference internal" href="#optparse.Option.TYPE_CHECKER" title="optparse.Option.TYPE_CHECKER"><code class="xref py py-attr docutils literal notranslate"><span class="pre">TYPE_CHECKER</span></code></a>。</p>
|
||
<dl class="attribute">
|
||
<dt id="optparse.Option.TYPES">
|
||
<code class="sig-prename descclassname">Option.</code><code class="sig-name descname">TYPES</code><a class="headerlink" href="#optparse.Option.TYPES" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>一个由类型名称组成的元组；在你的子类中，简单地定义一个在标准元组基础上构建的新元组 <a class="reference internal" href="#optparse.Option.TYPES" title="optparse.Option.TYPES"><code class="xref py py-attr docutils literal notranslate"><span class="pre">TYPES</span></code></a>。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="optparse.Option.TYPE_CHECKER">
|
||
<code class="sig-prename descclassname">Option.</code><code class="sig-name descname">TYPE_CHECKER</code><a class="headerlink" href="#optparse.Option.TYPE_CHECKER" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>一个将类型名称映射到类型检查函数的字典。 类型检查函数具有如下签名:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">check_mytype</span><span class="p">(</span><span class="n">option</span><span class="p">,</span> <span class="n">opt</span><span class="p">,</span> <span class="n">value</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>其中 <code class="docutils literal notranslate"><span class="pre">option</span></code> 是一个 <code class="xref py py-class docutils literal notranslate"><span class="pre">Option</span></code> 实例，<code class="docutils literal notranslate"><span class="pre">opt</span></code> 是一个选项字符串 (例如 <code class="docutils literal notranslate"><span class="pre">-f</span></code>)，而 <code class="docutils literal notranslate"><span class="pre">value</span></code> 是来自命令行的必须被检查并转换为你想要的类型的字符串。 <code class="docutils literal notranslate"><span class="pre">check_mytype()</span></code> 应当返回假设的类型 <code class="docutils literal notranslate"><span class="pre">mytype</span></code> 的对象。 类型检查函数所返回的值将最终出现在 <code class="xref py py-meth docutils literal notranslate"><span class="pre">OptionParser.parse_args()</span></code> 所返回的 OptionValues 实例中，或是作为 <code class="docutils literal notranslate"><span class="pre">value</span></code> 形参传给一个回调。</p>
|
||
<p>如果你的类型检查函数遇到任何问题则应当引发 <code class="xref py py-exc docutils literal notranslate"><span class="pre">OptionValueError</span></code>。 <code class="xref py py-exc docutils literal notranslate"><span class="pre">OptionValueError</span></code> 接受一个字符串参数，该参数将被原样传递给 <a class="reference internal" href="#optparse.OptionParser" title="optparse.OptionParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">OptionParser</span></code></a> 的 <code class="xref py py-meth docutils literal notranslate"><span class="pre">error()</span></code> 方法，该方法将随后附加程序名称和字符串 <code class="docutils literal notranslate"><span class="pre">"error:"</span></code> 并在终结进程之前将所有信息打印到 stderr。</p>
|
||
</dd></dl>
|
||
|
||
<p>下面这个很傻的例子演示了如何添加一个 <code class="docutils literal notranslate"><span class="pre">"complex"</span></code> 选项类型以便在命令行中解析 Python 风格的复数。 （现在这个例子比以前更傻了，因为 <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 1.3 增加了对复数的内置支持，但是不必管它了。）</p>
|
||
<p>首先，必要的导入操作:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">copy</span> <span class="kn">import</span> <span class="n">copy</span>
|
||
<span class="kn">from</span> <span class="nn">optparse</span> <span class="kn">import</span> <span class="n">Option</span><span class="p">,</span> <span class="n">OptionValueError</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>你必须先定义自己的类型检查器，因为以后它会被引用（在你的 Option 子类的 <a class="reference internal" href="#optparse.Option.TYPE_CHECKER" title="optparse.Option.TYPE_CHECKER"><code class="xref py py-attr docutils literal notranslate"><span class="pre">TYPE_CHECKER</span></code></a> 类属性中）:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">check_complex</span><span class="p">(</span><span class="n">option</span><span class="p">,</span> <span class="n">opt</span><span class="p">,</span> <span class="n">value</span><span class="p">):</span>
|
||
<span class="k">try</span><span class="p">:</span>
|
||
<span class="k">return</span> <span class="nb">complex</span><span class="p">(</span><span class="n">value</span><span class="p">)</span>
|
||
<span class="k">except</span> <span class="ne">ValueError</span><span class="p">:</span>
|
||
<span class="k">raise</span> <span class="n">OptionValueError</span><span class="p">(</span>
|
||
<span class="s2">"option </span><span class="si">%s</span><span class="s2">: invalid complex value: </span><span class="si">%r</span><span class="s2">"</span> <span class="o">%</span> <span class="p">(</span><span class="n">opt</span><span class="p">,</span> <span class="n">value</span><span class="p">))</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>最后，是 Option 子类:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">MyOption</span> <span class="p">(</span><span class="n">Option</span><span class="p">):</span>
|
||
<span class="n">TYPES</span> <span class="o">=</span> <span class="n">Option</span><span class="o">.</span><span class="n">TYPES</span> <span class="o">+</span> <span class="p">(</span><span class="s2">"complex"</span><span class="p">,)</span>
|
||
<span class="n">TYPE_CHECKER</span> <span class="o">=</span> <span class="n">copy</span><span class="p">(</span><span class="n">Option</span><span class="o">.</span><span class="n">TYPE_CHECKER</span><span class="p">)</span>
|
||
<span class="n">TYPE_CHECKER</span><span class="p">[</span><span class="s2">"complex"</span><span class="p">]</span> <span class="o">=</span> <span class="n">check_complex</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>（如果我们不对 <a class="reference internal" href="#optparse.Option.TYPE_CHECKER" title="optparse.Option.TYPE_CHECKER"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Option.TYPE_CHECKER</span></code></a> 执行 <a class="reference internal" href="copy.html#module-copy" title="copy: Shallow and deep copy operations."><code class="xref py py-func docutils literal notranslate"><span class="pre">copy()</span></code></a>，我们就将修改 <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 的 Option 类的 <a class="reference internal" href="#optparse.Option.TYPE_CHECKER" title="optparse.Option.TYPE_CHECKER"><code class="xref py py-attr docutils literal notranslate"><span class="pre">TYPE_CHECKER</span></code></a> 属性。 Python 就是这样，除了礼貌和常识以外没有任何东西能阻止你这样做。）</p>
|
||
<p>就是这样！ 现在你可以编写一个脚本以与其他基于 <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 的脚本相同的方式使用新的选项类型，除了你必须指示你的 OptionParser 使用 MyOption 而不是 Option:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">parser</span> <span class="o">=</span> <span class="n">OptionParser</span><span class="p">(</span><span class="n">option_class</span><span class="o">=</span><span class="n">MyOption</span><span class="p">)</span>
|
||
<span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s2">"-c"</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="s2">"complex"</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>作为替代选择，你可以构建你自己的选项列表并将它传给 OptionParser；如果你不是以上述方式使用 <code class="xref py py-meth docutils literal notranslate"><span class="pre">add_option()</span></code>，则你不需要告诉 OptionParser 使用哪个选项类:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">option_list</span> <span class="o">=</span> <span class="p">[</span><span class="n">MyOption</span><span class="p">(</span><span class="s2">"-c"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s2">"store"</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="s2">"complex"</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s2">"c"</span><span class="p">)]</span>
|
||
<span class="n">parser</span> <span class="o">=</span> <span class="n">OptionParser</span><span class="p">(</span><span class="n">option_list</span><span class="o">=</span><span class="n">option_list</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
<section id="adding-new-actions">
|
||
<span id="optparse-adding-new-actions"></span><h3>添加新的动作<a class="headerlink" href="#adding-new-actions" title="永久链接至标题">¶</a></h3>
|
||
<p>添加新的动作有一点复杂，因为你必须理解 <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 对于动作有几种分类:</p>
|
||
<dl class="simple">
|
||
<dt>"store" 类动作</dt><dd><p>会使得 <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 将某个值保存到当前 OptionValues 实例的特定属性中的动作；这些选项要求向 Option 构造器提供一个 <a class="reference internal" href="#optparse.Option.dest" title="optparse.Option.dest"><code class="xref py py-attr docutils literal notranslate"><span class="pre">dest</span></code></a> 属性。attribute to be supplied to the constructor.</p>
|
||
</dd>
|
||
<dt>"typed" 类动作</dt><dd><p>从命令行接受某个值并预期它是一个特定类型；或者更准确地说，是可被转换为一个特定类型的字符串的动作。 这些选项要求向 Option 构造器提供一个 <a class="reference internal" href="#optparse.Option.type" title="optparse.Option.type"><code class="xref py py-attr docutils literal notranslate"><span class="pre">type</span></code></a> 属性。attribute to the constructor.</p>
|
||
</dd>
|
||
</dl>
|
||
<p>这些是相互重叠的集合：默认的 "store" 类动作有 <code class="docutils literal notranslate"><span class="pre">"store"</span></code>, <code class="docutils literal notranslate"><span class="pre">"store_const"</span></code>, <code class="docutils literal notranslate"><span class="pre">"append"</span></code> 和 <code class="docutils literal notranslate"><span class="pre">"count"</span></code>，而默认的 "typed" 类动作有 <code class="docutils literal notranslate"><span class="pre">"store"</span></code>, <code class="docutils literal notranslate"><span class="pre">"append"</span></code> 和 <code class="docutils literal notranslate"><span class="pre">"callback"</span></code>。</p>
|
||
<p>当你添加一个动作时，你需要将它列在 Option 的以下类属性的至少一个当中以对它进行分类（全部为字符串列表）:</p>
|
||
<dl class="attribute">
|
||
<dt id="optparse.Option.ACTIONS">
|
||
<code class="sig-prename descclassname">Option.</code><code class="sig-name descname">ACTIONS</code><a class="headerlink" href="#optparse.Option.ACTIONS" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>所有动作必须在 ACTIONS 中列出。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="optparse.Option.STORE_ACTIONS">
|
||
<code class="sig-prename descclassname">Option.</code><code class="sig-name descname">STORE_ACTIONS</code><a class="headerlink" href="#optparse.Option.STORE_ACTIONS" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>"store" 类动作要额外地在此列出。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="optparse.Option.TYPED_ACTIONS">
|
||
<code class="sig-prename descclassname">Option.</code><code class="sig-name descname">TYPED_ACTIONS</code><a class="headerlink" href="#optparse.Option.TYPED_ACTIONS" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>"typed" 类动作要额外地在此列出。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="optparse.Option.ALWAYS_TYPED_ACTIONS">
|
||
<code class="sig-prename descclassname">Option.</code><code class="sig-name descname">ALWAYS_TYPED_ACTIONS</code><a class="headerlink" href="#optparse.Option.ALWAYS_TYPED_ACTIONS" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>总是会接受一个类型的动作（即其选项总是会接受一个值）要额外地在此列出。 它带来的唯一影响是 <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 会将默认类型 <code class="docutils literal notranslate"><span class="pre">"string"</span></code> 赋值给动作在 <a class="reference internal" href="#optparse.Option.ALWAYS_TYPED_ACTIONS" title="optparse.Option.ALWAYS_TYPED_ACTIONS"><code class="xref py py-attr docutils literal notranslate"><span class="pre">ALWAYS_TYPED_ACTIONS</span></code></a> 中列出而未显式指定类型的选项。</p>
|
||
</dd></dl>
|
||
|
||
<p>为了真正实现你的新动作，你必须重写 Option 的 <code class="xref py py-meth docutils literal notranslate"><span class="pre">take_action()</span></code> 方法并添加一个识别你的动作的分支。</p>
|
||
<p>例如，让我们添加一个 <code class="docutils literal notranslate"><span class="pre">"extend"</span></code> 动作。 它类似于标准的 <code class="docutils literal notranslate"><span class="pre">"append"</span></code> 动作，但 <code class="docutils literal notranslate"><span class="pre">"extend"</span></code> 不是从命令行接受单个值并将其添加到现有列表，而是接受形式为以单个逗号分隔的多个值的字符串，并用这些值来扩展现有列表。 也就是说，如果 <code class="docutils literal notranslate"><span class="pre">--names</span></code> 是一个类型为 <code class="docutils literal notranslate"><span class="pre">"string"</span></code> 的 <code class="docutils literal notranslate"><span class="pre">"extend"</span></code> 选项，则命令行</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="o">--</span><span class="n">names</span><span class="o">=</span><span class="n">foo</span><span class="p">,</span><span class="n">bar</span> <span class="o">--</span><span class="n">names</span> <span class="n">blah</span> <span class="o">--</span><span class="n">names</span> <span class="n">ding</span><span class="p">,</span><span class="n">dong</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>将得到一个列表</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="p">[</span><span class="s2">"foo"</span><span class="p">,</span> <span class="s2">"bar"</span><span class="p">,</span> <span class="s2">"blah"</span><span class="p">,</span> <span class="s2">"ding"</span><span class="p">,</span> <span class="s2">"dong"</span><span class="p">]</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>我们再定义一个 Option 的子类:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">MyOption</span><span class="p">(</span><span class="n">Option</span><span class="p">):</span>
|
||
|
||
<span class="n">ACTIONS</span> <span class="o">=</span> <span class="n">Option</span><span class="o">.</span><span class="n">ACTIONS</span> <span class="o">+</span> <span class="p">(</span><span class="s2">"extend"</span><span class="p">,)</span>
|
||
<span class="n">STORE_ACTIONS</span> <span class="o">=</span> <span class="n">Option</span><span class="o">.</span><span class="n">STORE_ACTIONS</span> <span class="o">+</span> <span class="p">(</span><span class="s2">"extend"</span><span class="p">,)</span>
|
||
<span class="n">TYPED_ACTIONS</span> <span class="o">=</span> <span class="n">Option</span><span class="o">.</span><span class="n">TYPED_ACTIONS</span> <span class="o">+</span> <span class="p">(</span><span class="s2">"extend"</span><span class="p">,)</span>
|
||
<span class="n">ALWAYS_TYPED_ACTIONS</span> <span class="o">=</span> <span class="n">Option</span><span class="o">.</span><span class="n">ALWAYS_TYPED_ACTIONS</span> <span class="o">+</span> <span class="p">(</span><span class="s2">"extend"</span><span class="p">,)</span>
|
||
|
||
<span class="k">def</span> <span class="nf">take_action</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">action</span><span class="p">,</span> <span class="n">dest</span><span class="p">,</span> <span class="n">opt</span><span class="p">,</span> <span class="n">value</span><span class="p">,</span> <span class="n">values</span><span class="p">,</span> <span class="n">parser</span><span class="p">):</span>
|
||
<span class="k">if</span> <span class="n">action</span> <span class="o">==</span> <span class="s2">"extend"</span><span class="p">:</span>
|
||
<span class="n">lvalue</span> <span class="o">=</span> <span class="n">value</span><span class="o">.</span><span class="n">split</span><span class="p">(</span><span class="s2">","</span><span class="p">)</span>
|
||
<span class="n">values</span><span class="o">.</span><span class="n">ensure_value</span><span class="p">(</span><span class="n">dest</span><span class="p">,</span> <span class="p">[])</span><span class="o">.</span><span class="n">extend</span><span class="p">(</span><span class="n">lvalue</span><span class="p">)</span>
|
||
<span class="k">else</span><span class="p">:</span>
|
||
<span class="n">Option</span><span class="o">.</span><span class="n">take_action</span><span class="p">(</span>
|
||
<span class="bp">self</span><span class="p">,</span> <span class="n">action</span><span class="p">,</span> <span class="n">dest</span><span class="p">,</span> <span class="n">opt</span><span class="p">,</span> <span class="n">value</span><span class="p">,</span> <span class="n">values</span><span class="p">,</span> <span class="n">parser</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>应注意的特性:</p>
|
||
<ul>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">"extend"</span></code> 既预期在命令行接受一个值又会将该值保存到某处，因此它同时被归类于 <a class="reference internal" href="#optparse.Option.STORE_ACTIONS" title="optparse.Option.STORE_ACTIONS"><code class="xref py py-attr docutils literal notranslate"><span class="pre">STORE_ACTIONS</span></code></a> 和 <a class="reference internal" href="#optparse.Option.TYPED_ACTIONS" title="optparse.Option.TYPED_ACTIONS"><code class="xref py py-attr docutils literal notranslate"><span class="pre">TYPED_ACTIONS</span></code></a>。</p></li>
|
||
<li><p>为确保 <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 将 <code class="docutils literal notranslate"><span class="pre">"string"</span></code> 的默认类型赋值给 <code class="docutils literal notranslate"><span class="pre">"extend"</span></code> 动作，我们同时将 <code class="docutils literal notranslate"><span class="pre">"extend"</span></code> 动作归类于 <a class="reference internal" href="#optparse.Option.ALWAYS_TYPED_ACTIONS" title="optparse.Option.ALWAYS_TYPED_ACTIONS"><code class="xref py py-attr docutils literal notranslate"><span class="pre">ALWAYS_TYPED_ACTIONS</span></code></a>。</p></li>
|
||
<li><p><code class="xref py py-meth docutils literal notranslate"><span class="pre">MyOption.take_action()</span></code> 只实现了这一个新动作，并将控制权回传给 <code class="xref py py-meth docutils literal notranslate"><span class="pre">Option.take_action()</span></code> 以执行标准的 <a class="reference internal" href="#module-optparse" title="optparse: Command-line option parsing library. (已移除)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a> 动作。</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">values</span></code> 是 optparse_parser.Values 类的一个实例，该类提供了非常有用的 <code class="xref py py-meth docutils literal notranslate"><span class="pre">ensure_value()</span></code> 方法。 <code class="xref py py-meth docutils literal notranslate"><span class="pre">ensure_value()</span></code> 实际就是一个带有安全阀的 <a class="reference internal" href="functions.html#getattr" title="getattr"><code class="xref py py-func docutils literal notranslate"><span class="pre">getattr()</span></code></a>；它的调用形式为</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">values</span><span class="o">.</span><span class="n">ensure_value</span><span class="p">(</span><span class="n">attr</span><span class="p">,</span> <span class="n">value</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>如果 <code class="docutils literal notranslate"><span class="pre">values</span></code> 的 <code class="docutils literal notranslate"><span class="pre">attr</span></code> 属性不存在或为 <code class="docutils literal notranslate"><span class="pre">None</span></code>，则 ensure_value() 会先将其设为 <code class="docutils literal notranslate"><span class="pre">value</span></code>，然后返回该值。 这非常适用于 <code class="docutils literal notranslate"><span class="pre">"extend"</span></code>, <code class="docutils literal notranslate"><span class="pre">"append"</span></code> 和 <code class="docutils literal notranslate"><span class="pre">"count"</span></code> 等动作，它们会将数据累积在一个变量中并预期该变量属于特定的类型（前两项是一个列表，后一项是一个整数）。 使用 <code class="xref py py-meth docutils literal notranslate"><span class="pre">ensure_value()</span></code> 意味着使用你的动作的脚本无需关心为相应的选项目标设置默认值；可以简单地保持默认的 <code class="docutils literal notranslate"><span class="pre">None</span></code> 则 <code class="xref py py-meth docutils literal notranslate"><span class="pre">ensure_value()</span></code> 将在必要时负责为其设置适当的值。</p>
|
||
</li>
|
||
</ul>
|
||
</section>
|
||
</section>
|
||
</section>
|
||
|
||
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
|
||
<div class="sphinxsidebarwrapper">
|
||
<h3><a href="../contents.html">目录</a></h3>
|
||
<ul>
|
||
<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code> --- 命令行选项的解析器</a><ul>
|
||
<li><a class="reference internal" href="#background">背景</a><ul>
|
||
<li><a class="reference internal" href="#terminology">术语</a></li>
|
||
<li><a class="reference internal" href="#what-are-options-for">选项的作用是什么？</a></li>
|
||
<li><a class="reference internal" href="#what-are-positional-arguments-for">位置参数有什么用？</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#tutorial">教程</a><ul>
|
||
<li><a class="reference internal" href="#understanding-option-actions">理解选项动作</a></li>
|
||
<li><a class="reference internal" href="#the-store-action">store 动作</a></li>
|
||
<li><a class="reference internal" href="#handling-boolean-flag-options">处理布尔值（旗标）选项</a></li>
|
||
<li><a class="reference internal" href="#other-actions">其他动作</a></li>
|
||
<li><a class="reference internal" href="#default-values">默认值</a></li>
|
||
<li><a class="reference internal" href="#generating-help">生成帮助</a><ul>
|
||
<li><a class="reference internal" href="#grouping-options">选项分组</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#printing-a-version-string">打印版本字符串</a></li>
|
||
<li><a class="reference internal" href="#how-optparse-handles-errors"><code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code> 如何处理错误handles errors</a></li>
|
||
<li><a class="reference internal" href="#putting-it-all-together">合并所有代码</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#reference-guide">参考指南</a><ul>
|
||
<li><a class="reference internal" href="#creating-the-parser">创建解析器</a></li>
|
||
<li><a class="reference internal" href="#populating-the-parser">填充解析器</a></li>
|
||
<li><a class="reference internal" href="#defining-options">定义选项</a></li>
|
||
<li><a class="reference internal" href="#option-attributes">选项属性</a></li>
|
||
<li><a class="reference internal" href="#standard-option-actions">标准选项动作</a></li>
|
||
<li><a class="reference internal" href="#standard-option-types">标准选项类型</a></li>
|
||
<li><a class="reference internal" href="#parsing-arguments">解析参数</a></li>
|
||
<li><a class="reference internal" href="#querying-and-manipulating-your-option-parser">查询和操纵你的选项解析器</a></li>
|
||
<li><a class="reference internal" href="#conflicts-between-options">选项之间的冲突</a></li>
|
||
<li><a class="reference internal" href="#cleanup">清理</a></li>
|
||
<li><a class="reference internal" href="#other-methods">其他方法</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#option-callbacks">选项回调</a><ul>
|
||
<li><a class="reference internal" href="#defining-a-callback-option">定义回调选项</a></li>
|
||
<li><a class="reference internal" href="#how-callbacks-are-called">回调应当如何调用</a></li>
|
||
<li><a class="reference internal" href="#raising-errors-in-a-callback">在回调中引发错误</a></li>
|
||
<li><a class="reference internal" href="#callback-example-1-trivial-callback">回调示例 1：最简回调</a></li>
|
||
<li><a class="reference internal" href="#callback-example-2-check-option-order">回调示例 2：检查选项顺序</a></li>
|
||
<li><a class="reference internal" href="#callback-example-3-check-option-order-generalized">回调示例 3：检查选项顺序（通用）</a></li>
|
||
<li><a class="reference internal" href="#callback-example-4-check-arbitrary-condition">回调示例 4：检查任意条件</a></li>
|
||
<li><a class="reference internal" href="#callback-example-5-fixed-arguments">回调示例 5：固定的参数</a></li>
|
||
<li><a class="reference internal" href="#callback-example-6-variable-arguments">回调示例 6：可变的参数</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#extending-optparse">扩展 <code class="xref py py-mod docutils literal notranslate"><span class="pre">optparse</span></code></a><ul>
|
||
<li><a class="reference internal" href="#adding-new-types">添加新的类型</a></li>
|
||
<li><a class="reference internal" href="#adding-new-actions">添加新的动作</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
<h4>上一个主题</h4>
|
||
<p class="topless"><a href="superseded.html"
|
||
title="上一章">被取代的模块</a></p>
|
||
<h4>下一个主题</h4>
|
||
<p class="topless"><a href="imp.html"
|
||
title="下一章"><code class="xref py py-mod docutils literal notranslate"><span class="pre">imp</span></code> --- 访问 <span class="xref std std-ref">import</span> 内部对象</a></p>
|
||
<div role="note" aria-label="source link">
|
||
<h3>本页</h3>
|
||
<ul class="this-page-menu">
|
||
<li><a href="../bugs.html">报告 Bug</a></li>
|
||
<li>
|
||
<a href="https://github.com/python/cpython/blob/3.8/Doc/library/optparse.rst"
|
||
rel="nofollow">显示源代码
|
||
</a>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="clearer"></div>
|
||
</div>
|
||
<div class="related" role="navigation" aria-label="related navigation">
|
||
<h3>导航</h3>
|
||
<ul>
|
||
<li class="right" style="margin-right: 10px">
|
||
<a href="../genindex.html" title="总目录"
|
||
>索引</a></li>
|
||
<li class="right" >
|
||
<a href="../py-modindex.html" title="Python 模块索引"
|
||
>模块</a> |</li>
|
||
<li class="right" >
|
||
<a href="imp.html" title="imp --- 访问 import 内部对象"
|
||
>下一页</a> |</li>
|
||
<li class="right" >
|
||
<a href="superseded.html" title="被取代的模块"
|
||
>上一页</a> |</li>
|
||
|
||
<li><img src="../_static/py.svg" alt="python logo" style="vertical-align: middle; margin-top: -1px"/></li>
|
||
<li><a href="https://www.python.org/">Python</a> »</li>
|
||
<li class="switchers">
|
||
<div class="language_switcher_placeholder"></div>
|
||
<div class="version_switcher_placeholder"></div>
|
||
</li>
|
||
<li>
|
||
|
||
</li>
|
||
<li id="cpython-language-and-version">
|
||
<a href="../index.html">3.8.20 Documentation</a> »
|
||
</li>
|
||
|
||
<li class="nav-item nav-item-1"><a href="index.html" >Python 标准库</a> »</li>
|
||
<li class="nav-item nav-item-2"><a href="superseded.html" >被取代的模块</a> »</li>
|
||
<li class="right">
|
||
|
||
|
||
<div class="inline-search" role="search">
|
||
<form class="inline-search" action="../search.html" method="get">
|
||
<input placeholder="快速搜索" aria-label="快速搜索" type="text" name="q" />
|
||
<input type="submit" value="转向" />
|
||
<input type="hidden" name="check_keywords" value="yes" />
|
||
<input type="hidden" name="area" value="default" />
|
||
</form>
|
||
</div>
|
||
|
|
||
</li>
|
||
|
||
</ul>
|
||
</div>
|
||
<div class="footer">
|
||
© <a href="../copyright.html">版权所有</a> 2001-2024, Python Software Foundation.
|
||
<br />
|
||
This page is licensed under the Python Software Foundation License Version 2.
|
||
<br />
|
||
Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License.
|
||
<br />
|
||
|
||
<br />
|
||
|
||
The Python Software Foundation is a non-profit corporation.
|
||
<a href="https://www.python.org/psf/donations/">Please donate.</a>
|
||
<br />
|
||
<br />
|
||
|
||
最后更新于 12月 09, 2024.
|
||
<a href="https://docs.python.org/3/bugs.html">Found a bug</a>?
|
||
<br />
|
||
|
||
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 2.4.4.
|
||
</div>
|
||
|
||
</body>
|
||
</html> |