tea.commander

class tea.commander.BaseCommand(config, ui)

The base class from which all management commands ultimately derive.

Use this class if you want access to all of the mechanisms which parse the command-line arguments and work out what code to call in response; if you don’t need to change any of that behavior, consider using one of the subclasses defined in this file.

If you are interested in overriding/customizing various aspects of the command-parsing and -execution behavior, the normal flow works as follows:

1. Loads the command class and calls its run_from_argv() method.
2. The run_from_argv() method calls create_parser() to get an OptionParser for the arguments, parses them, performs any environment changes requested by options, and then calls the execute() method, passing the parsed arguments.
3. The execute() method attempts to carry out the command by calling the handle() method with the parsed arguments; any output produced by handle() will be printed to standard output.
4. If handle() raised a CommandError, execute() will instead print an error message to stderr.

Thus, the handle() method is typically the starting point for subclasses.

Several attributes affect behavior at various steps along the way:

args

A string listing the arguments accepted by the command, suitable for use in help messages; e.g., a command which takes a list of application names might set this to ‘<appname appname ...>’.

option_list

This is the list of optparse options which will be fed into the command’s OptionParser for parsing arguments.

create_parser(prog_name, subcommand)

Create and return the OptionParser which will be used to parse the arguments to this command.

execute(*args, **options)

