Auto Handler

Auto Handler

All the handlers are callable objects, which accept an Docpie instance as the first argument, and the command line element as the second argument

def my_handler(pie, flag):
    pass

You may read the "Docpie" section to help customize.

Customize Default Handler

If you only want to customize the default handlers (-h/--help and -v/--version), inheriting is a recommended way. Here is a example to hide some options:

"""
Usage:
    prog [options] run | exit | status
    prog [options] --deamon
    prog [dev-options]

Options:
    -h, --help     print this message
    -v, --version  print version
Dev Options:
    -d, --debug          open debug mode
    -o, --output=<file>  debug output file
"""

from docpie import Docpie
from sys import exit


class MyPie(Docpie):

    # override the default help handler. Note the `staticmethod`
    @staticmethod
    def help_handler(pie, flag):
        doc = pie.doc
        options = pie.option_sections
        # get the 'Dev Options' section
        dev = options['Dev']
        print(doc.replace(dev, ''))
        exit()

    # override the default version handler. Note the `staticmethod`
    @staticmethod
    def version_handler(pie, flag):
        print(pie.version)
        exit()

set_auto_handler function

Docpie.set_auto_handler(flag, handler)

set_auto_handler can set a handler of an option and make all synonymous options have the same behavior.

When argv contain this option, Docpie will call the callback object first.

flag is the name of auto-handled option, handler is a callable object wich accept Docpie instance and the name of the option as it's arguments.

"""
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 will handle both -m and --moo.

extra argument

When set extra, the synonymous options you defined will NOT be checked by Docpie.

extra is a dict, the key is the name of the auto-handled option, the value is a callback object which accepts two arguments: the first one is the Docpie instance, the second one is the name of this option.

"""
Example for Docpie!

Usage: example.py [options]

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

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.%5Cn"
          "You may use this program like this:%5Cn")
    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)

Now when pass --moo, it will run moo_handler.

Now try:

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