Channel
Represents a Discord channel.
Attributes
int
The channel's guild's identifier. Defaults to 0
.
int
Unique identifier of the channel.
The channel's metadata storing it's type specific information.
The channel's type.
None
, MessageHistory
The channel's message history if any.
Properties
application_id
applied_tag_ids
applied_tags
archived
archived_at
audience
auto_archive_after
available_tags
bitrate
channel_list
Deprecated and will be removed in 2023 September. Please use .channels
instead.
channels
Returns the channels of the category in a list in their display order.
Returns
channels : list
of Channel
clients
created_at
Returns when the channel was created.
Returns
created_at : datetime
default_forum_layout
default_sort_order
default_thread_auto_archive_after
default_thread_reaction
Deprecated and will be removed in 2024 Marc. Please use .default_thread_reaction_emoji
instead.
default_thread_reaction_emoji
default_thread_slowmode
display_name
The channel's display name.
Returns
display_name : str
flags
guild
Returns the channel's guild. At the case of private channels this is always None
.
Returns
guild : None
, Guild
icon
invitable
mention
The channel's mention.
Returns
mention : str
message_history_reached_end
message_keep_limit
A property for getting or setting how much message the channel can store before removing the last.
Returns and accepts an int
.
messages
moderators
name
nsfw
open
order_group
Returns the channel's order group.
Returns
order_group : int
owner
owner_id
parent
Returns the channel's parent.
If the channel has no parent, or if not applicable for the specific channel type returns None
.
Returns
parent : None
, Channel
parent_id
partial
Whether this channel is partial.
A channel is partial if non of the running clients can see it.
Returns
is_partial : bool
permission_overwrites
position
region
slowmode
speakers
status
thread_users
threads
topic
user_limit
users
video_quality_mode
voice_users
_message_history_collector
_message_keep_limit
Methods
(...)
__new__Creates a partial channel with the given parameters.
Parameter | Type | Optional | Keyword only | Description |
---|---|---|---|---|
channel_type |
| The channel's type. | ||
**keyword_parameters | Keyword parameters | Additional predefined attributes for the channel. | ||
application_id |
| The application's identifier the channel is managed by. | ||
archived |
| Whether the (thread) channel is archived. | ||
archived_at |
| When the thread's archive status was last changed. | ||
applied_tag_ids |
| The tags' identifier which have been applied to the thread. Applicable for threads of a forum. | ||
auto_archive_after |
| The channel's | ||
available_tags |
| The available tags to assign to the child-thread channels. | ||
created_at |
| When the channel was created. | ||
bitrate |
| The bitrate (in bits) of the voice channel. | ||
created_at |
| When the (thread) channel was created. | ||
default_forum_layout |
| The default layout used to display threads of the forum. | ||
default_sort_order |
| The default thread ordering of the forum. | ||
default_thread_auto_archive_after |
| The default duration (in seconds) for newly created threads to automatically archive the themselves. | ||
default_thread_reaction_emoji |
| The emoji to show in the add reaction button on a thread of the forum channel. | ||
default_thread_slowmode |
| The default slowmode applied to the channel's threads. | ||
flags |
| The channel's flags. | ||
icon |
| The channel's icon. | ||
invitable |
| Whether non-moderators can invite other non-moderators to the threads. | ||
name |
| The channel's name. | ||
nsfw |
| Whether the channel is marked as non safe for work. | ||
open |
| Whether the thread channel is open. | ||
owner_id |
| The channel's owner's or creator's identifier. | ||
parent_id |
| The channel's parent's identifier. | ||
permission_overwrites |
| The channel's permission overwrites. | ||
position |
| The channel's position. | ||
region |
| The channel's voice region. | ||
slowmode |
| The channel's slowmode. | ||
topic |
| The channel's topic. | ||
status |
| The voice channel's status. | ||
user_limit |
| The maximal amount of users, who can join the voice channel, or | ||
users |
| The users in the channel. | ||
video_quality_mode | The video quality of the voice channel. |
Raises
TypeError
If any parameter's type is bad or if unexpected parameter is passed.
ValueError
If an parameter's type is good, but it's value is unacceptable.
(user)
cached_permissions_forReturns the permissions for the given user at the channel. If the user's permissions are not cached, calculates and stores them first.
Parameter | Type | Description |
---|---|---|
user | The user to calculate it's permissions of. |
Returns
permissions : Permission
The calculated permissions.
()
copyCopies the channel returning a new partial one.
Returns
new : instance<cls>
(...)
copy_withCopies the channel with the given fields.
Parameter | Type | Optional | Keyword only | Default | Description |
---|---|---|---|---|---|
channel_type |
|
| The new channel's type. | ||
**keyword_parameters | Keyword parameters | Additional parameters to pass to the channel-type specific constructor. | |||
application_id |
| The application's identifier the channel is managed by. | |||
archived |
| Whether the (thread) channel is archived. | |||
archived_at |
| When the thread's archive status was last changed. | |||
applied_tag_ids |
| The tags' identifier which have been applied to the thread. Applicable for threads of a forum. | |||
auto_archive_after |
| The channel's | |||
available_tags |
| The available tags to assign to the child-thread channels. | |||
created_at |
| When the channel was created. | |||
bitrate |
| The bitrate (in bits) of the voice channel. | |||
created_at |
| When the (thread) channel was created. | |||
default_forum_layout |
| The default layout used to display threads of the forum. | |||
default_sort_order |
| The default thread ordering of the forum. | |||
default_thread_auto_archive_after |
| The default duration (in seconds) for newly created threads to automatically archive the themselves. | |||
default_thread_reaction_emoji |
| The emoji to show in the add reaction button on a thread of the forum channel. | |||
default_thread_slowmode |
| The default slowmode applied to the channel's threads. | |||
flags |
| The channel's flags. | |||
icon |
| The channel's icon. | |||
invitable |
| Whether non-moderators can invite other non-moderators to the threads. | |||
name |
| The channel's name. | |||
nsfw |
| Whether the channel is marked as non safe for work. | |||
open |
| Whether the thread channel is open. | |||
owner_id |
| The channel's owner's or creator's identifier. | |||
parent_id |
| The channel's parent's identifier. | |||
permission_overwrites |
| The channel's permission overwrites. | |||
position |
| The channel's position. | |||
region |
| The channel's voice region. | |||
slowmode |
| The channel's slowmode. | |||
topic |
| The channel's topic. | |||
status |
| The voice channel's status. | |||
user_limit |
| The maximal amount of users, who can join the voice channel, or | |||
users |
| The users in the channel. | |||
video_quality_mode | The video quality of the voice channel. |
Returns
new : instance<type<self>>
Raises
TypeError
- If a parameter's type is incorrect.
- If extra or unused parameters were given.
ValueError
- If a parameter's value is incorrect.
(data, ...)
from_dataCreates a new channel from the channel data received from Discord. If the channel already exists and if it is partial, then updates it.
Parameter | Type | Optional | Keyword only | Default | Description |
---|---|---|---|---|---|
data |
| Channel data receive from Discord. | |||
client |
|
| The client, who received the channel's data, if any. | ||
guild_id |
|
| The guild's identifier of the channel. | ||
strong_cache |
|
| Whether the instance should be put into its strong cache. |
Returns
self : instance<cls>
Raises
RuntimeError
The respective channel type cannot be instanced.
(name, ...)
get_userTries to find the a user with the given name at the channel. Returns the first matched one.
Parameter | Type | Optional | Default | Description |
---|---|---|---|---|
name |
| The name to search for. | ||
default |
|
| The value what is returned when no user was found. Defaults to |
Returns
user : ClientUserBase
, default
(name, ...)
get_user_likeSearches a user, who's name or nick starts with the given string and returns the first find.
Parameter | Type | Optional | Default | Description |
---|---|---|---|---|
name |
| The name to search for. | ||
default |
|
| The value what is returned when no user was found. Defaults to |
Returns
user : ClientUserBase
, default
(name)
get_users_likeSearches the users, who's name or nick starts with the given string.
Parameter | Type | Description |
---|---|---|
name |
| The name to search for. |
Returns
users : list
of ClientUserBase
(name)
has_name_likeReturns whether the channel's name is like the given string.
Parameter | Type | Description |
---|---|---|
name |
| The name of the channel. |
Returns
has_name_like : bool
()
is_guild_announcementsReturns whether the channel is a guild announcements channel.
Returns
is_guild_announcements : int
()
is_guild_categoryReturns whether the guild is a guild directory channel.
Returns
is_guild_category : int
()
is_guild_directoryReturns whether the channel is a guild directory channel.
Returns
is_guild_directory : bool
()
is_guild_forumReturns whether the channel is a guild forum channel.
Returns
is_guild_forum : bool
()
is_guild_mediaReturns whether the channel is a guild media channel.
Returns
is_guild_media : bool
()
is_guild_stageReturns whether the channel is a guild stage channel.
Returns
is_guild_stage : bool
()
is_guild_storeReturns whether the channel is a guild store channels.
Store channels are deprecated & removed from Discord.
Returns
is_guild_store : int
()
is_guild_textReturns whether the channel is a guild text channel.
Excludes Announcements and thread channels.
Returns
is_guild_text : int
()
is_guild_thread_announcementsReturns whether the channel is a guild announcements thread.
Returns
is_guild_thread_announcements : bool
()
is_guild_thread_privateReturns whether the channel is a guild private thread.
Returns
is_guild_thread_private : bool
()
is_guild_thread_publicReturns whether the channel is a guild public thread.
Returns
is_guild_thread_public : bool
()
is_guild_voiceReturns whether the guild is a guild voice channel.
Excludes stage channels.
Returns
is_guild_voice : int
()
is_in_group_connectableReturns whether the channel is connectable.
Includes private connectable channels. Bots cannot connect to those, so you might want to use
.is_guild_connectable
instead.
Returns
is_in_group_connectable : bool
()
is_in_group_forumReturns whether the channel is a forum channel. Can be either forum
or media
.
Returns
is_in_group_forum : bool
()
is_in_group_guildReturns whether the channel is a guild channel.
Returns
is_in_group_guild : bool
()
is_in_group_guild_connectableReturns whether the channel is a guild connectable channel.
Returns
is_in_group_guild_connectable : bool
()
is_in_group_guild_sortableReturns whether the channel is a sortable guild channel.
Returns
is_in_group_guild_sortable : bool
()
is_in_group_guild_systemReturns whether the channel a guild text like channel.
Excludes connectable and thread channels.
Returns
is_in_group_guild_system : bool
()
is_in_group_guild_textualReturns whether the channel is a guild and messageable one.
Returns
is_in_group_guild_textual : bool
()
is_in_group_invitableReturns whether the channel have invites created to.
Returns
is_in_group_invitable : bool
()
is_in_group_privateReturns whether the channel is a private channel.
Returns
is_in_group_private : bool
()
is_in_group_textualReturns whether the channel is messageable.
Returns
is_in_group_textual : bool
()
is_in_group_threadReturns whether the channel is a thread.
Returns
is_in_group_thread : bool
()
is_in_group_threadableReturns whether the channel can have threads.
Returns
is_in_group_threadable : bool
()
is_privateReturns whether the channel is a private or direct message (DM) channel.
Returns
is_private : int
()
is_private_groupReturns whether the channel is a private group channel.
Returns
is_private_group : int
()
is_threadReturns whether the channel is a thread channel.
This thread channel type never made into Discord.
Returns
is_thread : bool
()
iter_applied_tag_idsIterates over the applied tag identifiers of the channel.
This method is an iterable generator.
Yields
applied_tag_id : int
()
iter_applied_tagsIterates over the applied tags of the channels.
This method is an iterable generator.
Yields
applied_tag : ForumTag
()
iter_audienceIterates over the audience in the stage channel.
This method is an iterable generator.
Yields
user : ClientUserBase
()
iter_available_tagsIterates over the available tags of the the forum channel.
This method is an iterable generator.
Yields
available_tag : ForumTag
()
iter_channelsIterates over the channels of the category.
Unordered.
This method is an iterable generator.
Yields
channel : Channel
()
iter_moderatorsIterates over the moderators in the stage channel.
This method is an iterable generator.
Yields
user : ClientUserBase
()
iter_speakersIterates over the speakers in the stage channel.
This method is an iterable generator.
Yields
user : ClientUserBase
()
iter_threads()
iter_usersIterates over the users who can see the channel.
This method is a generator.
Yields
user : ClientUserBase
()
iter_voice_usersIterates over the users who are in the voice channel.
This method is an iterable generator.
Yields
user : ClientUserBase
(user)
permissions_forReturns the permissions for the given user at the channel.
Parameter | Type | Description |
---|---|---|
user | The user to calculate it's permissions of. |
Returns
permissions : Permission
The calculated permissions.
See Also
.cached_permissions_for
: Cached permission calculator.
(...)
permissions_for_rolesReturns the channel permissions of an imaginary user who would have the listed roles.
Parameter | Type | Optional | Description |
---|---|---|---|
*roles | The roles to calculate final permissions from. |
Returns
permissions : Permission
The calculated permissions.
(channel_id, ...)
precreatePrecreates the channel by creating a partial one with the given parameters. When the channel is loaded the precreated channel will be picked up. If an already existing channel would be precreated, returns that instead and updates that only, if that is a partial channel.
Parameter | Type | Optional | Keyword only | Description |
---|---|---|---|---|
channel_id |
| The channel's id. | ||
channel_type |
| The channel's type. | ||
guild_id |
| The channel's parent guild's identifier. | ||
**keyword_parameters | Keyword parameters | Additional predefined attributes for the channel. | ||
application_id |
| The application's identifier the channel is managed by. | ||
archived |
| Whether the (thread) channel is archived. | ||
archived_at |
| When the thread's archive status was last changed. | ||
applied_tag_ids |
| The tags' identifier which have been applied to the thread. Applicable for threads of a forum. | ||
auto_archive_after |
| The channel's | ||
available_tags |
| The available tags to assign to the child-thread channels. | ||
created_at |
| When the channel was created. | ||
bitrate |
| The bitrate (in bits) of the voice channel. | ||
created_at |
| When the (thread) channel was created. | ||
default_forum_layout |
| The default layout used to display threads of the forum. | ||
default_sort_order |
| The default thread ordering of the forum. | ||
default_thread_auto_archive_after |
| The channel's | ||
default_thread_slowmode |
| The default slowmode applied to the channel's threads. | ||
default_thread_reaction_emoji |
| The emoji to show in the add reaction button on a thread of the forum channel. | ||
flags |
| The channel's flags. | ||
icon |
| The channel's icon.
| ||
icon_type | The channel's icon's type.
| |||
icon_hash |
| The channel's icon's hash.
| ||
invitable |
| Whether non-moderators can invite other non-moderators to the threads. | ||
name |
| The channel's name. | ||
nsfw |
| Whether the channel is marked as non safe for work. | ||
open |
| Whether the thread channel is open. | ||
owner_id |
| The channel's owner's or creator's identifier. | ||
parent_id |
| The channel's parent's identifier. | ||
permission_overwrites |
| The channel's permission overwrites. | ||
position |
| The channel's position. | ||
region |
| The channel's voice region. | ||
slowmode |
| The channel's slowmode. | ||
topic |
| The channel's topic. | ||
user_limit |
| The channel's | ||
users |
| The users in the channel. | ||
video_quality_mode | The video quality of the voice channel. |
Returns
self : instance<cls>
Raises
TypeError
If any parameter's type is bad or if unexpected parameter is passed.
ValueError
If an parameter's type is good, but it's value is unacceptable.
(...)
to_dataConverts the channel to json serializable representation dictionary.
Parameter | Type | Optional | Keyword only | Default | Description |
---|---|---|---|---|---|
defaults |
|
| Whether default values should be included as well. | ||
include_internals |
|
| Whether we want to include identifiers as well. |
Returns
data : dict
of (str
, object
) items
(delay)
_add_message_collection_delaySets message collection timeout to the exact given time.
Parameter | Type | Description |
---|---|---|
delay |
| The time to delay the message collection with. |
()
_cancel_message_collectionCancels the message collector of the channel.
(channel_id, channel_type, guild_id)
_create_emptyCreates a partial channel from the given parameters.
Parameter | Type | Description |
---|---|---|
channel_id |
| The channel's identifier. |
channel_type | The channel's type. | |
guild_id |
| A partial guild's identifier for the created channel. |
Returns
self : instance<cls>
The created partial channel.
(message_data, chained)
_create_find_messageTries to find whether the given message's data represents an existing message at the channel. If not, creates it. This method also returns whether the message existed at the channel's message history.
Parameter | Type | Description |
---|---|---|
message_data |
| The message's data to find or create. |
chained |
| Whether the created message should be chained to the channel's message history's end, if not found. |
Returns
message : Message
found : bool
(message_data)
_create_new_messageCreates a new message at the channel. If the message already exists inside of the channel's message history, returns that instead.
Parameter | Type | Description |
---|---|---|
message_data |
| Message data received from Discord. |
Returns
message : Message
(message_data)
_create_old_messageCreates an old message at the channel. If the message already exists inside of the channel's message history, returns that instead.
Parameter | Type | Description |
---|---|---|
message_data |
| Message data received from Discord. |
Returns
message : Message
Notes
The created message cannot be added to the channel's message history, if it has no more spaces.
(channel_id)
_create_private_data_lessCreates a private channel from a channel id. Might be called by events, when a message's channel is not found and it is a private channel.
Parameter | Type | Description |
---|---|---|
channel_id |
| The channel's respective id. |
Returns
self : instance<cls>
(client)
_deleteCalled when the channel is deleted.
Removes the channel's references.
Parameter | Type | Description |
---|---|---|
client |
| The parent client entity. |
(data)
_difference_update_attributesUpdates the channel and returns it's overwritten attributes as a dict
with a attribute-name
- old-value
relation.
Parameter | Type | Description |
---|---|---|
data |
| Channel data received from Discord. |
Returns
old_attributes : dict
of (str
, object
) items
All item in the returned dict is optional.
Might contain the following items:
Keys | Values |
---|---|
applied_tag_ids | None , tuple of int |
archived | bool |
archived_at | None , datetime |
auto_archive_after | int |
available_tags | ForumTagChange |
bitrate | int |
default_forum_layout | ForumLayout |
default_sort_order | SortOrder |
default_thread_auto_archive_after | int |
default_thread_reaction_emoji | None , Emoji |
default_thread_slowmode | int |
flags | ChannelFlag |
icon | Icon |
invitable | bool |
metadata | ChannelMetadataBase |
name | str |
nsfw | bool |
open | bool |
owner_id | int |
parent_id | int |
permission_overwrites | None , dict of (int , PermissionOverwrite ) items |
position | int |
region | None , VoiceRegion |
slowmode | int |
topic | None , str |
type | ChannelType |
user_limit | int |
video_quality_mode | VideoQualityMode |
(data)
_difference_update_statusUpdates the channel's status and if changed returns it in a dict
with a attribute-name
- old-value
relation.
Parameter | Type | Description |
---|---|---|
data |
| Channel status update data received from Discord. |
Returns
old_attributes : dict
of (str
, object
) items
All item in the returned dict is optional.
Might contain the following items:
Keys | Values |
---|---|
status | None , str |
(client, user)
_finish_private_data_lessFinishes the initialization of the channel after a ._create_private_data_less
call.
Parameter | Type | Description |
---|---|---|
client | The client recipient of the channel. | |
user | The other recipient of the channel. |
(data, channel_id, guild_id)
_from_partial_dataCreates a channel from partial data. Called by create_partial_channel_from_data
when a new partial channel is needed to be created.
Parameter | Type | Description |
---|---|---|
data |
| Partial channel data. |
channel_id |
| The channel's id. |
guild_id |
| The channel's guild's identifier if applicable. |
Returns
self : instance<cls>
()
_get_hash_partialCalculates the channel's hash based on their fields.
This method is called by .__hash__
if the channel has no .id
set.
Returns
hash_value : int
(other)
_is_equal_same_timeReturns whether the channel is equal to the other one.
Parameter | Type | Description |
---|---|---|
other |
| The other channel entity. |
Returns
is_equal : bool
(client)
_iter_deleteCalled when a channel is deleted. Not like ._delete
this will apply deletion to all related channel as well, technically calling ._delete
on all.
This method is an iterable generator.
Parameter | Type | Description |
---|---|---|
client |
| The parent client entity. |
Yields
channel : Channel
()
_maybe_create_queueGets the channel's messages when creating a new message is created.
Returns
messages : deque
, None
()
_maybe_increase_queue_sizeIncreases the queue size of the channel's message history if needed and returns it.
Returns
messages : deque
(delete_id)
_pop_messageRemoves the specific message by it's id from the channel's message history and from MESSAGES
as well.
Parameter | Type | Description |
---|---|---|
delete_id |
| The message's id to delete from the channel's message history. |
Returns
message : None
, Message
(delete_ids)
_pop_multipleRemoves the given messages from the channel and from MESSAGES
as well. Returns the found messages.
Parameter | Type | Description |
---|---|---|
delete_ids |
| The messages' id to delete from the channel's message history. |
Returns
found : list
of Message
The found and removed messages.
missed : list
of int
The identifier of the not found messages.
()
_switch_to_limitedSwitches a channel's .messages
to limited from unlimited.
(data)
_update_attributesUpdates the channel with overwriting it's old attributes.
Parameter | Type | Description |
---|---|---|
data |
| Channel data received from Discord. |
(data)
_update_statusUpdates the channel's status.
Parameter | Type | Description |
---|---|---|
data |
| Channel status update data received from Discord. |
()
__eq__Returns whether this channel's is equal to the other's.
(code)
__format__Formats the channel in a format string.
Parameter | Type | Description |
---|---|---|
code |
| The option on based the result will be formatted. |
Returns
channel : str
Raises
ValueError
Unknown format code.
Examples
>>> from hata import Channel, now_as_id
>>> channel = Channel.precreate(now_as_id(), name = 'GENERAL')
>>> channel
<Channel id = 710506058560307200, name = 'GENERAL'>
>>> # no code stands for `channel.name`.
>>> f'{channel}'
'GENERAL'
>>> # 'd' stands for display name.
>>> f'{channel:d}'
'general'
>>> # 'm' stands for mention.
>>> f'{channel:m}'
'<#710506058560307200>'
>>> # 'c' stands for created at.
>>> f'{channel:c}'
'2020.05.14-14:57:24'
()
__ge__Returns whether this channel's is greater or equal than the other's.
()
__getattr__Drops a rich attribute error.
()
__gt__Returns whether this channel's is greater than the other's.
()
__hash__Returns the channel's hash value.
()
__le__Returns whether this channel's is less or equal than the other's.
()
__lt__Returns whether this channel's is less than the other's.
()
__ne__Returns whether this channel's is not equal to the other's.
()
__repr__Returns the representation of the channel.