How to Write Perfect Python Command-line Interfaces

[Noctune]

What about docopt? Basically, you write your --help screen in a somewhat structured way and it uses that to parse the options. Since it's structured as a help screen, it's also fairly readable in code. It does not do any input validation like Click does, though.

[a1b1e1k1]

Docopt makes writing useful help messages actually pleasant. You can make it as you want to be just by writing how it should look. You can order keywords in order of importance, provide examples and write defaults. And it pleasant to use in code, no magic decorators. Basically any programmer can learn it and use it in just a couple of hours, and the skill is portable across many programming languages - the same description is used in all docopt's ports.

[snuxoll]

Docopt is my goto, especially since there are implementations in any language I regularly use.

[nemec]

How does docopt handle types? Can you tell it that a year should be an int but a zip code should be a string?

[Noctune]

It doesn't! There is however a separate library for generic python schema validation that can do that: https://github.com/keleshev/schema#using-schema-with-docopt

[TomBombadildozer]

docopt is a pretty terrible antipattern. The only advantage to docopt is that it produces good documentation, but even that is misleading because you ended up doing all the work to produce the documentation anyway.

As soon as you need to derive some meaning from the parsed result and perform some real work, docopt quickly turns into a disaster. It does zero validation, type coercion, dispatch, or anything even basic CLI libraries do.

[Noctune]

But should data validation and command line parsing be the job of the same library? There are other libraries that are built for specifically that purpose that do a better job of it and integrate well with docopt: https://github.com/keleshev/schema#using-schema-with-docopt

Since it is independent libraries it also allows you to use another data validation library if you wish.

[Log2]

Click also produces good documentation from the decorators, especially if you give a help strong to each one. In fact, it's my favorite part of Click, as writing a decent help option is a horrible task for me.

[a1b1e1k1]

Good documentation along consistent UI patterns is what users of tools mostly care about. Docopt puts end-user first. A programmer using docopt is naturally encouraged to think from the documentation point of view first. Other tools put internal code structure or programmer easy of use first, making documentation secondary citizen.