Channel

Represents a Discord channel.

Attributes

guild_id : int

The channel's guild's identifier. Defaults to 0.

id : int

Unique identifier of the channel.

The channel's metadata storing it's type specific information.

The channel's type.

_message_history : None, MessageHistory

The channel's message history if any.

Properties

application_id

applied_tag_ids

applied_tags

Returns the applied tags to the thread.

Returns

applied_tags : None, tuple of ForumTag

archived

archived_at

audience

Returns the audience in the stage channel.

Returns

users : list of ClientUserBase

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

The clients, who can access this channel.

Returns

clients : list of Client

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

Returns the moderators in the stage channel.

Returns

users : list of ClientUserBase

name

nsfw

open

order_group

Returns the channel's order group.

Returns

order_group : int

owner

Returns the group channel's owner.

Returns

owner : ClientUserBase

Defaults to ZEROUSER.

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

Returns the speakers in the stage channel.

Returns

users : list of ClientUserBase

status

thread_users

threads

Returns the channel's threads.

Returns

channels : list of Channel

topic

user_limit

users

The users who can see this channel.

Returns

users : list of ClientUserBase

video_quality_mode

voice_users

Returns a list of the users who are in the voice channel.

Returns

users : list of ClientUserBase

_message_history_collector

_message_keep_limit

Methods

__new__(...)

Creates a partial channel with the given parameters.

ParameterTypeOptionalKeyword onlyDescription
channel_type

None, int, ChanelType

The channel's type.

**keyword_parameters

Keyword parameters

Additional predefined attributes for the channel.

application_id

int, Application

The application's identifier the channel is managed by.

archived

bool

Whether the (thread) channel is archived.

archived_at

None, datetime

When the thread's archive status was last changed.

applied_tag_ids

None, tuple of (int, ForumTag)

The tags' identifier which have been applied to the thread. Applicable for threads of a forum.

auto_archive_after

int

The channel's .auto_archive_after.

available_tags

None, tuple of ForumTag

The available tags to assign to the child-thread channels.

created_at

None, datetime

When the channel was created.

bitrate

int

The bitrate (in bits) of the voice channel.

created_at

None, datetime

When the (thread) channel was created.

default_forum_layout

ForumLayout, int

The default layout used to display threads of the forum.

default_sort_order

SortOrder, int

The default thread ordering of the forum.

default_thread_auto_archive_after

int

The default duration (in seconds) for newly created threads to automatically archive the themselves.

default_thread_reaction_emoji

None, Emoji

The emoji to show in the add reaction button on a thread of the forum channel.

default_thread_slowmode

int

The default slowmode applied to the channel's threads.

flags

int, ChannelFlag

The channel's flags.

icon

None, Icon, str, bytes

The channel's icon.

invitable

bool

Whether non-moderators can invite other non-moderators to the threads.

name

str

The channel's name.

nsfw

bool

Whether the channel is marked as non safe for work.

open

bool

Whether the thread channel is open.

owner_id

int, ClientUserBase

The channel's owner's or creator's identifier.

parent_id

None, int, Channel

The channel's parent's identifier.

permission_overwrites

None, list of PermissionOverwrite

The channel's permission overwrites.

position

int

The channel's position.

region

None, VoiceRegion, str

The channel's voice region.

slowmode

int

The channel's slowmode.

topic

None, str

The channel's topic.

status

None, str

The voice channel's status.

user_limit

int

The maximal amount of users, who can join the voice channel, or 0 if unlimited.

users

iterable of (int, ClientUserBase)

The users in the channel.

video_quality_mode

VideoQualityMode

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.

cached_permissions_for(user)

Returns the permissions for the given user at the channel. If the user's permissions are not cached, calculates and stores them first.

ParameterTypeDescription
user

UserBase

The user to calculate it's permissions of.

Returns

permissions : Permission

The calculated permissions.

copy()

Copies the channel returning a new partial one.

Returns

new : instance<cls>

copy_with(...)

Copies the channel with the given fields.

