Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Intro to Docopt

Intro to Docopt

If you've ever struggled with argparse--and let's be honest, I know you have--then you might be interested in docopt. docopt is a simpler way to write an argument parser, by not writing the argument parser at all.

Bill Israel

January 22, 2015
Tweet

More Decks by Bill Israel

Other Decks in Programming

Transcript

  1. docopt
    http://docopt.org/

    View Slide

  2. bill israel
    @epochblue

    View Slide

  3. a typical example

    View Slide

  4. $ python boo-argparse.py -h
    usage: boo-argparse.py [-h] [--sum] N [N ...]
    Process some integers.
    positional arguments:
    N an integer for the accumulator
    optional arguments:
    -h, --help show this help message and exit
    --sum sum the integers (default: find the max)

    View Slide

  5. # boo-argparse.py
    import argparse
    parser = argparse.ArgumentParser(description='Process some integers.')
    parser.add_argument('integers', metavar='N', type=int, nargs='+',
    help='an integer for the accumulator')
    parser.add_argument('--sum', dest='accumulate', action='store_const',
    const=sum, default=max,
    help='sum the integers (default: find the max)')
    args = parser.parse_args()
    print args.accumulate(args.integers)

    View Slide

  6. argument parsing usage
    ARGPARSE

    View Slide

  7. usage statements

    View Slide

  8. Naval Fate.
    Usage:
    naval_fate ship new ...
    naval_fate ship move [--speed=]
    naval_fate ship shoot
    naval_fate mine (set|remove) [--moored|--drifting]
    naval_fate -h | --help
    naval_fate --version
    Options:
    -h --help Show this screen.
    --version Show version.
    --speed= Speed in knots [default: 10].
    --moored Moored (anchored) mine.
    --drifting Drifting mine.

    View Slide

  9. usage argument parsing
    DOCOPT

    View Slide

  10. $ python yay-docopt.py -h
    usage: yay-docopt.py [--sum] N [N ...]
    Process some integers.
    Arguments:
    N an integer for the accumulator
    Options:
    -h, --help show this help message and exit
    --version show version information
    --sum sum the integers

    View Slide

  11. # yay-docopt.py
    import argparse
    parser = argparse.ArgumentParser(description='Process some integers.')
    parser.add_argument('integers', metavar='N', type=int, nargs='+',
    help='an integer for the accumulator')
    parser.add_argument('--sum', dest='accumulate', action='store_const',
    const=sum, default=max,
    help='sum the integers (default: find the max)')
    args = parser.parse_args()
    print args.accumulate(args.integers)

    View Slide

  12. example: boom

    View Slide

  13. requirements
    simple key/value store
    four commands
    no command = get

    View Slide

  14. boom - a simple CLI key-value store
    Usage:
    boom
    boom get
    boom add [-f|--force] []
    boom delete [-f|--force]
    boom find
    Commands:
    add Adds with value
    get Displays the value of
    delete Deletes and its value
    find Find keys matching
    Options:
    -h, --help Print this message
    --version Print version information
    -f, --force Don't confirm the action

    View Slide

  15. BOOM.PY """
    boom - a simple CLI key-value store
    Usage:
    boom
    boom get
    boom add [-f|--force] []
    boom delete [-f|--force]
    boom find
    Commands:
    add Adds with value
    get Displays the value of
    delete Deletes and its value
    find Find keys matching
    Options:
    -h, --help Print this message
    --version Print version information
    -f, --force Don't confirm the action
    """

    View Slide

  16. BOOM.PY """
    boom - a simple CLI key-value store
    Usage:
    boom
    boom get
    boom add [-f|--force] []
    boom delete [-f|--force]
    boom find
    Commands:
    add Adds with value
    get Displays the value of
    delete Deletes and its value
    find Find keys matching
    Options:
    -h, --help Print this message
    --version Print version information
    -f, --force Don't confirm the action
    """
    from docopt import docopt

    View Slide

  17. """
    boom - a simple CLI key-value store
    Usage:
    boom
    boom get
    boom add [-f|--force] []
    boom delete [-f|--force]
    boom find
    Commands:
    add Adds with value
    get Displays the value of
    delete Deletes and its value
    find Find keys matching
    Options:
    -h, --help Print this message
    --version Print version information
    -f, --force Don't confirm the action
    """
    from docopt import docopt
    if __name__ == '__main__':
    arguments = docopt(__doc__, version='boom.py 1.0')
    print(arguments)
    BOOM.PY

    View Slide

  18. python boom.py add -f abc
    Usage:
    boom
    boom get
    boom add [-f|--force] []
    boom delete [-f|--force]
    boom find
    {'--force': True,
    '': None,
    '': 'abc',
    '': None,
    'add': True,
    'delete': False,
    'find': False,
    'get': False}
    $>

    View Slide

  19. python boom.py add abc xyz
    Usage:
    boom
    boom get
    boom add [-f|--force] []
    boom delete [-f|--force]
    boom find
    {'--force': False,
    '': 'xyz',
    '': 'abc',
    '': None,
    'add': True,
    'delete': False,
    'find': False,
    'get': False}
    $>

    View Slide

  20. python boom.py get abc xyz
    Usage:
    boom
    boom get
    boom add [-f|--force] []
    boom delete [-f|--force]
    boom find
    $>

    View Slide

  21. BOOM.PY """
    boom - a simple CLI key-value store
    Usage:
    boom
    boom get
    boom add [-f|--force] []
    boom delete [-f|--force]
    boom find
    Commands:
    add Adds with value
    get Displays the value of
    delete Deletes and its value
    find Find keys matching
    Options:
    -h, --help Print this message
    --version Print version information
    -f, --force Don't confirm the action
    """
    from docopt import docopt
    if __name__ == '__main__':
    arguments = docopt(__doc__, version='boom.py 1.0')
    print(arguments)

    View Slide

  22. ¯\_(ツ)_/¯

    View Slide

  23. benefits

    View Slide

  24. small dependency
    easy to read/write
    doubles as documentation
    follows a convention

    View Slide

  25. (fine print)

    View Slide

  26. what can’t it do?
    no validation/type safety
    no secondary parsing
    spotty error messages

    View Slide

  27. but it’s still better than argparse

    View Slide

  28. docopt
    @epochblue
    thank you.

    View Slide