16.4 自定义帮助文档的输出

下面是argparse.print _ help()直接打印的一些典型输出。

usage: p3_c16.py [-v] [—debug] [—dealerhit {Hit17,Stand17}]
　　　　　　　 　　　[—resplit {ReSplit,NoReSplit,NoReSplitAces}]
[—decks DECKS]
　　　　　　　　　[—limit LIMIT] [—payout PAYOUT]
　　　　　　　　　[-p {SomeStrategy,AnotherStrategy}]
　　　　　　　　　[-b {Flat,Martingale,OneThreeTwoSix}] [-r ROUNDS] [-s
STAKE]
　　　　　　　　　[—samples SAMPLES] [-V] [-?]
　　　　　　　　　output

Simulate Blackjack

positional arguments:
　　output

optional arguments:
　　-v, —verbose
　　—debug
　　—dealerhit {Hit17,Stand17}
　　—resplit {ReSplit,NoReSplit,NoReSplitAces}
　　—decks DECKS
　　—limit LIMIT
　　—payout PAYOUT
　　-p {SomeStrategy,AnotherStrategy}, —playerstrategy
{SomeStrategy,AnotherStrategy}
　　-b {Flat,Martingale,OneThreeTwoSix}, —bet {Flat,Martingale,OneThre
eTwoSix}
　　-r ROUNDS, —rounds ROUNDS
　　-s STAKE, —stake STAKE
　　—samples SAMPLES
　　-V, —version 　　　　　 show program's version number and exit
　　-?, —help

默认的帮助文本是基于解析器定义的4个方面创建的。

• usage行是选项的摘要。我们可以用自己的usage文本替换默认的，这样就可以省略一些不常用的细节。
• 接下来是描述信息。在默认情况下，我们提供的文本会被适当清理一下。在本例中，我们提供了只有两个单词的描述，所以没有明显的清理操作。
• 然后，显示参数。首先是位置参数，然后是选项，和它们定义的顺序一致。
• 在这之后，会显示一段可选的结束文本。

在一些情况下，这种简短的提示就足够了。但是，在其他情况下，我们可能需要提供更多细节。关于包含更多细节的帮助文本，我们有3层的支持。

• 在参数定义中添加help=：当自定义帮助文本的细节时，需要从这里开始。
• 用某个其他的帮助文本格式化类创建更美观的输出：这是在创建ArgumentParser时，通过formatter _ class=参数完成的。注意，ArgumentDefaultsHelp Formatter需要为参数定义提供help=，它会将所提供的文本作为默认值添加到帮助文本中。
• 扩展ArgumentParser类并且覆盖print_usage()和print_help()方法：总是可以创建一个新的帮助文本格式化器。如果必须选择这么复杂的选项，那么可能已经走的远了。

我们的目标是提高可用性。即使应用程序能够正常工作，也可以通过提供命令行的支持让程序更容易被使用从而建立用户的信任。