Guild¶

discord_http.guild module¶

class discord_http.guild.BanEntry(user, reason)¶

Bases: NamedTuple

Parameters:

user (User)
reason (str | None)

reason: str | None¶: Alias for field number 1

user: User¶: Alias for field number 0

class discord_http.guild.Guild(*, state, data)¶

Bases: PartialGuild

Parameters:

state (DiscordAPI)
data (dict)

property banner: Asset | None¶: The guild’s banner.

property bitrate_limit: int¶: The maximum bitrate the guild can have.

property default_role: Role¶: The guild’s default role, which is always provided.

property emojis_limit: int¶: The maximum amount of emojis the guild can have.

property filesize_limit: int¶: The maximum filesize the guild can have.

get_member_top_role(member) → Role | None¶

Get the top role of a member, because Discord API does not order roles.

Parameters:: member (Member) – The member to get the top role of
Return type:: Role | None
Returns:: The top role of the member

get_role(role_id) → Role | None¶

Get a role from the guild.

This simply returns the role from the role list in this object if it exists

Parameters:: role_id (int) – The ID of the role to get
Return type:: Role | None
Returns:: The role with the given ID, if it exists.

get_role_by_name(role_name) → Role | None¶

Gets the first role with the specified name.

Parameters:: role_name (str) – The name of the role to get (case sensitive)
Return type:: Role | None
Returns:: The role with the given name, if it exists.

property icon: Asset | None¶: The guild’s icon.

property me: Member | PartialMember | None¶

Returns the bot’s member object.

Only useable if you are using gateway and caching

property premium_subscriber_role: Role | None¶: The guild’s premium subscriber role if available.

property self_role: Role | None¶: The guild’s bot role if available.

property stickers_limit: int¶: The maximum amount of stickers the guild can have.

class discord_http.guild.PartialGuild(*, state, id)¶

Bases: PartialBase

Parameters:

state (DiscordAPI)
id (int)

async ban(member, *, delete_message_days=0, delete_message_seconds=0, reason=None) → None¶

Ban a member from the server.

Parameters:

member (Member | PartialMember | int) – The member to ban
reason (str | None) – The reason for banning the member
delete_message_days (int | None) – How many days of messages to delete
delete_message_seconds (int | None) – How many seconds of messages to delete

Return type:

None

async begin_guild_prune(*, days=7, compute_prune_count=True, include_roles=None, reason=None) → int | None¶

Begin a guild prune.

Parameters:

days (int | None) – How many days of inactivity to prune for
compute_prune_count (bool) – Whether to return the amount of members that would be pruned
include_roles (list[Role | PartialRole | int] | None) – Which roles to include in the prune
reason (str | None) – The reason for beginning the prune

Return type:

int | None

Returns:

The amount of members that were pruned

async bulk_ban(*members, delete_message_days=0, delete_message_seconds=0, reason=None) → list[PartialMember]¶

Ban multiple members from the server.

Parameters:

*members (Member | PartialMember | int) – The members to ban
delete_message_days (int | None) – How many days of messages to delete
delete_message_seconds (int | None) – How many seconds of messages to delete
reason (str | None) – The reason for banning the members

Return type:

list[PartialMember]

Returns:

The banned members

property categories: list[CategoryChannel]¶: Returns a list of all the category channels in the guild if they are cached.

property channels: list[BaseChannel | PartialChannel]¶: Returns a list of all the channels in the guild if they are cached.

property chunked: bool¶: Whether the guild is chunked or not.

async create_automod_rule(name, *, event_type, trigger_type, keyword_filter=None, regex_patterns=None, presets=None, allow_list=None, mention_total_limit=None, mention_raid_protection_enabled=False, alert_channel=None, timeout_seconds=None, message=None, enabled=True, exempt_roles=None, exempt_channels=None, reason=None) → AutoModRule¶

Create an automod rule.

Parameters:

