Introduction to the Controller Interface

Cement defines a Controller Interface, but does not enable any handlers that implement the interface by default.

Using application controllers is not necessary, but enables rapid development by wrapping pieces of the framework like adding arguments, and linking commands with controller methods. The examples below use the ArgparseController as examples (again, imported as cement.Controller for convenience).

Cement Extensions That Provide Controller Handlers

• ​Argparse​

API References:

• ​Cement Core Controller Module​

• ​Cement Argparse Extension​

Application Base Controllers

When using application controllers there must be a single base controller responsible for handling runtime dispatch. All other controllers are then stacked on top of the base controller (or other controllers already stacked on base). The base controller is the root of the application's command-line namespace.

from cement import App, Controller, ex
​
class Base(Controller):
    class Meta:
        label = 'base'
​
    @ex(help='example sub-command')
    def cmd1(self):
        print('Inside Base.cmd1()')
​
class MyApp(App):
    class Meta:
        label = 'myapp'
        handlers = [
            Base,
        ]
​
with MyApp() as app:
    app.run()

$ python myapp.py
usage: myapp [-h] [-d] [-q] {cmd1} ...
​
optional arguments:
  -h, --help   show this help message and exit
  -d, --debug  full application debug mode
  -q, --quiet  suppress all console output
​
sub-commands:
  {cmd1}
    cmd1       example sub-command
​
$ python myapp.py cmd1
Inside Base.cmd1()

The above example demonstrates registering an application base controller. You will note in the cli tab that running python myapp.py without any arguments produces help output (same as if passing --help). This is the default action of the ArgparseController, but can be modified by overriding the _default method.

from cement import App, Controller, ex
​
class Base(Controller):
    class Meta:
        label = 'base'
​
    def _default(self):
        print('Inside Base._default()')
​
    @ex(help='example sub-command')
    def cmd1(self):
        print('Inside Base.cmd1()')
​
​
class MyApp(App):
    class Meta:
        label = 'myapp'
        handlers = [
            Base,
        ]
​
with MyApp() as app:
    app.run()

$ python myapp.py
Inside Base._default()

Controller Arguments

Command line arguments defined by controllers are handled in two ways:

• Controller level

• Sub-command level

Controller level arguments are defined via Controller.Meta.arguments and are displayed/used at the top level of that controller, while sub-command level arguments are defined via the ex() decorator and only displayed and used under that sub-command namespace.

from cement import App, Controller, ex
​
class Base(Controller):
    class Meta:
        label = 'base'
​
        arguments = [
            ( [ '-f', '--foo' ],
              { 'help' : 'the notorious foo option',
                'action' : 'store',
                'dest' : 'foo', } ),
        ]
​
    @ex(
        help='example sub-command',
        arguments=[
            ( [ '--sub-option' ],
              { 'help' : 'option under sub-command',
                'action' : 'store_true',
                'dest' : 'sub_option' } ),
        ]
    )
    def cmd1(self):
        print('Inside Base.cmd1()')
​
        if self.app.pargs.foo is not None:
            print('Foo => %s' % self.app.pargs.foo)
​
        if self.app.pargs.sub_option is True:
            print('Sub Option Was Passed')
​
​
class MyApp(App):
    class Meta:
        label = 'myapp'
        handlers = [
            Base,
        ]
​
with MyApp() as app:
    app.run()

$ python myapp.py --help
usage: myapp [-h] [-d] [-q] [-f FOO] {cmd1} ...
​
optional arguments:
  -h, --help         show this help message and exit
  -d, --debug        full application debug mode
  -q, --quiet        suppress all console output
  -f FOO, --foo FOO  the notorious foo option
​
sub-commands:
  {cmd1}
    cmd1             example sub-command
​
​
$ python myapp.py cmd1 --help
usage: myapp cmd1 [-h] [--sub-option]
​
optional arguments:
  -h, --help    show this help message and exit
  --sub-option  option under sub-command
​
​
$ python myapp.py -f bar cmd1 --sub-option
Inside Base.cmd1()
Foo => bar
Sub Option Was Passed

Processing Controller Level Arguments

In the above example we demonstrated accessing the controller level argument via app.pargs.foo in the Base.cmd1() method/sub-command. This worked fine. However, because controller level arguments should be considered global to the entire namespace, we should reduce duplicate code and handle controller level argument parsing in one place, regardless of what sub-command is passed.

The ArgparseController defines both a _pre_argument_parsing and_post_argument_parsing method for providing direct access to that controller's sub-parser (self._parser) and processing arguments. This is very similar to the pre_argument_parsing and post_argument_parsing framework hooks, but local in scope to the controller.

from cement import App, Controller, ex
​
class Base(Controller):
    class Meta:
        label = 'base'
​
        arguments = [
            ( [ '-f', '--foo' ],
              { 'help' : 'the notorious foo option',
                'action' : 'store',
                'dest' : 'foo', } ),
        ]
​
    def _post_argument_parsing(self):
        if self.app.pargs.foo is not None:
            print('Foo => %s' % self.app.pargs.foo)
​
    @ex(help='example sub-command')
    def cmd1(self):
        print('Inside Base.cmd1()')
​
    @ex(help='another example sub-command')
    def cmd2(self):
        print('Inside Base.cmd2()')
​
​
class MyApp(App):
    class Meta:
        label = 'myapp'
        handlers = [
            Base,
        ]
​
with MyApp() as app:
    app.run()

$ python myapp.py -f bar cmd1
Foo => bar
Inside Base.cmd1()
​
$ python myapp.py -f bar cmd2
Foo => bar
Inside Base.cmd2()

Additional Controllers and Namespaces

Any number of additional controllers can be added to your application after a base controller is registered. 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 controller's name space.

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

For example, the base controller is accessed when calling myapp.py directly. Any commands under the base controller would be accessible as myapp.py <cmd1>, or myapp.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 myapp.py <embedded_cmd1>, etc (same for options).

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

from cement import App, Controller, ex
​
class Base(Controller):
    class Meta:
        label = 'base'
​
    @ex(help='example sub-command')
    def cmd1(self):
        print('Inside Base.cmd1()')
​
class Embedded(Controller):
    class Meta:
        label = 'embedded'
        stacked_on = 'base'
        stacked_type = 'embedded'
​
    @ex(help='embedded sub-command')
    def cmd2(self):
        print('Inside Embedded.cmd2()')
​
class Nested(Controller):
    class Meta:
        label = 'nested'
        stacked_on = 'base'
        stacked_type = 'nested'
​
    @ex(help='nested sub-command')
    def cmd3(self):
        print('Inside Nested.cmd3()')
​
class MyApp(App):
    class Meta:
        label = 'myapp'
        handlers = [
            Base,
            Embedded,
            Nested,
        ]
​
with MyApp() as app:
    app.run()

$ python myapp.py  --help
usage: myapp [-h] [-d] [-q] {nested,cmd1,cmd2} ...
​
optional arguments:
  -h, --help          show this help message and exit
  -d, --debug         full application debug mode
  -q, --quiet         suppress all console output
​
sub-commands:
  {nested,cmd1,cmd2}
    nested            nested controller
    cmd1              example sub-command
    cmd2              embedded sub-command
​
​
$ python myapp.py cmd1
Inside Base.cmd1()
​
​
$ python myapp.py cmd2
Inside Embedded.cmd2()
​
​
$ python myapp.py nested cmd3
Inside Nested.cmd3()