xotl.tools.cli – Command line application facilities

Tools for Command-Line Interface (CLI) applications.

Warning

Deprecated since 2.1.11

Deprecated since version 2.1.11: This module is completely deprecated. Please use a dedicated package like click.

CLI is a mean 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).

Commands can be registered by:

• sub-classing the Command,
• using register() ABC mechanism for virtual sub-classes,
• redefining Command.sub_commands class method.

New in version 1.4.1.

class xotl.tools.cli.Command

Base for all commands.

run(args=None)

Must return a valid value for “sys.exit”

class xotl.tools.cli.CommandMeta

Meta-class for all commands.

cli_name()

Calculate the command name.

Standard method uses ~xotl.tools.cli.tools.hyphen_name. Redefine it to obtain a different behaviour.

Example:

>>> class MyCommand(Command):
...     pass

>>> MyCommand.cli_name() == 'my-command'
True

register(subclass)

Register a virtual subclass of a Command.

Returns the sub-command, to allow usage as a class decorator.

Note

Python 3.7 hides internal registry (_abc_registry), so a sub-commands registry is implemented.

set_default_command(cmd=None)

Default command is called 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 xotl.tools.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:

__overwrite__ = True

classmethod get_arg_parser()

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

Use class method “get

run(args=[])

Must return a valid value for “sys.exit”

Applications

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

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

xotl.tools.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.

• program_name(): calculate the program name from “sys.argv[0]”.

• command_name() : calculate command names using class names in lower

  case inserting a hyphen before each new capital letter.

xotl.tools.cli.tools.command_name(cls)

Calculate a command name from given class.

Names are calculated putting class names in lower case and inserting hyphens before each new capital letter. For example “MyCommand” will generate “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:
...     pass

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

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

>>> class SomeCommand:
...    command_cli_name = 'adduser'

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

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

>>> class SomeCommand:
...    command_cli_name = None

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

xotl.tools.cli.tools.hyphen_name(name, join_numbers=True)

Convert a name to a hyphened slug.

Expects a name in Camel-Case. All invalid characters (those invalid in Python identifiers) are ignored. Numbers are joined with preceding part when join_numbers is True.

For example:

>>> hyphen_name('BaseNode') == 'base-node'
True

>> hyphen_name('--__ICQNámeP12_34Abc--') == 'icq-name-p12-34-abc'
True

>> hyphen_name('ICQNámeP12', join_numbers=False) == 'icq-name-p-12'
True

xotl.tools.cli.tools.program_name()

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