name (str) – Name of the automod
event_type (AutoModRuleEventType | int) – What type of event
trigger_type (AutoModRuleTriggerType | int) – What should make it get triggered
keyword_filter (list[str] | None) – Keywords to filter
regex_patterns (list[str] | None) – Keywords in regex pattern to filter
presets (list[AutoModRulePresetType] | None) – Automod presets to include
allow_list (list[str] | None) – List of keywords that are allowed
mention_total_limit (int | None) – How many unique mentions allowed before trigger
mention_raid_protection_enabled (bool) – If this should apply for raids
alert_channel (Snowflake | int | None) – Where the action should be logged
timeout_seconds (int | None) – How many seconds the user in question should be timed out
message (str | None) – What message the user gets when action is taken
enabled (bool) – If the automod should be enabled or not
exempt_roles (list[Snowflake | int] | None) – Which roles are allowed to bypass
exempt_channels (list[Snowflake | int] | None) – Which channels are allowed to bypass
reason (str | None) – Reason for creating the automod

Return type:

AutoModRule

Returns:

The automod that was just created

async create_category(name, *, overwrites=None, position=None, reason=None) → CategoryChannel¶

Create a category channel.

Parameters:

name (str) – The name of the category
overwrites (list[PermissionOverwrite] | None) – The permission overwrites of the category
position (int | None) – The position of the category
reason (str | None) – The reason for creating the category

Return type:

CategoryChannel

Returns:

The created category

async create_emoji(name, *, image, reason=None) → Emoji¶

Create an emoji.

Parameters:

name (str) – Name of the emoji
image (File | bytes) – File object to create an emoji from
reason (str | None) – The reason for creating the emoji

Return type:

Emoji

Returns:

The created emoji

async create_role(name, *, permissions=None, color=None, colour=None, unicode_emoji=None, icon=None, hoist=False, mentionable=False, reason=None) → Role¶

Create a role.

Parameters:

name (str) – The name of the role
permissions (Permissions | None) – The permissions of the role
color (Colour | Color | int | None) – The colour of the role
colour (Colour | Color | int | None) – The colour of the role
hoist (bool) – Whether the role should be hoisted
mentionable (bool) – Whether the role should be mentionable
unicode_emoji (str | None) – The unicode emoji of the role
icon (File | bytes | None) – The icon of the role
reason (str | None) – The reason for creating the role

Return type:

Role

Returns:

The created role

async create_scheduled_event(name, *, start_time, end_time=None, channel=None, description=None, privacy_level=None, entity_type=None, external_location=None, image=None, reason=None) → ScheduledEvent¶

Create a scheduled event.

Parameters:

name (str) – The name of the event
start_time (datetime | timedelta | int) – The start time of the event
end_time (datetime | timedelta | int | None) – The end time of the event
channel (PartialChannel | int | None) – The channel of the event
description (str | None) – The description of the event
privacy_level (PrivacyLevelType | None) – The privacy level of the event (default is guild_only)
entity_type (ScheduledEventEntityType | None) – The entity type of the event (default is voice)
external_location (str | None) – The external location of the event
image (File | bytes | None) – The image of the event
reason (str | None) – The reason for creating the event

Return type:

ScheduledEvent

Returns:

The created event

async create_soundboard_sound(name, *, sound, volume=None, emoji_id=None, emoji_name=None, reason=None) → SoundboardSound¶

Create a soundboard sound.

Parameters:

name (str) – Name of the soundboard sound
sound (File | bytes) – File object to create a soundboard sound from
volume (int | None) – The volume of the soundboard sound
emoji_name (str | None) – The unicode emoji of the soundboard sound
emoji_id (str | None) – The ID of the custom emoji of the soundboard sound
reason (str | None) – The reason for creating the soundboard sound

Return type:

SoundboardSound

Returns:

The created soundboard sound

Raises:

ValueError – If both emoji_name and emoji_id are set

async create_stage_channel(name, *, bitrate=None, user_limit=None, overwrites=None, position=None, parent_id=None, video_quality_mode=None, reason=None) → StageChannel¶

Create a stage channel.

Parameters:

