xoutil.cli – Command line application facilities

Define tools for command-line interface (CLI) applications.

CLi is a means of interaction with a computer program where the user (or client) issues commands to the program in the form of successive lines of text (command lines).

New in version 1.4.1.

class xoutil.cli.Command

A command base registry.

There are several methods to register new commands:

• Inheriting from this class
• Using the ABC mechanism of register virtual subclasses.
• Registering a class with the method “__commands__” defined.

If the method “__commands__” is used, it must be a class or static method.

Command names are calculated as class names in lower case inserting a hyphen before each new capital letter. For example “MyCommand” will be used as “my-command”.

Each command could include its own argument parser, but it isn’t used automatically, all arguments will be passed as a single parameter to run() removing the command when obtained from “sys.argv”.

run(args=None)

Must return a valid value for “sys.exit”

classmethod set_default_command(cmd=None)

A default command can be defined for call it when no one is specified.

A command is detected when its name appears as the first command-line argument.

To specify a default command, use this method with the command as a string (the command name) or the command class.

If the command is specified, then the calling class is the selected one.

For example:

>>> Command.set_default_command('server')  
>>> Server.set_default_command()           
>>> Command.set_default_command(Server)    

class xoutil.cli.Help

Show all commands

Define the class attribute __order__ to sort commands in special command “help”.

Commands could define its help in the first line of a sequence of documentations until found:

• command class,
• “run” method,
• definition module.

This command could not be overwritten unless using the class attribute:

__override__ = True

classmethod get_arg_parser()

This is an example on how to build local argument parser.

Use class method “get

Applications

A simple main() entry point for CLI based applications.

This module provides an example of how to use xoutil.cli to create a CLI application.

xoutil.cli.app.main(default=None)

Execute a command, it can be given as the first program argument or it’s the default command is defined.

Tools

Utilities for command-line interface (CLI) applications.

xoutil.cli.tools.command_name(cls)

Command names are calculated as class names in lower case inserting a hyphen before each new capital letter. For example “MyCommand” will be used as “my-command”.

It’s defined as an external function because a class method don’t apply to minimal commands (those with only the “run” method).

Example:

>>> class SomeCommand(object):
...     pass

>>> command_name(SomeCommand) == 'some-command'
True

If the command class has an attribute command_cli_name, this will be used instead:

>>> class SomeCommand(object):
...    command_cli_name = 'adduser'

>>> command_name(SomeCommand) == 'adduser'
True

It’s an error to have a non-string command_cli_name attribute:

>>> class SomeCommand(object):
...    command_cli_name = None

>>> command_name(SomeCommand)  
Traceback (most recent call last):
   ...
TypeError: Attribute 'command_cli_name' must be a string.

xoutil.cli.tools.program_name()

Calculate the program name from “sys.argv[0]”.