plug.telegram#

exception immp.plug.telegram.TelegramAPIConnectError#

Bases: PlugError

Generic error whilst attempting to call the Telegram API.

exception immp.plug.telegram.TelegramAPIRequestError#

Bases: PlugError

Generic error from the Telegram API.

class immp.plug.telegram.TelegramUser(id_=None, plug=None, *, username=None, real_name=None, avatar=None, link=None, suggested=False, raw=None)#

Bases: User

User present in Telegram.

classmethod from_bot_user(telegram, json)#

Convert a user dict (attached to a message) to a User.

Parameters:

  • telegram (.TelegramPlug) – Related plug instance that provides the user.

  • json (dict) – Telegram API User object.

Returns:

Parsed user object.

Return type:

.TelegramUser

classmethod from_bot_channel(telegram, json, author=None)#

Convert a chat dict (attached to a message) to a User.

Parameters:

  • telegram (.TelegramPlug) – Related plug instance that provides the user.

  • json (dict) – Telegram API Chat object.

  • author (str) – Optional post author, for channel messages.

Returns:

Parsed user object.

Return type:

.TelegramUser

classmethod from_proto_user(telegram, user)#

Convert a telethon.tl.types.User into a User.

Parameters:

  • telegram (.TelegramPlug) – Related plug instance that provides the user.

  • user (telethon.tl.types.User) – Telegram user retrieved from the MTProto API.

Returns:

Parsed user object.

Return type:

.TelegramUser

classmethod from_proto_channel(telegram, chat, author=None)#

Convert a telethon.tl.types.Channel into a User.

Parameters:

  • telegram (.TelegramPlug) – Related plug instance that provides the user.

  • chat (telethon.tl.types.Channel) – Telegram channel retrieved from the MTProto API.

  • author (str) – Optional post author, for channel messages.

Returns:

Parsed user object.

Return type:

.TelegramUser

async classmethod from_proto_message(telegram, message)#

Try to find the sender or chat of a message, and produce a related User.

Parameters:

  • telegram (.TelegramPlug) – Related plug instance that provides the user.

  • message (telethon.tl.patched.Message) – Telegram message retrieved from the MTProto API.

Returns:

Parsed user object, or None if no sender information is present.

Return type:

.TelegramUser

classmethod from_entity(telegram, entity)#

Convert a client entity row into a User.

Parameters:

  • telegram (.TelegramPlug) – Related plug instance that provides the user.

  • entity ((str, str, str) tuple) – ID, username and real name of a cached Telegram user.

Returns:

Parsed user object.

Return type:

.TelegramUser

class immp.plug.telegram.TelegramSegment(text, *, bold=False, italic=False, underline=False, strike=False, code=False, pre=False, link=None, mention=None)#

Bases: Segment

Plug-friendly representation of Telegram message formatting.

classmethod to_html(telegram, segment)#

Convert a Segment into HTML suitable for Telegram’s automatic parsing.

Parameters:

  • telegram (.TelegramPlug) – Related plug instance to cross-reference users.

  • segment (.Segment) – Message segment created by another plug.

Returns:

HTML-formatted string.

Return type:

str

class immp.plug.telegram.TelegramRichText(segments=None)#

Bases: RichText

Wrapper for Telegram-specific parsing of formatting.

async classmethod from_bot_entities(telegram, text, entities)#

Convert a string annotated by Telegram’s entities to RichText.

Parameters:

  • telegram (.TelegramPlug) – Related plug instance that provides the text.

  • text (str) – Plain text without formatting.

  • entities (dict list) – List of Telegram API MessageEntity objects.

Returns:

Parsed rich text container.

Return type:

.TelegramRichText

async classmethod from_proto_entities(telegram, text, entities)#

Convert a string annotated by Telegram’s entities to RichText.

Parameters:

  • telegram (.TelegramPlug) – Related plug instance that provides the text.

  • text (str) – Plain text without formatting.

  • entities (telethon.types.TypeMessageEntity list) – List of Telegram entity objects.

Returns:

Parsed rich text container.

Return type:

.TelegramRichText

class immp.plug.telegram.TelegramFile(title=None, type_=Type.unknown, source=None)#

Bases: File

File attachment originating from Telegram.

async classmethod from_id(telegram, id_, type_=Type.unknown, name=None)#

Generate a file using the bot API URL for a Telegram file.

Parameters:

  • telegram (.TelegramPlug) – Related plug instance that provides the file.

  • id (str) – File ID as provided in the bot API, or constructed from a raw MTProto file.

  • type (.File.Type) – Corresponding file type.

  • name (str) – Original filename, if available for the file format.

Returns:

Parsed file object.

Return type:

.TelegramFile

class immp.plug.telegram.TelegramMessage(*, 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 Telegram.

async classmethod from_bot_message(telegram, json)#

Convert an API message dict to a Message.

Parameters:

  • telegram (.TelegramPlug) – Related plug instance that provides the event.

  • json (dict) – Telegram API message object.

Returns:

Parsed message object.

Return type:

.TelegramMessage

async classmethod from_bot_update(telegram, update)#

Convert an API update dict to a Message.

Parameters:

  • telegram (.TelegramPlug) – Related plug instance that provides the event.

  • update (dict) – Telegram API update object.

Returns:

Parsed message object.

Return type:

.TelegramMessage

async classmethod from_proto_message(telegram, message)#

Convert a Telegram message event to a Message.

Parameters:

  • telegram (.TelegramPlug) – Related plug instance that provides the event.

  • message (telethon.tl.custom.Message) – Received message from an event or get request.

Returns:

Parsed message object.

Return type:

.TelegramMessage

class immp.plug.telegram.TelegramPlug(name, config, host)#

Bases: Plug, HTTPOpenable

Plug for a Telegram bot.

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_rename(channel, title)#

Update the friendly name of this conversation.

Parameters:

  • channel (.Channel) – Requested channel instance.

  • title (str) – New display name for the channel.

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_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.

Create a URL that can be used by non-members to join the given channel. To link existing participants to the channel without invite authorisation, see channel_link().

Parameters:

  • channel (.Channel) – Requested channel instance.

  • shared (bool) –

    True (default) for a common, unlimited-use, non-expiring link (subject to any limitations from the underlying network); False for a private, single-use link.

    Networks may only support one of these two modes of link creation; if None is returned, but the caller can make do with the other type, they may retry the call and flip this option.

Returns:

Shareable invite link, or None if one couldn’t be created.

Return type:

str

Revoke an invite link, or otherwise prevent its use in the future.

Parameters:

  • channel (.Channel) – Requested channel instance.

  • link (str) – Existing invite link to revoke. This should be provided when known; if None, the plug will revoke the default invite link, if such a link exists for the channel in the underlying network.

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)#

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.