Try to execute this command, performing validations if needed (as controlled by the attributes. If the command raises a CommandError, intercept it and print it sensibly to stderr.

handle(*args, **options)

The actual logic of the command. Subclasses must implement this method.

print_help(prog_name, subcommand)

Print the help message for this command, derived from self.usage().

run_from_argv(argv)

Set up any environment changes requested (e.g., Python path, then run this command.

usage(subcommand=None)

Return a brief description of how to use this command, by default from the attribute self.__doc__.

validate()

Validates the given command, raising CommandError for any errors.

exception tea.commander.CommandError

Exception class indicating a problem while executing a command.

If this exception is raised during the execution of a management command, it will be caught and turned into a nicely-printed error message to the appropriate output stream (i.e., stderr); as a result, raising this exception (with a sensible description of the error) is the preferred way to indicate that something has gone wrong in the execution of a command.

class tea.commander.Application(argv, command_modules, preparser=None, app_config=None, config=None, ui=None)

Encapsulates the logic of the commander.

A ManagementUtility has a number of commands, which can be manipulated by editing the self.commands dictionary.

commands: python module path to commands module

execute()

Given the command-line arguments, this figures out which subcommand is being run, creates a parser appropriate to that command, and runs it.

fetch_command_klass(config, subcommand)

Tries to fetch the given subcommand, printing a message with the appropriate command called from the command line if it can’t be found.

main_help_text(config, commands_only=False)

Returns the script’s main help text, as a string.

class tea.commander.UserInterface

Abstract class representing user interface object for commander.

Commander Application can be provided with a custom implementation of the UserInterface so it can be used in different environments, i.e. console, gui, web application...

Every command will receive a UserInterface object in it’s constructor and can call all methods to provide user feedback.

Initialization method

ask(message=None, password=False, strip=False)

Ask for user input

This method should ask the user for input, presenting to user a message and returning a string. Also if password is set to True, user should not be able to see what he types

error(message, newline=True)

Present an error message to the user

info(message, newline=True)

Present an information message to the user

message(message, newline=True)

Show just an ordinary message to the user

report(obj, status=0, data=None)

This is the central part of the user interface. Every command does some amount of work. This work can be represented in steps. Command should report to the user interface on every finished step so the user can have a live stream of information from the command. Every report contains three parts:

Parameters:

• obj – The object on which the operation is performed. The object should be either a dictionary or have a __serialize__ method that serializes it to dict
• status – Status of the operation. No status is considered to be successful or unsuccessful. It’s just an integer that represents the status of the operation.
• data – Custom data provided by the command. This also has to be either dict or has a __serialize__ method, that serializes it to dict.

warn(message, newline=True)

Present a warning message to the user

class tea.commander.ConsoleUserInterface

Simple implementation of the user interface intended for usage in console applications.

If no other UserInterface implementation is provided to commander it will use this user interface

class tea.commander.base.BaseCommand(config, ui)

The base class from which all management commands ultimately derive.

Use this class if you want access to all of the mechanisms which parse the command-line arguments and work out what code to call in response; if you don’t need to change any of that behavior, consider using one of the subclasses defined in this file.

If you are interested in overriding/customizing various aspects of the command-parsing and -execution behavior, the normal flow works as follows:

1. Loads the command class and calls its run_from_argv() method.
2. The run_from_argv() method calls create_parser() to get an OptionParser for the arguments, parses them, performs any environment changes requested by options, and then calls the execute() method, passing the parsed arguments.
3. The execute() method attempts to carry out the command by calling the handle() method with the parsed arguments; any output produced by handle() will be printed to standard output.
4. If handle() raised a CommandError, execute() will instead print an error message to stderr.

Thus, the handle() method is typically the starting point for subclasses.

Several attributes affect behavior at various steps along the way:

args

A string listing the arguments accepted by the command, suitable for use in help messages; e.g., a command which takes a list of application names might set this to ‘<appname appname ...>’.

option_list

This is the list of optparse options which will be fed into the command’s OptionParser for parsing arguments.

create_parser(prog_name, subcommand)

Create and return the OptionParser which will be used to parse the arguments to this command.

execute(*args, **options)

Try to execute this command, performing validations if needed (as controlled by the attributes. If the command raises a CommandError, intercept it and print it sensibly to stderr.

handle(*args, **options)

The actual logic of the command. Subclasses must implement this method.

print_help(prog_name, subcommand)

Print the help message for this command, derived from self.usage().

run_from_argv(argv)

Set up any environment changes requested (e.g., Python path, then run this command.

usage(subcommand=None)

Return a brief description of how to use this command, by default from the attribute self.__doc__.

validate()

Validates the given command, raising CommandError for any errors.

class tea.commander.base.LabelCommand(config, ui)

A management command which takes one or more arbitrary arguments (labels) on the command line, and does something with each of them.

Rather than implementing handle(), subclasses must implement handle_label(), which will be called once for each label.

handle_label(label, **options)

Perform the command’s actions for label, which will be the string as given on the command line.

class tea.commander.base.NoArgsCommand(config, ui)

A command which takes no arguments on the command line.

Rather than implementing handle(), subclasses must implement handle_noargs(); handle() itself is overridden to ensure no arguments are passed to the command.

Attempting to pass arguments will raise CommandError.

handle_noargs(**options)

Perform this command’s actions.

exception tea.commander.exceptions.CommandError

Exception class indicating a problem while executing a command.

If this exception is raised during the execution of a management command, it will be caught and turned into a nicely-printed error message to the appropriate output stream (i.e., stderr); as a result, raising this exception (with a sensible description of the error) is the preferred way to indicate that something has gone wrong in the execution of a command.

class tea.commander.ui.ConsoleUserInterface

Simple implementation of the user interface intended for usage in console applications.

If no other UserInterface implementation is provided to commander it will use this user interface

class tea.commander.ui.UserInterface

Abstract class representing user interface object for commander.

Commander Application can be provided with a custom implementation of the UserInterface so it can be used in different environments, i.e. console, gui, web application...

Every command will receive a UserInterface object in it’s constructor and can call all methods to provide user feedback.

Initialization method

ask(message=None, password=False, strip=False)

Ask for user input

This method should ask the user for input, presenting to user a message and returning a string. Also if password is set to True, user should not be able to see what he types

error(message, newline=True)

Present an error message to the user

info(message, newline=True)

Present an information message to the user

message(message, newline=True)

Show just an ordinary message to the user

report(obj, status=0, data=None)

This is the central part of the user interface. Every command does some amount of work. This work can be represented in steps. Command should report to the user interface on every finished step so the user can have a live stream of information from the command. Every report contains three parts:

Parameters:

• obj – The object on which the operation is performed. The object should be either a dictionary or have a __serialize__ method that serializes it to dict
• status – Status of the operation. No status is considered to be successful or unsuccessful. It’s just an integer that represents the status of the operation.
• data – Custom data provided by the command. This also has to be either dict or has a __serialize__ method, that serializes it to dict.

warn(message, newline=True)

Present a warning message to the user

class tea.commander.application.Application(argv, command_modules, preparser=None, app_config=None, config=None, ui=None)

Encapsulates the logic of the commander.

A ManagementUtility has a number of commands, which can be manipulated by editing the self.commands dictionary.

commands: python module path to commands module

execute()

Given the command-line arguments, this figures out which subcommand is being run, creates a parser appropriate to that command, and runs it.

fetch_command_klass(config, subcommand)

Tries to fetch the given subcommand, printing a message with the appropriate command called from the command line if it can’t be found.

main_help_text(config, commands_only=False)

Returns the script’s main help text, as a string.

tea.commander.options.create_parser(options, description='', defaults=None, app_config=None)

Create a options parser form configuration

Parameters:

• options – dictionary of configurations
• defaults – default values
• configuration – name of the json file with default options for this user

tea.commander.options.parse_arguments(args, options, description='', defaults=None, app_config=None, check_and_set_func=None)

Create a options parser form configuration and parse arguments

Parameters:

• args – arguments to parse
• options – dictionary of configurations
• defaults – default values
• inifile – ini file with default values for this user
• check_and_set_func – function that receives options, and checks and sets additional values