Migrate CLI parsing to click library

[ashander]

This is a large PR, but would fix #234 . If maintainers agree this is a good direction, some additional work is needed:

• modify test suite to deal with new api of functions in commands.py
• modify docs for new look of command-line interaction

Complete overhaul of top-level parsing. Delegation to subcommands using
click.group(). Structure of parsing within each of the subcommand is
retained, but some of the wrapping code for help functions and version
options is no longer needed.

Changes to CLI API:

• webdav/archive/mirror flags no longer specifiable as mutually
  exclusive group
• argument order in comment is changed to smt comment COMMENT [LABEL]

The first of these cannot be fixed without changes to click API (see
issue #257 at click pallets/click#257). The second is
a little more annoying from a user perspective. Though it may be fixable
given current api. So far, though, I can't figure out how to pass
optional arguments before required. I wouldn't be surprised if it isn't
possible either.

A few associated changes:

• Currently using click to print in simplest way possible: click echo,
• and for
  error-like messages specifying err=True to print to standard error.
• Because of change, help files look and print slightly (or in some
  cases majorly) differently

Changes to commands.py API:

• Breaking changes to the arguments expected by all functions
  implementing smt subcommands. This is unavoidable with click.

Remaining issues :

• many test failures due to API changes -- around 67
  (filtering calls to parse_arguments from grep -E 'commands..+((|,)'
  test_commands.py) lines of the test suite for commands.py will need to
  be rewritten
• test rewrite should be straightforward change from tuples to named args
• migration to click doesn't intend to change downstream behavior so
  passing tests can serve as a check on rewrite
• docs not updated to modified look of help pages

[apdavison]

Changes to CLI API:

webdav/archive/mirror flags no longer specifiable as mutually exclusive group
argument order in comment is changed to smt comment COMMENT [LABEL]

For the first, it seems this can be supported by adding our own check that only one of the options has been chosen; it's just that click will not auto-generate an appropriate help message.

The second (which also applies to smt tag) is more problematic, and needs to be investigated further.

Changes to commands.py API:

Breaking changes to the arguments expected by all functions implementing smt subcommands. This is unavoidable with click.

I think this is ok. The commands.py API is not really intended to be used directly.

[apdavison]

One feature I'd like to add to Sumatra is being able to run "smt" with no arguments, as an equivalent to "smt run" but with arguments that get passed straight to the process, e.g.

smt python run.py arg1

as an alternative to

smt run -e python -m run.py arg1

Will click handle this case, or must there always be a subcommand?

[ashander]

Good suggestion on the exclusive group issue. I need to dig into the other issue further.

For the second feature you mention, a crude approach would be to add wrappers for each executable name as subcommands that call run under the hood. It might be better to just dispatch unknown subcommands to our own parsing command though.

In sum, I'll look into these:

• required and optional argument order in click for this first issue
• dispatch with unknown subcommands

[ashander]

Looking at the second issue, it seems smt tag actually doesn't have this issue (per current docs argument order is TAG [LIST] which is the same with click implementation here)

I'd advocate for switching the argument order in smt comment. This is not only consistent with smt tag but also similar commands in other CLI apps (see eg git help tag). A hack around this could be to implement smt comment with a variadic argument and parse based on the length

[ashander]

The unknown command dispatch seems possible: http://click.pocoo.org/4/commands/#group-invocation-without-command

@apdavison thoughts on the course I suggested in last comment? Specifically:

I'd advocate for switching the argument order in smt comment. This is not only consistent with smt tag but also similar commands in other CLI apps (see eg git help tag). A hack around this could be to implement smt comment with a variadic argument and parse based on the length

[apdavison]

The unknown command dispatch seems possible: http://click.pocoo.org/4/commands/#group-invocation-without-command

Unfortunately, this seems to be just "no command", not "unknown command". I tried with a toy script, and giving unknown arguments produces an error. However, having dug into the click source code a bit, I think we can implement unknown commands by subclassing Group or MultiCommand and over-riding the get_command() method.

switching the argument order in smt comment

On reflection, I agree this is a good idea.

[ashander]

Oops thanks for checking. I'll open the unknown command as a separate enhancement issue and work on tests for this 

 I may wait for py3 stuff to stabilize and rebase onto it. Sound good?

- Jaime

On Tue, Jun 2, 2015 at 12:27 PM, Andrew Davison notifications@github.com
wrote:

The unknown command dispatch seems possible: http://click.pocoo.org/4/commands/#group-invocation-without-command
Unfortunately, this seems to be just "no command", not "unknown command". I tried with a toy script, and giving unknown arguments produces an error. However, having dug into the click source code a bit, I think we can implement unknown commands by subclassing Group or MultiCommand and over-riding the get_command() method.
switching the argument order in smt comment

On reflection, I agree this is a good idea.

Reply to this email directly or view it on GitHub:
#237 (comment)

[apdavison]

I may wait for py3 stuff to stabilize and rebase onto it. Sound good?

Yes, sounds like a good plan.

[apdavison]

ok, the py3 stuff is merged. You should be ok to rebase this onto master.