EFBMsg

class ehforwarderbot.EFBMsg[source]

A message.

attributes

Attributes used for a specific message type. Only specific message type requires this attribute. Defaulted to None.

Note

Do NOT use object of the abstract class EFBMsgAttribute for attributes, but object of specific class instead.

Type

Optional[EFBMsgAttribute]

author

Author of this message.

Type

EFBChat

chat

Sender of the message.

Type

EFBChat

commands

Commands attached to the message

Type

Optional[EFBMsgCommands]

deliver_to

The channel that the message is to be delivered to

Type

EFBChannel

edit

Flag this up if the message is edited. Flag only this if no multimedia file is modified, otherwise flag up both this one and edit_media as well.

If no media file is modified, the edited message may carry no information about the file.

Type

bool

edit_media

Flag this up if any file attached to the message is modified. If this value is true, edit must also be True.

Type

bool

file

File object to multimedia file, type “ra”. None if N/A. recommended to use NamedTemporaryFile object, the file can be deleted when closed, if not used otherwise. All file object must be rewind back to 0 (file.seek(0)) before sending.

Type

IO[bytes]

filename

File name of the multimedia file. None if N/A

Type

str

is_system

Mark as true if this message is a system message.

Type

bool

mime

MIME type of the file. None if N/A

Type

str

path

Local path of multimedia file. None if N/A

Type

str

reactions

Indicate reactions to the message. Dictionary key represents the reaction name, usually an emoji. Value is a collection of users who reacted to the message with that certain emoji. All EFBChat objects in this dict must be of a user or a group member.

Type

Dict[str, Iterable[EFBChat]]

substitutions

Substitutions of messages, usually used when the some parts of the text of the message refers to another user or chat.

Type

Optional[EFBMsgSubstitutions]

target

Target message (usually for messages that “replies to” another message).

Note

This message may be a “minimum message”, with only required fields:

Type

Optional[EFBMsg]

text

text of the message

Type

str

type

Type of message

Type

MsgType

uid

Unique ID of message. Usually stores the message ID from slave channel. This ID must be unique among all chats in the same channel.

Note

Some channels may not support message editing. Some channels may issue a new uid for edited message.

Type

str

vendor_specific

A series of vendor specific attributes attached. This can be used by any other channels or middlewares that is compatible with such information. Note that no guarantee is provided for information in this section.

Type

Dict[str, Any]

verify()[source]

Verify the validity of message.

class ehforwarderbot.message.EFBMsgAttribute[source]

Bases: abc.ABC

Abstract class of a message attribute.

class ehforwarderbot.message.EFBMsgLinkAttribute(title: str = None, description: Optional[str] = None, image: Optional[str] = None, url: str = None)[source]

Bases: ehforwarderbot.message.EFBMsgAttribute

EFB link message attribute.

title

Title of the link.

Type

str

description

Description of the link.

Type

str, optional

image

Image/thumbnail URL of the link.

Type

str, optional

url

URL of the link.

Type

str

__init__(title: str = None, description: Optional[str] = None, image: Optional[str] = None, url: str = None)[source]
Parameters
  • title (str) – Title of the link.

  • description (str, optional) – Description of the link.

  • image (str, optional) – Image/thumbnail URL of the link.

  • url (str) – URL of the link.

class ehforwarderbot.message.EFBMsgLocationAttribute(latitude: float, longitude: float)[source]

Bases: ehforwarderbot.message.EFBMsgAttribute

EFB location message attribute.

latitude

Latitude of the location.

Type

float

longitude

Longitude of the location.

Type

float

__init__(latitude: float, longitude: float)[source]
Parameters
  • latitude (float) – Latitude of the location.

  • longitude (float) – Longitude of the location.

class ehforwarderbot.message.EFBMsgCommand(name: str, callable_name: str, args: Iterable[Any] = None, kwargs: Optional[Mapping[str, Any]] = None)[source]

Bases: object

EFB message command. This object records a way to call a method in the module object. In case where the message has an author from a different module from the chat, this function should be called on the author’s module.

name

Human-friendly name of the command.

Type

str

callable_name

Callable name of the command.

Type

str

args

Arguments passed to the function.

Type

Iterable[Any]

kwargs

Keyword arguments passed to the function.

Type

Mapping[str, Any]

__init__(name: str, callable_name: str, args: Iterable[Any] = None, kwargs: Optional[Mapping[str, Any]] = None)[source]
Parameters
  • name (str) – Human-friendly name of the command.

  • callable_name (str) – Callable name of the command.

  • args (Optional[Iterable[Any]]) – Arguments passed to the function. Defaulted to empty list;

  • kwargs (Optional[Mapping[str, Any]]) – Keyword arguments passed to the function. Defaulted to empty dict.

class ehforwarderbot.message.EFBMsgCommands(commands: List[ehforwarderbot.message.EFBMsgCommand])[source]

Bases: object

EFB message commands. Message commands allow user to take action to a specific message, including vote, add friends, etc.

commands

Commands for the message.

Type

list of EFBMsgCommand

__init__(commands: List[ehforwarderbot.message.EFBMsgCommand])[source]
Parameters

