Skip to main content

CLI sub-command library

Project description

This is a tiny library to help you write CLI applications with many sub-commands.


pip install subc


Create your own command subclass for your application:

class MyCmd(subc.Command):

Then, write commands in your application which sub-class this:

class HelloWorld(MyCmd):
    name = 'hello-world'
    description = 'say hello'
    def run(self):
        print('hello world')

Finally, use your application-level subclass for creating the argument parser and running your application:

if __name__ == '__main__':
    MyCmd.main('description of app')

Advanced Use

Intermediate Base Classes

You may find yourself wanting to create intermediate subclasses for your application, in order to share common functionality. For example, you might create a class for all commands which handle a single file as an argument:

class FileCmd(MyCmd):
    def add_args(self, parser):
        parser.add_args('file', help='the single file')

You can do that, so long as your intermediate subclasses are not executable. For example, given the following class hierarchy:

|- FileCmd*
|  |- AppendLineCmd
|  |- RemoveLineCmd
|- DoSomethingElseCmd

The non-leaf commands (marked with an asterisk) will not be included as executable commands. Only leaf classes will be executable.

Default Command

When the user does not provide any argument on the command-line, the default action is to raise an Exception which states “you must select a sub-command”. You can provide a default command to run instead, via the default argument to main() (or add_subcommands()). For example:

if __name__ == '__main__':
    MyCmd.main('description', default='help')

The above code will run the help subcommand when no subcommand is specified. Note that in this case, the default sub-command may not receive all of its expected arguments.

Shortest Prefix Aliasing

subc has an optional feature which allows the user to specify a subcommand by the shortest prefix which uniquely identifies the subcommand, or any longer prefix thereof. As an example, imagine a git command with the following sub-commands: clone, checkout, commit, cherry-pick. The shortest prefix aliasing would allow you to run “git clone” by executing git cl, since only “clone” begins with “cl”. You could also execute “git clone” with a longer prefix like git clo. The feature can be enabled by setting shortest_prefix to true in main() or add_subcommands().


This project is released under the Revised BSD license. See LICENSE.txt for details.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for subc, version 0.4.1
Filename, size File type Python version Upload date Hashes
Filename, size subc-0.4.1-py3-none-any.whl (7.7 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size subc-0.4.1.tar.gz (5.2 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page