Protocols

High-level interface definitions.

class signal_bot_framework.protocol.PersonalityProto(*args, **kwargs)

Bases: Protocol

Defines a “personality” that applies only to messages in specific contexts (e.g., in a specific group).

This Protocol contains shared functionality between a SignalBot instance (a “root” personality) and individual signal_bot_framework.personality.Personality instances. When a message is received, it is checked against any personalities’ callbacks first, then the root peronality’s callbacks.

To use, create an instance of (or subclass) Personality and register it with SignalBot.add_personality().

Not listed here are associated remove_xxx(...) methods (e.g., remove_cron()).

matches_context(context)

Whether this personality matches a given context.

Parameters:

context (Context) – The context to match against.

Return type:

bool

on_message(cb)

Register a callback to be called on any DataMessage.

Parameters:

cb (MessageCb) – The function to call.

Return type:

None

on_prefix(prefix, cb)

Register a callback to be called on any DataMessage matching a given prefix (exact match).

Parameters:

• prefix (str) – The exact-match prefix to trigger on.

• cb (MessageCb) – The function to call.

Return type:

None

on_cron(schedule, cb)

Register a callback to be called on a Cron schedule.

Parameters:

• schedule (str) – The Cron schedule to trigger on.

• cb (MessageCb) – The function to call.

Return type:

CronItem

on_mention(mention, cb)

Register a callback to be called when a given AccountNumber/AccountUUID is @-mentioned.

Parameters:

• mention (Union[AccountNumber, AccountUUID]) – The Signal account to trigger on mentions of.

• cb (MessageCb) – The function to call.

Return type:

None

on_keyword(keyword, cb, case_sensitive=False, whole_word=True)

Register a callback to be called when DataMessage contains a keyword.

Parameters:

• keyword (str) – The keyword to trigger on.

• cb (MessageCb) – The function to call.

• case_sensitive (bool) – Whether the match is case-sensitive.

• whole_word (bool) – Whether to match whole words only.

Return type:

None

async started(signal)

Handle when SignalBot is first started.

Parameters:

signal (SignalBot) – An instance of the current SignalBot.

Return type:

None

abstract handle_callback_exception(exception, cb)

Personalities should implement this to handle when unhandled exceptions occur in a callback.

Parameters:

• exception (BaseException) – The exception that occurred.

• cb (AnyCb) – The callback that raised the exception.

Return type:

bool

Returns:

Whether Cron callbacks should be rescheduled.

class signal_bot_framework.protocol.SignalBot

Bases: PersonalityProto, Protocol

The high-level abstraction of signal_bot_framework functionality.

Implementation can be found in signal_bot_framework._signal_impl. To create an instance, call signal_bot_framework.create().

property account_number: AccountNumber

The currently registered Signal account.

async send_reaction(to, emoji)

React to a previous message.

Parameters:

• to (DataMessage) – The message to react to.

• emoji (str) – The emoji to react with.

Return type:

Future[Response]

async send_typing(to, stop=False)

Start (or stop) the “Typing…” indicator.

When started, will display for 15 seconds unless stopped.

Parameters:

• to (Union[AccountNumber, AccountUUID, GroupID]) – The destination of the typing indicator (an individual or a group).

• stop (bool) – Stop (rather than start) the typing indicator.

Return type:

Future[Response]

async send_message(to, message=None, args=None)

Send a message.

Parameters:

• to (Union[AccountNumber, AccountUUID, GroupID]) – The destination of the message (an individual or a group).

• message (Optional[str]) – The textual message to send (if any).

• args (Optional[SendMessageArgs]) – Additional arguments to send_message.

Return type:

Future[Response]

async delete_message(to, target_timestamp)

Delete a sent message (by timestamp).

Parameters:

• to (Union[AccountNumber, AccountUUID, GroupID]) – The destination (an individual or a group) in which to delete a message.

• target_timestamp (datetime) – The timestamp of the message to delete.

Return type:

Future[Response]

async run()

Start Cron callbacks and the message pump loop.

Runs until the transport raises asyncio.CancelledError (e.g., stop() is called).

Return type:

None

async stop()

Stop the message pump loop (if running) and any scheduled Cron callbacks, in-flight requests, etc.

Return type:

None

add_personality(personality)

Add a sub-personality.

Parameters:

personality (PersonalityProto) – The Personality to add.

Return type:

None