6. pypsi.core - Core classes for pluggable features

Base classes for developing pluggable commands and plugins.

6.1. Command objects

class pypsi.core.Command(name, usage=None, brief=None, topic=None, parser=None, pipe='str')[source]

Bases: object

A pluggable command that users can execute. All commands need to derive from this class. When a command is executed by a user, the command’s run() method will be called. The return value of the run() method is used when processing forthcoming commands in the active statement. The return value must be an int and follows the Unix standard: 0 on success, less than 0 on error, and greater than 0 given invalid input or incorrect usage.

Each command has a topic associated with it. This topic can be referenced by commands such as pypsi.commands.help.HelpCommand to categorize commands in help messages.

A command can be used as a fallback handler by implementing the fallback() method. This is similar to the run() method, except that is accepts one more argument: the command name to execute that wasn’t found by the shell. The return value of fallback() holds the same purpose as the return value of run().

By the time run() is called, the system streams have been updated to point to the current file streams issued in the statement. For example, if the statement redirects standard out (sys.stdout) to a file, the destination file is automatically opened and sys.stdout is redirected to the opened file stream. Once the command has complete execution, the redirected stream is automatically closed and sys.stdout is set to its original stream.

Parameters:
  • name (str) – the name of the command which the user will reference in the shell
  • usage (str) – the usage message to be displayed to the user
  • brief (str) – a brief description of the command
  • topic (str) – the topic that this command belongs to
  • pipe (str) – the type of data that will be read from and written to any pipes
complete(shell, args, prefix)[source]

Called when the user attempts a tab-completion action for this command.

Parameters:
  • shell (pypsi.shell.Shell) – the active shell
  • args (list) – the list of arguments, the last one containing the cursor position
  • prefix (str) – the prefix that all items returned must start with
Returns list:

the list of strings that could complete the current action
error(shell, *args)[source]

Display an error message to the user.

Parameters:
  • shell (pypsi.shell.Shell) – the active shell
  • args – the error message to display
fallback(shell, name, args)[source]

Called when this command was set as the fallback command. The only difference between this and run() is that this method accepts the command name that was entered by the user.

Parameters:
  • shell (pypsi.shell.Shell) – the active shell
  • name (str) – the name of the command to run
  • args (list) – arguments
Returns int:

0 on success, less than 0 on error, and greater than 0 on invalid usage
run(shell, args)[source]

Execute the command. All commands need to implement this method.

Parameters:
Returns int:

0 on success, less than 0 on error, and greater than 0 on invalid usage
setup(shell)[source]

Called when the plugin has been registered to the active shell.

Parameters:shell (pypsi.shell.Shell) – the active shell
Returns int:0 on success, -1 on error
usage_error(shell, *args)[source]

Display an error message that indicates incorrect usage of this command. After the error is displayed, the usage is printed.

Parameters:
  • shell (pypsi.shell.Shell) – the active shell
  • args – list of strings that are the error message

6.2. Plugin objects

class pypsi.core.Plugin(preprocess=None, postprocess=None)[source]

Bases: object

A plugin is an object that is able to modify a pypsi.shell.Shell object’s behavior. Whereas a command can be execute from user input, the Plugin class does not contain a run() function.

Constructor can take two parameters: preprocess and postprocess These values determine where the plugin resides inside of the preprocess and postprocess list. This list, inside of pypsi.shell.Shell, is iterated sequentially, from most priority to least. So, the highest priority value is 0, which means it will be the first plugin to run, and the lowest value is 100, which means it will be the last plugin to run. If either value is None, the plugin is not added to the processing list. For example, if this plugin only provides a preprocessing functionality, then postprocess should be set to None.

Parameters:
  • preprocess (int) – the preprocess priority
  • postprocess (int) – the postprocess priority
on_input(shell, line)[source]

Called after input from the user has been received. The return value is the preprocessed line. This means that modifying the line argument will not populate back. If this function does no preprocessing, return line unmodified.

Parameters:
Returns str:

the preprocessed line
on_input_canceled(shell)[source]

Called when the user can canceled entering a statement via SIGINT (Ctrl+C).

Parameters:shell (pypsi.shell.Shell) – the active shell
Returns int:0 on success, -1 on error
on_statement_finished(shell, rc)[source]

Called when a statement has been completely executed.

Parameters:shell (pypsi.shell.Shell) – the active shell
Returns int:0 on success, -1 on error
on_tokenize(shell, tokens, origin)[source]

Called after an input string has been tokenized. If this function performs no preprocessing, return the tokens unmodified.

Parameters:
  • shell (pypsi.shell.Shell) – the active shell
  • tokens (list) – the list of pypsi.cmdline.Token objects
  • origin (str) – the origin of the input, can be either ‘input’ if received from a call to input() or ‘prompt’ if the input is the prompt to display to the user
Returns list:

the list of preprocessed pypsi.cmdline.Token objects
setup(shell)[source]

Called after the plugin has been registered to the active shell.

Parameters:shell (pypsi.shell.Shell) – the active shell
Returns int:0 on success, -1 on failure

6.3. Argument parsing

class pypsi.core.PypsiArgParser(*args, **kwargs)[source]

Bases: argparse.ArgumentParser

Customized argparse.ArgumentParser for use in pypsi. This class slightly modifies the base ArgumentParser so that the following occurs:

  • The whole program does not exit on printing the help message or bad arguments
  • Any error messages are intercepted and printed on the active shell’s error stream
  • Adds the option to provide callbacks for tab-completing options and parameters
add_argument(*args, completer=None, **kwargs)[source]

Override add_argument function of argparse.ArgumentParser to handle callback functions. :param args: Positional arguments to pass up to argparse :param function completer: Optional callback function for argument :param kwargs: Keywork arguments to pass up to argparse :return:

get_option_completer(option)[source]

Returns the callback for the specified optional argument, Or None if one was not specified. :param str option: The Option :return function: The callback function or None

get_options()[source]
Returns:All optional arguments (ex, ‘-v’/’–verbose’)
get_positional_arg_index(args)[source]

Get the positional index of a cursor, based on optional arguments and positional arguments :param list args: List of str arguments from the Command Line :return:

get_positional_completer(pos)[source]

Get the callback for a positional parameter :param pos: index of the parameter - first param’s index = 0 :return: The callback if it exists, else None

has_value(arg)[source]

Check if the optional argument has a value associated with it. :param str arg: Optional argument to check :return: True if arg has a value, false otherwise

class pypsi.core.CommandShortCircuit(code)[source]

Bases: Exception

Exception raised when the user enter invalid arguments or requests usage information via the -h and –help flags.

Parameters:code (int) – the code the command should return

6.4. Enhanced Printing