name (str) – The name of the channel
bitrate (int | None) – The bitrate of the channel
user_limit (int | None) – The user limit of the channel
overwrites (list[PermissionOverwrite] | None) – The permission overwrites of the category
position (int | None) – The position of the channel
video_quality_mode (VideoQualityType | int | None) – The video quality mode of the channel
parent_id (Snowflake | int | None) – The Category ID where the channel will be placed
reason (str | None) – The reason for creating the stage channel

Return type:

StageChannel

Returns:

The created channel

async create_sticker(name, *, description, emoji, file, reason=None) → Sticker¶

Create a sticker.

Parameters:

name (str) – Name of the sticker
description (str) – Description of the sticker
emoji (str) – Emoji that represents the sticker
file (File) – File object to create a sticker from
reason (str | None) – The reason for creating the sticker

Return type:

Sticker

Returns:

The created sticker

async create_text_channel(name, *, topic=None, position=None, rate_limit_per_user=None, overwrites=None, parent_id=None, nsfw=None, reason=None) → TextChannel¶

Create a text channel.

Parameters:

name (str) – The name of the channel
topic (str | None) – The topic of the channel
position (int | None) – The position of the channel
rate_limit_per_user (int | None) – The rate limit per user of the channel
overwrites (list[PermissionOverwrite] | None) – The permission overwrites of the category
parent_id (Snowflake | int | None) – The Category ID where the channel will be placed
nsfw (bool | None) – Whether the channel is NSFW or not
reason (str | None) – The reason for creating the text channel

Return type:

TextChannel

Returns:

The created channel

async create_voice_channel(name, *, bitrate=None, user_limit=None, rate_limit_per_user=None, overwrites=None, position=None, video_quality_mode=None, parent_id=None, nsfw=None, reason=None) → VoiceChannel¶

Create a voice channel.

Parameters:

name (str) – The name of the channel
bitrate (int | None) – The bitrate of the channel
user_limit (int | None) – The user limit of the channel
rate_limit_per_user (int | None) – The rate limit per user of the channel
overwrites (list[PermissionOverwrite] | None) – The permission overwrites of the category
position (int | None) – The position of the channel
video_quality_mode (VideoQualityType | int | None) – The video quality mode of the channel
parent_id (Snowflake | int | None) – The Category ID where the channel will be placed
nsfw (bool | None) – Whether the channel is NSFW or not
reason (str | None) – The reason for creating the voice channel

Return type:

VoiceChannel

Returns:

The created channel

property default_role: PartialRole¶: Returns the default role, but as a partial role object.

async delete() → None¶

Delete the guild (the bot must own the server).

Return type:: None

async edit(*, name=<MISSING>, verification_level=<MISSING>, default_message_notifications=<MISSING>, explicit_content_filter=<MISSING>, afk_channel_id=<MISSING>, afk_timeout=<MISSING>, icon=<MISSING>, owner_id=<MISSING>, splash=<MISSING>, discovery_splash=<MISSING>, banner=<MISSING>, system_channel_id=<MISSING>, system_channel_flags=<MISSING>, rules_channel_id=<MISSING>, public_updates_channel_id=<MISSING>, preferred_locale=<MISSING>, description=<MISSING>, features=<MISSING>, premium_progress_bar_enabled=<MISSING>, safety_alerts_channel_id=<MISSING>, reason=None) → PartialGuild¶

Edit the guild.

Parameters:

name (str | None) – New name of the guild
verification_level (VerificationLevel | None) – Verification level of the guild
default_message_notifications (DefaultNotificationLevel | None) – Default message notification level of the guild
explicit_content_filter (ContentFilterLevel | None) – Explicit content filter level of the guild
afk_channel_id (VoiceChannel | PartialChannel | int | None) – AFK channel of the guild
afk_timeout (int | None) – AFK timeout of the guild
icon (File | bytes | None) – Icon of the guild
owner_id (Member | PartialMember | int | None) – Owner of the guild
splash (File | bytes | None) – Splash of the guild
discovery_splash (File | None) – Discovery splash of the guild
banner (File | bytes | None) – Banner of the guild
system_channel_id (TextChannel | PartialChannel | int | None) – System channel of the guild
system_channel_flags (SystemChannelFlags | None) – System channel flags of the guild
rules_channel_id (TextChannel | PartialChannel | int | None) – Rules channel of the guild
public_updates_channel_id (TextChannel | PartialChannel | int | None) – Public updates channel of the guild
preferred_locale (str | None) – Preferred locale of the guild
description (str | None) – Description of the guild
features (list[str] | None) – Features of the guild
premium_progress_bar_enabled (bool | None) – Whether the premium progress bar is enabled
safety_alerts_channel_id (TextChannel | PartialChannel | int | None) – Safety alerts channel of the guild
reason (str | None) – The reason for editing the guild

