shellbot.commands package¶

Submodules¶

Module contents¶

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

Bases: shellbot.commands.base.Command

Checks and changes audit status

In essence, audit starts with the capture of information in real-time, and continues with the replication of information.

A typical use case is the monitoring of interactions happening in a channel, for security reasons, for compliancy or, simply speaking, for traceability.

Audit can be suspended explicitly by channel participants. This allows for some private exchanges that are not audited at all. However, then command is put in the audit log itself, so that people can be queried afterwards on their private interactions. If the parameter off_duration is set, then it is used by a watchdog to restart auditing. Else it is up to channel participants to activate or to de-activate auditing, at will.

The command itself allows for suspending or restarting the audit process. When audit has been activated in a channel, the attribute audit.switch.<channel_id> is set to on in the context. This can be checked by the observer while handling inbound records.

The audit has to be armed beforehand, and this is checked from the context attribute audit.has_been_armed. In normal cases, audit is armed from the underlying space by setting this attribute to True.

audit_off(bot)[source]¶

Activates private mode

Parameters:	bot (Shellbot) – The bot for this execution

audit_on(bot)[source]¶

Activates audit mode

Parameters:	bot (Shellbot) – The bot for this execution

audit_status(bot)[source]¶

Reports on audit status

Parameters:	bot (Shellbot) – The bot for this execution

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

Checks and changes audit status

Parameters:	bot (Shellbot) – The bot for this execution arguments (str) – either ‘on’ or ‘off’

has_been_enabled¶

Are we ready for auditing or not?

Return type:	bool

in_direct = False¶

off_duration = 60¶

on_bond(bot)[source]¶: Activates audit when a bot joins a channel

on_init()[source]¶: Localize strings for this command and register event

on_off(bot)[source]¶: Triggers watchdog when audit is disabled

watchdog(bot)[source]¶: Ensures that audit is restarted

class shellbot.commands.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.commands.Close(engine=None, **kwargs)[source]¶

Bases: shellbot.commands.base.Command

Closes the space

>>>close = Close(engine=my_engine) >>>shell.load_command(close)

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

Closes the space

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

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

in_direct = False¶

on_init()[source]¶: Localize strings for this command

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

Bases: shellbot.commands.base.Command

Handles unmatched command

This function looks for a named list and adds participants accordingly. Note that only list with attribute as_command set to true are considered.

In other cases, the end user is advised that the command is unknown.

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

Handles unmatched command

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

Arguments provided should include all of the user input, including the first token that has not been recognised as a valid command.

If arguments match a named list, then items of the list are added as participants to the channel. This applies only: - if the named list has the attribute as_command - and if this is not a direct channel (limited to 1:1 interactions)

is_hidden = True¶

on_init()[source]¶: Localize strings for this command

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

Bases: shellbot.commands.base.Command

Echoes input string

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

Echoes input string

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

is_hidden = True¶

on_init()[source]¶: Localize strings for this command

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

Bases: shellbot.commands.base.Command

Handles empty command

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

Handles empty command

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

is_hidden = True¶

on_init()[source]¶: Localize strings for this command

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

Bases: shellbot.commands.base.Command

Displays input data

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

Displays input data

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

on_init()[source]¶: Localize strings for this command

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

Bases: shellbot.commands.base.Command

Lists available commands and related usage information

allow(bot, command)[source]¶

Allows a command for this bot

Parameters:	bot (ShellBot) – Can be a direct channel, or a group channel command (Command) – Can be restricted either to direct or to group channels
Returns:	True is this command is allowed for this bot, else False

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

Lists available commands and related usage information

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

on_init()[source]¶: Localize strings for this command

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

Bases: shellbot.commands.base.Command

Does absolutely nothing

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

Does absolutely nothing

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

is_hidden = True¶

on_init()[source]¶: Localize strings for this command

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

Bases: shellbot.commands.base.Command

Sleeps for a while

DEFAULT_DELAY = 1.0¶

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

Sleeps for a while

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

is_hidden = True¶

on_init()[source]¶: Localize strings for this command

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

Bases: shellbot.commands.base.Command

Moves underlying state machine to the next step

This command sends an event to the current state machine. This can be handled by the state machine, e.g., a Steps instance, for moving forward.

You can check examples/pushy.py as a practical tutorial.

Example to load the command in the engine:

engine = Engine(commands=['shellbot.commands.step', ...])

By default, the command sends the event next to the state machine. This can be changed while creating your own command instance, before it is given to the engine. For example:

step = Steps(event='super_event')
engine = Engine(commands=[step, ...])

Obviously, this command should not be loaded if your use case does not rely on state machines, or if your state machines do not expect events from human beings.

event = 'next'¶

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

Moves underlying state machine to the next step

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

This function calls the step() function of the underlying state machine and provides a static event. It also transmits text typed by the end user after the command verb, and any other parameters received from the shell, e.g., attachment, etc.

on_init()[source]¶: Localize strings for this command

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

Bases: shellbot.commands.base.Command

Handles a bare file upload

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

Handles bare upload

Parameters:	bot (Shellbot) – The bot for this execution attachment (str) – External name of the uploaded file url (str) – The link to fetch actual content arguments (str or `None`) – The arguments for this command

is_hidden = True¶

on_init()[source]¶: Localize strings for this command

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

Bases: shellbot.commands.base.Command

Displays software version

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

Displays software version

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

is_hidden = True¶

on_init()[source]¶: Localize strings for this command

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

Bases: shellbot.commands.base.Command

Update input data

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

Update input data

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

on_init()[source]¶: Localize strings for this command