`cement.core.controller`¶

Cement core controller module.

class cement.core.controller.CementBaseController(*args, **kw)¶

Bases: cement.core.handler.CementBaseHandler

This is an implementation of the IControllerHandler interface, but as a base class that application controllers should subclass from. Registering it directly as a handler is useless.

NOTE: This handler requires that the applications ‘arg_handler’ be argparse. If using an alternative argument handler you will need to write your own controller base class.

NOTE: This the initial default implementation of CementBaseController. In the future it will be replaced by CementBaseController2, therefore using CementBaseController2 is recommended for new development.

Usage:

from cement.core.controller import CementBaseController

class MyAppBaseController(CementBaseController):
    class Meta:
        label = 'base'
        description = 'MyApp is awesome'
        config_defaults = dict()
        arguments = []
        epilog = "This is the text at the bottom of --help."
        # ...

class MyStackedController(CementBaseController):
    class Meta:
        label = 'second_controller'
        aliases = ['sec', 'secondary']
        stacked_on = 'base'
        stacked_type = 'embedded'
        # ...

class Meta¶

Bases: object

Controller meta-data (can be passed as keyword arguments to the parent class).

aliases = []¶: A list of aliases for the controller. Will be treated like command/function aliases for non-stacked controllers. For example: myapp <controller_label> --help is the same as myapp <controller_alias> --help.

aliases_only = False¶: When set to True, the controller label will not be displayed at command line, only the aliases will. Effectively, aliases[0] will appear as the label. This feature is useful for the situation Where you might want two controllers to have the same label when stacked on top of separate controllers. For example, ‘myapp users list’ and ‘myapp servers list’ where ‘list’ is a stacked controller, not a function.

argument_formatter¶

The argument formatter class to use to display –help output.

alias of RawDescriptionHelpFormatter

arguments = []¶

Arguments to pass to the argument_handler. The format is a list of tuples whos items are a ( list, dict ). Meaning:

[ ( ['-f', '--foo'], dict(dest='foo', help='foo option') ), ]

This is equivelant to manually adding each argument to the argument parser as in the following example:

parser.add_argument(['-f', '--foo'], help='foo option', dest='foo')

config_defaults = {}¶: Configuration defaults (type: dict) that are merged into the applications config object for the config_section mentioned above.

config_section = None¶: A config [section] to merge config_defaults into. Cement will default to controller.<label> if None is set.

default_func = 'default'¶: Function to call if no sub-command is passed. Note that this can not start with an _ due to backward compatibility restraints in how Cement discovers and maps commands.

description = None¶: The description shown at the top of ‘–help’. Default: None

epilog = None¶: The text that is displayed at the bottom when ‘–help’ is passed.

hide = False¶: Whether or not to hide the controller entirely.

interface¶

The interface this class implements.

alias of IController

label = None¶: The string identifier for the controller.

stacked_on = 'base'¶: A label of another controller to ‘stack’ commands/arguments on top of.

stacked_type = 'embedded'¶: Whether to embed commands and arguments within the parent controller or to simply nest the controller under the parent controller (making it a sub-sub-command). Must be one of [‘embedded’, ‘nested’] only if stacked_on is not None.

usage = None¶: The text that is displayed at the top when ‘–help’ is passed. Although the default is None, Cement will set this to a generic usage based on the prog, controller name, etc if nothing else is passed.

CementBaseController._dispatch()¶: Takes the remaining arguments from self.app.argv and parses for a command to dispatch, and if so... dispatches it.

CementBaseController._help_text¶: Returns the help text displayed when ‘–help’ is passed.

CementBaseController._setup(app_obj)¶: See IController._setup().

CementBaseController._usage_text¶: Returns the usage text displayed when --help is passed.

class cement.core.controller.IController¶

Bases: cement.core.interface.Interface

This class defines the Controller Handler Interface. Classes that implement this handler must provide the methods and attributes defined below.

Implementations do not subclass from interfaces.

Usage:

from cement.core import controller

class MyBaseController(controller.CementBaseController):
    class Meta:
        interface = controller.IController
        ...

class IMeta¶

Bases: object

Interface meta-data.

label = 'controller'¶: The string identifier of the interface.

validator(klass, obj)¶: The interface validator function.

IController._dispatch()¶

Reads the application object’s data to dispatch a command from this controller. For example, reading self.app.pargs to determine what command was passed, and then executing that command function.

Note that Cement does not parse arguments when calling _dispatch() on a controller, as it expects the controller to handle parsing arguments (I.e. self.app.args.parse()).

Returns:	Returns the result of the executed controller function, or `None` if no controller function is called.

IController._setup(app_obj)¶

The _setup function is after application initialization and after it is determined that this controller was requested via command line arguments. Meaning, a controllers _setup() function is only called right before it’s _dispatch() function is called to execute a command. Must ‘setup’ the handler object making it ready for the framework or the application to make further calls to it.

Parameters:	app_obj – The application object.
Returns:	`None`

cement.core.controller.controller_validator(klass, obj)¶: Validates a handler implementation against the IController interface.

class cement.core.controller.expose(help='', hide=False, aliases=[], aliases_only=False)¶

Bases: object

Used to expose controller functions to be listed as commands, and to decorate the function with Meta data for the argument parser.

Parameters:

help (str) – Help text to display for that command.
hide (boolean) – Whether the command should be visible.
aliases (list) – Aliases to this command.
aliases_only – Whether to only display the aliases (not the label). This is useful for situations where you have obscure function names which you do not want displayed. Effecively, if there are aliases and aliases_only is True, then aliases[0] will appear as the actual command/function label.

Usage:

from cement.core.controller import CementBaseController, expose

class MyAppBaseController(CementBaseController):
    class Meta:
        label = 'base'

    @expose(hide=True, aliases=['run'])
    def default(self):
        print("In MyAppBaseController.default()")

    @expose()
    def my_command(self):
        print("In MyAppBaseController.my_command()")

cement.core.controller¶

`cement.core.controller`¶