开始 0.9

概述

为 懒惰 人类提供的命令行程序。

• 装饰一个函数作为程序的起始点。

• 基于函数签名生成命令行解析器。

• 在系统环境中搜索选项默认值。

为什么选择Begins？

我经常用Python编写很多小型程序。这些程序通常只接受少量简单的命令行参数。在每一个小程序中都编写命令行解析代码不仅打断了我的思路，还极大地增加了我需要编写的代码量。

Begins的实现是为了从这些Python程序中移除样板代码。它并不打算取代大型应用程序所需的丰富命令行处理。

要求

对于早于Python 3.3的Python版本，需要从Python包索引中的funcsigs包。

对于Python 2.6版本，还需要从Python包索引中的argparse包。

这两个依赖项都已列在包配置中。如果您使用Pip安装begins，则所需的依赖项将自动安装。

安装

开始安装 可从 Python 包索引 下载。要使用 Pip 安装

$ pip install begins

或者，可以直接从 Github 安装最新开发版本。

$ pip install git+https://github.com/aliles/begins.git

请注意，开始安装 目前仍处于 alpha 阶段，因此 API 或行为可能会更改。

设置程序的起始点

begin.start() 函数可以用作函数调用或装饰器。如果作为函数调用，当从 __main__ 模块调用时返回 True。为此，它会检查调用者的堆栈帧，检查全局的 __name__。

这允许以下 Python 模式

>>> if __name__ == '__main__':
...     pass

被替换为

>>> import begin
>>> if begin.start():
...    pass

如果用作装饰器来注释一个函数，当通过检查当前堆栈帧确定定义在 __main__ 模块中时，将调用该函数。任何跟随装饰器函数的定义都不会在函数调用完成后创建。

begin.start() 作为装饰器的用法如下

>>> import begin
>>> @begin.start
... def run():
...     pass

通过将函数执行推迟到模块其余部分加载完毕之后，确保主函数不会因为依赖于稍后代码中定义的内容而失败。

解析命令行选项

如果 begin.start() 装饰的函数接受参数，begin.start() 将处理命令以传递作为那些参数的选项

>>> import begin
>>> @begin.start
... def run(name='Arther', quest='Holy Grail', colour='blue', *knights):
...     "tis but a scratch!"

上述装饰函数将生成以下命令行帮助

usage: example.py [-h] [-n NAME] [-q QUEST] [-c COLOUR]
                  [knights [knights ...]]

tis but a scratch!

positional arguments:
  knights

optional arguments:
  -h, --help            show this help message and exit
  -n NAME, --name NAME  (default: Arther)
  -q QUEST, --quest QUEST
                        (default: Holy Grail)
  -c COLOUR, --colour COLOUR
                        (default: blue)

在 Python3 中，任何 函数注释 都成为命令行选项的帮助。例如

>>> import begin
>>> @begin.start                                         # doctest: +SKIP
... def run(name: 'What, is your name?',
...         quest: 'What, is your quest?',
...         colour: 'What, is your favourite colour?'):
...     pass

将生成如下命令帮助

usage: holygrail_py3.py [-h] -n NAME -q QUEST -c COLOUR

optional arguments:
  -h, --help            show this help message and exit
  -n NAME, --name NAME  What, is your name?
  -q QUEST, --quest QUEST
                        What, is your quest?
  -c COLOUR, --colour COLOUR
                        What, is your favourite colour?

命令行解析支持

• 位置参数

• 关键字参数

• 默认值

• 可变长度参数

• 注释

命令行解析不支持可变长关键字参数，通常写作 **kwargs。如果装饰函数使用可变长关键字参数，将引发异常。

如果参数没有默认值，则命令行未传递值会导致程序运行时打印错误并退出。

对于具有大量选项的程序，可能更喜欢仅使用长选项。要抑制短选项，请将 begin.start 装饰器的 short_args 关键字参数传递为 False

>>> import begin
>>> @begin.start(short_args=False)
... def run(name='Arther', quest='Holy Grail', colour='blue', *knights):
...     "tis but a scratch!"

该程序不接受 -n、-q 或 -c 作为选项名称。

类似地，大量命令行选项可能按字母顺序显示更好。可以通过将 lexical_order 传递为 True 来实现这一点

>>> import begin
>>> @begin.start(lexical_order=True)
... def main(charlie=3, alpha=1, beta=2):
...     pass

该程序将按 alpha、beta、charlie 的顺序列出命令行选项，而不是按函数接受的顺序。

进一步阅读

本指南的其余部分、教程和 API 文档都是官方 开始安装 文档的一部分，这些文档托管在 Read The Docs 上。

问题

任何错误报告或功能请求都可以通过 GitHub 的 问题系统 进行。