Controllers

Introduction to the Controller Interface

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

For convenience, the preferred ArgparseController and expose() decorator from the Argparse Extension are available as Controller and ex in the top level cement module.

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 often includes multiple handler implementations of an interface that may or may not have additional features or functionality than the interface requires. The documentation below only references usage based on the interface and default handler (not the full capabilities of an implementation).

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.

The initial base controller must have a Controller.Meta.label of base to designate it as the application's route of handing over runtime (argument parsing, mapping sub-commands to controllers, etc).

If no controller handler is registered with a base label, Cement will register a minimal controller in it's place that doesn't do anything other than allow extensions to stack properly.

Example: Defining an Application Base Controller

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()

cli

$ 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.

Example: Controller 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()

cli

$ python myapp.py
Inside Base._default()

The Controller._default method is hidden from the command-line (ex: --help output), and does not require the ex() decorator to be active. You can modify the default method by setting it via Controller.Meta.default_func.

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.

Controller level arguments should be considered global, and relevant to the entire controller namespace. Sub-command level arguments are only relevant to that sub-command.

Example: Defining Controller Arguments

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()

cli

$ 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

How and where arguments are defined determines how they are used. An argument defined under a controller must be passed before any sub-command namespaces, otherwise the sub-parser will not recognize it and result in an unrecognized argument error.

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.

Example: Processing Controller Level Arguments

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()

cli

$ 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>.

Example: Multiple Stacked Controllers

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()

cli

$ 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()

Controllers can be stacked on other controllers as many levels deep as necessary. An embedded controller can be stacked on top of a nested controller, and vice versa. There is little, if any, limitation.