Application Controllers¶

Cement defines a controller interface called IController, but does not enable any default handlers that implement the interface.

Using application controllers is not necessary, but enables rapid development by wrapping pieces of the framework like adding arguments, and linking commands with functions to name a few. The examples below use the CementBaseController for examples. It is important to note that this class also requires that your application’s argument_handler be the ArgParseArgumentHandler. That said, the CementBaseController is relatively useless when used directly and therefore should be used as a Base class to create your own application controllers from.

The following controllers are included and maintained with Cement:

CementBaseController

Please reference the IController interface documentation for writing your own controller.

Example Application Base Controller¶

This example demonstrates the use of application controllers that handle command dispatch and rapid development.

from cement.core import backend,
from cement.core.foundation import CementApp
from cement.core.controller import CementBaseController, expose

# define an application base controller
class MyAppBaseController(CementBaseController):
    class Meta:
        label = 'base'
        description = "My Application does amazing things!"
        epilog = "This is the text at the bottom of --help."

        config_defaults = dict(
            foo='bar',
            some_other_option='my default value',
            )

        arguments = [
            (['-f', '--foo'],
             dict(action='store', help='the notorious foo option')),
            (['-C'],
             dict(action='store_true', help='the big c option')),
            ]

    @expose(hide=True, aliases=['run'])
    def default(self):
        self.app.log.info('Inside base.default function.')
        if self.app.pargs.foo:
            self.app.log.info("Recieved option 'foo' with value '%s'." % \
                          self.app.pargs.foo)

    @expose(help="this command does relatively nothing useful.")
    def command1(self):
        self.app.log.info("Inside base.command1 function.")

    @expose(aliases=['cmd2'], help="more of nothing.")
    def command2(self):
        self.app.log.info("Inside base.command2 function.")


class MyApp(CementApp):
    class Meta:
        label = 'example'
        base_controller = MyAppBaseController


with MyApp() as app:
    app.run()

As you can see, we’re able to build out the core functionality of our app via a controller class. Lets see what this looks like:

$ python example.py --help
usage: example.py <CMD> -opt1 --opt2=VAL [arg1] [arg2] ...

My Application does amazing things!

commands:

  command1
    this command does relatively nothing useful.

  command2 (aliases: cmd2)
    more of nothing.

optional arguments:
  -h, --help  show this help message and exit
  --debug     toggle debug output
  --quiet     suppress all output
  --foo FOO   the notorious foo option
  -C          the big C option

This is the text at the bottom of --help.


$ python example2.py
INFO: Inside base.default function.

$ python example2.py command1
INFO: Inside base.command1 function.

$ python example2.py cmd2
INFO: Inside base.command2 function.

Additional Controllers and Namespaces¶

Any number of additional controllers can be added to your application after a base controller is created. Additionally, these controllers can be stacked onto the base controller (or any other controller) in one of two ways:

embedded - The controllers commands and arguments are included under the parent controllers name space.

nested - The controller label is added as a sub-command under the parent controllers namespace (effectively this is a sub-command with additional sub-sub-commands under it)

For example, The base controller is accessed when calling example.py directly. Any commands under the base controller would be accessible as example.py <cmd1>, or example.py <cmd2>, etc. An embedded controller will merge its commands and options into the base controller namespace and appear to be part of the base controller... meaning you would still access the embedded controllers commands as example.py <embedded_cmd1>, etc (same for options).

For nested controllers, a prefix will be created with that controllers label under its parents namespace. Therefore you would access that controllers commands and options as example.py <controller_label> <controller_cmd1>.

See the Multiple Stacked Controllers example for more help.