shellbot.bot module

class shellbot.bot.ShellBot(engine, channel_id=None, space=None, store=None, fan=None, machine=None)

Bases: object

Manages interactions with one space, one store, one state machine

A bot consists of multiple components devoted to one chat channel: - a space - a store - a state machine - ... other optional components that may prove useful

It is designated by a unique id, that is also the unique id of the channel itself.

A bot relies on an underlying engine instance for actual access to the infrastructure, including configuration settings.

The life cycle of a bot can be described as follows:

1. A bot is commonly created from the engine, or directly:

   bot = ShellBot(engine, channel_id='123')
   

2. The space is connected to some back-end API:

   space.connect()
   

3. Multiple channels can be handled by a single space:

   channel = space.create(title)
   
   channel = space.get_by_title(title)
   channel = space.get_by_id(id)
   
   channel.title = 'A new title'
   space.update(channel)
   
   space.delete(id)
   

   Channels feature common attributes, yet can be extended to convey specificities of some platforms.

4. Messages can be posted:

   space.post_message(id, 'Hello, World!')
   

5. The interface allows for the addition or removal of channel participants:

   space.add_participants(id, persons)
   space.add_participant(id, person, is_moderator)
   space.remove_participants(id, persons)
   space.remove_participant(id, person)
   

add_participant(person, is_moderator=False)

Adds one participant

Parameters:person (str) – e-mail addresses of person to add

The underlying platform may, or not, take the optional parameter is_moderator into account. The default bahaviour is to discard it, as if the parameter had the value False.

add_participants(persons=[])

Adds multiple participants

Parameters:persons (list of str) – e-mail addresses of persons to add

append(key, item)

Appends an item to a list

Parameters:

• key (str) – name of the list
• item (any serializable type is accepted) – a new item to append

Example:

>>>bot.append('names', 'Alice')
>>>bot.append('names', 'Bob')
>>>bot.recall('names')
['Alice', 'Bob']

bond()

Bonds to a channel

This function is called either after the creation of a new channel, or when the bot has been invited to an existing channel. In such situations the banner should be displayed as well.

There are also situations where the engine has been completely restarted. The bot bonds to a channel where it has been before. In that case the banner should be avoided.

dispose(**kwargs)

Disposes all resources

This function deletes the underlying channel in the cloud and resets this instance. It is useful to restart a clean environment.

>>>bot.bond(title=”Working Space”) ... >>>bot.dispose()

After a call to this function, bond() has to be invoked to return to normal mode of operation.

forget(key=None)

Forgets a value or all values

Parameters:key (str) – name of the value to forget, or None

To clear only one value, provides the name of it. For example:

bot.forget('variable_123')

To clear all values in the store, just call the function without a value. For example:

bot.forget()

id

Gets unique id of the related chat channel

Returns:the id of the underlying channel, or None

is_ready

Checks if this bot is ready for interactions

Returns:True or False

on_bond()

Adds processing to channel bonding

This function should be changed in sub-class, where necessary.

Example:

def on_bond(self):
    do_something_important_on_bond()

on_enter()

Enters a channel

on_exit()

Exits a channel

on_init()

Adds to bot initialization

It can be overlaid in subclass, where needed

on_reset()

Adds processing to space reset

This function should be expanded in sub-class, where necessary.

Example:

def on_reset(self):
    self._last_message_id = 0

recall(key, default=None)

Recalls a value

Parameters:

• key (str) – name of the value
• default (any serializable type is accepted) – default value

Returns:

the actual value, or the default value, or None

Example:

value = bot.recall('variable_123')

remember(key, value)

Remembers a value

Parameters:

• key (str) – name of the value
• value (any serializable type is accepted) – new value

This functions stores or updates a value in the back-end storage system.

Example:

bot.remember('variable_123', 'George')

remove_participant(person)

Removes one participant

Parameters:person (str) – e-mail addresses of person to add

remove_participants(persons=[])

Removes multiple participants

Parameters:persons (list of str) – e-mail addresses of persons to remove

reset()

Resets a space

After a call to this function, bond() has to be invoked to return to normal mode of operation.

say(text=None, content=None, file=None, person=None)

Sends a message to the chat space

Parameters:

• text (str or None) – Plain text message
• content (str or None) – Rich content such as Markdown or HTML
• file (str or None) – path or URL to a file to attach
• person (str) – for direct message to someone

say_banner()

Sends banner to the channel

This function uses following settings from the context:

• bot.banner.text or bot.on_enter - a textual message
• bot.banner.content - some rich content, e.g., Markdown or HTML
• bot.banner.file - a document to be uploaded

The quickest setup is to change bot.on_enter in settings, or the environment variable $BOT_ON_ENTER.

Example:

os.environ['BOT_ON_ENTER'] = 'You can now chat with Batman'
engine.configure()

Then there are situtations where you want a lot more flexibility, and rely on a smart banner. For example you could do the following:

settings = {
    'bot': {
        'banner': {
            'text': u"Type '@{} help' for more information",
            'content': u"Type ``@{} help`` for more information",
            'file': "http://on.line.doc/guide.pdf"
        }
    }
}

engine.configure(settings)

When bonding to a channel, the bot will send an update similar to the following one, with a nice looking message and image:

Type '@Shelly help' for more information

Default settings for the banner rely on the environment, so it is easy to inject strings from the outside. Use following variables:

• $BOT_BANNER_TEXT or $BOT.ON_ENTER - the textual message
• $BOT_BANNER_CONTENT - some rich content, e.g., Markdown or HTML
• $BOT_BANNER_FILE - a document to be uploaded

title

Gets title of the related chat channel

Returns:the title of the underlying channel, or None

update(key, label, item)

Updates a dict

Parameters:

• key (str) – name of the dict
• label (str) – named entry in the dict
• item (any serializable type is accepted) – new value of this entry

Example:

>>>bot.update('input', 'PO Number', '1234A')
>>>bot.update('input', 'description', 'some description')
>>>bot.recall('input')
{'PO Number': '1234A',
 'description': 'some description'}