shellbot package¶

Subpackages¶

Submodules¶

Module contents¶

class shellbot.Bus(context)[source]¶

Bases: object

Represents an information bus between publishers and subscribers

In the context of shellbot, channels are channel identifiers, and messages are python objects serializable with json.

A first pattern is the synchronization of direct channels from the group channel:

every direct channel is a subscriber, and filters messages sent to their own channel identifier
group channel is a publisher, and broadcast instructions to the list of direct channel identifiers it knows about

A second pattern is the observation by a group channel of what is happening in related direct channels:

every direct channel is a publisher, and the channel used is their own channel identifier
group channel is a subscriber, and observed messages received from all direct channels it knows about

For example, a distributed voting system can be built by combining the two patterns. The vote itself can be triggered simultaneously to direct channels on due time, so that every participants are involved more or less at the same time. And data that is collected in direct channels can ce centralised back to the group channel where results are communicated.

DEFAULT_ADDRESS = 'tcp://127.0.0.1:5555'¶

check()[source]¶

Checks configuration settings

This function reads key bus and below, and update the context accordingly. It handles following parameters:

bus.address - focal point of bus exchanges on the network. The default value is tcp://*:5555 which means ‘use TCP port 5555 on local machine’.

publish()[source]¶

Publishes messages

Returns:	Publisher

Example:

# get a publisher for subsequent broadcasts
publisher = bus.publish()

# start the publishing process
publisher.start()

...

# broadcast information_message
publisher.put(channel, message)

subscribe(channels)[source]¶

Subcribes to some channels

Parameters:	channels (str or list of str) – one or multiple channels
Returns:	Subscriber

Example:

# subscribe from all direct channels related to this group channel
subscriber = bus.subscribe(bot.direct_channels)

...

# get next message from these channels
message = subscriber.get()

class shellbot.Channel(attributes=None)[source]¶

Bases: object

Represents a chat channel managed by a space

A channel is a group of interactions within a chat space. It features a unique identifier, and a title. It also have participants and content.

This class is a general abstraction of a communication channel, that can easily been adapted to various chat systems. It has been designed as a dictionary wrapper, with minimum exposure to shellbot, while enabling the transmission of rich information through serialization.

Instances of Channel are created within a Space object, and consumed by it as well.

For example, to create a channel with a given title, you could write:

channel = space.create(title='A new channel')
bot.say(u"I am happy to join {}".format(channel.title))

And to change the title of the channel:

channel.title = 'An interesting place'
space.update(channel)

Direct channels support one-to-one interactions between the bot and one person. The creation of a direct channel can only be indirect, by sending an invitation to the target person. For example:

bot.say(person='foo.bar@acme.com',
        text='Do you want to deal with me?')

If the person receives and accepts the invitation, the engine will receive a join event and load a new bot devoted to the direct channel. So, at the end of the day, when multiple persons interact with a shellbot, this involve both group and direct channels.

For example, if you create a shellbot named shelly, that interacts with Alice and with Bob, then shelly will overlook multiple bots and channels:

shelly main channel (bot + channel + store + state machine)
direct channel with Alice (bot + channel + store + state machine)
direct channel with Bob (bot + channel + store + state machine)

get(key, default=None)[source]¶

Returns the value of one attribute :param key: name of the attribute :type key: str

Parameters:	default (str or other serializable object) – default value of the attribute
Returns:	value of the attribute
Return type:	str or other serializable object or None

The use case for this function is when you adapt a channel that does not feature an attribute that is expected by shellbot. More specifically, call this function on optional attributes so as to avoid AttributeError

id¶

Returns channel unique id

Return type:	str

is_direct¶

Indicates if this channel is only for one person and the bot

Return type:	str

A channel is deemed direct when it is reserved to one-to-one interactions. Else it is considered a group channel, with potentially many participants.

is_moderated¶

Indicates if this channel is moderated

Return type:	str

A channel is moderated when some participants have specific powers that others do not have. Else all participants are condidered the same and peer with each others.

title¶

Returns channel title

Return type:	str

class shellbot.Command(engine=None, **kwargs)[source]¶

Bases: object

Implements one command

