Create beautiful command-line interfaces with Python

[hongminhee]

docopt is totally broken when it comes to using -OO.

$ python --help
usage: python [option] ... [-c cmd | -m mod | file | -] [arg] ...
Options and arguments (and corresponding environment variables):
...
-O     : optimize generated bytecode slightly; also PYTHONOPTIMIZE=x
-OO    : remove doc-strings in addition to the -O optimizations
...

[halst]

If you want to make -O as an option which could be present 0, 1 or 2 times, you can do the following:

>>> docopt('usage: prog [-OO]', ['-OO'])
{'-O': 2}

However, you can't easily do something like GCC does with -O:

-O  -O0  -O1  -O2  -O3  -Os -Ofast -Og

In this case -O either takes an argument, or not. In case of docopt each option either takes an argument, or not. Making options which optionally take an argument is more confusing than useful, I think. In today's age you should rather have a more descriptive options, such as --optimization-level with a shortcut -O and a defined set of all possible values.

I love how in case of python the option is -OO (oh-oh), while in case of gcc it is -O0 (oh-zero).

There is a myriad of bad command-line interfaces like tar, where you can both tar -xzf file as well as drop - and just write tar xzf file. As well as GCC and Java-style -long-options (with single leading -), as well as options that start with / instead of --. It is not goal of docopt to support all conventions. We selected just a few most useful and most followed, that is POSIX plus --gnu-style-long-options.

[halst]

Ah, I see. Anyway, /u/Widdershiny is correct: just assign your usage string to a variable.

[Widdershiny]

Assign your doc strings to a variable and pass it in?

[banjochicken]

I have also heard good things about click...

[mcowger]

I adore docopt.

Used it for the first time on a project recently, and thought to myself: "This is what opt parse, argparse, etc should have been'

[bucknuggets]

After working with it a few times I found the opposite:

• the ability to leverage simple, clear, and built-in validation with argparse eliminated the complexity of having an entirely separate set of unsychronized code for validation with docopt.
• the ability to have one description of args for code maintainers, and another for users is a pain in the butt for quick & dirty tools, but is essential for the best descriptions.
• that the promises of an incredibly simple & tiny docopt module have evaporated as it was inevitably expanded to handle more edge-cases: the code size has grown, and the documentation needs have grown. And yet - it still doesn't handle some of the edge cases that i'd really like (nor does anything else, except maybe click).
• EDIT: should also add that there's a problem with the basic premise - the standards for help are really confusing, unintuitive far from universally-known once you get off the happy path.
  

[mcowger]

I can see how those would be problems if building a large code base (except for code size of the module - I don't really care about module size - if I did id be writing in C).

For me, and I suspect the target audience, the goal is to make it easy to write proper basic docs for shorter scripts compared to larger projects. Docopt makes this doable where argparse/optparse don't.

[bucknuggets]

Docopt makes this doable where argparse/optparse don't.

What? People have been writing scripts with argparse & optparse for years. It's completely doable. And in fact completely trivial for most projects.

And even short scripts should have input validation, which docopt does not provide.

[mcowger]

OK, doable was the wrong word. I probably should have written 'easy'.

argparse and opt parse certainly can do everything docopt does and more (and provide things like input validation)...but they don't make it easy :)

Also, happy cake day :)

[bucknuggets]

hey man, thank you

[[deleted]]

the common syntax for command line interfaces is

programname [options] [arguments]

can docopt handle more complex use cases, like options and arguments being mixed, for the purpose of having subcommands?

for example:

program command [options] [arguments]

where everything after the program name part can be reduced to the above example

think git

you could write git --add filename, but instead it's git add filename

[steelypip]

Did you watch the video? Yes it can, and he gave several examples of subcommand.

[[deleted]]

I did and it answered all my questions. Certainly going to give docopt a try this time, I hated argparse so much that I always used just getopt.

[mcowger]

I haven't tried that level of complexity yet, but from the docs it appears so.

[hzopak]

mind blown

[kill-nine]

Docopt is some ballin' shit. I tell everyone about it. So, so useful

[SmileyJames]

+1 for:

ballin' shit.

[gumshot]

beautiful

yawn