Guild

Represents a Discord guild (or server).

Attributes

afk_channel_id : int

The afk channel's identifier of the guild if it has.

Defaults to 0.

afk_timeout : int

The afk timeout at the afk_channel. Can be 0, 60, 300, 900, 1800, 3600 in seconds.

Defaults to 0 if not applicable.

approximate_online_count : int

The approximate amount of online users at the guild.

Defaults to 0 if not yet received / requested.

approximate_user_count : int

The approximate amount of users at the guild.

Defaults to 0 if not yet received / requested.

available : bool

Whether the guild is available.

banner_hash : int

The guild's banner's hash in uint128.

banner_type : IconType

The guild's banner's type.

boost_count : int

The total number of boosts of the guild.

boost_progress_bar_enabled : bool

Whether the guild has the boost progress bar enabled.

channels : dict of (int, Channel) items

The channels of the guild stored in channel_id- channel relation.

clients : list of Client

The loaded clients, who are the member of the guild. If no clients are member of a guild, it is partial.

default_message_notification_level : MessageNotificationLevel

The default message notification level of the guild.

description : None, str

Description of the guild. The guild must be a Community guild.

discovery_splash_hash : int

The guild's discovery splash's hash in uint128. The guild must be a discoverable.

discovery_splash_type : IconType

The guild's discovery splash's type.

embedded_activity_states : None, set of EmbeddedActivityState

Embedded activity states to keep them alive in cache.

emojis : dict of (int, Emoji) items

The emojis of the guild stored in emoji_id- emoji relation.

explicit_content_filter_level : ExplicitContentFilterLevel

The explicit content filter level of the guild.

features : None, tuple of GuildFeature

The guild's features.

hub_type : HubType

The guild's hub type. Only applicable for hub guilds.

icon_hash : int

The guild's icon's hash in uint128.

icon_type : IconType

The guild's icon's type.

id : int

The unique identifier number of the guild.

incidents : None, GuildIncidents

The guild's incidents (if any).

inventory_settings : None, GuildInventorySettings

The guild's inventory settings (if any).

invite_splash_hash : int

The guild's invite splash's hash in uint128. The guild must have INVITE_SPLASH feature.

invite_splash_type : IconType

The guild's invite splash's type.

large : bool

Whether the guild is considered as a large one.

locale : Locale

The preferred language of the guild.

The guild must be a Community guild, defaults to 'en-US'.

max_presences : int

The maximal amount of presences for the guild.

Defaults to 0. Only applicable for very large guilds.

max_stage_channel_video_users : int

The maximal amount of users watching a video in a stage channel.

Defaults to 50.

max_users : int

The maximal allowed users in the guild.

Defaults to 250000.

max_voice_channel_video_users : int

The maximal amount of users watching a video in a stage channel.

Defaults to 25.

mfa_level : MfaLevel

The required multi-factor authentication level for the guild.

name : str

The name of the guild.

nsfw_level : NsfwLevel

The guild's nsfw level.

owner_id : int

The guild's owner's id.

Defaults to 0.

premium_tier : int

The premium tier of the guild. More boosters = higher tier.

Defaults to 0.

public_updates_channel_id : int

The channel's identifier where the guild's public updates should go.

Defaults to 0. The guild must be a community guild.

roles : dict of (int, Role) items

The roles of the guild stored in role_id- role relation.

rules_channel_id : int

The channel's identifier where the rules of a public guild's should be.

Defaults to 0. The guild must be a community guild.

safety_alerts_channel_id : int

The channel's identifier where safety alerts are sent by Discord.

Defaults to 0.

scheduled_events : dict of (int, ScheduledEvent) items

The scheduled events of the guild.

soundboard_sounds : None, dict of (int, SoundboardSound) items

The soundboard sounds of the guild.

Defaults to None if would be empty.

stages : None, dict of (int, Stage) items

Active stages of the guild.

Defaults to None if would be empty.

stickers : dict of (int, Sticker) items

Stickers of the guild.

system_channel_flags : SystemChannelFlag

Describe which type of messages are sent automatically to the system channel.

system_channel_id : int

The channel's identifier where the system messages are sent.

Defaults to 0.

threads : dict of (int, Channel)

Thread channels of the guild.

user_count : int

The amount of users at the guild.

Defaults to 0.

users : dict, WeakValueDictionary of (int, ClientUserBase) items

The users at the guild stored within user_id- user relation.

vanity_code : None, str

The guild's vanity invite's code if it has.

verification_level : VerificationLevel

The minimal verification needed to join or to interact with guild.

voice_states : dict of (int, VoiceState) items

Each user at a voice channel is represented by a their voice state. Voice state are stored in respective user's id- voice state relation.

widget_channel_id : int

The channel's identifier for which the guild's widget is for.

Defaults to 0.

widget_enabled : bool

Whether the guild's widget is enabled. Linked to .widget_channel.

_cache_boosters : None, list of ClientUserBase

Cached slot for the boosters of the guild.

_cache_permission : None, dict of (int, Permission) items

A user_id to Permission relation mapping for caching permissions. Defaults to None.

_state : int

Bitwise mask used to track the guild's state.

Notes

When a guild is loaded first time, some of it's attributes might not reflect their real value. These are the following:

Properties

afk_channel