ParameterTypeOptionalKeyword onlyDefaultDescription
channel_type

int, ChannelType

None

The new channel's type.

**keyword_parameters

Keyword parameters

Additional parameters to pass to the channel-type specific constructor.

application_id

int, Application

The application's identifier the channel is managed by.

archived

bool

Whether the (thread) channel is archived.

archived_at

None, datetime

When the thread's archive status was last changed.

applied_tag_ids

None, tuple of (int, ForumTag)

The tags' identifier which have been applied to the thread. Applicable for threads of a forum.

auto_archive_after

int

The channel's .auto_archive_after.

available_tags

None, tuple of ForumTag

The available tags to assign to the child-thread channels.

created_at

None, datetime

When the channel was created.

bitrate

int

The bitrate (in bits) of the voice channel.

created_at

None, datetime

When the (thread) channel was created.

default_forum_layout

ForumLayout, int

The default layout used to display threads of the forum.

default_sort_order

SortOrder, int

The default thread ordering of the forum.

default_thread_auto_archive_after

int

The default duration (in seconds) for newly created threads to automatically archive the themselves.

default_thread_reaction_emoji

None, Emoji

The emoji to show in the add reaction button on a thread of the forum channel.

default_thread_slowmode

int

The default slowmode applied to the channel's threads.

flags

int, ChannelFlag

The channel's flags.

icon

None, Icon, str, bytes

The channel's icon.

invitable

bool

Whether non-moderators can invite other non-moderators to the threads.

name

str

The channel's name.

nsfw

bool

Whether the channel is marked as non safe for work.

open

bool

Whether the thread channel is open.

owner_id

int, ClientUserBase

The channel's owner's or creator's identifier.

parent_id

None, int, Channel

The channel's parent's identifier.

permission_overwrites

None, list of PermissionOverwrite

The channel's permission overwrites.

position

int

The channel's position.

region

None, VoiceRegion, str

The channel's voice region.

slowmode

int

The channel's slowmode.

topic

None, str

The channel's topic.

status

None, str

The voice channel's status.

user_limit

int

The maximal amount of users, who can join the voice channel, or 0 if unlimited.

users

iterable of (int, ClientUserBase)

The users in the channel.

video_quality_mode

VideoQualityMode

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.

from_data(data, ...)

Creates a new channel from the channel data received from Discord. If the channel already exists and if it is partial, then updates it.

ParameterTypeOptionalKeyword onlyDefaultDescription
data

dict of (str, object) items

Channel data receive from Discord.

client

None, Client

None

The client, who received the channel's data, if any.

guild_id

int

0

The guild's identifier of the channel.

strong_cache

bool

True

Whether the instance should be put into its strong cache.

Returns

self : instance<cls>

Raises

RuntimeError

The respective channel type cannot be instanced.

get_user(name, ...)

Tries to find the a user with the given name at the channel. Returns the first matched one.

ParameterTypeOptionalDefaultDescription
name

str

The name to search for.

default

object

None

The value what is returned when no user was found. Defaults to None.

Returns

user : ClientUserBase, default

get_user_like(name, ...)

Searches a user, who's name or nick starts with the given string and returns the first find.

ParameterTypeOptionalDefaultDescription
name

str

The name to search for.

default

object

None

The value what is returned when no user was found. Defaults to None.

Returns

user : ClientUserBase, default

get_users_like(name)

Searches the users, who's name or nick starts with the given string.

ParameterTypeDescription
name

str

The name to search for.

Returns

users : list of ClientUserBase

has_name_like(name)

Returns whether the channel's name is like the given string.

ParameterTypeDescription
name

str

The name of the channel.

Returns

has_name_like : bool

is_guild_announcements()

Returns whether the channel is a guild announcements channel.

Returns

is_guild_announcements : int

is_guild_category()

Returns whether the guild is a guild directory channel.

Returns

is_guild_category : int

is_guild_directory()

Returns whether the channel is a guild directory channel.

Returns

is_guild_directory : bool