commands (list of EFBMsgCommand) – Commands for the message.

class ehforwarderbot.message.EFBMsgStatusAttribute(status_type: ehforwarderbot.message.EFBMsgStatusAttribute.Types, timeout: int = 5000)[source]

Bases: ehforwarderbot.message.EFBMsgAttribute

EFB Message status attribute. Message with type Status notifies the other end to update a chat-specific status, such as typing, send files, etc.

status_type

Type of status, possible values are defined in the EFBMsgStatusAttribute.

timeout

Number of milliseconds for this status to expire. Default to 5 seconds.

Type

Optional[int]

Types[source]

List of status types supported

class Types[source]

Bases: enum.Enum

TYPING

Used in status_type, represent the status of typing.

UPLOADING_FILE

Used in status_type, represent the status of uploading file.

UPLOADING_IMAGE

Used in status_type, represent the status of uploading image.

UPLOADING_AUDIO

Used in status_type, represent the status of uploading audio.

UPLOADING_VIDEO

Used in status_type, represent the status of uploading video.

__init__(status_type: ehforwarderbot.message.EFBMsgStatusAttribute.Types, timeout: int = 5000)[source]
Parameters
  • status_type – Type of status.

  • timeout (Optional[int]) – Number of milliseconds for this status to expire. Default to 5 seconds.

class ehforwarderbot.message.EFBMsgSubstitutions(substitutions: Dict[Tuple[int, int], ehforwarderbot.chat.EFBChat])[source]

Bases: dict

EFB message substitutions.

This is for the case when user “@-referred” a list of users in the message. Substitutions here is a dict of correspondence between the string used to refer to the user in the message and a user object.

Dictionary of text substitutions targeting to a user or member.

The key of the dictionary is a tuple of two ints, where first of it is the starting position in the string, and the second is the ending position defined similar to Python’s substring. A tuple of (3, 15) corresponds to msg.text[3:15]. The value of the tuple (a, b) must lie within a [0, l), b (a, l], where l is the length of the message text.

Value of the dict may be any user of the chat, or a member of a group. Notice that the EFBChat object here must NOT be a group.

Type:

Dict[Tuple[int, int], EFBChat]

Examples

Initialization and marking chats

message = EFBMsg()

# 1. a chat delivered from slave to master, or
message.deliver_to = master
message.chat = wonderland
message.author = alice

# 2. a chat delivered from master to slave
message.deliver_to = slave
message.chat = alice
message.author = EFBChat(slave).self()

Marking message references (targeted message)

# Information in this part should be retrieved
# from recorded historical data.
message.target = EFBMsg()
message.target.chat = alice
message.target.author = alice
message.target.text = "Hello, world."
message.target.type = MsgType.Text
message.target.uid = "100000002"

Edit a previously sent message

message.edit = True
message.uid = "100000003"
# Message UID should be the UID from the slave channel
# regardless of where the message is delivered to.

Type-specific Information

  1. Text message
    message.type = MsgType.Text
    message.text = "Hello, Wonderland."
    
  2. Media message

    Information related to media processing is described in Media processing.

    The example below is for image (picture) messages. Audio, file, video, sticker works in the same way.

    In non-text messages, the text attribute is optional.

    message.type = MsgType.Image
    message.text = "Image caption"
    message.file = NamedTemporaryFile(suffix=".png")
    message.file.write(binary_data)
    message.filename = "holiday photo.png"
    message.mime = "image/png"
    
  3. Location message

    In non-text messages, the text attribute is optional.

    message.type = MsgType.Location
    message.text = "I'm here! Come and find me!"
    message.attributes = EFBMsgLocationAttribute(51.4826, -0.0077)
    
  4. Link message

    In non-text messages, the text attribute is optional.

    message.type = MsgType.Link
    message.text = "Check it out!"
    message.attributes = EFBMsgLinkAttribute(
        title="Example Domain",
        description="This domain is established to be used for illustrative examples in documents.",
        image="https://example.com/thumbnail.png",
        url="https://example.com"
    )
    
  5. Status

    In non-text messages, the text attribute is optional.

    message.type = MsgType.Status
    message.attributes = EFBMsgStatusAttribute(EFBMsgStatusAttribute.TYPING)
    
  6. Unsupported message

    text attribute is required for this type of message.

    message.type = MsgType.Unsupported
    message.text = "Alice requested USD 10.00 from you. "
                   "Please continue from your client."
    

Additional information

  1. Substitution
    message.text = "Hey @alice, @bob, and @all. Attention!"
    message.substitutions = EFBMsgSubstitutions({
        (4, 10): alice,
        (12, 16): bob,
        (22, 26): EFBChat(slave).self()
    })
    
  2. Commands
    message.text = "Carol sent you a friend request."
    message.commands = EFBMsgCommands([
        EFBCommand(name="Accept", callable_name="accept_friend_request",
                   kwargs={"username": "carol_jhonos", "hash": "2a9329bd93f"}),
        EFBCommand(name="Decline", callable_name="decline_friend_request",
                   kwargs={"username": "carol_jhonos", "hash": "2a9329bd93f"})
    ])