3. Pypsi Builtin Plugins

Pypsi ships with several useful plugins that enhance the shell.

3.1. Block Commands

class pypsi.plugins.block.BlockPlugin(end_cmd='end', preprocess=20, **kwargs)

Bases: pypsi.core.Plugin

Provide the ability to record multiple statements for future processing and execution. By itself, the BlockPlugin doesn’t do anything. Rather, new BlockCommand are developed that leverage this plugin’s preprocessor to record multiple statements from the user. Blocks are terminated the user inputs the value of end_cmd, at which point, the active BlockCommand is retrieved and BlockCommand.end_block() is called.

Parameters:end_cmd (str) – the statement that will terminate the active block

begin_block(shell, cmd)

Begin recording a new block.

Parameters:

• shell (pypsi.shell.Shell) – the active shell
• cmd (BlockCommand) – the active block command

end_block(shell)

End the block. Calls the active block command’s BlockCommand.end_block() method.

setup(shell)

Adds a reference to this instance in the shell’s context. Allows plugins and commands to get this plugin by accessing shell.ctx.block.

class pypsi.plugins.block.BlockCommand(prompt='> ', **kwargs)

Bases: pypsi.core.Command

Base class for any block commands that accept multiple statements from the user. Block commands allow the user to input several individual statement lines and postpone processing and execution until a later time. For example, the pypsi.commands.macro.MacroCommand is a block command that allows the user to record several statements and then execute them when the macro is called.

begin_block(shell)

Begin a block command and record subsequent statements to the block buffer.

end_block(shell, lines)

Called when a block has ended recording. Subclasses must implement this method.

Parameters:

• shell (pypsi.shell.Shell) – the active shell
• lines (list) – the list of unprocessed statements (str)

3.2. Escape Sequence Processors

class pypsi.plugins.hexcode.HexCodePlugin(preprocess=5, **kwargs)

Bases: pypsi.core.Plugin

Allows the user to input hex code escape sequences. Hex code sequences will be converted to a raw UTF8 character after processing. Escape sequences are in the format of: \xDD, where DD is a 2-digit hex value. This plugin can be used, for example, to print ANSI escape codes to the screen. To print the color red, for example, the user would input the sequence \x1b[1;31m.

class pypsi.plugins.multiline.MultilinePlugin(prompt='> ', preprocess=30, **kwargs)

Bases: pypsi.core.Plugin

Provides the ability to input and execute multiline statements. Input lines that end in the escape character \ can be continued on the subsequent input line. This allows for the user to type the following and produces the the statement:

echo this is a multiline \

statement

=>

echo this is a multiline statement

Parameters:prompt (str) – the prompt when recording a multiline statement

3.3. Shell History

class pypsi.plugins.history.HistoryPlugin(history_cmd='history', **kwargs)

Bases: pypsi.core.Plugin

Provides access to the shell’s statement history.

setup(shell)

Adds a reference to the current History in the shell’s context. The history can be accessed by retrieving the shell.ctx.history attribute.

class pypsi.plugins.history.HistoryCommand(name='history', brief='manage shell history', topic='shell', **kwargs)

Bases: pypsi.core.Command

Interact with and manage the shell’s history.

class pypsi.plugins.history.History

Bases: object

Wraps the readline module. Provides the following abilities:

• Accessing and manipulating history items via __getitem__(), __setitem__(), __delitem__(), and __iter__(). Indexes must be int and negative indexes are handled and automatically normalized before passing them to readline. __getitem__() also supports slicing, which also normalizes negative indexes.
• Appending new history items via append().
• Clearing all history items via clear().

Methods that access an index (or slice) will raise an IndexError if the index is invalid or out of range of the history.

__delitem__(index)

Delete a history event at index.

__getitem__(index)

Get a single event at index or a slice of events.

__iter__()

__len__()

Get the number of history events.

__setitem__(index, value)

Set the history event at index.

append(event)

Append a new history event.

Parameters:event (str) – event to append

clear()

Remove all history events.

search_prefix(prefix)

Find the most recent event that starts with the provided prefix. Provides a Bash ![prefix]-esque interface.

Parameters:prefix (str) – the prefix to search for Returns str:the event, if found, None if no matching event is found

3.4. Variables

class pypsi.plugins.variable.VariablePlugin(var_cmd='var', prefix='$', locals=None, env=True, topic='shell', case_sensitive=True, preprocess=10, postprocess=90, **kwargs)

Bases: pypsi.core.Plugin

Provides variable management and substitution in user input.

Parameters:

• var_cmd (str) – the name of the variable command
• prefix (str) – the prefix that all variables need to start with
• locals (dict) – the base variables to register initially
• case_sensitive (bool) – whether variable names are case sensitive

setup(shell)

Register the VariableCommand and add the vars attribute (pypsi.namespace.ScopedNamespace) to the shell’s context.

class pypsi.plugins.variable.VariableCommand(name='var', brief='manage local variables', topic='shell', **kwargs)

Bases: pypsi.core.Command

Manage variables.

class pypsi.plugins.variable.ManagedVariable(getter, setter=None)

Bases: object

Represents a variable that is managed by the shell. Managed variables have get and set hooks that allow for input validation or read-only enforcement. Each variable needs a getter, which is called to retrieve the value, and possibly a setter, which is called to set the value. If the setter is None, the variable is read-only. The setter must accept two arguments when it is called: the active Shell instance, and the str value.

Parameters:

• getter (callable) – the callable to call when retrieving the variable’s value (must return a value)
• setter (callable) – the callable to call when setting the variable’s value

3.5. Cmd

class pypsi.plugins.cmd.CmdPlugin(cmd_args=0, **kwargs)

Bases: pypsi.core.Plugin

Wraps existing cmd-based shell commands to be pypsi compatible. This plugin is designed to ease the transition from the cmd module and isn’t intended to be used in production. Tab completion is not supported for cmd commands.

Parameters:cmd_args (int) – determines how the command arguments are passed to the wrapped command (see CmdArgsList and CmdArgsString)

setup(shell)

Retrieves do_*() functions from the shell, parsing out help messages, generating FunctionCommand wrappers, and registering the commands to the shell.

class pypsi.plugins.cmd.CommandFunction(func, completer=None, cmd_args=0, **kwargs)

Bases: pypsi.core.Command

Wraps a function as a pypsi command.

Parameters:

• func (callable) – the function to wrap
• cmd_args (int) – whether to keep the arguments as a list or convert them to a single string

pypsi.plugins.cmd.CmdArgsList = 0

Keep command arguments as a list of strings

pypsi.plugins.cmd.CmdArgsString = 1

Turn the list of arguments to a single string