is_guild_forum()

Returns whether the channel is a guild forum channel.

Returns

is_guild_forum : bool

is_guild_media()

Returns whether the channel is a guild media channel.

Returns

is_guild_media : bool

is_guild_stage()

Returns whether the channel is a guild stage channel.

Returns

is_guild_stage : bool

is_guild_store()

Returns whether the channel is a guild store channels.

Store channels are deprecated & removed from Discord.

Returns

is_guild_store : int

is_guild_text()

Returns whether the channel is a guild text channel.

Excludes Announcements and thread channels.

Returns

is_guild_text : int

is_guild_thread_announcements()

Returns whether the channel is a guild announcements thread.

Returns

is_guild_thread_announcements : bool

is_guild_thread_private()

Returns whether the channel is a guild private thread.

Returns

is_guild_thread_private : bool

is_guild_thread_public()

Returns whether the channel is a guild public thread.

Returns

is_guild_thread_public : bool

is_guild_voice()

Returns whether the guild is a guild voice channel.

Excludes stage channels.

Returns

is_guild_voice : int

is_in_group_connectable()

Returns 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_forum()

Returns whether the channel is a forum channel. Can be either forum or media.

Returns

is_in_group_forum : bool

is_in_group_guild()

Returns whether the channel is a guild channel.

Returns

is_in_group_guild : bool

is_in_group_guild_connectable()

Returns whether the channel is a guild connectable channel.

Returns

is_in_group_guild_connectable : bool

is_in_group_guild_sortable()

Returns whether the channel is a sortable guild channel.

Returns

is_in_group_guild_sortable : bool

is_in_group_guild_system()

Returns whether the channel a guild text like channel.

Excludes connectable and thread channels.

Returns

is_in_group_guild_system : bool

is_in_group_guild_textual()

Returns whether the channel is a guild and messageable one.

Returns

is_in_group_guild_textual : bool

is_in_group_invitable()

Returns whether the channel have invites created to.

Returns

is_in_group_invitable : bool

is_in_group_private()

Returns whether the channel is a private channel.

Returns

is_in_group_private : bool

is_in_group_textual()

Returns whether the channel is messageable.

Returns

is_in_group_textual : bool

is_in_group_thread()

Returns whether the channel is a thread.

Returns

is_in_group_thread : bool

is_in_group_threadable()

Returns whether the channel can have threads.

Returns

is_in_group_threadable : bool

is_private()

Returns whether the channel is a private or direct message (DM) channel.

Returns

is_private : int

is_private_group()

Returns whether the channel is a private group channel.

Returns

is_private_group : int

is_thread()

Returns whether the channel is a thread channel.

This thread channel type never made into Discord.

Returns

is_thread : bool

iter_applied_tag_ids()

Iterates over the applied tag identifiers of the channel.

This method is an iterable generator.

Yields

applied_tag_id : int

iter_applied_tags()

Iterates over the applied tags of the channels.

This method is an iterable generator.

Yields

applied_tag : ForumTag

iter_audience()

Iterates over the audience in the stage channel.

This method is an iterable generator.

Yields

user : ClientUserBase

iter_available_tags()

Iterates over the available tags of the the forum channel.

This method is an iterable generator.

Yields

available_tag : ForumTag

iter_channels()

Iterates over the channels of the category.

Unordered.

This method is an iterable generator.

Yields

channel : Channel

iter_moderators()

Iterates over the moderators in the stage channel.

This method is an iterable generator.

Yields

user : ClientUserBase

iter_speakers()

Iterates over the speakers in the stage channel.

This method is an iterable generator.

Yields

user : ClientUserBase

iter_threads()

Iterates over the channel's threads.

This method is an iterable generator.

Yields

channel : Channel

iter_users()

Iterates over the users who can see the channel.

This method is a generator.

Yields

user : ClientUserBase

iter_voice_users()

Iterates over the users who are in the voice channel.

This method is an iterable generator.

Yields

user : ClientUserBase

permissions_for(user)

