Quick Start¶
The following creates and runs a sample ‘helloworld’ application.
helloworld.py
from cement.core.foundation import CementApp
with CementApp('helloworld') as app:
app.run()
print('Hello World')
The above is equivalent to (should you need more control over setup and closing an application):
from cement.core.foundation import CementApp
app = CementApp('helloworld')
app.setup()
app.run()
print('Hello World')
app.close()
Running the application looks like:
$ python helloworld.py
Hello World
Oh, I can just here you saying, “Whoa whoa... hang on a minute. This is a joke right, all you did was print ‘Hello World’ to STDOUT. What kind of framework is this?”. Well obviously this is just an introduction to show that the creation of an application is dead simple. Lets take a look further:
$ python helloworld.py --help
usage: helloworld.py [-h] [--debug] [--quiet]
optional arguments:
-h, --help show this help message and exit
--debug toggle debug output
--quiet suppress all output
Oh nice, ok... ArgParse is already setup with a few options I see. What else?
$ python helloworld.py --debug
2014-04-15 12:28:24,705 (DEBUG) cement.core.foundation : laying cement for the 'helloworld' application
2014-04-15 12:28:24,705 (DEBUG) cement.core.hook : defining hook 'pre_setup'
2014-04-15 12:28:24,705 (DEBUG) cement.core.hook : defining hook 'post_setup'
2014-04-15 12:28:24,705 (DEBUG) cement.core.hook : defining hook 'pre_run'
2014-04-15 12:28:24,705 (DEBUG) cement.core.hook : defining hook 'post_run'
2014-04-15 12:28:24,706 (DEBUG) cement.core.hook : defining hook 'pre_argument_parsing'
2014-04-15 12:28:24,706 (DEBUG) cement.core.hook : defining hook 'post_argument_parsing'
2014-04-15 12:28:24,706 (DEBUG) cement.core.hook : defining hook 'pre_close'
2014-04-15 12:28:24,706 (DEBUG) cement.core.hook : defining hook 'post_close'
2014-04-15 12:28:24,706 (DEBUG) cement.core.hook : defining hook 'signal'
2014-04-15 12:28:24,706 (DEBUG) cement.core.hook : defining hook 'pre_render'
2014-04-15 12:28:24,706 (DEBUG) cement.core.hook : defining hook 'post_render'
2014-04-15 12:28:24,706 (DEBUG) cement.core.handler : defining handler type 'extension' (IExtension)
2014-04-15 12:28:24,706 (DEBUG) cement.core.handler : defining handler type 'log' (ILog)
2014-04-15 12:28:24,706 (DEBUG) cement.core.handler : defining handler type 'config' (IConfig)
2014-04-15 12:28:24,706 (DEBUG) cement.core.handler : defining handler type 'plugin' (IPlugin)
2014-04-15 12:28:24,706 (DEBUG) cement.core.handler : defining handler type 'output' (IOutput)
2014-04-15 12:28:24,706 (DEBUG) cement.core.handler : defining handler type 'argument' (IArgument)
2014-04-15 12:28:24,706 (DEBUG) cement.core.handler : defining handler type 'controller' (IController)
2014-04-15 12:28:24,706 (DEBUG) cement.core.handler : defining handler type 'cache' (ICache)
2014-04-15 12:28:24,706 (DEBUG) cement.core.handler : registering handler '<class 'cement.core.extension.CementExtensionHandler'>' into handlers['extension']['cement']
2014-04-15 12:28:24,706 (DEBUG) cement.core.foundation : now setting up the 'helloworld' application
2014-04-15 12:28:24,706 (DEBUG) cement.core.foundation : adding signal handler for signal 15
2014-04-15 12:28:24,712 (DEBUG) cement.core.foundation : adding signal handler for signal 2
2014-04-15 12:28:24,712 (DEBUG) cement.core.foundation : setting up helloworld.extension handler
2014-04-15 12:28:24,712 (DEBUG) cement.core.extension : loading the 'cement.ext.ext_dummy' framework extension
2014-04-15 12:28:24,712 (DEBUG) cement.core.handler : registering handler '<class 'cement.ext.ext_dummy.DummyOutputHandler'>' into handlers['output']['null']
2014-04-15 12:28:24,712 (DEBUG) cement.core.extension : loading the 'cement.ext.ext_plugin' framework extension
2014-04-15 12:28:24,713 (DEBUG) cement.core.handler : registering handler '<class 'cement.ext.ext_plugin.CementPluginHandler'>' into handlers['plugin']['cement']
2014-04-15 12:28:24,713 (DEBUG) cement.core.extension : loading the 'cement.ext.ext_configparser' framework extension
2014-04-15 12:28:24,713 (DEBUG) cement.core.handler : registering handler '<class 'cement.ext.ext_configparser.ConfigParserConfigHandler'>' into handlers['config']['configparser']
2014-04-15 12:28:24,713 (DEBUG) cement.core.extension : loading the 'cement.ext.ext_logging' framework extension
2014-04-15 12:28:24,713 (DEBUG) cement.core.handler : registering handler '<class 'cement.ext.ext_logging.LoggingLogHandler'>' into handlers['log']['logging']
2014-04-15 12:28:24,713 (DEBUG) cement.core.extension : loading the 'cement.ext.ext_argparse' framework extension
2014-04-15 12:28:24,714 (DEBUG) cement.core.handler : registering handler '<class 'cement.ext.ext_argparse.ArgParseArgumentHandler'>' into handlers['argument']['argparse']
2014-04-15 12:28:24,714 (DEBUG) cement.core.foundation : setting up helloworld.config handler
2014-04-15 12:28:24,714 (DEBUG) cement.ext.ext_configparser : config file '/etc/helloworld/helloworld.conf' does not exist, skipping...
2014-04-15 12:28:24,714 (DEBUG) cement.ext.ext_configparser : config file '/Users/derks/.helloworld/config' does not exist, skipping...
2014-04-15 12:28:24,715 (DEBUG) cement.core.foundation : no cache handler defined, skipping.
2014-04-15 12:28:24,715 (DEBUG) cement.core.foundation : setting up helloworld.log handler
2014-04-15 12:28:24,715 (DEBUG) cement.core.handler : merging config defaults from '<cement.ext.ext_logging.LoggingLogHandler object at 0x1015c4ed0>' into section 'log.logging'
2014-04-15 12:28:24,715 (DEBUG) helloworld:None : logging initialized for 'helloworld:None' using LoggingLogHandler
2014-04-15 12:28:24,715 (DEBUG) cement.core.foundation : setting up helloworld.plugin handler
2014-04-15 12:28:24,715 (DEBUG) cement.ext.ext_plugin : plugin config dir /Users/derks/Development/boss/tmp/helloworld/config/plugins.d does not exist.
2014-04-15 12:28:24,716 (DEBUG) cement.core.foundation : setting up helloworld.arg handler
2014-04-15 12:28:24,716 (DEBUG) cement.core.foundation : setting up helloworld.output handler
2014-04-15 12:28:24,716 (DEBUG) cement.core.foundation : setting up application controllers
Hello World
2014-04-15 12:28:24,716 (DEBUG) cement.core.foundation : closing the application
Damn son, WTF? Don’t worry, we’ll explain everything in the rest of the doc.
Getting Warmer¶
The following is a more advanced example that showcases some of the default application features. Notice the creation of command line arguments, default config creation, and logging.
myapp.py
from cement.core.foundation import CementApp
from cement.core import hook
from cement.utils.misc import init_defaults
# define our default configuration options
defaults = init_defaults('myapp')
defaults['myapp']['debug'] = False
defaults['myapp']['some_param'] = 'some value'
# define any hook functions here
def my_cleanup_hook(app):
pass
# define the application class
class MyApp(CementApp):
class Meta:
label = 'myapp'
config_defaults = defaults
extensions = ['daemon', 'memcached', 'json', 'yaml']
hooks = [
('pre_close', my_cleanup_hook),
]
with MyApp() as app:
# add arguments to the parser
app.args.add_argument('-f', '--foo', action='store', metavar='STR',
help='the notorious foo option')
# log stuff
app.log.debug("About to run my myapp application!")
# run the application
app.run()
# continue with additional application logic
if app.pargs.foo:
app.log.info("Received option: foo => %s" % app.pargs.foo)
And execution:
$ python myapp.py --help
usage: myapp.py (sub-commands ...) [options ...] {arguments ...}
optional arguments:
-h, --help show this help message and exit
--debug toggle debug output
--quiet suppress all output
-f STR, --foo STR the notorious foo option
$ python myapp.py --foo=bar
INFO: Received option: foo => bar
Diving Right In¶
This final example demonstrates the use of application controllers that handle command dispatch and rapid development.
myapp.py
from cement.core.foundation import CementApp
from cement.core.controller import CementBaseController, expose
class MyBaseController(CementBaseController):
class Meta:
label = 'base'
description = "My Application does amazing things!"
arguments = [
( ['-f', '--foo'],
dict(action='store', help='the notorious foo option') ),
( ['-C'],
dict(action='store_true', help='the big C option') ),
]
@expose(hide=True)
def default(self):
self.app.log.info('Inside MyBaseController.default()')
if self.app.pargs.foo:
print("Recieved option: foo => %s" % self.app.pargs.foo)
@expose(help="this command does relatively nothing useful")
def command1(self):
self.app.log.info("Inside MyBaseController.command1()")
@expose(aliases=['cmd2'], help="more of nothing")
def command2(self):
self.app.log.info("Inside MyBaseController.command2()")
class MySecondController(CementBaseController):
class Meta:
label = 'second'
stacked_on = 'base'
@expose(help='this is some command', aliases=['some-cmd'])
def second_cmd1(self):
self.app.log.info("Inside MySecondController.second_cmd1")
class MyApp(CementApp):
class Meta:
label = 'myapp'
base_controller = 'base'
handlers = [MyBaseController, MySecondController]
with MyApp() as app:
app.run()
As you can see, we’re able to build out the core functionality of our app such as arguments and sub-commands via controller classes.
Lets see what this looks like:
$ python myapp.py --help
usage: myapp.py (sub-commands ...) [options ...] {arguments ...}
My Application does amazing things!
commands:
command1
this command does relatively nothing useful
command2 (aliases: cmd2)
more of nothing
second-cmd1 (aliases: some-cmd)
this is some command
optional arguments:
-h, --help show this help message and exit
--debug toggle debug output
--quiet suppress all output
-f FOO, --foo FOO the notorious foo option
-C the big C option
$ python myapp.py
INFO: Inside MyBaseController.default()
$ python myapp.py command1
INFO: Inside MyBaseController.command1()
$ python myapp.py command2
INFO: Inside MyBaseController.command2()
$ python myapp.py second-cmd1
INFO: Inside MySecondController.second_cmd1()