Return type:

PartialGuild

Returns:

The edited guild

property emojis: list[Emoji | PartialEmoji]¶: Returns a list of all the emojis in the guild if they are cached.

async fetch() → Guild¶

Fetches more information about the guild.

Return type:: Guild

async fetch_audit_logs(*, before=None, after=None, user=None, action=None, limit=100) → AsyncIterator[AuditLogEntry]¶

Fetches the audit logs for the guild.

Parameters:

before (datetime | AuditLogEntry | Snowflake | int | None) – Consider only entries before given entry
after (datetime | AuditLogEntry | Snowflake | int | None) – Consider only entries after given entry
user (Snowflake | int | None) – Consider only entries made by given user
action (AuditLogType | None) – Consider only entries with given action
limit (int | None) – The maximum amount of messages to fetch.

Return type:

AsyncIterator[AuditLogEntry]

Returns:

The audit logs for the guild

async fetch_automod_rule(automod_id) → AutoModRule¶

Fetches a automod rule from the guild.

Return type:: AutoModRule
Parameters:: automod_id (int)

async fetch_automod_rules() → list[AutoModRule]¶

Fetches all the automod rules in the guild.

Return type:: list[AutoModRule]

async fetch_ban(user) → BanEntry¶

Fetches a user’s ban of the guild.

Parameters:: user (Snowflake | int) – The user to fetch the ban of
Return type:: BanEntry
Returns:: Ban entry that was found

async fetch_bans(*, before=None, after=None, limit=1000) → AsyncIterator[BanEntry]¶

Fetch the bans of the guild.

Parameters:

before (Snowflake | int | None) – Consider only users before given user id
after (Snowflake | int | None) – Consider only users after given user id
limit (int | None) – The maximum amount of messages to fetch. None will fetch all users.

Yields:

The message object

Return type:

AsyncIterator[BanEntry]

async fetch_channel(channel_id) → BaseChannel¶

Fetch a channel from the guild.

Parameters:: channel_id (int) – The ID of the channel
Return type:: BaseChannel
Returns:: The channel object

async fetch_channels() → list[type[BaseChannel]]¶

Fetches all the channels in the guild.

Return type:: list[type[BaseChannel]]

async fetch_emoji(emoji_id) → Emoji¶

Fetches an emoji from the guild.

Return type:: Emoji
Parameters:: emoji_id (int)

async fetch_emojis() → list[Emoji]¶

Fetches all the emojis in the guild.

Return type:: list[Emoji]

async fetch_guild_prune_count(*, days=7, include_roles=None) → int¶

Fetch the amount of members that would be pruned.

Parameters:

days (int | None) – How many days of inactivity to prune for
include_roles (list[Role | PartialRole | int] | None) – Which roles to include in the prune

Return type:

int

Returns:

The amount of members that would be pruned

async fetch_integrations() → list[Integration]¶

Fetches the integrations for the guild.

This requires the MANAGE_GUILD permission.

Return type:: list[Integration]
Returns:: The integrations in the guild.

async fetch_invites() → list[Invite]¶

Fetches all the invites for the guild.

Return type:: list[Invite]

async fetch_member(member_id) → Member¶

Fetch a member from the guild.

Parameters:: member_id (int) – The ID of the member
Return type:: Member
Returns:: The member object

async fetch_members(*, limit=1000, after=None) → AsyncIterator[Member]¶

Fetches all the members in the guild.

Parameters:

limit (int | None) – The maximum amount of members to return
after (Snowflake | int | None) – The member to start after

Yields:

The members in the guild

Return type:

AsyncIterator[Member]

async fetch_public_threads() → list[PublicThread]¶

Fetches all the public threads in the guild.

Return type:: list[PublicThread]
Returns:: The public threads in the guild

async fetch_regions() → list[VoiceRegion]¶

Fetches all the voice regions for the guild.

Return type:: list[VoiceRegion]

async fetch_roles() → list[Role]¶

Fetches all the roles in the guild.

Return type:: list[Role]

async fetch_scheduled_event(id) → ScheduledEvent¶

Fetches a scheduled event object.

Parameters:: id (int) – The ID of the scheduled event.
Return type:: ScheduledEvent
Returns:: The scheduled event object.

async fetch_scheduled_events_list() → list[ScheduledEvent]¶

Fetches all the scheduled events in the guild.

Return type:: list[ScheduledEvent]

async fetch_soundboard_sound(sound_id) → SoundboardSound¶

Fetches a soundboard sound from the guild.

Return type:: SoundboardSound
Parameters:: sound_id (int)

async fetch_soundboard_sounds() → list[SoundboardSound]¶

Fetches all the soundboard sounds in the guild.

Return type:: list[SoundboardSound]

async fetch_sticker(sticker_id) → Sticker¶

Fetch a sticker from the guild.

Parameters:: sticker_id (int) – The ID of the sticker
Return type:: Sticker
Returns:: The sticker object

async fetch_stickers() → list[Sticker]¶

Fetches all the stickers in the guild.

Return type:: list[Sticker]

get_channel(channel_id) → BaseChannel | PartialChannel | None¶

Returns the channel from cache if it exists.

Parameters:: channel_id (int) – The ID of the channel to get.
Return type:: BaseChannel | PartialChannel | None
Returns:: The channel with the given ID, if it exists.

get_channel_voice_states(channel_id) → list[VoiceState | PartialVoiceState]¶

Returns the voice state of a channel.

Parameters:: channel_id (int) – The ID of the channel to get the voice state of.
Return type:: list[VoiceState | PartialVoiceState]
Returns:: The voice state of the channel

get_member(member_id) → Member | PartialMember | None¶

Returns the member from cache if it exists.

Parameters:: member_id (int) – The ID of the member to get.
Return type:: Member | PartialMember | None
Returns:: The member with the given ID, if it exists.

get_member_voice_state(member_id) → VoiceState | PartialVoiceState | None¶

Returns the voice state of a member from cache if it exists.

Parameters:: member_id (int) – The ID of the member to get the voice state of.
Return type:: VoiceState | PartialVoiceState | None
Returns:: The voice state of the member, if it exists.

get_partial_automod_rule(automod_id) → PartialAutoModRule¶

Returns a partial automod rule object.

Return type:: PartialAutoModRule
Parameters:: automod_id (int)

get_partial_channel(channel_id) → PartialChannel¶

Get a partial channel object.

Parameters:: channel_id (int) – The ID of the channel
Return type:: PartialChannel
Returns:: The partial channel object

get_partial_emoji(emoji_id) → PartialEmoji¶

Get a partial emoji object.

Parameters:: emoji_id (int) – The ID of the emoji
Return type:: PartialEmoji
Returns:: The partial emoji object

get_partial_member(member_id) → PartialMember¶

Get a partial member object.

Parameters:: member_id (int) – The ID of the member
Return type:: PartialMember
Returns:: The partial member object

get_partial_role(role_id) → PartialRole¶

Get a partial role object.

Parameters:: role_id (int) – The ID of the role
Return type:: PartialRole
Returns:: The partial role object

get_partial_scheduled_event(id) → PartialScheduledEvent¶

Creates a partial scheduled event object.

Parameters:: id (int) – The ID of the scheduled event.
Return type:: PartialScheduledEvent
Returns:: The partial scheduled event object.

get_partial_soundboard_sound(sound_id) → PartialSoundboardSound¶

Get a partial soundboard sound object.

Parameters:: sound_id (int) – The ID of the sound
Return type:: PartialSoundboardSound
Returns:: The partial soundboard sound object