execute(bot, arguments=None, **kwargs)[source]¶

Executes this command

Parameters:	bot (Shellbot) – The bot for this execution arguments (str or `None`) – The arguments for this command

The function is invoked with a variable number of arguments. Therefore the need for **kwargs, so that your code is safe in all cases.

The recommended signature for commands that handle textual arguments is the following:

``` def execute(self, bot, arguments=None, **kwargs):

... if arguments:

...

```

In this situation, arguments contains all text typed after the verb itself. For example, when the command magic is invoked with the string:

magic rub the lamp

then the related command instance is called like this:

magic = shell.command('magic')
magic.execute(bot, arguments='rub the lamp')

For commands that can handle file attachments, you could use following approach:

def execute(self,
            bot,
            arguments=None,
            attachment=None,
            url=None,
            **kwargs):
    ...
    if url:  # a document has been uploaded with this command
        content = bot.space.download_attachment(url)
        ...

Reference information on parameters provided by the shell:

bot - This is the bot instance for which the command is executed. From this you can update the chat with bot.say(), or access data attached to the bot in bot.store. The engine and all global items can be access with bot.engine.
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.

This function should report on progress by sending messages with one or multiple bot.say("Whatever response").

in_direct = True¶

in_group = True¶

information_message = None¶

is_hidden = False¶

keyword = None¶

on_init()[source]¶

Handles extended initialisation

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

Example:

def on_init(self):
    self.engine.register('stop', self)

usage_message = None¶

class shellbot.Context(settings=None, filter=None)[source]¶

Bases: object

Stores settings across multiple independent processing units

This is a key-value store, that supports concurrency across multiple processes.

apply(settings={})[source]¶

Applies multiple settings at once

Parameters:	settings (dict) – variables to be added to this context

check(key, default=None, is_mandatory=False, validate=None, filter=False)[source]¶

Checks some settings

Parameters:	key – the key that has to be checked default (str) – the default value if no statement can be found is_mandatory (bool) – raise an exception if keys are not found validate (callable) – a function called to validate values before the import filter (bool) – look at the content, and change it eventually

Example:

context = Context({
    'spark': {
        'room': 'My preferred room',
        'participants':
            ['alan.droit@azerty.org', 'bob.nard@support.tv'],
        'team': 'Anchor team',
        'token': 'hkNWEtMJNkODk3ZDZLOGQ0OVGlZWU1NmYtyY>',
        'webhook': "http://73a1e282.ngrok.io",
        'weird_token', '$WEIRD_TOKEN',
    }
})

context.check('spark.room', is_mandatory=True)
context.check('spark.team')
context.check('spark.weird_token', filter=True)

When a default value is provided, it is used to initialize properly a missing key:

context.check('general.switch', 'on')

Another usage is to ensure that a key has been set:

context.check('spark.room', is_mandatory=True)

Additional control can be added with the validation function:

context.check('general.switch',
              validate=lambda x: x in ('on', 'off'))

When filter is True, if the value is a string starting with ‘$’, then a variable with the same name is loaded from the environment:

>>>token=context.check('spark.weird_token', filter=True)
>>>assert token == os.environ.get('WEIRD_TOKEN')
True

The default filter can be changed at the creation of a context:

>>>context=Context(filter=lambda x : x + '...')

This function raises KeyError if a mandatory key is absent. If a validation function is provided, then a ValueError can be raised as well in some situations.

clear()[source]¶: Clears content of a context

decrement(key, delta=1)[source]¶: Decrements a value

get(key, default=None)[source]¶

Retrieves the value of one configurationkey

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:

message = context.get('bot.on_start')

This function is safe on multiprocessing and multithreading.

has(prefix)[source]¶

Checks the presence of some prefix

Parameters:	prefix (str) – key prefix to be checked
Returns:	True if one or more key start with the prefix, else False

This function looks at keys actually used in this context, and return True if prefix is found. Else it returns False.

Example:

context = Context(settings={'space': {'title', 'a title'}})

>>>context.has('space')
True

>>>context.has('space.title')
True

>>>context.has('spark')
False

increment(key, delta=1)[source]¶: Increments a value

is_empty¶

Does the context store something?

Returns:	True if there at least one value, False otherwise

set(key, value)[source]¶

Changes the value of one configuration key

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

Example:

context.set('bot.on_start', 'hello world')

This function is safe on multiprocessing and multithreading.

classmethod set_logger(level=10)[source]¶

Configure logging

Parameters:	level – expected level of verbosity

This utility function should probably be put elsewhere

class shellbot.Engine(context=None, settings={}, configure=False, mouth=None, ears=None, fan=None, space=None, type=None, server=None, store=None, command=None, commands=None, driver=<class 'shellbot.bot.ShellBot'>, machine_factory=None, updater_factory=None, preload=0)[source]¶

Bases: object

Powers multiple bots

The engine manages the infrastructure that is used accross multiple bots acting in multiple spaces. It is made of an extensible set of components that share the same context, that is, configuration settings.

Shellbot allows the creation of bots with a given set of commands. Each bot instance is bonded to a single chat space. The chat space can be either created by the bot itself, or the bot can join an existing space.

The first use case is adapted when a collaboration space is created for semi-automated interactions between human and machines. In the example below, the bot controls the entire life cycle of the chat space. A chat space is created when the program is launched. And it is deleted when the program is stopped.

Example of programmatic chat space creation:

from shellbot import Engine, ShellBot, Context, Command
Context.set_logger()

# create a bot and load command
#
class Hello(Command):
    keyword = 'hello'
    information_message = u"Hello, World!"

engine = Engine(command=Hello(), type='spark')

# load configuration
#
engine.configure()

# create a chat space, or connect to an existing one
# settings of the chat space are provided
# in the engine configuration itself
#
engine.bond(reset=True)

# run the engine
#
engine.run()

# delete the chat channel when the engine is stopped
#
engine.dispose()

A second interesting use case is when a bot is invited to an existing chat space. On such an event, a new bot instance can be created and bonded to the chat space.

Example of invitation to a chat space:

def on_enter(self, channel_id):
    bot = engine.get_bot(channel_id=channel_id)

The engine is configured by setting values in the context that is attached to it. This is commonly done by loading the context with a dict before the creation of the engine itself, as in the following example:

context = Context({

    'bot': {
        'on_enter': 'You can now chat with Batman',
        'on_exit': 'Batman is now quitting the channel, bye',
    },

    'server': {
        'url': 'http://d9b62df9.ngrok.io',
        'hook': '/hook',
    },

})

engine = Engine(context=context)

engine.configure()

Please note that the configuration is checked and actually used on the call engine.configure(), rather on the initialisation itself.

When configuration statements have been stored in a separate text file in YAML format, then the engine can be initialised with an empty context, and configuration is loaded afterwards.

Example:

engine = Engine()
engine.configure_from_path('/opt/shellbot/my_bot.yaml')

When no configuration is provided to the engine, then default settings are considered for the engine itself, and for various components.

For example, for a basic engine interacting in a Cisco Spark channel:

engine = Engine(type='spark')
engine.configure()

When no indication is provided at all, the engine loads a space of type ‘local’.

So, in other terms:

engine = Engine()
engine.configure()

is strictly equivalent to:

engine = Engine('local')
engine.configure()

In principle, the configuration of the engine is set once for the full life of the instance. This being said, some settings can be changed globally with the member function set(). For example:

engine.set('bot.on_banner': 'Hello, I am here to help')

DEFAULT_SETTINGS = {'bot': {'banner.content': '$BOT_BANNER_CONTENT', 'on_enter': '$BOT_ON_ENTER', 'on_exit': '$BOT_ON_EXIT', 'banner.text': '$BOT_BANNER_TEXT', 'banner.file': '$BOT_BANNER_FILE'}}¶

bond(title=None, reset=False, participants=None, **kwargs)[source]¶

Bonds to a channel

Parameters:	title – title of the target channel reset (bool) – if True, delete previous channel and re-create one participants (list of str) – the list of initial participants (optional)
Type:	title: str
Returns:	Channel or None

This function creates a channel, or connect to an existing one. If no title is provided, then the generic title configured for the underlying space is used instead.

For example:

channel = engine.bond('My crazy channel')
if channel:
    ...

Note: this function asks the listener to load a new bot in its cache on successful channel creation or lookup. In other terms, this function can be called safely from any process for the creation of a channel.

build_bot(id=None, driver=<class 'shellbot.bot.ShellBot'>)[source]¶

Builds a new bot

Parameters:	id (str) – The unique id of the target space
Returns:	a ShellBot instance, or None

This function receives the id of a chat space, and returns the related bot.

build_machine(bot)[source]¶

Builds a state machine for this bot

Parameters:	bot (ShellBot) – The target bot
Returns:	a Machine instance, or None

This function receives a bot, and returns a state machine bound to it.

build_store(channel_id=None)[source]¶

Builds a store for this bot

Parameters:	channel_id (str) – Identifier of the target chat space
Returns:	a Store instance, or None

This function receives an identifier, and returns a store bound to it.

build_updater(id)[source]¶

Builds an updater for this channel

Parameters:	id (str) – The identifier of an audited channel
Returns:	an Updater instance, or None

This function receives a bot, and returns a state machine bound to it.

check()[source]¶

Checks settings of the engine

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

This function reads key bot and below, and update the context accordingly.

Example:

context = Context({

    'bot': {
        'on_enter': 'You can now chat with Batman',
        'on_exit': 'Batman is now quitting the channel, bye',
    },

    'server': {
        'url': 'http://d9b62df9.ngrok.io',
        'hook': '/hook',
    },

})
engine = Engine(context=context)
engine.check()

configure(settings={})[source]¶

Checks settings

Parameters:	settings (dict) – configuration information

If no settings is provided, and the context is empty, then self.DEFAULT_SETTINGS and self.space.DEFAULT_SETTINGS are used instead.

configure_from_file(stream)[source]¶

Reads configuration information

Parameters:	stream (file) – the handle that contains configuration information

The function loads configuration from the file and from the environment. Port number can be set from the command line.

configure_from_path(path='settings.yaml')[source]¶

Reads configuration information

Parameters:	path (str) – path to the configuration file

The function loads configuration from the file and from the environment. Port number can be set from the command line.

dispatch(event, **kwargs)[source]¶

Triggers objects that have registered to some event

Parameters:	event (str) – label of the event

Example:

def on_bond(self):
    self.dispatch('bond', bot=this_bot)

For each registered object, the function will look for a related member function and call it. For example for the event ‘bond’ it will look for the member function ‘on_bond’, etc.

Dispatch uses weakref so that it affords the unattended deletion of registered objects.

dispose(title=None, **kwargs)[source]¶

Destroys a named channel

Parameters:	title – title of the target channel
Type:	title: str

enumerate_bots()[source]¶: Enumerates all bots

get(key, default=None)[source]¶

Retrieves the value of one configuration key

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:

message = engine.get('bot.on_start')

This function is safe on multiprocessing and multithreading.

get_bot(channel_id=None, **kwargs)[source]¶

Gets a bot by id

Parameters:	channel_id (str) – The unique id of the target chat space
Returns:	a bot instance, or None

This function receives the id of a chat space, and returns the related bot.

If no id is provided, then the underlying space is asked to provide with a default channel, as set in overall configuration.

Note: this function should not be called from multiple processes, because this would create one bot per process. Use the function engine.bond() for the creation of a new channel.

get_hook()[source]¶: Provides the hooking function to receive messages from Cisco Spark

hook(server=None)[source]¶

Connects this engine with back-end API

Parameters:	server (Server) – web server to be used

This function adds a route to the provided server, and asks the back-end service to send messages there.

initialize_store(bot)[source]¶: Copies engine settings to the bot store

load_command(*args, **kwargs)[source]¶

Loads one commands for this bot

This function is a convenient proxy for the underlying shell.

load_commands(*args, **kwargs)[source]¶

Loads commands for this bot

This function is a convenient proxy for the underlying shell.

name¶

Retrieves the dynamic name of this bot

Returns:	The value of `bot.name` key in current context
Return type:	str

on_build(bot)[source]¶

Extends the building of a new bot instance

Parameters:	bot (ShellBot) – a new bot instance