Returns the afk channel of the guild if it has.

Returns

afk_channel : None, Channel

announcement_channels

Returns the announcement channels of the guild.

Returns

channels : list of Channel

banner

Returns the respective icon.

Returns

icon : Icon

banner_url

Returns the guild's banner's image's url. If the guild has no banner, then returns None.

This function is a shared property of Guild-s.

Returns

url : None, str

bitrate_limit

The maximal bitrate for the guild's voice channels.

Returns

limit : int

boosters

The boosters of the guild sorted by their subscription date.

These users are queried from the guild's .users dictionary, so make sure that is populated before accessing the property.

Returns

boosters : None, tuple of ClientUserBase

category_channels

Returns the category channels of the guild.

Returns

channels : list of Channel

channel_list

Returns the channels of the guild in a list in their display order. Note, that channels inside of categories are excluded.

Returns

channels : list of Channel

channel_list_flattened

Returns the channels of the guild in a list in their display order. Note, that channels inside of categories are included as well.

channels : list of Channel

connectable_channels

Returns the connectable channels of the guild.

Returns

channels : list of Channel

content_filter

Returns the guild's explicit content filter level.

Deprecated and will be removed in 2024 April. Please use .explicit_content_filter_level instead.

created_at

When the entity was created.

Returns

created_at : datetime

default_role

Returns the default role of the guild (@everyone).

Might return None at the case of partial guilds.

Returns

default_role : None, Role

discovery_splash

Returns the respective icon.

Returns

icon : Icon

discovery_splash_url

Returns the guild's discovery splash's image's url. If the guild has no discovery splash, then returns None.

This function is a shared property of Guild-s.

Returns

url : None, str

emoji_counts

Returns the emoji counts of the guild.

Returns

emoji_counts : EmojiCounts

emoji_limit

The maximal amount of emojis, what the guild can have.

Returns

limit : int

forum_channels

Returns the forum channels of the guild.

Returns

channels : list of Channel

icon

Returns the respective icon.

Returns

icon : Icon

icon_url

Returns the guild's icon's image's url. If the guild has no icon, then returns None.

This function is a shared property of Guild, GuildPreview.

Returns

url : None, str

invite_splash

Returns the respective icon.

Returns

icon : Icon

invite_splash_url

Returns the guild's invite splash's image's url. If the guild has no invite splash, then returns None.

This function is a shared property of Guild, GuildPreview.

Returns

url : None, str

is_large

Deprecated and will be removed in 2023 December. Please use .large instead.

max_video_channel_users

.max_video_channel_users is deprecated and will be removed in 2023 August. Please use .max_voice_channel_video_users instead.

message_notification

Returns the guild's default message notification level.

Deprecated and will be removed in 2024 April. Please use .default_message_notification_level instead.

messageable_channels

Returns the messageable channels (excluding threads) of the guild.

Returns

channels : list of Channel

mfa

Returns the guild's multi-factory authentication level.

Deprecated and will be removed in 2024 April. Please use .mfa_level instead.

nsfw

Returns whether the guild is nsfw.

Returns

nsfw : bool

owner

Returns the guild's owner's.

Returns

owner : UserClientBase

If user the guild has no owner, returns ZEROUSER.

partial

Returns whether the guild is partial.

A guild is partial, if it has no active clients.

Returns

partial : bool

preferred_locale

Returns the guild's preferred language.

Deprecated and will be removed in 2024 February. Please use .locale instead.

premium_perks

Returns the guild's premium tier perks for it's current level.

Returns

premium_perks : GuildPremiumPerks

public_updates_channel

Returns the channel's where the guild's public updates should go.

Returns

public_updates_channel : None, Channel

role_list

Returns the roles of the guild in their display order.

Returns

roles : list of Role

rules_channel

Returns the channel where the rules of a public guild's should be.

Returns

rules_channel : None, Channel

safety_alerts_channel

Returns the channel where safety alerts are sent by Discord.

Returns

safety_alerts_channel : None, Channel

soundboard_sounds_cached

Returns whether the guild has its soundboard sounds cached.

stage_channels

Returns the stage channels of the guild.

Returns

channels : list of Channel

sticker_count

.sticker_count is deprecated and will be removed in 2023 August. Please use .sticker_counts instead.

sticker_counts

Returns the sticker counts of the guild for each type.

Returns

sticker_counts : StickerCounts

sticker_limit

The maximal amount of stickers, what the guild can have.

Returns

limit : int

store_channels

Returns the store channels of the guild.

Returns

channels : list of Channel

system_channel

Returns the channel where the system messages are sent.

Returns

public_updates_channel : None, Channel

text_channels

Returns the text channels of the guild. Announcement channels are not included.

Returns

channels : list of Channel

thread_channels

Returns the thread channels of the guild.

Returns

channels : list of Channel

upload_limit

The maximal size of files, which can be uploaded to the guild's channels.

Returns

limit : int

vanity_url

Returns the guild vanity invite's url.

This function is a shared property of Guild-s.

Returns

url : None, str

voice_channels

Returns the voice channels of the guild.

Returns

channels : list of Channel

widget_channel

Returns the channel for which the guild's widget is for.

Returns

public_updates_channel : None, Channel

widget_json_url

Returns an url to request a Guild 's widget data.