Returns the permissions for the given user at the channel.

ParameterTypeDescription
user

UserBase

The user to calculate it's permissions of.

Returns

permissions : Permission

The calculated permissions.

See Also

.cached_permissions_for: Cached permission calculator.

permissions_for_roles(...)

Returns the channel permissions of an imaginary user who would have the listed roles.

ParameterTypeOptionalDescription
*roles

Role

The roles to calculate final permissions from.

Returns

permissions : Permission

The calculated permissions.

precreate(channel_id, ...)

Precreates 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.

ParameterTypeOptionalKeyword onlyDescription
channel_id

int, str

The channel's id.

channel_type

None, int, ChanelType

The channel's type.

guild_id

int, Guild

The channel's parent guild's identifier.

**keyword_parameters

Keyword parameters

Additional predefined attributes for the channel.

application_id

int, Application

The application's identifier the channel is managed by.

archived

bool

Whether the (thread) channel is archived.

archived_at

None, datetime

When the thread's archive status was last changed.

applied_tag_ids

None, tuple of (int, ForumTag)

The tags' identifier which have been applied to the thread. Applicable for threads of a forum.

auto_archive_after

int

The channel's .auto_archive_after.

available_tags

None, tuple of ForumTag

The available tags to assign to the child-thread channels.

created_at

None, datetime

When the channel was created.

bitrate

int

The bitrate (in bits) of the voice channel.

created_at

None, datetime

When the (thread) channel was created.

default_forum_layout

ForumLayout, int

The default layout used to display threads of the forum.

default_sort_order

SortOrder, int

The default thread ordering of the forum.

default_thread_auto_archive_after

int

The channel's .default_thread_auto_archive_after.

default_thread_slowmode

int

The default slowmode applied to the channel's threads.

default_thread_reaction_emoji

None, Emoji

The emoji to show in the add reaction button on a thread of the forum channel.

flags

int, ChannelFlag

The channel's flags.

icon

None, Icon, str, bytes-like

The channel's icon.

Mutually exclusive with icon_type and icon_hash parameters.

icon_type

IconType

The channel's icon's type.

Mutually exclusive with the icon parameter.

icon_hash

int

The channel's icon's hash.

Mutually exclusive with the icon parameter.

invitable

bool

Whether non-moderators can invite other non-moderators to the threads.

name

str

The channel's name.

nsfw

bool

Whether the channel is marked as non safe for work.

open

bool

Whether the thread channel is open.

owner_id

int, ClientUserBase

The channel's owner's or creator's identifier.

parent_id

None, int, Channel

The channel's parent's identifier.

permission_overwrites

None, list of PermissionOverwrite

The channel's permission overwrites.

position

int

The channel's position.

region

None, VoiceRegion, str

The channel's voice region.

slowmode

int

The channel's slowmode.

topic

None, str

The channel's topic.

user_limit

int

The channel's .user_limit.

users

iterable of (int, ClientUserBase)

The users in the channel.

video_quality_mode

VideoQualityMode

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_data(...)

Converts the channel to json serializable representation dictionary.

ParameterTypeOptionalKeyword onlyDefaultDescription
defaults

bool

False

Whether default values should be included as well.

include_internals

bool

False

Whether we want to include identifiers as well.

Returns

data : dict of (str, object) items

_add_message_collection_delay(delay)

Sets message collection timeout to the exact given time.

ParameterTypeDescription
delay

float

The time to delay the message collection with.

_cancel_message_collection()

Cancels the message collector of the channel.

_create_empty(channel_id, channel_type, guild_id)

Creates a partial channel from the given parameters.

ParameterTypeDescription
channel_id

int

The channel's identifier.

channel_type

ChannelType

The channel's type.

guild_id

int

A partial guild's identifier for the created channel.

Returns

self : instance<cls>

The created partial channel.

_create_find_message(message_data, chained)

Tries 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.

ParameterTypeDescription
message_data

dict of (str, object) items

The message's data to find or create.

chained

bool

