Implement API for "subcommand" style interfaces

[khorn]

Plumbum should provide an API for "subcommand" style interfaces, in which the cli app has a number of subcommands.

e.g. svn, hg, bzr, git, etc.

One way to do this might be to provide a cli.subcommand decorator which you would use to decorate functions in a cli.Application. Then the parsing logic would look for any of these and use whichever one was specified on the command line instead of the current main method.

[tomerfiliba]

nice idea!

[khorn]

After thinking about it, I'm not sure my suggested method for how to implement this is the best one (though it might work fine, it depends on plumbum internals, which I'm not that familiar with), but regardless, I'd like to see some kind of subcommand support in plumbum. Thanks for giving the world such a nice tool!

[tomerfiliba]

here's a sketch:

class Git(cli.Application):

     @cli.subcommand("commit")
     class Commit(cli.Subcommand):
          @cli.switch("-a")
          def all(self):
              pass
          @cli.switch("-m", str)
          def message(self, msg):
              pass

which allows you to write run git commit -a -m foo

[khorn]

Ah, nice! And you could maybe still use @cli.switch to create "global" flags for the base command. I like it.

[khorn]

Though it would also be nice to have a way to define subcommands outside of the cli.Application class. It's not clear from your sketch whether the subcommand would be required to be a nested class, and I can't think why it would be required, but I thought I'd mention it.

Also an API for adding subcommands to a cli.Application might be handy, e.g.

app.addSubcommand(subcommand)

or something like that. This would allow you to store your subcommands someplace else and import them. Useful for anyone who wants to build a plugin architecture around this.

[tomerfiliba]

a better approach:

class GitCommit(cli.SubApplication):
    @switch("-a")
    def all(self):
        pass

class Git(cli.Application):
    commit = cli.Subcommand(GitCommit)
    verbose = cli.Flag("--verbose")

[khorn]

Yes, that's even nicer. As long as whatever processes/detects the subcommands happens when cli.Application.run is called rather than at class instantiation (__init__) time, so you can add subcommands to the application object at run time. I assume this is already the case.

questions:

• do you need cli.SubApplication or could you use cli.Application as the base class for the subcommand? (depends on plumbum internal I presume)
• do you need the cli.Subcommand call? What would it do exactly?

It seems to me that you might only need either a special type for subcommands (cli.SubApplication') **or** a callable to register the suncommand (cli.Subcommand`), but not both. This may be my lack of understanding of how plumbum works internally showing, though.

Hmmm...maybe you need both in order to give the subcommand a reference to the parent application? (You might need this in order to e.g. honor a global --verbose flag on all subcommands)

[tomerfiliba]

hey @khorn - i've pushed subcommand support. see the unittest for how to use it:

plumbum/tests/test_cli.py

Line 27 in b24fcce

class GeetAdd(cli.Application):

[khorn]

Totally awesome! Way to go!