Basic APIs

from docpie import docpie
docpie(doc, argv=None, help=True, version=None, ...,
       name=None, ...)

For basic usage, docpie accepts one required argument and three optional arguments, and one optional key-word argument.

• doc: the help message you defined
• help: let docpie print then help message when receiving -h & --help command
• version: let docpie print the version of your program when receiving -v & --version command
• name: specify the executable program name in your usage pattern

doc

type: str; required

doc is the description of your program which docpie can parse. It's usually the __doc__ string of your python script, but it can also be any string in correct format. Here is an example:

"""
Usage: my_program.py [-hso FILE] [--quiet | --verbose] [INPUT ...]

Options:
 -h --help    show this
 -s --sorted  sorted output
 -o FILE      specify output file [default: ./test.txt]
 --quiet      print less text
 --verbose    print more text
"""

from docpie import docpie
print(docpie(__doc__))

online demo >>

argv

type: sequence; default: None

argv is the command line your program accepted and it should be a list or tuple. When set to None, docpie will use sys.argv.

note:

Don't pass str directly to argv, otherwise docpie will split the str into a list by the white spaces, which can be wrong. You may use shlex instead:

>>> import shlex
>>> cmd = input()
prog --config="/path/to/my config.json"
>>> shlex.split(cmd)
['prog', '--config=/path/to/my config.json']

help

type: bool; default: True

help tells docpie to handle -h & --help automatically.

When it's set to True, -h will print "Usage" and "Option" sections you defined, then exit; --help will print the whole value of doc and exit. set help=False if you want to handle it by yourself.

See "Advanced Usage" if you want to customize the behavior.

online demo >>

version

type: any non-None printable object; default: None

version specifies the version of your program. When it's not None, docpie will handle -v / --version, print this value, and exit.

See "Advanced Usage" if you want to customize the behavior.

online demo >>

name

type: str; default: None

name specifies the executable name in your Usage patterns.

By default, docpie will drop the first element in your Usage pattern. Thought it's not recommended: you can specifies the real program name by passing name argument.

(Note: always pass this argument as key-word argument)

"""
Usage:
    make.py --config
    make.py clear
    sudo make.py install
"""

from docpie import docpie
print(docpie(__doc__, name="make.py"))

online demo >>

---

That's all you need to know about docpie. Now you're good to go!

Don't read the following content before you start using it. It will only make things complex!

Come back to read the following section when you feel you need more customize :D