shellbot.events module

class shellbot.events.Event(attributes=None)

Bases: object

Represents an event received from the chat system

Events, and derivated objects such as instances of Message, abstract pieces of information received from various chat systems. They are designed as dictionary wrappers, with minimum exposure to shellbot, while enabling the transmission of rich information through serialization.

The life cycle of an event starts within a Space instance, most often, in the webhook triggered by a remote chat system. In order to adapt to shellbot, code should build the appropriate event instance, and push it to the queue used by the listener.

Example:

item = self.api.messages.get(messageId=message_id)
my_engine.ears.put(Message(item._json))

get(key, default=None)

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 an event that does not feature an attribute that is expected by shellbot. More specifically, call this function on optional attributes so as to avoid AttributeError

For example, some Cisco Spark messages may have toPersonId, but not all. So you could do:

message = Message(received_item)
to_id = message.get('toPersonId')
if to_id:
   ...

type = 'event'

class shellbot.events.EventFactory

Bases: object

Generates events

classmethod build_event(attributes)

Turns a dictionary to a typed event

Parameters:attributes (dict) – the set of attributes to consider Returns:an Event, such as a Message, a Join, a Leave, etc.

class shellbot.events.Join(attributes=None)

Bases: shellbot.events.Event

Represents the addition of someone to a space

actor_address

Returns the address of the joining actor

Return type:str or None

This attribute can be passed to add_participant() if needed.

actor_id

Returns the id of the joining actor

Return type:str or None

This attribute allows listener to identify who joins a space.

actor_label

Returns the name or title of the joining actor

Return type:str or None

This attribute allows listener to identify who joins a space.

channel_id

Returns the id of the joined space

Return type:str or None

stamp

Returns the date and time of this event in ISO format

Return type:str or None

type = 'join'

class shellbot.events.Leave(attributes=None)

Bases: shellbot.events.Event

Represents the removal of someone to a space

actor_address

Returns the address of the leaving actor

Return type:str or None

This attribute can be passed to add_participant() if needed.

actor_id

Returns the id of the leaving actor

Return type:str or None

This attribute allows listener to identify who leaves a space.

actor_label

Returns the name or title of the leaving actor

Return type:str or None

This attribute allows listener to identify who leaves a space.

channel_id

Returns the id of the left space

Return type:str or None

stamp

Returns the date and time of this event in ISO format

Return type:str or None

type = 'leave'

class shellbot.events.Message(attributes=None)

Bases: shellbot.events.Event

Represents a message received from the chat system

attachment

Returns name of uploaded file

Return type:str

This attribute is set on file upload. It provides with the external name of the file that has been shared, if any.

For example, to get a local copy of an uploaded file:

if message.attachment:
    path = space.download_attachment(message.url)

channel_id

Returns the id of the chat space

Return type:str or None

content

Returns message rich content

Return type:str

This function preserves rich content that was used to create the message, be it Markdown, HTML, or something else.

If no rich content is provided, than this attribute is equivalent to self.text

from_id

Returns the id of the message originator

Return type:str or None

This attribute allows listener to distinguish between messages from the bot and messages from other chat participants.

from_label

Returns the name or title of the message originator

Return type:str or None

This attribute is used by updaters that log messages or copy them for archiving.

is_direct

Determines if this is a direct message

Return type:True or False

This attribute is set for 1-to-1 channels. It allows the listener to determine if the input is explicitly for this bot or not.

mentioned_ids

Returns the list of mentioned persons

Return type:list of str, or []

This attribute allows the listener to determine if the input is explicitly for this bot or not.

stamp

Returns the date and time of this event in ISO format

Return type:str or None

This attribute allows listener to limit the horizon of messages fetched from a space back-end.

text

Returns message textual content

Return type:str

This function returns a bare string that can be handled directly by the shell. This has no tags nor specific binary format.

type = 'message'

url

Returns link to uploaded file

Return type:str

This attribute is set on file upload. It provides with the address that can be used to fetch the actual content.

There is a need to rely on the underlying space to authenticate and get the file itself. For example:

if message.url:
    content = space.get_attachment(message.url)