This function is a shared property of Guild, GuildWidget.

Returns

url : str

widget_url

Returns the guild's widget image's url in .png format.

This function is a shared property of Guild-s.

Returns

url : str

Methods

new(...)

Creates a new partial guild with the given fields.

Parameter	Type	Description
afk_channel_id	`int`, `Channel`	The afk channel or its identifier.
afk_timeout	`int`	The afk timeout at the `afk_channel`.
banner	`None`, `Icon`, `str`, `bytes-like`	The guild's banner.
boost_progress_bar_enabled	`bool`	Whether the guild has the boost progress bar enabled.
default_message_notification_level	`MessageNotificationLevel`, `int`	The default message notification level of the guild.
description	`None`, `str`	Description of the guild. The guild must be a Community guild.
discovery_splash	`None`, `Icon`, `str`, `bytes-like`	The guild's discovery splash.
explicit_content_filter_level	`ExplicitContentFilterLevel`, `int`	The explicit content filter level of the guild.
features	`None`, `iterable` of `(` int `,` GuildFeature)	The guild's features.
hub_type	`HubType`, `int`	The guild's hub type.
icon	`None`, `Icon`, `str`, `bytes-like`	The guild's icon.
invite_splash	`None`, `Icon`, `str`, `bytes-like`	The guild's invite splash.
locale	`Locale`, `int`	The preferred language of the guild.
mfa_level	`MfaLevel`, `int`	The required multi-factor authentication level for the guild.
name	`str`	The guild's name.
nsfw_level	`NsfwLevel`, `int`	The nsfw level of the guild.
owner_id	`int`, `ClientUserBase`	The guild's owner or their id.
public_updates_channel_id	`int`, `Channel`	The channel's identifier where the guild's public updates should go.
rules_channel_id	`int`, `Channel`	The channel or its identifier where the rules of a public guild's should be.
safety_alerts_channel_id	`int`, `Channel`	The channel or its identifier where safety alerts are sent by Discord.
system_channel_flags	`SystemChannelFlag`, `int`	Describe which type of messages are sent automatically to the system channel.
system_channel_id	`int`, `Channel`	The channel or its identifier where the system messages are sent.
vanity_code	`None`, `str`	The guild's vanity invite's code if it has.
verification_level	`VerificationLevel`, `int`	The minimal verification needed to join or to interact with guild.
widget_channel_id	`int`, `Channel`	The channel or its identifier for which the guild's widget is for.
widget_enabled	`bool`	Whether the guild's widget is enabled.

Returns

self : instance<cls>

Raises

TypeError

If any parameter's type is incorrect.

ValueError

If a parameter's value is incorrect.

banner_url_as(...)

Returns the guild's banner's image's url. If the guild has no banner, then returns None.

This function is a shared method of Guild-s.

Parameter	Type	Optional	Default	Description
ext	`None`, `str`		`None`	The extension of the image's url. Can be any of: `'jpg'`, `'jpeg'`, `'png'`, `'webp'`, `'gif'`.
size	`None`, `int`		`None`	The preferred minimal size of the image's url.

Returns

url : None, str

Raises

ValueError

If ext, size was not passed as any of the expected values.

cached_permissions_for(user)

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

Parameter	Type	Description
user	`UserBase`	The user to calculate it's permissions of.

Returns

permissions : Permission

The calculated permissions.

Notes

Mainly designed for getting clients' permissions and stores only their as well. Do not caches other user's permissions.

copy()

Copies the guild.

Returns

new : instance<type<cls>>

copy_with(...)

Copies the guild with the given fields.

Parameter	Type	Description
afk_channel_id	`int`, `Channel`	The afk channel or its identifier.
afk_timeout	`int`	The afk timeout at the `afk_channel`.
banner	`None`, `Icon`, `str`, `bytes-like`	The guild's banner.
boost_progress_bar_enabled	`bool`	Whether the guild has the boost progress bar enabled.
default_message_notification_level	`MessageNotificationLevel`, `int`	The message notification level of the guild.
description	`None`, `str`	Description of the guild. The guild must be a Community guild.
discovery_splash	`None`, `Icon`, `str`, `bytes-like`	The guild's discovery splash.
explicit_content_filter_level	`ExplicitContentFilterLevel`, `int`	The explicit content filter level of the guild.
features	`None`, `iterable` of `(` int `,` GuildFeature)	The guild's features.
hub_type	`HubType`, `int`	The guild's hub type.
icon	`None`, `Icon`, `str`, `bytes-like`	The guild's icon.
invite_splash	`None`, `Icon`, `str`, `bytes-like`	The guild's invite splash.
locale	`Locale`, `int`	The preferred language of the guild.
mfa_level	`MfaLevel`, `int`	The required multi-factor authentication level for the guild.
name	`str`	The guild's name.
nsfw_level	`NsfwLevel`, `int`	The nsfw level of the guild.
owner_id	`int`, `ClientUserBase`	The guild's owner or their id.
public_updates_channel_id	`int`, `Channel`	The channel's identifier where the guild's public updates should go.
rules_channel_id	`int`, `Channel`	The channel or its identifier where the rules of a public guild's should be.
safety_alerts_channel_id	`int`, `Channel`	The channel or its identifier where safety alerts are sent by Discord.
system_channel_flags	`SystemChannelFlag`, `int`	Describe which type of messages are sent automatically to the system channel.
system_channel_id	`int`, `Channel`	The channel or its identifier where the system messages are sent.
vanity_code	`None`, `str`	The guild's vanity invite's code if it has.
verification_level	`VerificationLevel`, `int`	The minimal verification needed to join or to interact with guild.
widget_channel_id	`int`, `Channel`	The channel or its identifier for which the guild's widget is for.
widget_enabled	`bool`	Whether the guild's widget is enabled.

