Chat and Chat Members

Inheritance diagram

Summary

PrivateChat(*[, channel, middleware, ...])	A private chat, where usually only the User Themself and the other participant are in the chat.
SystemChat(*[, channel, middleware, ...])	A system chat, where usually only the User Themself and the other participant (system chat member) are in the chat.
GroupChat(*[, channel, middleware, ...])	A group chat, where there are usually multiple members present.
ChatMember(chat, *[, name, alias, uid, id, ...])	Member of a chat.
SelfChatMember(chat, *[, name, alias, id, ...])	The User Themself as member of a chat.
SystemChatMember(chat, *[, name, alias, id, ...])	A system account/prompt as member of a chat.
ChatNotificationState(value)	Indicates the notifications settings of a chat in its slave channel or middleware.

Classes

class ehforwarderbot.chat.BaseChat(*, channel=None, middleware=None, module_name='', channel_emoji='', module_id='', name='', alias=None, uid='', id='', vendor_specific=None, description='')

Basis: abc.ABC

Base chat class, this is an abstract class sharing properties among all chats and members. No instance can be created directly from this class.

Catatan

BaseChat objects are picklable, thus it is RECOMMENDED to keep any object of its subclass also picklable.

module_id

Unique ID of the module.

Type

ModuleID (str)

channel_emoji

Emoji of the channel, empty string if the chat is from a middleware.

Type

str

module_name

Name of the module.

Type

ModuleID (str)

name

Name of the chat.

Type

str

alias

Alternative name of the chat, usually set by user.

Type

Optional[str]

uid

Unique ID of the chat. This MUST be unique within the channel.

Type

ChatID (str)

description

A text description of the chat, usually known as “bio”, “description”, “purpose”, or “topic” of the chat.

Type

str

vendor_specific

Any vendor specific attributes.

Type

Dict[str, Any]

__init__(*, channel=None, middleware=None, module_name='', channel_emoji='', module_id='', name='', alias=None, uid='', id='', vendor_specific=None, description='')

Parameter

• channel (Optional[SlaveChannel]) -- Provide the channel object to fill module_name, channel_emoji, and module_id automatically.

• middleware (Optional[Middleware]) -- Provide the middleware object to fill module_name, and module_id automatically.

• module_id (NewType()(ModuleID, str)) -- Unique ID of the module.

• channel_emoji (str) -- Emoji of the channel, empty string if the chat is from a middleware.

• module_name (str) -- Name of the module.

• name (str) -- Name of the chat.

• alias (Optional[str]) -- Alternative name of the chat, usually set by user.

• uid (NewType()(ChatID, str)) -- Unique ID of the chat. This MUST be unique within the channel.

• description (str) -- A text description of the chat, usually known as “bio”, “description”, “purpose”, or “topic” of the chat.

• vendor_specific (Dict[str, Any]) -- Any vendor specific attributes.

copy()

Return a shallow copy of the object.

Return type

TypeVar(_BaseChatSelf, bound= BaseChat, covariant=True)

property display_name: str

Shortcut property, equivalent to alias or name

Return type

str

property long_name: str

Shortcut property, if alias exists, this will provide the alias with name in parenthesis. Otherwise, this will return the name

Return type

str

abstract verify()

Verify the completeness of the data.

Raises

AssertionError -- When this chat is invalid.

class ehforwarderbot.chat.Chat(*, channel=None, middleware=None, module_name='', channel_emoji='', module_id='', name='', alias=None, id='', uid='', vendor_specific=None, description='', members=None, notification=ChatNotificationState.ALL, with_self=True)

Basis: ehforwarderbot.chat.BaseChat, abc.ABC

A chat object, indicates a user, a group, or a system chat. This class is abstract. No instance can be created directly from this class.

If your IM platform is providing an ID of the User Themself, and it is using this ID to indicate the author of a message, you SHOULD update Chat.self.uid accordingly.

>>> channel.my_chat_id
"david_divad"
>>> chat = Chat(channel=channel, name="Alice", uid=ChatID("alice123"))
>>> chat.self.uid = channel.my_chat_id

By doing so, you can get the author in one step:

author = chat.get_member(author_id)

... instead of using a condition check:

if author_id == channel.my_chat_id:
    author = chat.self
else:
    author = chat.get_member(author_id)

Catatan

Chat objects are picklable, thus it is RECOMMENDED to keep any object of its subclass also picklable.

module_id

Unique ID of the module.

Type

ModuleID (str)

channel_emoji

Emoji of the channel, empty string if the chat is from a middleware.

Type

