`cement.ext.ext_argparse`

Cement argparse extension module.

class cement.ext.ext_argparse.ArgparseArgumentHandler(*args, **kw)[source]

Bases: ArgumentParser, ArgumentHandler

This class implements the Argument Handler interface, and sub-classes from argparse.ArgumentParser. Please reference the argparse documentation for full usage of the class.

Arguments and keyword arguments are passed directly to ArgumentParser on initialization.

class Meta[source]

Bases: object

Handler meta-data.

ignore_unknown_arguments = False

Whether or not to ignore any arguments passed that are not defined. Default behavoir by Argparse is to raise an “unknown argument” exception by Argparse.

This affectively triggers the difference between using parse_args and parse_known_args. Unknown arguments will be accessible as unknown_args.

interface = 'argument': The interface that this class implements.

label = 'argparse': The string identifier of the handler.

add_argument(*args, **kw)[source]: Add an argument to the parser. Arguments and keyword arguments are passed directly to ArgumentParser.add_argument(). See the argparse.ArgumentParser documentation for help.

parse(arg_list)[source]

Parse a list of arguments, and return them as an object. Meaning an argument name of ‘foo’ will be stored as parsed_args.foo.

Parameters:: arg_list (list) – A list of arguments (generally sys.argv) to be parsed.
Returns:: Instance object whose members are the arguments parsed.
Return type:: object

class cement.ext.ext_argparse.ArgparseController(*args, **kw)[source]

Bases: ControllerHandler

This is an implementation of the Controller handler interface, and is 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 or modify this one.

Example

from cement.ext.ext_argparse import ArgparseController

class Base(ArgparseController):
    class Meta:
        label = 'base'
        description = 'description at the top of --help'
        epilog = "the text at the bottom of --help."
        arguments = [
            (
                ['-f', '--foo'],
                { 'help' : 'my foo option',
                  'dest' : 'foo' }
            ),
        ]

class Second(ArgparseController):
    class Meta:
        label = 'second'
        stacked_on = 'base'
        stacked_type = 'embedded'
        arguments = [
            (
                ['--foo2'],
                { 'help' : 'my foo2 option',
                  'dest' : 'foo2' }
            ),
        ]

class Meta[source]

Bases: object

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

aliases = []: A list of aliases for the controller/sub-parser. Only available in Python > 3.

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(help='foo option', dest='foo') ), ]

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

add_argument('-f', '--foo', help='foo option', dest='foo')

config_defaults = {}

dict) that are merged into the applications config object for the config_section mentioned above.

Type:: Configuration defaults (type

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. By default this is _default, which is equivelant to passing -h/--help. It should be noted that this is the only place where having a command function start with _ is OK simply because we treat it as a special case (different that other exposed commands).

If set to None, Cement will simply pass and exit 0.

Note: Currently, default function/sub-command only works on Python > 3.4. Previous versions of Python/Argparse will throw the exception error: too few arguments.

description = None: Description for the sub-parser group in help output.

epilog = None: The text that is displayed at the bottom when --help is passed.

help = None: Text for the controller/sub-parser group in help output (for nested stacked controllers only).

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

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

parser_options = {}: Additional keyword arguments passed when ArgumentParser.add_parser() is called to create this controller sub-parser. WARNING: This could break things, use at your own risk. Useful if you need additional features from Argparse that is not built into the controller Meta-data.

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’s namespace, or to nest this controller under the parent controller (making it a sub-command). Must be one of ['embedded', 'nested'].

subparser_options = {}: Additional keyword arguments passed when ArgumentParser.add_subparsers() is called to create this controller namespace. WARNING: This could break things, use at your own risk. Useful if you need additional features from Argparse that is not built into the controller Meta-data.

title = 'sub-commands': The title for the sub-parser group in help output.

usage = None: The text that is displayed at the top when --help is passed. Defaults to Argparse standard usage.

_dispatch()[source]

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:: The result of the executed controller function, or None if no controller function is called.
Return type:: unknown

_get_exposed_commands()[source]

Get a list of exposed commands for this controller

Returns:: List of exposed commands (labels)
Return type:: exposed_commands (list)

_post_argument_parsing()[source]

Called on every controller just after arguments are parsed (assuming that the parser hasn’t thrown an exception). Provides an alternative means of handling passed arguments. Note that, this function is called on every controller, regardless of what namespace and sub-command is eventually going to be called. Therefore, every controller can handle their arguments if the user passed them.

For example:

$ myapp --foo bar some-controller --foo2 bar2 some-command

In the above, the base controller (or a nested controller) would handle --foo, while some-controller would handle foo2 before some-command is executed.

class Base(ArgparseController):
    class Meta:
        label = 'base'

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

    def _post_argument_parsing(self):
        if self.app.pargs.foo:
            print('Got Foo Option Before Controller Dispatch')

Note that self._parser within a controller is that individual controllers sub-parser, and is not the root parser app.args (unless you are the base controller, in which case self._parser is synonymous with app.args).

_pre_argument_parsing()[source]

Called on every controller just before arguments are parsed. Provides an alternative means of adding arguments to the controller, giving more control than using Meta.arguments.

Example

class Base(ArgparseController):
    class Meta:
        label = 'base'

    def _pre_argument_parsing(self):
        p = self._parser
        p.add_argument('-f', '--foo',
                       help='my foo option',
                       dest='foo')

    def _post_argument_parsing(self):
        if self.app.pargs.foo:
            print('Got Foo Option Before Controller Dispatch')

_validate()[source]: Perform any validation to ensure proper data, meta-data, etc.

cement.ext.ext_argparse.ex: alias of expose

class cement.ext.ext_argparse.expose(hide=False, arguments=[], label=None, **parser_options)[source]

Bases: object

Used to expose functions to be listed as sub-commands under the controller namespace. It also decorates the function with meta-data for the argument parser.

Keyword Arguments:

hide (bool) – Whether the command should be visible.
arguments (list) – List of tuples that define arguments to add to this commands sub-parser.
parser_options (dict) – Additional options to pass to Argparse.
label (str) – String identifier for the command.

Example

class Base(ArgparseController):
    class Meta:
        label = 'base'

    # Note: Default functions only work in Python > 3.4
    @expose(hide=True)
    def default(self):
        print("In Base.default()")

    @expose(
        help='this is the help message for my_command',
        aliases=['my_cmd'], # only available in Python 3+
        arguments=[
            (['-f', '--foo'],
             dict(help='foo option', action='store', dest='foo')),
        ]
    )
    def my_command(self):
        print("In Base.my_command()")

cement.ext.ext_argparse

`cement.ext.ext_argparse`