Chat and Chat Members¶
Inheritance diagram
Summary
|
A private chat, where usually only the User Themself and the other participant are in the chat. |
|
A system chat, where usually only the User Themself and the other participant (system chat member) are in the chat. |
|
A group chat, where there are usually multiple members present. |
|
Member of a chat. |
|
The User Themself as member of a chat. |
|
A system account/prompt as member of a chat. |
|
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='')[source]¶
Bases:
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.
Note
BaseChat
objects are picklable, thus it is RECOMMENDED to keep any object of its subclass also picklable.- description¶
A text description of the chat, usually known as “bio”, “description”, “purpose”, or “topic” of the chat.
- Type
- __init__(*, channel=None, middleware=None, module_name='', channel_emoji='', module_id='', name='', alias=None, uid='', id='', vendor_specific=None, description='')[source]¶
- Parameters
channel (Optional[
SlaveChannel
]) – Provide the channel object to fillmodule_name
,channel_emoji
, andmodule_id
automatically.middleware (Optional[
Middleware
]) – Provide the middleware object to fillmodule_name
, andmodule_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.
- 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
- abstract verify()[source]¶
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)[source]¶
Bases:
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)
Note
Chat
objects are picklable, thus it is RECOMMENDED to keep any object of its subclass also picklable.- description¶
A text description of the chat, usually known as “bio”, “description”, “purpose”, or “topic” of the chat.
- Type
- notification¶
Indicate the notification settings of the chat in its slave channel (or middleware), defaulted to
ALL
.
- 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
- 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)[source]¶
- Keyword Arguments
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 emptylist
.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)[source]¶
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=...)
- Parameters
- Keyword Arguments
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
- add_self()[source]¶
Add self to the list of members.
- Raises
AssertionError – When there is already a self in the list of members.
- Return type
- add_system_member(name='', alias=None, id='', uid='', vendor_specific=None, description='', middleware=None)[source]¶
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.
- Keyword Arguments
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
- get_member(member_id)[source]¶
Find a member of chat by its ID.
- make_system_member(name='', alias=None, id='', uid='', vendor_specific=None, description='', middleware=None)[source]¶
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.
- Keyword Arguments
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
- 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)[source]¶
Bases:
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
.ChatMember
s 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.ChatMember
s are RECOMMENDED to be created usingChat.add_member()
method.Note
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)[source]¶
- Parameters
chat (
Chat
) – Chat associated with this member.- Keyword Arguments
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()[source]¶
Verify the completeness of the data.
- Raises
AssertionError – When this chat is invalid.
- class ehforwarderbot.chat.ChatNotificationState(value)[source]¶
Bases:
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)[source]¶
Bases:
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 isTrue
(which is the default setting), the User Themself would also be initialized as a member of the chat.Examples
>>> 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='')]
Note
GroupChat
objects are picklable, thus it is RECOMMENDED to keep any object of its subclass also picklable.- verify()[source]¶
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)[source]¶
Bases:
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 isTrue
(which is the default setting), the User Themself would also be initialized as a member of the chat.- Parameters
other – the other participant of the chat as a member
Note
PrivateChat
objects are picklable, thus it is RECOMMENDED to keep any object of its subclass also picklable.- verify()[source]¶
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)[source]¶
Bases:
ehforwarderbot.chat.ChatMember
The User Themself as member of a chat.
SelfChatMember
s are RECOMMENDED to be created together with a chat object by settingwith_self
value toTrue
. The created object is accessible atChat.self
.The default ID of a
SelfChatMember
object isSelfChatMember.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.
Note
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)[source]¶
- Parameters
chat (
Chat
) – Chat associated with this member.- Keyword Arguments
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)[source]¶
Bases:
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 isTrue
(which is the default setting), the User Themself would also be initialized as a member of the chat.- Parameters
other – the other participant of the chat as a member
Note
SystemChat
objects are picklable, thus it is RECOMMENDED to keep any object of its subclass also picklable.- verify()[source]¶
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)[source]¶
Bases:
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 plainChatMember
instead.SystemChatMember
s are RECOMMENDED to be created usingChat.add_system_member()
orChat.make_system_member()
method.Note
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)[source]¶
- Parameters
chat (
Chat
) – Chat associated with this member.- Keyword Arguments
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.