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:

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]
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:
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.

  • EFBMessageNotFound – Raised when an existing message indicated is not found. E.g.: The message to be removed.

  • EFBOperationNotSupported – Raised when the channel does not support message removal.

  • 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).