str

module_name

Name of the module.

Type

str

name

Name of the chat.

Type

str

alias

Alternative name of the chat, usually set by user.

Type

Optional[str]

uid

Unique ID of the chat. This MUST be unique within the channel.

Type

ChatID (str)

description

A text description of the chat, usually known as “bio”, “description”, “purpose”, or “topic” of the chat.

Type

str

notification

Indicate the notification settings of the chat in its slave channel (or middleware), defaulted to ALL.

Type

ChatNotificationState

members

Provide a list of members in the chat. Defaulted to an empty list.

You can extend this object and implement a @property method set for loading members on demand.

Note that this list may include members created by middlewares when the object is a part of a message, and these members MAY not appear when trying to retrieve from the slave channel directly. These members would have a different module_id specified from the chat.

Type

list of ChatMember

vendor_specific

Any vendor specific attributes.

Type

Dict[str, Any]

self

the User as a member of the chat (if available).

Type

Optional[SelfChatMember]

__init__(*, channel=None, middleware=None, module_name='', channel_emoji='', module_id='', name='', alias=None, id='', uid='', vendor_specific=None, description='', members=None, notification=ChatNotificationState.ALL, with_self=True)

Argumen Kata Kunci

• module_id (str) -- Unique ID of the module.

• channel_emoji (str) -- Emoji of the channel, empty string if the chat is from a middleware.

• module_name -- Name of the module.

• name (str) -- Name of the chat.

• alias (Optional[str]) -- Alternative name of the chat, usually set by user.

• id -- Unique ID of the chat. This MUST be unique within the channel.

• description (str) -- A text description of the chat, usually known as “bio”, “description”, “purpose”, or “topic” of the chat.

• notification (ChatNotificationState) -- Indicate the notification settings of the chat in its slave channel (or middleware), defaulted to ALL.

• members (MutableSequence[ChatMember]) -- Provide a list of members of the chat. Defaulted to an empty list.

• vendor_specific (Dict[str, Any]) -- Any vendor specific attributes.

• with_self (bool) -- Initialize the chat with the User Themself as a member.

add_member(name, uid, alias=None, id='', vendor_specific=None, description='', middleware=None)

Add a member to the chat.

Tip

This method does not check for duplicates. Only add members with this method if you are sure that they are not added yet. To check if the member is already added before adding, you can do something like this:

with contextlib.suppress(KeyError):
    return chat.get_member(uid)
return chat.add_member(name, uid, alias=..., vendor_specific=...)

Parameter

• name (str) -- Name of the member.

• uid (NewType()(ChatID, str)) -- ID of the member.

Argumen Kata Kunci

• alias (Optional[str]) -- Alias of the member.

• vendor_specific (Dict[str, Any]) -- Any vendor specific attributes.

• description (str) -- A text description of the chat, usually known as “bio”, “description”, “purpose”, or “topic” of the chat.

• middleware (Optional[Middleware]) -- Initialize this chat as a part of a middleware.

Return type

ChatMember

add_self()

Add self to the list of members.

Raises

AssertionError -- When there is already a self in the list of members.

Return type

SelfChatMember

add_system_member(name='', alias=None, id='', uid='', vendor_specific=None, description='', middleware=None)

Add a system member to the chat.

Useful for slave channels and middlewares to create an author of a message from a system member when the “system” member is intended to become a member of the chat.

Tip

This method does not check for duplicates. Only add members with this method if you are sure that they are not added yet.

Argumen Kata Kunci

• name (str) -- Name of the member.

• uid -- ID of the member.

• alias (Optional[str]) -- Alias of the member.

• vendor_specific (Dict[str, Any]) -- Any vendor specific attributes.

• description (str) -- A text description of the chat, usually known as “bio”, “description”, “purpose”, or “topic” of the chat.

• middleware (Optional[Middleware]) -- Initialize this chat as a part of a middleware.

Return type

SystemChatMember

get_member(member_id)

Find a member of chat by its ID.

Parameter

member_id (NewType()(ChatID, str)) -- ID of the chat member.

Return type

ChatMember

Kembali

the chat member.

Raises

KeyError -- when the ID provided is not found.

property has_self: bool

Indicate if this chat has yourself.

Return type

bool

make_system_member(name='', alias=None, id='', uid='', vendor_specific=None, description='', middleware=None)

Make a system member for this chat.

Useful for slave channels and middlewares to create an author of a message from a system member when the “system” member is NOT intended to become a member of the chat.

Argumen Kata Kunci

• name (str) -- Name of the member.