get_partial_sticker(sticker_id) → PartialSticker¶

Get a partial sticker object.

Parameters:: sticker_id (int) – The ID of the sticker
Return type:: PartialSticker
Returns:: The partial sticker object

get_role(role_id) → Role | PartialRole | None¶

Returns the role from cache if it exists.

Parameters:: role_id (int) – The ID of the role to get.
Return type:: Role | PartialRole | None
Returns:: The role with the given ID, if it exists.

get_soundboard_sound(sound_id) → SoundboardSound | PartialSoundboardSound | None¶

Returns the soundboard sound from cache if it exists.

Parameters:: sound_id (int) – The ID of the soundboard sound to get.
Return type:: SoundboardSound | PartialSoundboardSound | None
Returns:: The soundboard sound with the given ID, if it exists.

get_thread(thread_id) → BaseChannel | PartialChannel | None¶

Returns the thread from cache if it exists.

Parameters:: thread_id (int) – The ID of the thread to get.
Return type:: BaseChannel | PartialChannel | None
Returns:: The thread with the given ID, if it exists.

get_voice_states() → list[VoiceState | PartialVoiceState]¶

Returns the voice state of the guild.

Return type:: list[VoiceState | PartialVoiceState]

async kick(member, *, reason=None) → None¶

Kick a member from the server.

Parameters:

member (Member | PartialMember | int) – The member to kick
reason (str | None) – The reason for kicking the member

Return type:

None

property large: bool¶: Whether the guild is considered large.

async leave() → None¶

Leave the guild.

Return type:: None

property members: list[Member | PartialMember]¶: Returns a list of all the members in the guild if they are cached.

property roles: list[Role | PartialRole]¶: Returns a list of all the roles in the guild if they are cached or if the guild was fetched.

async search_members(query, *, limit=100) → list[Member]¶

Search for members in the guild.

Parameters:

query (str) – The query to search for
limit (int | None) – The maximum amount of members to return

Return type:

list[Member]

Returns:

The members that matched the query

Raises:

ValueError – If the limit is not between 1 and 1000

property soundboard_sounds: list[SoundboardSound | PartialSoundboardSound]¶: Returns a list of all the soundboard sounds in the guild if they are cached.

property stickers: list[Sticker | PartialSticker]¶: Returns a list of all the stickers in the guild if they are cached.

property text_channels: list[TextChannel]¶: Returns a list of all the text channels in the guild if they are cached.

property threads: list[BaseChannel | PartialChannel]¶: Returns a list of all the threads in the guild if they are cached.

async unban(member, *, reason=None) → None¶

Unban a member from the server.

Parameters:

member (Member | PartialMember | int) – The member to unban
reason (str | None) – The reason for unbanning the member

Return type:

None

property voice_channels: list[VoiceChannel]¶: Returns a list of all the voice channels in the guild if they are cached.

class discord_http.guild.PartialScheduledEvent(*, state, id, guild_id)¶

Bases: PartialBase

Parameters:

state (DiscordAPI)
id (int)
guild_id (int)

async delete(*, reason=None) → None¶

Delete the event (the bot must own the event).

Return type:: None
Parameters:: reason (str | None)

async edit(*, name=<MISSING>, description=<MISSING>, channel=<MISSING>, external_location=<MISSING>, privacy_level=<MISSING>, entity_type=<MISSING>, status=<MISSING>, start_time=<MISSING>, end_time=<MISSING>, image=<MISSING>, reason=None) → ScheduledEvent¶

Edit the event.

Parameters:

name (str | None) – New name of the event
description (str | None) – New description of the event
channel (PartialChannel | int | None) – New channel of the event
external_location (str | None) – New external location of the event
privacy_level (PrivacyLevelType | None) – New privacy level of the event
entity_type (ScheduledEventEntityType | None) – New entity type of the event
status (ScheduledEventStatusType | None) – New status of the event
start_time (datetime | timedelta | int | None) – New start time of the event
end_time (datetime | timedelta | int | None) – New end time of the event (only for external events)
image (File | bytes | None) – New image of the event
reason (str | None) – The reason for editing the event

Return type: