Interactive Shell

Shell Class APIs

class okaara.shell.Shell(prompt=None, auto_render_menu=False, include_long_triggers=True)

Represents a single shell interface. A shell constists of one or more screens that drive the different sections of the shell. At any given time, only one screen is active. Only the active screen’s menu will be used when interacting with the user’s input. Based on the user’s decisions, the state of the shell may be transitioned between different screens.

This class contains methods screens and actions may use for transitioning between screens and interacting with user input.

__init__(prompt=None, auto_render_menu=False, include_long_triggers=True)

Creates an empty shell. At least one screen must be added to the shell before it is used.

Parameters:

• prompt (L{Prompt}) – specifies a prompt object to use for reading/writing to the console; if not specified will default to L{Prompt}
• auto_render_menu (bool) – if True, the menu will automatically be rendered after the execution of each menu item; defaults to False
• include_long_triggers (bool) – if True, the long versions of default triggers will be added, if False only single-character triggers will be added; defaults to True

add_menu_item(menu_item)

Adds a new menu item that will be available anywhere in the shell. Each menu item added to this screen must have a unique trigger. If a menu item with the same trigger already exists, it will be removed from the menu and replaced by the newly added item.

Parameters:menu_item (L{MenuItem}) – new item to add to the shell; may not be None

add_screen(screen, is_home=False)

Adds a new screen for the shell. If a screen was previously added with the same screen ID, the newly added screen will replace it.

Parameters:screen (L{Screen}) – describes a screen in the shell; may not be None

clear_screen()

Calls to the command line to clear the console.

execute(func, *args, **kwargs)

Executes a function selected by the user from a menu item. This call may raise Exit in order to quit the shell.

Subclasses should override this method to inject pre-run and post-run functionality.

home()

Transitions the state of the shell to the home screen.

previous()

Transitions the state of the shell to the previous screen. If there is no previous screen, the shell will be transitioned to the home screen.

render_menu(display_shell_menu=True)

Renders the menu for the current screen to the screen.

safe_start(show_menu=True, clear=True)

Launches the shell in an exception block to catch all unexpected exceptions to prevent the entire thing from crashing. If an exception is caught, the start loop will be restarted.

start(show_menu=True, clear=True)

Starts the loop to listen for user input and handle according to the current screen.

stop()

Causes the shell to stop listening for user commands.

transition(to_screen_id, show_menu=False, clear=False)

Transitions the state of the shell to the identified screen. If no screen exists with the given ID, the shell will be transitioned to the home screen.

Parameters:

• to_screen_id (string) – identifies the screen to change the shell to; may not be None
• show_menu (bool) – if True, the menu for the newly transitioned to screen will be displayed
• clear (bool) – if True, the screen will be cleared before the transition is made

Screen Class APIs

class okaara.shell.Screen(id)

A screen is an individual “section” of a shell. The granularity of its use will vary based on the application but can most easily be related to different screens in a graphical UI.

__init__(id)

Parameters:id (string) – uniquely identifies this screen instance in a shell; may not be None

add_menu_item(menu_item)

Adds a new menu item that will be available on this screen. Each menu item added to this screen must have a unique trigger. If a menu item with the same trigger already exists, it will be removed from the menu and replaced by the newly added item.

Parameters:menu_item (L{MenuItem}) – new item to add to this screen; may not be None

item(trigger)

Returns the menu item for the given trigger if one exists; None otherwise.

Parameters:trigger (string) – identifies the menu item being searched for Returns:menu item for the given trigger if one is found; None otherwise Return type:L{MenuItem} or None

items()

Returns a list of menu items in this screen.

Returns:list of menu items; empty list if none have been added Return type:list of L{MenuItem}

MenuItem Class APIs

class okaara.shell.MenuItem(triggers, description, func=<function noop at 0x31e9488>, *args, **kwargs)

An individual menu item the user can interact with. The shell instance will take care of determining which menu item the user has selected and invoking its associated function. Any extra arguments input by the user when calling the menu item will be passed to the function on invocation.

The shell reserves certain triggers for general use. Be sure that a menu item trigger does not overlap with one of the shell-level triggers defined in the shell instance.

__init__(triggers, description, func=<function noop at 0x31e9488>, *args, **kwargs)

Parameters:

• triggers (str or list) – character or string (or list of them) the user will input to cause the associated function to be invoked; may not be None
• description (string) – short (1-2 line) description of what the menu item does; displayed
• func (function) – function to invoke when this menu item is selected; extra arguments specified after the trigger will be passed to this function; may not be None
• args – arguments that will be passed to the function when it is executed
• kwargs – key word arguments to be passed to the function when it is executed

Exceptions

class okaara.shell.Exit

May be raised by any menu item function to stop the shell loop.