EFBChannel

class ehforwarderbot.EFBChannel(instance_id: str = None)[source]

The abstract channel class.

channel_name

A human-friendly name of the channel.

Type

str

channel_emoji

Emoji icon of the channel. Recommended to use a visually-length-one emoji that represents the channel best.

Type

str

channel_type

Type of the channel.

Type

ChannelType

supported_message_types

Types of messages that the channel accepts as incoming messages.

Type

Set[MsgType]

channel_id

Unique identifier of the channel. Convention of IDs is specified in Packaging and Publish. This ID will be appended with its instance ID when available.

Type

str

instance_id

The instance ID if available.

Type

str

__init__(instance_id: str = None)[source]

Initialize the channel. Inherited initializer must call the “super init” method at the beginning.

Parameters

instance_id – Instance ID of the channel.

get_chat(self, chat_uid: str, member_uid: Optional[str] = None) → EFBChat[source]

Get the chat object from a slave channel.

Parameters
  • chat_uid (str) – UID of the chat.

  • member_uid (Optional[str]) – UID of group member, only when the selected chat is a group.

Returns

The chat found.

Return type

EFBChat

:raises EFBChatNotFound: Raised when a chat required is not found.

Note

This is not required by Master Channels

get_chat_picture(chat: EFBChat) → IO[bytes][source]

Get the profile picture of a chat. Profile picture is also referred as profile photo, avatar, “head image” sometimes.

Parameters

chat (EFBChat) – Chat to get picture from.

Returns

Opened temporary file object. The file object must have appropriate extension name that matches to the format of picture sent, and seek to position 0.

It can be deleted when closed if not required otherwise.

Return type

IO[bytes]

:raises EFBChatNotFound: Raised when a chat required is not found. :raises EFBOperationNotSupported: Raised when the chat does not offer a profile picture.

Examples

if chat.channel_uid != self.channel_uid:
    raise EFBChannelNotFound()
file = tempfile.NamedTemporaryFile(suffix=".png")
response = requests.post("https://api.example.com/get_profile_picture/png",
                         data={"uid": chat.chat_uid})
if response.status_code == 404:
    raise EFBChatNotFound()
file.write(response.content)
file.seek(0)
return file

Note

This is not required by Master Channels

get_chats() → List[EFBChat][source]

Return a list of available chats in the channel.

Returns

a list of available chats in the channel.

Return type

List[EFBChat]

Note

This is not required by Master Channels

get_extra_functions() → Dict[str, Callable][source]

Get a list of additional features

Returns

A dict of methods marked as additional features. Method can be called with get_extra_functions()["methodName"]().

Return type

Dict[str, Callable]

get_message_by_id(msg_id: str) → Optional[EFBMsg][source]

Get message entity by its ID. Applicable to both master channels and slave channels. Return None when message not found.

Override this method and raise EFBOperationNotSupported if it is not feasible to perform this for your platform.

poll()[source]

Method to poll for messages. This method is called when the framework is initialized. This method should be blocking.

send_message(msg: EFBMsg) → EFBMsg[source]

Send a message to, or edit a sent message in the channel.

Parameters

msg (EFBMsg) – Message object to be processed.

Returns

The same message object with message ID from the recipient.

Return type

EFBMsg

:raises EFBChatNotFound: Raised when a chat required is not found. :raises EFBMessageTypeNotSupported: Raised when the message type sent is not supported by the channel. :raises EFBOperationNotSupported: Raised when an message edit request is sent, but not supported by the channel. :raises EFBMessageNotFound: Raised when an existing message indicated is not found. E.g.: The message to be edited, the message referred in the msg.target attribute. :raises EFBMessageError: Raised when other error occurred while sending or editing the message.

send_status(status: EFBStatus)[source]

Send a status to the channel.

Parameters

status (EFBStatus) – the status

:raises EFBChatNotFound: Raised when a chat required is not found. :raises EFBMessageNotFound: Raised when an existing message indicated is not found. E.g.: The message to be removed. :raises EFBOperationNotSupported: Raised when the channel does not support message removal. :raises EFBMessageError: Raised when other error occurred while removing the message. .. note:: Avoid raising exceptions from this method in Master Channels as it would be hard for a Slave Channel to process the exception.

Note

This is not applicable to Slave Channels

stop_polling()[source]

When EFB framework is asked to stop gracefully, this method is called to each channel object to stop all processes in the channel, save all status if necessary, and terminate polling.

When the channel is ready to stop, the polling function must stop blocking. EFB framework will quit completely when all polling threads end.

Common operations

Sending messages and statuses

Sending messages and statuses to other channels is the most common operation of a channel. When the channel has gathered enough information from external sources, it should be further processed and packed into the relative objects, i.e. EFBMsg and EFBStatus.

When the related information is packed into their relative objects, it can be sent to the coordinator for the next step.

For now, both EFBMsg and EFBStatus has an attribute that indicates that where this object should be delivered to (EFBMsg.deliver_to and EFBStatus.destination_channel). This is used by the coordinator when delivering the message.

For messages, it can be delivered with coordinator.send_message(), and statuses can be delivered with coordinator.send_status().

When the object is passed onto the coordinator, it will be further processed by the middleware.

About Channel ID

With the introduction of instance IDs, it is required to use the self.channel_id or equivalent instead of any hard-coded ID or constants while referring to the channel (e.g. while retrieving the path to the configuration files, creating chat and message objects, etc).