begins 0.9

概述

用于lazy人类的命令行程序。

• 将函数修饰为程序的起点。
• 基于函数签名生成命令行解析器。
• 在系统环境中搜索选项默认值。

为什么开始？

我写了很多 Python中的小程序。 这些程序经常 接受少量 简单的命令行参数。 不得不写 命令行分析代码 在每一个 小型程序 打破了我的思路 大大增加了 我写的代码量。

开始被实现为 删除样板代码 从这些python程序。 它不打算取代 丰富的命令行处理 需要更大的应用程序。

要求

对于早期的python版本 比Python3.3， 来自的funcsigs包 Python Package Index是 必修的。

对于Python2.6版， 来自的argparse包 Python Package Index是 也是必需的。

这两种依赖都是 在包配置中列出。 如果使用Pip来 安装开始然后 所需的依赖项将 自动安装。

安装

开始可用 下载自 这是Python Package Index。 使用Pip安装

$ pip install begins

或者，最新的 开发版本可以是 直接安装 来自Github。

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

请注意 开始仍在 阿尔法状态 因此 API或行为 可能会改变。

设置程序起点

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

这允许使用以下python模式：

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

替换为：

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

如果用作装饰 注释函数 函数将被调用 如果在__main__模块中定义 通过检查确定 当前堆栈帧。 以下任何定义 装饰的功能 不会被创造直到 函数调用后 已经完成。

使用begin.start()as 装潢师看起来像：

>>> 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中，任何function annotations 对于一个参数 命令行选项帮助。 例如：

>>> 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。 if变长关键字参数 由使用 装饰的功能 例外 将被抚养。

如果一个参数 没有违约， 未能传递值 在命令行上 将导致运行程序 打印错误并退出。

对于那些 大量的选择 最好是 只使用长选项。 为了抑制做空期权， 将False作为 short_args关键字参数 begin.start装饰符：

>>> 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'issues system生成。