[Docpie]

Fork me on GitHub

高级API


docpie参数

from docpie import docpie
docpie(doc, argv=None, help=True, version=None,
       stdopt=True, attachopt=True, attachvalue=True,
       auto2dashes=True, name=None, case_sensitive=False,
       optionsfirst=False, appearedonly=False, extra={})

注意:

请传入关键字参数,不要依赖位置传入参数。

auto2dashes

类型:bool;默认:True

auto2dashesTrue 时将自动处理 -- 的情况(命令行 option结束标志,参见 这里

from docpie import docpie
print(docpie('Usage: prog <file>'), ['prog', '--', '--test'])
# {'--': True, '<file>': '--test'}

在线试试 >>

name

类型:str;默认:None

name为你程序的名字。“Usage”中出现的第一个name会被忽略掉。设为None时忽略所有“Usage”中的第一个元素。

"""
Usage:
    myscript.py config
    $ python myscript.py make
    $ sudo python myscript.py make install
"""
from docpie import docpie
print(docpie(__doc__, ['myscript.py', 'make', 'install'], name='myscript.py'))
# {'--': False,
#  'config': False,
#  'install': True,
#  'make': True}

在线试试 >>

case_sensitive

类型:bool;默认:False

case_sensitive表明在匹配“Usage:”和“"Options:"”时是否大小写敏感。设为False时则大小写敏感。

optionsfirst

类型:bool;默认:False

optionsfirst设为 True 则在第一个positional元素后的所有元素都将被视为positional参数。

"""
Usage: sudo [-v] [<command>] [<options>...]
"""

from docpie import docpie
import sys

sys.argv = ['sudo', 'cp', '-v', 'a.txt', '/tmp']
print(docpie(__doc__, optionsfirst=True))
# {'--': False,
#  '-v': False,
#  '<command>': 'cp',
#  '<options>': ['-v', 'a.txt', '/tmp']}

sys.argv = ['sudo', '-v', 'cp', '-v', 'a.txt', '/tmp']
print(docpie(__doc__, optionsfirst=True))
# {'--': False,
#  '-v': True,
#  '<command>': 'cp',
#  '<options>': ['-v', 'a.txt', '/tmp']}

在线试试 >>

这个特性可以帮助你包装其它程序命令行参数。请参见例子example-get

appearedonly

类型:bool;默认:False

注意:

  1. 如果你构建标准POSIX,则不需要这个参数
  2. 这个参数仅对option有效

一般来说,optioncommand的值为False0argument 值为None, []则意味着这些未出现在argv中。但考虑以下情况:

Usage: prog [options]

Options:
   -s, --sth=[<value>]    Just an example. Not POSIX standard

此时['prog']['prog', '--sth']都将得到--sth=None。若设置appearedonly=False,则前一种情况下,--sth不会出现在结果中。

from docpie import docpie
args = docpie(__doc__)
if '--sth' in args:
    if args['--sth'] is None:
        print('--sth is in argv without value')
    else:
        print('--sth is in argv with value %s' % args['--sth'])
else:
    print('--sth is not in argv')

extra

见下方Docpie部分


Docpie对象

概述

一般来讲docpie就已经够用了。不过通过Docpie对象你可以使用更多的技巧。

当调用

from docpie import docpie
print(docpie(__doc__))

其效果等同于

from docpie import Docpie
pie = Docpie(__doc__)
pie.docpie()
print(pie)

Docpie对象接受除了argvdocpie的一切参数

Docpie(doc, help=True, version=None,
       stdopt=True, attachopt=True, attachvalue=True,
       auto2dashes=True, name=None, case_sensitive=False,
       optionsfirst=False, appearedonly=False, extra={})

Docpie.docpie函数接受argv参数,进行匹配。同样,为None时使用sys.argv这个值

Docpie.docpie(argv=None)

自动处理

如前所示,当设置help=True或者version="sth"时,docpie会自动处理一些参数。以version="0.0.1"为例,docpie自动处理的机制如下:

  1. 检查--version是否在Options中定义
  2. 如果定义了,则将其和同名option映射到默认方法Docpie.version_handler
  3. 如果没有定义,则检查-v是否在Options中定义,并重复第2
  4. 如果都没定义,则直接将--version-v映射到Docpie.version_handler
  5. 检查传入的argv,如果找到映射的元素,进行下一步
  6. 对于找到的元素,例如--version,则会调用 Docpie.version_handler(pie, "--version")。其中pieDocpie实例
  7. 默认会打印version值,然后退出程序

你可以通过extra参数,或者set_auto_handler方法来修改这个值

extra参数

extra需要传入一个字典,键为需要预处理的option名称,值为一个可回调对象。可回调对象必须接受两个参数,第一个为Docpie实例,第二个为这个option。这样当argv中含有这个option时,Docpie会先运行对应的可回调对象。

"""
Example for Docpie!

Usage: example.py [options]

Options:
  -v, --obvious    print more infomation  # note the `-v` is here
  --version        print version
  -h, -?, --help   print this infomation

Hidden Options:
  --moo            the Easter Eggs!

Have fun, my friend.
"""
from docpie import Docpie
import sys


def moo_handler(pie, flag):
    print("Alright you got me. I'm an Easter Egg.\n"
          "You may use this program like this:\n")
    print(pie.usage_text)
    print("")    # compatible python2 & python3
    print(pie.option_sections[''])
    sys.exit()    # Don't forget to exit

pie = Docpie(__doc__, version='0.0.1')
pie.set_config(
  extra={
    '--moo': moo_handler,  # set moo handler
  }
)

pie.docpie()
print(pie)

这样在传入--moo参数时,就会运行moo_handler(注:pie.option_sections见下部分)。现在试试:

example.py -v
example.py --version
example.py --moo

set_auto_handler函数

Docpie.set_auto_handler(flag, handler)

extra类型,用来设定自动处理的option。其中flag为需要自动处理的option名称, handler为可回调对象,需要接受两个参数,一个为Docpie实例,一个为这个option名称。

不同之处在于,set_auto_handler会找到定义在options中的所有同名option,然后将这些都映射到对应方法中。

"""
Usage: [options]

Options: --moo, -m     the Easter Eggs!
"""

from docpie import Docpie
import sys

def moo_handler(pie, flag):
    print("I'm an Easter Egg!")
    sys.exit()

pie = Docpie(__doc__)
pie.set_auto_handler('-m', moo_handler)
pie.docpie()
print(pie)

这样Docpie会同时自动处理-m--moo

Docpie属性

对于extraset_auto_handler的回调函数,会得到一个Docpie实例。 Docpie实例的以下属性可以帮助你更好地自定义行为。

pie = Docpie(__doc__)
  • pie.version为你设定的version(默认None)
  • pie.usage_text为你定义的“Usage”区域
  • pie.option_sections为一个dict,包含了你定义的所有Options章节。 键为你"Options:"前面的字符(不含前后空白):
    usage: example.py <command> [options]
    
    # the key will be an empty string
    options:
       -h, --help        print this message
    
    # the key will be 'help'
    help options:
       -o, --out=<file>  output file
    
    # the key will be 'advanced control'
    advanced control options:
       -u, --up          move upward
       -d, --down        move downward
    

set_config

set_config(help=True, version=None,
           stdopt=True, attachopt=True, attachvalue=True,
           auto2dashes=True, name=None, case_sensitive=False,
           optionsfirst=False, appearedonly=False, extra={})

set_config可以覆盖你传入Docpie除了doc的任何参数。

注意:

修改stdoptattachoptattachvaluecase_sensitivename 会导致Docpie重新解析。你应该创建一个新的Docpie对象而非修改这些值。


如果你喜欢这个项目,可以买我一杯啤酒,让我做的更好! | Flattr this

侧栏导航