In all of the examples so far, we've had a single command, with a single set of parameters. This works fine for smaller applications, but once a tool starts to grow in scope, it is useful to start breaking up it's functionality into descrete units using subcommands.
What is a Subcommand?¶
A subcommand is an arc command object that lives underneath another command object. Each subcommand will have it's own callback function and it's own set of parameters. When ran from the commandline it will look a little something like this
There are a couple of ways to define subcommands, in this doc we'll focus on the most common
We can then execute each subcommand by referring to them by name.
Subcommands also get their own
$ python subcommand.py --help USAGE subcommand.py [-h] subcommand.py <subcommand> [ARGUMENTS ...] OPTIONS --help (-h) Displays this help message SUBCOMMANDS sub1 sub2 $ python subcommand.py sub1 --help hello there! USAGE subcommand.py sub1 [-h] OPTIONS --help (-h) Displays this help message $ python subcommand.py sub2 --help hello there! USAGE subcommand.py sub2 [-h] OPTIONS --help (-h) Displays this help message
Subcommands can be arbitrarly nested
import arc @arc.command() def command(): print("hello there!") @command.subcommand() def sub1(): print("This is sub 1") @sub1.subcommand() def nested1(): print("This is nested 1") @command.subcommand() def sub2(): print("This is sub 2") @sub2.subcommand() def nested2(): print("This is nested 2") command()
When you define subcommands for you application, the root
@arc.command() object becomes a callback for global parameters. This is useful for defining things that can apply to the entirety of your applcation. For example, logging configuration.
Global arguments must come before the name of the command for them to be interpreted correctly. You can see this reflected in the
Things to be aware of¶
- The root object can no longer define argument parameters, because arc doesn't have a way of knowing what is a positional parameter and what is the name of a command. Note: This may change in the future if I have time / care to change it.
- The root callback will be executed before every subcommand, regardless of whether or not you actually provide any global arguments. If this behavior isn't desired, it can be changed with
By default, commands are the kebab-case version of the function they decorate. This can be modified to change the name
or provide multiple names, for a command.
Subcommands in other Files¶
Breaking up your CLI interface into multiple files in arc is a very straightforward process.