plug.slack¶

exception immp.plug.slack.SlackAPIError¶

Bases: PlugError

Generic error from the Slack API.

exception immp.plug.slack.MessageNotFound¶: Bases: Exception

class immp.plug.slack.SlackUser(id_=None, plug=None, display_name=None, real_name=None, avatar=None, bot_id=None, app=False, raw=None)¶

Bases: User

User present in Slack.

bot_id¶

Reference to the Slack integration app for a bot user.

Type:: str

classmethod from_member(slack, json)¶

Convert an API member dict to a User.

Parameters:

slack (.SlackPlug) – Related plug instance that provides the user.
json (dict) – Slack API user object.

Returns:

Parsed user object.

Return type:

.SlackUser

classmethod from_bot(slack, json)¶

Convert an API bot dict to a User.

Parameters:

slack (.SlackPlug) – Related plug instance that provides the user.
json (dict) – Slack API bot object.

Returns:

Parsed user object.

Return type:

.SlackUser

class immp.plug.slack.SlackRichText(segments=None)¶

Bases: RichText

Wrapper for Slack-specific parsing of formatting.

async classmethod from_mrkdwn(slack, text)¶

Convert a string of Slack’s Mrkdwn into a RichText.

Parameters:

slack (.SlackPlug) – Related plug instance that provides the text.
text (str) – Slack-style formatted text.

Returns:

Parsed rich text container.

Return type:

.SlackRichText

classmethod to_mrkdwn(slack, rich)¶

Convert a RichText instance into a string of Slack’s Mrkdwn.

Parameters:

slack (.SlackPlug) – Related plug instance to cross-reference users.
rich (.SlackRichText) – Parsed rich text container.

Returns:

Slack-style formatted text.

Return type:

str

class immp.plug.slack.SlackFile(slack, title=None, type_=Type.unknown, source=None)¶

Bases: File

File attachment originating from Slack.

async get_content(sess)¶

Stream the contents of the file, suitable for writing to a file or uploading elsewhere.

The default implementation will try to fetch a file by the source field. It may be overridden to add authentication or other metadata, but the method must remain callable with only a session passed to it.

Parameters:: sess (aiohttp.ClientSession) – Existing HTTP session with which to make any requests.
Returns:: Readable stream of the raw file.
Return type:: io.IOBase

classmethod from_file(slack, json)¶

Convert an API file dict to a File.

Parameters:

slack (.SlackPlug) – Related plug instance that provides the file.
json (dict) – Slack API file data.

Returns:

Parsed file object.

Return type:

.SlackFile

class immp.plug.slack.SlackMessage(*, text=None, user=None, edited=False, action=False, reply_to=None, joined=None, left=None, title=None, attachments=None, raw=None)¶

Bases: Message

Message originating from Slack.

async classmethod from_event(slack, json, parent=True)¶

Convert an API event dict to a Message.

Parameters:

slack (.SlackPlug) – Related plug instance that provides the event.
json (dict) – Slack API message event data.
parent (bool) – True (default) to retrieve the thread parent if one exists.

Returns:

Parsed message object.

Return type:

.SlackMessage

async classmethod from_post(slack, json)¶

Convert an API post response dict to a Message.

Parameters:

slack (.SlackPlug) – Related plug instance that provides the event.
json (dict) – Slack API response payload from postMessage.

Returns:

Parsed message object.

Return type:

.SlackMessage

classmethod to_attachment(slack, msg, reply=False)¶

Convert a Message to a message attachment structure, suitable for embedding within an outgoing message.

Parameters:

slack (.SlackPlug) – Target plug instance for this attachment.
msg (.Message) – Original message from another plug or hook.
reply (bool) – Whether to show a reply icon instead of a quote icon.

Returns.

dict:: Slack API attachment object.

class immp.plug.slack.SlackPlug(name, config, host)¶

Bases: Plug, HTTPOpenable

Plug for a Slack team.

same_team(other)¶

Test if two Slack plugs represent the same team.

Parameters:: other (.SlackPlug) – Second plug instance to compare with.
Returns:: True if both plugs are connected to the same team.
Return type:: bool

async start()¶

Perform any underlying operations needed to ready this resource for use, such as opening connections to an external network or API.

If using an event-driven framework that yields and runs in the background, you should use a signal of some form (e.g. asyncio.Condition) to block this method until the framework is ready for use.

async stop()¶

Perform any underlying operations needed to stop using this resource and tidy up, such as terminating open network connections.