Returns

new : instance<type<self>>

Raises

TypeError

If any parameter's type is incorrect.

ValueError

If a parameter's value is incorrect.

discovery_splash_url_as(...)

Returns the guild's discovery splash's image's url. If the guild has no discovery splash, then returns None.

This function is a shared method of Guild-s.

Parameter	Type	Optional	Default	Description
ext	`None`, `str`		`None`	The extension of the image's url. Can be any of: `'jpg'`, `'jpeg'`, `'png'`, `'webp'`.
size	`None`, `int`		`None`	The preferred minimal size of the image's url.

Returns

url : None, str

Raises

ValueError

If ext, size was not passed as any of the expected values.

from_data(data, ...)

Tries to find the guild from the already existing ones. If it can not find, creates a new one. If the found guild is partial (or freshly created), sets it's attributes from the given data. If the the guild is not added to the client's guild profiles yet, adds it, and the client to the guilds' .clients as well.

Parameter	Type	Optional	Default	Description
data	`dict` of (`str`, `object`) items			Received guild data.
client	`None`, `Client`		`None`	The client who received the guild's data.

Returns

self : instance<cls>

get_channel(name, ...)

Searches a channel of the guild, what's name equals the given name.

Parameter	Type	Default	Description
name	`str`		The name to search for.
default	`object`	`None`	The value what is returned when no channel was found.
type_checker	`None`, `FunctionType`	`None`	Function specifically to check the channel's type.

Returns

channel : Channel, default

get_channel_like(name, ...)

Searches a channel of the guild, whats name starts with the given string and returns the first find.

Parameter	Type	Default	Description
name	`str`		The name to search for.
default	`object`	`None`	The value what is returned when no channel was found.
type_checker	`None`, `FunctionType`	`None`	Function specifically to check the channel's type.

Returns

channel : Channel, default

get_channels_like(name, ...)

Searches the channels, what's name match the given value.

The returned value is ordered by match rate.

Parameter	Type	Optional	Default	Description
name	`str`			The name to search for.
type_checker	`None`, `FunctionType`		`None`	Function specifically to check the channel's type.

Returns

channels : list of Channel

get_emoji(name, ...)

Searches an emoji of the guild, what's name equals the given name.

Parameter	Type	Optional	Default	Description
name	`str`			The name to search for.
default	`object`		`None`	The value what is returned when no emoji was found. Defaults to `None`.

Returns

emoji : Emoji, default

get_emoji_like(name, ...)

Searches an emoji of the guild that matches the given name the most.

Parameter	Type	Optional	Default	Description
name	`str`			The name to search for.
default	`object`		`None`	The value what is returned when no emoji was found. Defaults to `None`.

Returns

emoji : Emoji, default

get_emojis_like(name)

Searches the emojis, what's name match the given value.

The returned value is ordered by match rate.

Parameter	Type	Description
name	`str`	The name to search for.

Returns

emojis : list of Emoji

get_role(name, ...)

Searches a role of the guild, what's name equals the given name.

Parameter	Type	Optional	Default	Description
name	`str`			The name to search for.
default	`object`		`None`	The value what is returned when no role was found. Defaults to `None`.

Returns

role : Role, default

get_role_like(name, ...)

Searches a role of the guild, whats name starts with the given string and returns the first find.

Parameter	Type	Optional	Default	Description
name	`str`			The name to search for.
default	`object`		`None`	The value what is returned when no role was found. Defaults to `None`.

Returns

role : Role, default

get_roles_like(name)

Searches the roles, what's name match the given value.

The returned value is ordered by match rate.

Parameter	Type	Description
name	`str`	The name to search for.

Returns

roles : list of Role

get_soundboard_sound(name, ...)

Searches an soundboard sound of the guild that has it name set to same value as the given name.

Parameter	Type	Optional	Default	Description
name	`str`			The name to search for.
default	`object`		`None`	The value what is returned when no soundboard sound was found. Defaults to `None`.

Returns

soundboard_sound : SoundboardSound, default

get_soundboard_sound_like(name, ...)

Searches the soundboard sound of the guild that have its name matching the given name value the most.

Parameter	Type	Optional	Default	Description
name	`str`			The name to search for.
default	`object`		`None`	The value what is returned when no soundboard sound was found. Defaults to `None`.

Returns

soundboard_sound : SoundboardSound, default

get_soundboard_sounds_like(name)

Searches the soundboard sounds that have their name matching the given value.

The returned value is ordered by match rate.

Parameter	Type	Description
name	`str`	The name to search for.

Returns

soundboard_sounds : list of SoundboardSound

get_sticker(name, ...)

Searches a sticker of the guild, what's name equals to the given name.

