Arguments

Introduction to the Argument Interface

Cement defines an Argument Interface, as well as the default ArgParseArgumentHandler that implements the interface. This handler is built on top of the ArgParse module which is included in the Python standard library.

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 Argument Handlers:

API References:

Configuration

Application Meta Options

The following options under App.Meta modify configuration handling:

Option

Description

arg_handler

The handler that implements the argument interface.

Adding Arguments

The argument interface is loosely based on Argparse, but only defines a minimal set of params that must be honored as to ensure that the framework and extensions can add arguments regardless of what the argument handler implementation is. That said, Cement has never intended to use anything other than Argparse to handle arguments and for that reason there may be some assumptions inherently builtin that assume the underlying argument handler is 100% argparse compliant. For that reason, adding and working with arguments will be completely familiar for anyone who has ever used Argparse.

Example: Adding Arguments
cli
Example: Adding Arguments
from cement import App
with App('myapp') as app:
# add arguments before app.run()
app.args.add_argument('-f', '--foo',
action='store',
dest='foo')
# run the application (parses arguments)
app.run()
cli
$ python myapp.py --help
usage: myapp [-h] [-d] [-q] [-f FOO]
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

Accessing Parsed Arguments

During app.run(), command line arguments are parsed by the argument handler, and the results are stored by the application. Arguments are then accessible by App.pargs (parsed args).

Example: Accessing Parsed Arguments
Example: Accessing Parsed Arguments
from cement import App
with App('myapp') as app:
# add arguments before app.run()
app.args.add_argument('-f', '--foo',
action='store',
dest='foo')
# run the application (parses arguments)
app.run()
# test if argument was passed
if app.pargs.foo is not None:
print('Foo => %s ' app.pargs.foo

Creating an Argument Handler

All interfaces in Cement can be overridden with your own implementation. This can be done either by sub-classing ArgumentHandler itself, or by sub-classing an existing extension's handlers in order to alter their functionality.

Example: Creating an Argument Handler
Example: Creating an Argument Handler
myapp.py
from cement import App
from cement.core.arg import ArgumentHandler
class MyArgumentHandler(ArgumentHandler):
class Meta:
label = 'my_argument_handler'
# do something to implement the interface
class MyApp(App):
class Meta:
label = 'myapp'
argument_handler = 'my_argument_handler'
handlers = [
MyArgumentHandler,
]