• uid -- ID of the member.

• alias (Optional[str]) -- Alias of the member.

• vendor_specific (Dict[str, Any]) -- Any vendor specific attributes.

• description (str) -- A text description of the chat, usually known as “bio”, “description”, “purpose”, or “topic” of the chat.

• middleware (Optional[Middleware]) -- Initialize this chat as a part of a middleware.

Return type

SystemChatMember

self: Optional[ehforwarderbot.chat.SelfChatMember]

The user as a member of the chat (if available).

class ehforwarderbot.chat.ChatMember(chat, *, name='', alias=None, uid='', id='', vendor_specific=None, description='', middleware=None)

Basis: ehforwarderbot.chat.BaseChat

Member of a chat. Usually indicates a member in a group, or the other participant in a private chat. Chat bots created by the users of the IM platform is also considered as a plain ChatMember.

To represent the User Themself, use SelfChatMember.

To represent a chat member that is a part of the system, the slave channel, or a middleware, use SystemChatMember.

ChatMembers MUST be created with reference of the chat it belongs to. Different objects MUST be created even when the same person appears in different groups or in a private chat.

ChatMembers are RECOMMENDED to be created using Chat.add_member() method.

Catatan

ChatMember objects are picklable, thus it is RECOMMENDED to keep any object of its subclass also picklable.

__init__(chat, *, name='', alias=None, uid='', id='', vendor_specific=None, description='', middleware=None)

Parameter

chat (Chat) -- Chat associated with this member.

Argumen Kata Kunci

• name (str) -- Name of the member.

• alias (Optional[str]) -- Alternative name of the member, usually set by user.

• uid (ChatID (str)) -- Unique ID of the member. This MUST be unique within the channel. This ID can be the same with a private chat of the same person.

• description (str) -- A text description of the member, usually known as “bio”, “description”, “summary” or “introduction” of the member.

• middleware (Middleware) -- Initialize this chat as a part of a middleware.

verify()

Verify the completeness of the data.

Raises

AssertionError -- When this chat is invalid.

class ehforwarderbot.chat.ChatNotificationState(value)

Basis: enum.Enum

Indicates the notifications settings of a chat in its slave channel or middleware. If an exact match is not available, choose the most similar one.

ALL = -1

All messages in the chat triggers notifications.

MENTIONS = 1

Notifications are sent only when the User is mentioned in the message, in the form of @-references or quote-reply (message target).

NONE = 0

No notification is sent to slave IM channel at all.

class ehforwarderbot.chat.GroupChat(*, channel=None, middleware=None, module_name='', channel_emoji='', module_id='', name='', alias=None, id='', uid='', vendor_specific=None, description='', notification=ChatNotificationState.ALL, with_self=True)

Basis: ehforwarderbot.chat.Chat

A group chat, where there are usually multiple members present.

Members can be added with the add_member() method.

If the with_self argument is True (which is the default setting), the User Themself would also be initialized as a member of the chat.

Contoh-contoh

>>> group = GroupChat(channel=slave_channel, name="Wonderland", uid=ChatID("wonderland001"))
>>> group.add_member(name="Alice", uid=ChatID("alice"))
ChatMember(chat=<GroupChat: Wonderland (wonderland001) @ Example slave channel>, name='Alice', alias=None, uid='alice', vendor_specific={}, description='')
>>> group.add_member(name="bob", alias="Bob James", uid=ChatID("bob"))
ChatMember(chat=<GroupChat: Wonderland (wonderland001) @ Example slave channel>, name='bob', alias='Bob James', uid='bob', vendor_specific={}, description='')
>>> from pprint import pprint
>>> pprint(group.members)
[SelfChatMember(chat=<GroupChat: Wonderland (wonderland001) @ Example slave channel>, name='You', alias=None, uid='__self__', vendor_specific={}, description=''),
 ChatMember(chat=<GroupChat: Wonderland (wonderland001) @ Example slave channel>, name='Alice', alias=None, uid='alice', vendor_specific={}, description=''),
 ChatMember(chat=<GroupChat: Wonderland (wonderland001) @ Example slave channel>, name='bob', alias='Bob James', uid='bob', vendor_specific={}, description='')]

Catatan

GroupChat objects are picklable, thus it is RECOMMENDED to keep any object of its subclass also picklable.

verify()

Verify the completeness of the data.

Raises

AssertionError -- When this chat is invalid.

class ehforwarderbot.chat.PrivateChat(*, channel=None, middleware=None, module_name='', channel_emoji='', module_id='', name='', alias=None, id='', uid='', vendor_specific=None, description='', notification=ChatNotificationState.ALL, with_self=True, other_is_self=False)