Parameter	Type	Optional	Default	Description
name	`str`			The name to search for.
default	`object`		`None`	The value what is returned when no emoji was found. Defaults to `None`.

Returns

sticker : Sticker, default

get_sticker_like(name, ...)

Searches a sticker of the guild that's name or tag matches the given name the most.

Parameter	Type	Optional	Default	Description
name	`str`			The name to search for.
default	`object`		`None`	The value what is returned when no emoji was found. Defaults to `None`.

Returns

sticker : Sticker, default

get_stickers_like(name)

Searches the stickers, what's name and tags matches the given value.

The returned value is ordered by match rate.

Parameter	Type	Description
name	`str`	The name to search for.

Returns

stickers : list of Sticker

get_user(name, ...)

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

The search order is the following:

name with discriminator
name
global name
nick

Parameter	Type	Optional	Default	Description
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. Also matches full name.

Parameter	Type	Optional	Default	Description
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 start with the given string.

Parameter	Type	Description
name	`str`	The name to search for.

Returns

users : list of ClientUserBase

get_users_like_ordered(name)

Searches the users, who's name or nick start with the given string. At the orders them at the same ways, as Discord orders them when requesting guild users chunk.

Parameter	Type	Description
name	`str`	The name to search for.

Returns

users : list of ClientUserBase

has_feature(feature)

Returns whether the guild has the give feature.

Parameter	Type	Description
feature	`GuildFeature`	The feature to look for.

Returns

has_feature : bool

icon_url_as(...)

Returns the guild's icon's url. If the guild has no icon, then returns None.

This function is a shared method of Guild, GuildPreview.

Parameter	Type	Optional	Default	Description
ext	`None`, `str`		`None`	The extension of the image's url. Can be any of: `'jpg'`, `'jpeg'`, `'png'`, `'webp'`. If the guild has animated icon, it can `'gif'` as well.
size	`None`, `int`		`None`	The preferred minimal size of the image's url.

Returns

url : None, str

Raises

ValueError

If ext, size was not passed as any of the expected values.

invite_splash_url_as(...)

Returns the guild's invite splash's image's url. If the guild has no invite splash, then returns None.

This function is a shared method of Guild, GuildPreview.

Parameter	Type	Optional	Default	Description
ext	`None`, `str`		`None`	The extension of the image's url. Can be any of: `'jpg'`, `'jpeg'`, `'png'`, `'webp'`.
size	`None`, `int`		`None`	The preferred minimal size of the image's url.

Returns

url : None, str

Raises

ValueError

If ext, size was not passed as any of the expected values.

iter_channels(...)

Iterates over the channels of the guild.

This method is an iterable generator.

Parameter	Type	Optional	Default	Description
type_checker	`None`, `FunctionType`		`None`	Function specifically to check the channel's type.

Yields

channel : Channel

iter_embedded_activity_states()

Iterates over the embedded activity states of the guild.

This method is an iterable generator.

Yields

embedded_activity_state : EmbeddedActivityState

iter_emojis()

Iterates over the emojis of the guild.

This method is an iterable generator.

Yields

emoji : Emoji

iter_features()

Iterates over the features of the guild.

This method is an iterable generator.

Yields

feature : GuildFeature

iter_roles()

Iterates over the roles of the guild.

This method is an iterable generator.

Yields

role : Role

iter_scheduled_events()

Iterates overt he scheduled events of the guild.

This method is an iterable generator.

Yields

scheduled_event : ScheduledEvent

iter_soundboard_sounds()

Iterates over the guild's soundboard sounds.

This method is an iterable generator.

Yields

soundboard_sound : SoundboardSound

iter_stages()

Iterates over the stages of the guild.

This method is an iterable generator.

Yields

stage : Stage

iter_stickers()

Iterates over the stickers of the guild.

This method is an iterable generator.

Yields

sticker : Sticker

iter_threads()

Iterates over the threads of the guild.

This method is an iterable generator.

Yields

thread : Channel

iter_users()

Iterates over the users of the guild.

This method is an iterable generator.

Yields

user : ClientUserBase

iter_voice_states()

Iterates over the voice state of the guild.

This method is an iterable generator.

Yields

voice_state : VoiceState

permissions_for(user)

Returns the permissions for the given user at the guild.

Parameter	Type	Description
user	`UserBase`	The user to calculate it's permissions of.

Returns

permissions : Permission

The calculated permissions.

permissions_for_roles(...)

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

Parameter	Type	Optional	Description
*roles	`Role`		The roles to calculate final permissions from.

Returns

permissions : Permission

The calculated permissions.

Notes

Partial roles and roles from other guilds as well are ignored.

precreate(guild_id, ...)

Precreates the guild with the given parameters. Precreated guilds are picked up when a guild's data is received with the same id.

First tries to find whether a guild exists with the given id. If it does and it is partial, updates it with the given parameters, else it creates a new one.

