shellbot.shell module

class shellbot.shell.Shell(engine)

Bases: object

Parses input and reacts accordingly

command(keyword)

Get one command

Parameters:keyword (str) – the keyword for this command Returns:the instance for this command Return type:command or None

Lists available commands and related usage information.

Example:

>>>print(shell.command('help').information_message)

commands

Lists available commands

Returns:a list of verbs Return type:list of str

This function provides with a dynamic inventory of all capabilities of this shell.

Example:

>>>print(shell.commands)
['*default', '*empty', 'help']

configure(settings={})

Checks settings of the shell

Parameters:settings (dict) – a dictionary with some statements for this instance

This function reads key shell and below, and update the context accordingly:

>>>shell.configure({'shell': {
       'commands':
          ['examples.exception.state', 'examples.exception.next']
       }})

This can also be written in a more compact form:

>>>shell.configure({'shell.commands':
       ['examples.exception.state', 'examples.exception.next']
       })

Note that this function does preserve commands that could have been loaded previously.

do(line, received=None)

Handles one line of text

Parameters:

• line (str) – a line of text to parse and to handle
• received (Message) – the message that contains the command

This function uses the first token as a verb, and looks for a command of the same name in the shell.

If the command does not exist, the command *default is used instead. Default behavior is implemented in shellbot.commands.default yet you can load a different command for customization.

If an empty line is provided, the command *empty is triggered. Default implementation is provided in shellbot.commands.empty.

When a file has been uploaded, the information is given to the command that is executed. If no message is provided with the file, the command *upload is triggered instad of *empty. Default implementation is provided in shellbot.commands.upload.

Following parameters are used for the execution of a command:

• bot - A bot instance is retrieved from the channel id mentioned in received, and provided to the command.
• arguments - This is a string that contains everything after the command verb. When hello How are you doing? is submitted to the shell, hello is the verb, and How are you doing? are the arguments. This is the regular case. If there is no command hello then the command *default is used instead, and arguments provided are the full line hello How are you doing?.
• attachment - When a file has been uploaded, this attribute provides its external name, e.g., picture024.png. This can be used in the executed command, if you keep in mind that the same name can be used multiple times in a conversation.
• url - When a file has been uploaded, this is the handle by which actual content can be retrieved. Usually, ask the underlying space to get a local copy of the document.

load_command(command)

Loads one command for this shell

Parameters:command (str or command) – A command to load

If a string is provided, it should reference a python module that can be used as a command. Check base.py in shellbot.commands for a clear view of what it means to be a vaid command for this shell.

Example:

>>>shell.load_command('shellbot.commands.help')

If an object is provided, it should duck type the command defined in base.py in shellbot.commands.

Example:

>>>from shellbot.commands.version import Version
>>>command = Version()
>>>shell.load_command(command)

load_commands(commands=[])

Loads commands for this shell

Parameters:commands (List of labels or list of commands) – A list of commands to load

Example:

>>>commands = ['shellbot.commands.help']
>>>shell.load_commands(commands)

Each label should reference a python module that can be used as a command. Check base.py in shellbot.commands for a clear view of what it means to be a vaid command for this shell.

If objects are provided, they should duck type the command defined in base.py in shellbot.commands.

Example:

>>>from shellbot.commands.version import Version
>>>version = Version()
>>>from shellbot.commands.help import Help
>>>help = Help()
>>>shell.load_commands([version, help])

load_default_commands()

Loads default commands for this shell

Example:

>>>shell.load_default_commands()