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.

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