Whether the created message should be chained to the channel's message history's end, if not found.

Returns

message : Message found : bool

_create_new_message(message_data)

Creates a new message at the channel. If the message already exists inside of the channel's message history, returns that instead.

ParameterTypeDescription
message_data

dict of (str, object) items

Message data received from Discord.

Returns

message : Message

_create_old_message(message_data)

Creates an old message at the channel. If the message already exists inside of the channel's message history, returns that instead.

ParameterTypeDescription
message_data

dict of (str, object) items

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.

_create_private_data_less(channel_id)

Creates 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.

ParameterTypeDescription
channel_id

int

The channel's respective id.

Returns

self : instance<cls>

_delete(client)

Called when the channel is deleted.

Removes the channel's references.

ParameterTypeDescription
client

None, Client

The parent client entity.

_difference_update_attributes(data)

Updates the channel and returns it's overwritten attributes as a dict with a attribute-name- old-value relation.

ParameterTypeDescription
data

dict of (str, object) items

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:

KeysValues
applied_tag_idsNone, tuple of int
archivedbool
archived_atNone, datetime
auto_archive_afterint
available_tagsForumTagChange
bitrateint
default_forum_layoutForumLayout
default_sort_orderSortOrder
default_thread_auto_archive_afterint
default_thread_reaction_emojiNone, Emoji
default_thread_slowmodeint
flagsChannelFlag
iconIcon
invitablebool
metadataChannelMetadataBase
namestr
nsfwbool
openbool
owner_idint
parent_idint
permission_overwritesNone, dict of (int, PermissionOverwrite) items
positionint
regionNone, VoiceRegion
slowmodeint
topicNone, str
typeChannelType
user_limitint
video_quality_modeVideoQualityMode

_difference_update_status(data)

Updates the channel's status and if changed returns it in a dict with a attribute-name- old-value relation.

ParameterTypeDescription
data

dict of (str, object) items

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:

KeysValues
statusNone, str

_finish_private_data_less(client, user)

Finishes the initialization of the channel after a ._create_private_data_less call.

ParameterTypeDescription
client

Client

The client recipient of the channel.

user

ClientUserBase

The other recipient of the channel.

_from_partial_data(data, channel_id, guild_id)

Creates a channel from partial data. Called by create_partial_channel_from_data when a new partial channel is needed to be created.

ParameterTypeDescription
data

None, dict of (str, object) items

Partial channel data.

channel_id

int

The channel's id.

guild_id

int

The channel's guild's identifier if applicable.

Returns

self : instance<cls>

_get_hash_partial()

Calculates 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

_is_equal_same_time(other)

Returns whether the channel is equal to the other one.

ParameterTypeDescription
other

instance<type<self>>

The other channel entity.

Returns

is_equal : bool

_iter_delete(client)

Called 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.

ParameterTypeDescription
client

None, Client

The parent client entity.

Yields

channel : Channel

_maybe_create_queue()

Gets the channel's messages when creating a new message is created.

Returns

messages : deque, None

_maybe_increase_queue_size()

Increases the queue size of the channel's message history if needed and returns it.

Returns

messages : deque

_pop_message(delete_id)

Removes the specific message by it's id from the channel's message history and from MESSAGES as well.

ParameterTypeDescription
delete_id

int

The message's id to delete from the channel's message history.

Returns

message : None, Message

_pop_multiple(delete_ids)

Removes the given messages from the channel and from MESSAGES as well. Returns the found messages.

ParameterTypeDescription
delete_ids

list of int

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_limited()

Switches a channel's .messages to limited from unlimited.

_update_attributes(data)

Updates the channel with overwriting it's old attributes.

ParameterTypeDescription
data

dict of (str, object) items

Channel data received from Discord.

_update_status(data)

Updates the channel's status.

ParameterTypeDescription
data

dict of (str, object) items

Channel status update data received from Discord.

__eq__()

Returns whether this channel's is equal to the other's.

__format__(code)

Formats the channel in a format string.

ParameterTypeDescription
code

str

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.