Parameter	Type	Description
guild_id	`snowflake`	The guild's id.
**keyword_parameters	keyword parameters	Additional predefined attributes for the guild.
afk_channel	`int`, `Channel`	Alternative for `afk_channel_id`.
afk_channel_id	`int`, `Channel`	The afk channel or its identifier.
afk_timeout	`int`	The afk timeout at the `afk_channel`.
approximate_online_count	`int`	The approximate amount of online users at the guild
approximate_user_count	`int`	The approximate amount of users at the guild.
available	`bool`	Whether the guild is available.
banner	`None`, `Icon`, `str`	The guild's banner.
boost_count	`int`	The total number of boosts of the guild.
boost_progress_bar_enabled	`bool`	Whether the guild has the boost progress bar enabled.
channels	`None`, `iterable` of `Channel`, `dict` of (`int`, `Channel`) items	The channels of the guild.
default_message_notification_level	`MessageNotificationLevel`, `int`	The message notification level of the guild.
description	`None`, `str`	Description of the guild. The guild must be a Community guild.
discovery_splash	`None`, `Icon`, `str`	The guild's discovery splash.
embedded_activity_states	`None`, `iterable` of `EmbeddedActivityState`	Embedded activity states to keep them alive in cache.
emojis	`None`, `iterable` of `Emoji`, `dict` of (`int`, `Emoji`) items	The emojis of the guild.
explicit_content_filter_level	`ExplicitContentFilterLevel`, `int`	The explicit content filter level of the guild.
features	`None`, `features` of `(` int `,` GuildFeature)	The guild's features.
hub_type	`HubType`, `int`	The guild's hub type.
icon	`None`, `Icon`, `str`	The guild's icon.
incidents	`None`, `GuildIncidents`	The guild's incidents.
inventory_settings	`None`, `GuildInventorySettings`	The guild's inventory settings.
invite_splash	`None`, `Icon`, `str`	The guild's invite splash.
large	`bool`	Whether the guild is considered as a large one.
locale	`Locale`, `int`	The preferred language of the guild.
max_presences	`int`	The maximal amount of presences for the guild.
max_stage_channel_video_users	`int`	The maximal amount of users watching a video in a stage channel.
max_users	`int`	The maximal allowed users in the guild.
max_voice_channel_video_users	`int`	The maximal amount of users watching a video in a stage channel.
mfa_level	`MfaLevel`, `int`	The required multi-factor authentication level for the guild.
name	`str`	The guild's name.
nsfw_level	`NsfwLevel`, `int`	The nsfw level of the guild.
owner	`int`, `ClientUserBase`	Alternative for `owner`.
owner_id	`int`, `ClientUserBase`	The guild's owner or their id.
premium_tier	`int`	The premium tier of the guild.
public_updates_channel	`int`, `Channel`	Alternative for `public_updates_channel_id`.
public_updates_channel_id	`int`, `Channel`	The channel's identifier where the guild's public updates should go.
roles	`None`, `iterable` of `Role`, `dict` of (`int`, `Role`) items	The roles of the guild.
rules_channel	`int`, `Channel`	Alternative for `rules_channel_id`.
rules_channel_id	`int`, `Channel`	The channel or its identifier where the rules of a public guild's should be.
safety_alerts_channel	`int`, `Channel`	Alternative for `safety_alerts_channel_id`.
safety_alerts_channel_id	`int`, `Channel`	The channel or its identifier where safety alerts are sent by Discord.
scheduled_events	`None`, `iterable` of `ScheduledEvent`, `dict` of (`int`, `ScheduledEvent`) items	The scheduled events of the guild.
soundboard_sounds	`None`, `iterable` of `SoundboardSound`, `dict` of (`int`, `SoundboardSound`) items	The soundboard sounds of the guild.
stages	`None`, `iterable` of `Stage`, `dict` of (`int`, `Stage`) items	Active stages of the guild. Defaults to `None` if would be empty.
stickers	`None`, `iterable` of `Sticker`, `dict` of (`int`, `Sticker`) items	The stickers of the guild.
system_channel_flags	`SystemChannelFlag`, `int`	Describe which type of messages are sent automatically to the system channel.
system_channel	`int`, `Channel`	Alternative for `system_channel_id`.
system_channel_id	`int`, `Channel`	The channel or its identifier where the system messages are sent.
threads	`None`, `iterable` of `Channel`, `dict` of (`int`, `Channel`) items	The threads of the guild.
user_count	`int`	The amount of users at the guild.
users	`None`, `iterable` of `ClientUserBase`, `dict` of (`int`, `ClientUserBase`) items	The users of the guild.
vanity_code	`None`, `str`	The guild's vanity invite's code if it has.
verification_level	`VerificationLevel`, `int`	The minimal verification needed to join or to interact with guild.
voice_states	`None`, `iterable` of `VoiceState`, `dict` of (`int`, `VoiceState`) items	The users represented in the guild's voice channels.
widget_channel	`int`, `Channel`	Alternative for `widget_channel_id`.
widget_channel_id	`int`, `Channel`	The channel or its identifier for which the guild's widget is for.
widget_enabled	`bool`	Whether the guild's widget is enabled.

Returns

self : instance<cls>

Raises

TypeError

If any parameter's type is incorrect.
Extra parameters given.

ValueError

If a parameter's value is incorrect.

to_data(...)

Converts the guild to its json representation.

Parameter	Type	Optional	Keyword only	Default	Description
defaults	`bool`			`False`	Whether default values should be included as well.
include_internals	`bool`			`False`	Whether internal fields should be included as well.

Returns

data : dict of (str, str) items

widget_url_as(...)

Returns the guild's widget image's url in .png format.

This function is a shared method of Guild-s.

Parameter	Type	Optional	Default	Description
style	`str`		`'shield'`	The widget image's style. Can be any of: `'shield'`, `'banner1'`, `'banner2'`, `'banner3'`, `'banner4'`.

Returns

url : str

Raises

ValueError

If style was not passed as any of the expected values.

_clear_cache()

Clears the guild's cache fields.

_create_empty(guild_id)

Creates a guild with default parameters set.

Parameter	Type	Description
guild_id	`int`	The guild's identifier.

Returns

self : instance<cls>

_delete(client)

When a client leaves (gets kicked or banned) from a guild, this method is called. If the guild loses it's last active client, then the it's references are cleared.

Parameter	Type	Description
client	`Client`	The client, who left the guild.

_difference_update_attributes(data)

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

Parameter	Type	Description
data	`dict` of (`str`, `object`) items	Guild data received from Discord.

Returns

old_attributes : dict of (str, object) items

All item in the returned dict is optional.

Returned Data Structure

Keys	Values
afk_channel_id	`int`
afk_timeout	`int`
available	`bool`
banner	`Icon`
boost_count	`int`
boost_progress_bar_enabled	`bool`
explicit_content_filter_level	`ExplicitContentFilterLevel`
default_message_notification_level	`MessageNotificationLevel`
description	`None`, `str`
discovery_splash	`Icon`
features	`None`, `tuple` of `GuildFeature`
hub_type	`HubType`
icon	`Icon`
incidents	`None`, `GuildIncidents`
inventory_settings	`None`, `GuildInventorySettings`
invite_splash	`Icon`
max_presences	`int`
max_stage_channel_video_users	`int`
max_users	`int`
max_voice_channel_video_users	`int`
mfa_level	`MfaLevel`
name	`str`
nsfw_level	`NsfwLevel`
owner_id	`int`
locale	`Locale`
premium_tier	`int`
public_updates_channel_id	`int`
rules_channel_id	`int`
safety_alerts_channel_id	`int`
system_channel_id	`int`
system_channel_flags	`SystemChannelFlag`
vanity_code	`None`, `str`
verification_level	`VerificationLevel`
widget_channel_id	`int`
widget_enabled	`bool`

_difference_update_emojis(data)

Updates the emojis o the guild and returns all the changes broke down for each changes emoji.

Parameter	Type	Description
data	`list` of (`dict` of (`str`, `object`) items)	Received emoji datas.

Returns

changes : list of tuple(int, Emoji, (None, dict of (str, object) items)))

The changes broken down for each changed emoji. Each element of the list is a tuple of 3 elements:

Index	Respective name	Type
0	action	`int`
1	emoji	`Emoji`
2	old_attributes	`None`, `dict` of (`str`, `object`) items

Possible actions:

Respective name	Value
EMOJI_EVENT_NONE	`0`
EMOJI_EVENT_CREATE	`1`
EMOJI_EVENT_DELETE	`2`
EMOJI_EVENT_UPDATE	`3`

If action is EMOJI_EVENT_UPDATE, then old_attributes is passed as a dictionary containing the changed attributes in an attribute-name- old-value relation. Every item in old_attributes is optional.

Keys	Values
animated	`bool`
available	`bool`
managed	`bool`
name	`int`
require_colons	`bool`
roles_ids	`None`, `tuple` of `int`

_difference_update_soundboard_sounds(data)

Updates the soundboard_sounds of the guild and returns the changes broke down for each changed soundboard sound.

Parameter	Type	Description
data	`list` of (`dict` of (`str`, `object`) items)	Received soundboard sound datas.

Returns

changes : list of tuple(int, SoundboardSound, (None, dict of (str, object) items)))

The changes broken down for each changed soundboard sound. Each element of the list is a tuple of 3 elements:

Index	Respective name	Type
0	action	`int`
1	soundboard_sound	`SoundboardSound`
2	old_attributes	`None`, `dict` of (`str`, `object`) items

Possible actions:

Respective name	Value
SOUNDBOARD_SOUND_EVENT_NONE	`0`
SOUNDBOARD_SOUND_EVENT_CREATE	`1`
SOUNDBOARD_SOUND_EVENT_DELETE	`2`
SOUNDBOARD_SOUND_EVENT_UPDATE	`3`

If action is SOUNDBOARD_SOUND_EVENT_UPDATE, then old_attributes is passed as a dictionary containing the changed attributes in an attribute-name- old-value relation. Every item in old_attributes is optional.

Keys	Values
available	`bool`
emoji	`None`, `Emoji`
name	`str`
volume	`float`

_difference_update_stickers(data)

Updates the stickers of the guild and returns the changes broke down for each changed sticker.

Parameter	Type	Description
data	`list` of (`dict` of (`str`, `object`) items)	Received sticker datas.

Returns

changes : list of tuple(int, Sticker, (None, dict of (str, object) items)))

The changes broken down for each changed sticker. Each element of the list is a tuple of 3 elements:

Index	Respective name	Type
0	action	`int`
1	sticker	`Sticker`
2	old_attributes	`None`, `dict` of (`str`, `object`) items

Possible actions:

Respective name	Value
STICKER_EVENT_NONE	`0`
STICKER_EVENT_CREATE	`1`
STICKER_EVENT_DELETE	`2`
STICKER_EVENT_UPDATE	`3`

If action is STICKER_EVENT_UPDATE, then old_attributes is passed as a dictionary containing the changed attributes in an attribute-name- old-value relation. Every item in old_attributes is optional.

Keys	Values
available	`bool`
description	`None`, `str`
name	`str`
sort_value	`int`
tags	`None` or `frozenset` of `str`

_get_boosters()

Iterates over the users of the guild and selects the ones boosting. The output is sorted.

Returns

boosters : None, tuple of ClientUserBase

_get_hash_partial()

Hashes the fields of the guild.

Returns

hash_value : int

_invalidate_cache_permission()

Invalidates the cached permissions of the guild.

_is_equal_partial(other)

Returns whether the guild is equal to the given one. This function is called when one or both the guilds are templates.

Parameter	Type	Description
other	`instance<type<self>>`	The other guild to compare self to.

Returns

is_equal : bool

_set_attributes(data, ...)

Finishes the guild's initialization process by setting it's attributes.

This method required .id to be set already.

Parameter	Type	Optional	Default	Description
data	`dict` of (`str`, `object`) items			Guild data.
creation	`bool`		`True`	Whether the entity was just created.

_update_attributes(data)

Updates the guild and with overwriting it's old attributes.

Parameter	Type	Description
data	`dict` of (`str`, `object`) items	Guild data received from Discord.

_update_channels(data)

Syncs the guild's channels with the given guild channel datas.

Parameter	Type	Description
data	`list` of `dict` of (`str`, `object`) items	Received guild channel datas.

_update_counts_only(data)

Updates the guilds' counts if given.

Parameter	Type	Description
data	`dict` of (`str`, `object`) items	Received guild data.

_update_emojis(emoji_datas)

Syncs the emojis of the guild.

Parameter	Type	Description
emoji_datas	`list` of (`dict` of (`str`, `object`) items)	Received emoji datas.

_update_generic(data)

Syncs the guild with the requested guild data.

Parameter	Type	Description
data	`dict` of (`str`, `object`) items	Received guild data.

_update_roles(data)

Syncs the guild's roles with the given guild role datas.

Parameter	Type	Description
data	`list` of `dict` of (`str`, `object`) items	Received guild role datas.

_update_soundboard_sounds(data)

Syncs the guild's soundboard_sounds with the given guild soundboard_sound datas.

Parameter	Type	Description
data	`list` of `dict` of (`str`, `object`) items	Received guild soundboard sound datas.

_update_stickers(sticker_datas)

Syncs the stickers of the guild.

Parameter	Type	Description
sticker_datas	`list` of (`dict` of (`str`, `object`) items)	Received sticker datas.

_update_voice_state(data, user)

Called by dispatch event. Updates the voice state of the represented user with the given data.

This method is an iterable generator.

Parameter	Type	Description
data	`dict` of (`str`, `object`) items	Data received from Discord.
user	`ClientUserBase`	The respective user.

Yields

action : int

The respective action.

Can be one of the following:

Respective name	Value
VOICE_STATE_EVENT_NONE	0
VOICE_STATE_EVENT_JOIN	1
VOICE_STATE_EVENT_LEAVE	2
VOICE_STATE_EVENT_UPDATE	3
VOICE_STATE_EVENT_MOVE	4

voice_state : None, VoiceState

The user's respective voice state.

Will be returned as None if action is VOICE_STATE_EVENT_NONE.

old_attributes / old_channel_id : None or (dict of (str, object) items / int)

If action is VOICE_STATE_EVENT_UPDATE, then old_attributes is returned as a dict containing the changed attributes in attribute-name- old-value relation. All item at the returned dictionary is optional.

Keys	Values
deaf	`str`
mute	`bool`
self_deaf	`bool`
self_mute	`bool`
self_stream	`bool`
self_video	`bool`

If action is VOICE_STATE_EVENT_LEAVE, VOICE_STATE_EVENT_MOVE, then the old channel's identifier is returned.

_update_voice_state_restricted(data, user)

Called by dispatch event. Updates the voice state of the represented user by user_id with the given data.

This method is an iterable generator.

Parameter	Type	Description
data	`dict` of (`str`, `object`) items	Data received from Discord.
user	`ClientUserBase`	The respective user.

eq()

Returns whether the two guilds are equal.

format(code)

Formats the guild in a format string.

Parameter	Type	Description
code	`str`	The option on based the result will be formatted.

Returns

guild : str

Raises

ValueError

Unknown format code.

Examples

>>> from hata import Guild, now_as_id
>>> guild = Guild.precreate(now_as_id(), name = 'GrassGrass')
>>> guild
<Guild id = 713718885970345984 (partial), name = 'GrassGrass'>
>>> # no code stands for `guild.name`
>>> f'{guild}'
'GrassGrass'
>>> # 'c' stands for created at.
>>> f'{guild:c}'
'2020-05-23 11:44:02'

ge()

Whether this entity's id is greater or equal than the other's.

getattr()

Drops a rich attribute error.

gt()

Whether this entity's id is greater than the other's.

hash()

le()

Whether this entity's id is less or equal than the other's.

lt()

Whether this entity's id is less than the other's.

ne()

Returns whether the two guilds are not equal.

repr()

Returns the guild's representation.