Switch CLI arg processing to docopt

[mmabey]

I know it would be a significant refactor, but the docopt library is so much cleaner and easier to read than argparse and I think it would be worthwhile to make the switch. The length of cli.py would be half its current length easily, and without all the confusing parameters to create each argument and option.

I know that core.py references methods from the args object, so to continue to accommodate this, I've already started writing a wrapper for the bunch library that would allow a smoother transition to using docopt.

In terms of compatibility, docopt is compatible with Python 2.5+ and 3.x, and bunch is a fairly simple wrapper around the dict object, so there shouldn't be an issue with the versions of Python that HTTPie woks with.

In any case, I wanted to get some feedback about this idea before I started real work on it. So what do you think?

[kracekumar]

If changing command line parsing library is an option why not consider click http://click.pocoo.org/

[mmabey]

I haven't ever worked with click before, but from what I can tell it seems that fully using its API would fundamentally change how everything is called in httpie. My motivation for suggesting the change to docopt was to increase the simplicity of the httpie command-line parameters' definitions without too much disruption to how the rest of the library utilizes the arguments given by the user. My hope was that this change would make additions and deprecations easier and allow new contributors to understand the workings of the library with less effort.

On Thu, Jun 19, 2014 at 1:52 PM, kracekumar notifications@github.com wrote:

If changing command line parsing library is an option why not consider click http://click.pocoo.org/

— Reply to this email directly or view it on GitHub https://github.com/jakubroztocil/httpie/issues/228#issuecomment-46593914 .

[sigmavirus24]

Except that argparse is just as popular (if not more popular) than docopt so I would expect new contributors to more easily understand argparse based on their experience with it. If you instead mean "new Pythonistas who want to contribute", then I don't see how the magic that is taking the docstring and turning it into command-line flags is easy to understand to a new Pythonista.

[mmabey]

I guess I was basing my estimation of effort on the simplicity of docopt, not on its popularity. After all, isn't simple better than complex? And at least in my book, readability counts, which I think docopt also has in its favor over argparse, even if for the simple fact that the documentation is so much shorter.

I understand that I'm not going to win over argparse aficionados to use docopt. But IMHO, regardless of your programming experience, having the help text in one place instead of spread over 20+ method calls is easier to work with, as is having a dict with all your arguments and flags named the same thing as in the help text.

[jkbrzt]

@mmabey I appreciate the initiative :+1:

HTTPie's focus is user experience, code readability comes in second. argparse is far from perfect (e.g. #125, #239), but it does its job reasonably well. Please keep in mind that the CLI is complex and somewhat unusual.

I'd argue that the way the CLI is defined is far from unmaintainable (cli.py). What is quite messy though is the additional logic layer in input.py.

So, unless docopt (or click) allows the same (or higher) degree of flexibility while significantly reducing code complexity, I'd strongly prefer sticking with argparse (whose additional advantage is that it's included in the stdlib of newer Python versions).

---

Update: See also https://twitter.com/jakubroztocil/status/508591400930525185

[sigmavirus24]

If I'm following the twitter conversation properly, docopt is out of the question (assuming of course that we want full backwards compatiblity).

[jkbrzt]

@sigmavirus24 Yes. I guess we can revisit this again in the future. Closing for now.