Command line programs for busy developers

Command line interface tools are the new web framework. In addition to the
Python standard library's getopt, optparse and argparse there is a bewildering
array of packages available on the Python Packaging Index. Packages like Click,
Cliff, Docopt, Invoke all provide different mechanics for creating command line
applications. When all you want to do is expose a command line and get back to
creating functionality, it’s hard to know which alternative to reach for.

This presentation will have two parts, the first half will be a brief survey
of popular modules. Strengths, weaknesses and design philosophies will be
compared by creating command line processing for the same example program.

The second half will go into more depth on a specific package, Begins. This
package was authored by the presenter to minimise the disruption developers
experience when breaking flow to implement command line processing. The
audience will be shown how a single line of code can create a complex command
line interface. It will also be shown how a handful of decorators from the
Begins API can eliminate boilerplate code and create powerful, complex
applications.

Transcript

1. Command line programs for busy developers
2. busy, busy, busy …
3. … too busy
4. Creating command line programs
5. Aaron Iles http://www.aaroniles.net
6. One: survey existing tools Two: deep dive into begins
7. Part One: Survey
8. Review Process • Minimal Twitter Client • 3 sub-commands • API tokens from command line options • API tokens from environment variables
9. Review Criteria • Small API • Minimise disruption to workflow • Minimise boilerplate code • Feature rich command lines
10. Review Code https://github.com/aliles/cmdline_examples https://speakerdeck.com/aliles
11. Python Standard Library
12. getopt
13. getopt • Original command line parsing module • Thin wrapper over C library • Function based API
14. getopt Minimal functionality
15. getopt >>> opts, args = getopt.getopt(args,’abc:d:’)
16. optparse
17. optparse • High level command line parser • Support for common option behaviours • Object based API
18. optparse Verbose API Large API No sub-commands Positional arguments ignored
19. optparse >>> parser = OptionParser() >>> parser.add_option("-f", “—file”, ... dest=“filename”, ... help=“write report to FILE”, ... metavar=“FILE”) >>> parser.add_option("-q", “--quiet", ... action=“store_false”, ... dest=“verbose", ... default=True, ... help="don't print status messages") >>> (options, args) = parser.parse_args()
20. argparse
21. argparse • High level command line parser • Support for common option behaviours • Support for sub-commands • Object base API
22. argparse Python 2.7+ or PyPI backport Verbose API Large API
23. 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') >>> args = parser.parse_args()
24. Python Package Index
25. cliff
26. cliff • Framework over argparse • Intended to use setuptools’ entry points • Class based API
27. cliff ✓ Many hook points during application lifecycle No abstraction of argparse Requires use of sub-commands Expect use of entry points
28. cliff >>> class DemoApp(cliff.app.App): ... pass ! >>> class Simple(cliff.command.Command): ... pass ! >>> DemoApp().run(argv)
29. docopt
30. docopt • Command line interface description language • Docstring based API
31. docopt ✓ Easily create complex command line logic Multiple points of control New syntax language to understand Fewer option behaviours
32. docopt """Minimal Twitter client. ! Usage: tw_docopt.py [options] (timeline|retweets) tw_docopt.py -h | --help ! Options: -h --help Show this screen. --version Show version. """ ! >>> args = docopt(__doc__, version="PyConAU")
33. click
34. click • High level abstraction for optparse • Decorator based API
35. click ✓ Simple but powerful API ✓ Robust unicode support Multiple points of control
36. click >>> @click.command() ... @click.option(‘--count’, default=1, ... help=‘Number of greetings.') ... @click.option(‘--name’, prompt='Your name', ... help=‘The person to greet.') ... def hello(count, name): ... pass
37. Part Two: Begins
38. begins
39. begins • High level abstraction for argparse • Decorator based API
40. begins ✓ Simple but powerful API ✓ Reflection on function signature ✓ Replaces the use of __name__ Beta
41. begins >>> @begin.start ... def run(): ... “Does nothing!”
42. begins usage: app.py [-h] ! Does nothing! ! optional arguments: -h, --help show this help message and exit
43. not begins >>> if __name__ == “__main__”: ... run()
44. More Begins
45. Default Values >>> @begin.start ... def run(name=‘Arther', ... quest=‘Holy Grail’, ... colour=‘blue’, ... *knights): ... "tis but a scratch!"
46. Default Values usage: app.py [-h] [--name NAME] [--quest QUEST] [--colour COLOUR] [knights [knights ...]] ! tis but a scratch! ! positional arguments: knights ! optional arguments: -h, --help show this help message and exit --name NAME, -n NAME (default: Arthur) --quest QUEST, -q QUEST (default: Holy Grail) --colour COLOUR, -c COLOUR (default: blue)
47. Annotations for help >>> @begin.start ... def run(name: 'What, is your name?', ... quest: 'What, is your quest?', ... colour: 'What, is your favourite colour?'): ... pass
48. Annotations for help usage: app.py [-h] NAME QUEST COLOUR ! positional arguments: NAME What, is your name? QUEST What, is your quest? COLOUR What, is your favourite colour? ! optional arguments: -h, --help show this help message and exit
49. Boolean Flags >>> @begin.start ... def main(enable=False, disable=True): ... pass
50. Boolean Flags usage: app.py [-h] [--enable] [--no-enable] [--disable] [--no-disable] ! optional arguments: -h, --help show this help message and exit --enable (default: False) --no-enable --disable --no-disable (default: True)
51. Sub-Commands >>> import begin >>> @begin.subcommand ... def name(answer): ... "What is your name?” ... >>> @begin.subcommand ... def quest(answer): ... "What is your quest?” ... >>> @begin.start ... def main(): ... pass
52. Sub-Commands usage: app.py [-h] {name,quest} ... ! optional arguments: -h, --help show this help message and exit ! Available subcommands: {name,quest} name What is your name? quest What is your quest?
53. Even More Begins
54. Entry Points ! >>> @begin.start(plugins='begins.plugin.demo') ... def main(): ... pass
55. Multiple Commands >>> @begin.subcommand ... def subcmd(): ... pass ... >>> @begin.start(cmd_delim='--') ... def main(): ... pass
56. Environment Variables >>> @begin.start(env_prefix='MP_') ... def run(name='Arther', quest='Holy Grail’, colour='blue', *knights): ... "tis but a scratch!"
57. Configuration Files >>> import begin >>> @begin.start(config_file='.camelot.cfg') ... def run(name='Arther', quest='Holy Grail’, ... colour='blue', *knights): ... "tis but a scratch!"
58. Type Casting >>> @begin.start ... @begin.convert(port=int, ... debug=begin.utils.tobool) ... def main(host=‘127.0.0.1', ... port=8080, ... debug=False): ... "Run web application"
59. Automatic Type Casting >>> @begin.start ... @begin.convert(_automatic=True) ... def main(host=‘127.0.0.1', ... port=8080, ... debug=False): ... "Run web application"
60. Yet More Begins
61. Logging >>> @begin.start ... @begin.logging ... def main(*message): ... for msg in message: ... logging.info(msg)
62. Logging usage: app.py [-h] [-v | -q] [--loglvl {DEBUG,INFO,WARNING,ERROR,CRITICAL}] [--logfile LOGFILE] [--logfmt LOGFMT] [messages [messages ...]] ! positional arguments: messages ! optional arguments: -h, --help show this help message and exit -v, --verbose Increse logging output -q, --quiet Decrease logging output ! logging: Detailed control of logging output ! --loglvl {DEBUG,INFO,WARNING,ERROR,CRITICAL} Set explicit log level --logfile LOGFILE Ouput log messages to file --logfmt LOGFMT Log message format
63. Tracebacks >>> @begin.start ... @begin.tracebacks ... def main(*message): ... pass
64. Tracebacks usage: app.py [-h] [--tracebacks] [--tbdir TBDIR] [messages [messages ...]] ! positional arguments: messages ! optional arguments: -h, --help show this help message and exit ! tracebacks: Extended traceback reports on failure ! --tracebacks Enable extended traceback reports --tbdir TBDIR Write tracebacks to directory
65. Enough Already
66. Closing Thoughts
67. Pragmatism over ideology
68. Your application is not its command toolkit
69. Good Luck
70. Thank You