Basis: ehforwarderbot.chat.Chat

A private chat, where usually only the User Themself and the other participant are in the chat. Chat bots SHOULD also be categorized under this type.

There SHOULD only be at most one non-system member of the chat apart from the User Themself, otherwise it might lead to unintended behavior.

This object is by default initialized with the other participant as its member.

If the with_self argument is True (which is the default setting), the User Themself would also be initialized as a member of the chat.

Parameter

other -- the other participant of the chat as a member

Catatan

PrivateChat objects are picklable, thus it is RECOMMENDED to keep any object of its subclass also picklable.

verify()

Verify the completeness of the data.

Raises

AssertionError -- When this chat is invalid.

class ehforwarderbot.chat.SelfChatMember(chat, *, name='', alias=None, id='', uid='', vendor_specific=None, description='', middleware=None)

Basis: ehforwarderbot.chat.ChatMember

The User Themself as member of a chat.

SelfChatMembers are RECOMMENDED to be created together with a chat object by setting with_self value to True. The created object is accessible at Chat.self.

The default ID of a SelfChatMember object is SelfChatMember.SELF_ID, and the default name is a translated version of the word “You”.

You are RECOMMENDED to change the ID of this object if provided by your IM platform, and you MAY change the name or alias of this object depending on your needs.

Catatan

SelfChatMember objects are picklable, thus it is RECOMMENDED to keep any object of its subclass also picklable.

SELF_ID

The default ID of a SelfChatMember.

__init__(chat, *, name='', alias=None, id='', uid='', vendor_specific=None, description='', middleware=None)

Parameter

chat (Chat) -- Chat associated with this member.

Argumen Kata Kunci

• name (str) -- Name of the member.

• alias (Optional[str]) -- Alternative name of the member, usually set by user.

• uid (ChatID (str)) -- Unique ID of the member. This MUST be unique within the channel. This ID can be the same with a private chat of the same person.

• description (str) -- A text description of the member, usually known as “bio”, “description”, “summary” or “introduction” of the member.

• middleware (Middleware) -- Initialize this chat as a part of a middleware.

class ehforwarderbot.chat.SystemChat(*, channel=None, middleware=None, module_name='', channel_emoji='', module_id='', name='', alias=None, id='', uid='', vendor_specific=None, description='', notification=ChatNotificationState.ALL, with_self=True)

Basis: ehforwarderbot.chat.Chat

A system chat, where usually only the User Themself and the other participant (system chat member) are in the chat. This object is used to represent system chat where the other participant is neither a user nor a chat bot of the remote IM.

Middlewares are RECOMMENDED to create chats with this type when they want to send messages in this type.

This object is by default initialized with the system participant as its member.

If the with_self argument is True (which is the default setting), the User Themself would also be initialized as a member of the chat.

Parameter

other -- the other participant of the chat as a member

Catatan

SystemChat objects are picklable, thus it is RECOMMENDED to keep any object of its subclass also picklable.

verify()

Verify the completeness of the data.

Raises

AssertionError -- When this chat is invalid.

class ehforwarderbot.chat.SystemChatMember(chat, *, name='', alias=None, id='', uid='', vendor_specific=None, description='', middleware=None)

Basis: ehforwarderbot.chat.ChatMember

A system account/prompt as member of a chat.

Use this chat to send messages that is not from any specific member. Middlewares are RECOMMENDED to use this member type to communicate with the User in an existing chat.

Chat bots created by the users of the IM platform SHOULD NOT be created as a SystemChatMember, but a plain ChatMember instead.

SystemChatMembers are RECOMMENDED to be created using Chat.add_system_member() or Chat.make_system_member() method.

Catatan

SystemChatMember objects are picklable, thus it is RECOMMENDED to keep any object of its subclass also picklable.

SYSTEM_ID

The default ID of a SystemChatMember.

__init__(chat, *, name='', alias=None, id='', uid='', vendor_specific=None, description='', middleware=None)

Parameter

chat (Chat) -- Chat associated with this member.

Argumen Kata Kunci

• name (str) -- Name of the member.

• alias (Optional[str]) -- Alternative name of the member, usually set by user.

• uid (ChatID (str)) -- Unique ID of the member. This MUST be unique within the channel. This ID can be the same with a private chat of the same person.

• description (str) -- A text description of the member, usually known as “bio”, “description”, “summary” or “introduction” of the member.

• middleware (Middleware) -- Initialize this chat as a part of a middleware.