Like with start(), this should block as needed to wait for other frameworks – this method should return only when ready to be started again.

async user_from_id(id_)¶

Retrieve a User based on the underlying network’s identifier.

Parameters:: id (str) – Network identifier of the user.
Returns:: Corresponding user instance.
Return type:: .User

async user_from_username(username)¶

Retrieve a User based on the underlying network’s username.

Parameters:: username (str) – Network username of the user.
Returns:: Corresponding user instance.
Return type:: .User

async user_is_system(user)¶

Check if a given user is automated by the plug (for example a bot user from which the plug operates). Hooks may exclude system users from certain operations.

Returns:: True if the user relates to the plug itself.
Return type:: bool

async public_channels()¶

Retrieve all shared channels known to this plug, either public or otherwise accessible. May return None if the network doesn’t support channel discovery.

Returns:: All available non-private channels.
Return type:: .Channel list

async private_channels()¶

Retrieve all private (one-to-one) channels known to this plug. May return None if the network doesn’t support channel discovery.

Returns:: All available private channels.
Return type:: .Channel list

async channel_for_user(user)¶

Retrieve a Channel representing a private (one-to-one) conversation between a given user and the service. Returns None if the user does not have a private channel.

Parameters:: user (.User) – Requested user instance.
Returns:: Private channel for this user.
Return type:: .Channel

async channel_is_private(channel)¶

Test if a given channel represents a private (one-to-one) conversation between a given user and the service. May return None if the network doesn’t have a notion of public/shared and private channels.

Parameters:: channel (.Channel) – Requested channel instance.
Returns:: True if the channel is private.
Return type:: bool

async channel_title(channel)¶

Retrieve the friendly name of this channel, as used in the underlying network. May return None if the service doesn’t have a notion of titles.

Returns:: Display name for the channel.
Return type:: str

async channel_link(channel)¶

Return a URL that acts as a direct link to the given channel. This is not a join link, rather one that opens a conversation in the client (it may e.g. use a custom protocol).

Parameters:: channel (.Channel) – Requested channel instance.
Returns:: Internal deep link to this channel.
Return type:: str

async channel_members(channel)¶

Retrieve a User list representing all members of the given channel. May return None if the plug doesn’t recognise the channel, or is unable to query members.

Parameters:: channel (.Channel) – Requested channel instance.
Returns:: Members present in the channel.
Return type:: .User list

async channel_admins(channel)¶

Retrieve a User list representing members of the given channel with the ability to manage the channel or its members. May return None if the plug doesn’t recognise the channel, is unable to query members, or has no concept of admins.

Parameters:: channel (.Channel) – Requested channel instance.
Returns:: Members with admin privileges present in the channel.
Return type:: .User list

async channel_invite_multi(channel, users)¶

Add multiple users to the channel’s list of members.

By default, calls channel_invite() for each channel-user pair, but can be overridden in order to optimise any necessary work.

Parameters:

channel (.Channel) – Requested channel instance.
users (.User list) – New users to invite.

async channel_invite(channel, user)¶

Add the given user to the channel’s list of members.

Parameters:

channel (.Channel) – Requested channel instance.
user (.User) – New user to invite.

async channel_remove(channel, user)¶

Remove the given user from the channel’s list of members.

Parameters:

channel (.Channel) – Requested channel instance.
user (.User) – Existing user to kick.

async channel_history(channel, before=None)¶

Retrieve the most recent messages sent or received in the given channel. May return an empty list if the plug is unable to query history.

Parameters:

channel (.Channel) – Requested channel instance.
before (.Receipt) – Starting point message, or None to fetch the most recent.

Returns:

Messages from the channel, oldest first.

Return type:

.Receipt list

async get_message(receipt, parent=True)¶

Lookup a Receipt and fetch the corresponding SentMessage.

Parameters:: receipt (.Receipt) – Existing message reference to retrieve.
Returns:: Full message.
Return type:: .SentMessage

async put(channel, msg)¶

Take a Message object, and push it to the underlying network.

Because some plugs may not support combinations of message components (such as text and an accompanying image), this method may send more than one physical message.

Parameters:

channel (.Channel) – Target channel for the new message.
msg (.Message) – Original message received from another channel or plug.

Returns:

References to new messages sent to the plug.

Return type:

.Receipt list

async delete(sent)¶

Request deletion of this message, if supported by the network.

Parameters:: sent (.SentMessage) – Existing message to be removed.