Application and entities that are used to describe invites on Discord.
# -*- coding: utf-8 -*-
# cython: language_level=3
# Copyright (c) 2020 Nekokatt
# Copyright (c) 2021-present davfsa
#
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to deal
# in the Software without restriction, including without limitation the rights
# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
# copies of the Software, and to permit persons to whom the Software is
# furnished to do so, subject to the following conditions:
#
# The above copyright notice and this permission notice shall be included in all
# copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
# SOFTWARE.
"""Application and entities that are used to describe invites on Discord."""
from __future__ import annotations
__all__: typing.Sequence[str] = (
"TargetType",
"VanityURL",
"InviteGuild",
"InviteCode",
"Invite",
"InviteWithMetadata",
)
import abc
import typing
import attr
from hikari import guilds
from hikari import urls
from hikari.internal import attr_extensions
from hikari.internal import enums
from hikari.internal import routes
if typing.TYPE_CHECKING:
import datetime
from hikari import applications
from hikari import channels
from hikari import files
from hikari import snowflakes
from hikari import traits
from hikari import users
@typing.final
class TargetType(int, enums.Enum):
"""The target of the invite."""
STREAM = 1
"""This invite is targeting a "Go Live" stream."""
EMBEDDED_APPLICATION = 2
"""This invite is targeting an embedded application."""
class InviteCode(abc.ABC):
"""A representation of a guild/channel invite."""
__slots__: typing.Sequence[str] = ()
@property
@abc.abstractmethod
def code(self) -> str:
"""Return the code for this invite.
Returns
-------
builtins.str
The invite code that can be appended to a URL.
"""
def __str__(self) -> str:
return f"https://discord.gg/{self.code}"
@attr_extensions.with_copy
@attr.define(hash=True, kw_only=True, weakref_slot=False)
class VanityURL(InviteCode):
"""A special case invite object, that represents a guild's vanity url."""
app: traits.RESTAware = attr.field(
repr=False, eq=False, hash=False, metadata={attr_extensions.SKIP_DEEP_COPY: True}
)
"""The client application that models may use for procedures."""
code: str = attr.field(hash=True, repr=True)
"""The code for this invite."""
uses: int = attr.field(eq=False, hash=False, repr=True)
"""The amount of times this invite has been used."""
@attr.define(hash=True, kw_only=True, weakref_slot=False)
class InviteGuild(guilds.PartialGuild):
"""Represents the partial data of a guild that is attached to invites."""
features: typing.Sequence[typing.Union[guilds.GuildFeature, int]] = attr.field(eq=False, hash=False, repr=False)
"""A list of the features in this guild."""
splash_hash: typing.Optional[str] = attr.field(eq=False, hash=False, repr=False)
"""The hash of the splash for the guild, if there is one."""
banner_hash: typing.Optional[str] = attr.field(eq=False, hash=False, repr=False)
"""The hash for the guild's banner.
This is only present if `hikari.guilds.GuildFeature.BANNER` is in the
`features` for this guild. For all other purposes, it is `builtins.None`.
"""
description: typing.Optional[str] = attr.field(eq=False, hash=False, repr=False)
"""The guild's description.
This is only present if certain `features` are set in this guild.
Otherwise, this will always be `builtins.None`. For all other purposes, it is `builtins.None`.
"""
verification_level: typing.Union[guilds.GuildVerificationLevel, int] = attr.field(eq=False, hash=False, repr=False)
"""The verification level required for a user to participate in this guild."""
vanity_url_code: typing.Optional[str] = attr.field(eq=False, hash=False, repr=True)
"""The vanity URL code for the guild's vanity URL.
This is only present if `hikari.guilds.GuildFeature.VANITY_URL` is in the
`features` for this guild. If not, this will always be `builtins.None`.
"""
welcome_screen: typing.Optional[guilds.WelcomeScreen] = attr.field(eq=False, hash=False, repr=False)
"""The welcome screen of a community guild shown to new members, if set."""
nsfw_level: guilds.GuildNSFWLevel = attr.field(eq=False, hash=False, repr=False)
"""The NSFW level of the guild."""
@property
def splash_url(self) -> typing.Optional[files.URL]:
"""Splash URL for the guild, if set."""
return self.make_splash_url()
def make_splash_url(self, *, ext: str = "png", size: int = 4096) -> typing.Optional[files.URL]:
"""Generate the guild's splash image URL, if set.
Parameters
----------
ext : builtins.str
The extension to use for this URL, defaults to `png`.
Supports `png`, `jpeg`, `jpg` and `webp`.
size : builtins.int
The size to set for the URL, defaults to `4096`.
Can be any power of two between 16 and 4096.
Returns
-------
typing.Optional[hikari.files.URL]
The URL to the splash, or `builtins.None` if not set.
Raises
------
builtins.ValueError
If `size` is not a power of two or not between 16 and 4096.
"""
if self.splash_hash is None:
return None
return routes.CDN_GUILD_SPLASH.compile_to_file(
urls.CDN_URL,
guild_id=self.id,
hash=self.splash_hash,
size=size,
file_format=ext,
)
@property
def banner_url(self) -> typing.Optional[files.URL]:
"""Banner URL for the guild, if set."""
return self.make_banner_url()
def make_banner_url(self, *, ext: typing.Optional[str] = None, size: int = 4096) -> typing.Optional[files.URL]:
"""Generate the guild's banner image URL, if set.
Parameters
----------
ext : typing.Optional[builtins.str]
The ext to use for this URL, defaults to `png` or `gif`.
Supports `png`, `jpeg`, `jpg`, `webp` and `gif` (when
animated).
If `builtins.None`, then the correct default extension is
determined based on whether the banner is animated or not.
size : builtins.int
The size to set for the URL, defaults to `4096`.
Can be any power of two between 16 and 4096.
Returns
-------
typing.Optional[hikari.files.URL]
The URL of the banner, or `builtins.None` if no banner is set.
Raises
------
builtins.ValueError
If `size` is not a power of two or not between 16 and 4096.
"""
if self.banner_hash is None:
return None
if ext is None:
if self.banner_hash.startswith("a_"):
ext = "gif"
else:
ext = "png"
return routes.CDN_GUILD_BANNER.compile_to_file(
urls.CDN_URL,
guild_id=self.id,
hash=self.banner_hash,
size=size,
file_format=ext,
)
@attr_extensions.with_copy
@attr.define(hash=True, kw_only=True, weakref_slot=False)
class Invite(InviteCode):
"""Represents an invite that's used to add users to a guild or group dm."""
app: traits.RESTAware = attr.field(
repr=False, eq=False, hash=False, metadata={attr_extensions.SKIP_DEEP_COPY: True}
)
"""The client application that models may use for procedures."""
code: str = attr.field(hash=True, repr=True)
"""The code for this invite."""
guild: typing.Optional[InviteGuild] = attr.field(eq=False, hash=False, repr=False)
"""The partial object of the guild this invite belongs to.
Will be `builtins.None` for group DM invites and when attached to a gateway event;
for invites received over the gateway you should refer to `Invite.guild_id`.
"""
guild_id: typing.Optional[snowflakes.Snowflake] = attr.field(eq=False, hash=False, repr=True)
"""The ID of the guild this invite belongs to.
Will be `builtins.None` for group DM invites.
"""
channel: typing.Optional[channels.PartialChannel] = attr.field(eq=False, hash=False, repr=False)
"""The partial object of the channel this invite targets.
Will be `builtins.None` for invite objects that are attached to gateway events,
in which case you should refer to `Invite.channel_id`.
"""
channel_id: snowflakes.Snowflake = attr.field(eq=False, hash=False, repr=True)
"""The ID of the channel this invite targets."""
inviter: typing.Optional[users.User] = attr.field(eq=False, hash=False, repr=False)
"""The object of the user who created this invite."""
target_type: typing.Union[TargetType, int, None] = attr.ib(eq=False, hash=False, repr=False)
"""The type of the target of this invite, if applicable."""
target_user: typing.Optional[users.User] = attr.field(eq=False, hash=False, repr=False)
"""The object of the user who this invite targets, if set."""
target_application: typing.Optional[applications.InviteApplication] = attr.ib(eq=False, hash=False, repr=False)
"""The embedded application this invite targets, if applicable."""
approximate_active_member_count: typing.Optional[int] = attr.field(eq=False, hash=False, repr=False)
"""The approximate amount of presences in this invite's guild.
This is only returned by the GET REST Invites endpoint.
"""
approximate_member_count: typing.Optional[int] = attr.field(eq=False, hash=False, repr=False)
"""The approximate amount of members in this invite's guild.
This is only returned by the GET Invites REST endpoint.
"""
expires_at: typing.Optional[datetime.datetime] = attr.field(eq=False, hash=False, repr=False)
"""When this invite will expire.
This field is only returned by the GET Invite REST endpoint and will be
returned as `builtins.None` by said endpoint if the invite doesn't have a set
expiry date. Other places will always return this as `builtins.None`.
"""
@attr.define(hash=True, kw_only=True, weakref_slot=False)
class InviteWithMetadata(Invite):
"""Extends the base `Invite` object with metadata.
The metadata is only returned when getting an invite with
guild permissions, rather than it's code.
"""
uses: int = attr.field(eq=False, hash=False, repr=True)
"""The amount of times this invite has been used."""
max_uses: typing.Optional[int] = attr.field(eq=False, hash=False, repr=True)
"""The limit for how many times this invite can be used before it expires.
If set to `builtins.None` then this is unlimited.
"""
# TODO: can we use a non-None value to represent infinity here somehow, or
# make a timedelta that is infinite for comparisons?
max_age: typing.Optional[datetime.timedelta] = attr.field(eq=False, hash=False, repr=False)
"""The timedelta of how long this invite will be valid for.
If set to `builtins.None` then this is unlimited.
"""
is_temporary: bool = attr.field(eq=False, hash=False, repr=True)
"""Whether this invite grants temporary membership."""
created_at: datetime.datetime = attr.field(eq=False, hash=False, repr=False)
"""When this invite was created."""
expires_at: typing.Optional[datetime.datetime]
"""When this invite will expire.
If this invite doesn't have a set expiry then this will be `builtins.None`.
"""
@property
def uses_left(self) -> typing.Optional[int]:
"""Return the number of uses left for this invite.
Returns
-------
typing.Optional[builtins.int]
The number of uses left for this invite. This will be `builtins.None`
if the invite has unlimited uses.
"""
if self.max_uses:
return self.max_uses - self.uses
return Noneclass Invite (
*,
app: traits.RESTAware,
code: str,
guild: Optional[InviteGuild],
guild_id: Optional[snowflakes.Snowflake],
channel: Optional[channels.PartialChannel],
channel_id: snowflakes.Snowflake,
inviter: Optional[users.User],
target_type: Union[TargetType, int, None],
target_user: Optional[users.User],
target_application: Optional[applications.InviteApplication],
approximate_active_member_count: Optional[int],
approximate_member_count: Optional[int],
expires_at: Optional[datetime.datetime],
): ...Represents an invite that's used to add users to a guild or group dm.
Method generated by attrs for class Invite.
class Invite(InviteCode):
"""Represents an invite that's used to add users to a guild or group dm."""
app: traits.RESTAware = attr.field(
repr=False, eq=False, hash=False, metadata={attr_extensions.SKIP_DEEP_COPY: True}
)
"""The client application that models may use for procedures."""
code: str = attr.field(hash=True, repr=True)
"""The code for this invite."""
guild: typing.Optional[InviteGuild] = attr.field(eq=False, hash=False, repr=False)
"""The partial object of the guild this invite belongs to.
Will be `builtins.None` for group DM invites and when attached to a gateway event;
for invites received over the gateway you should refer to `Invite.guild_id`.
"""
guild_id: typing.Optional[snowflakes.Snowflake] = attr.field(eq=False, hash=False, repr=True)
"""The ID of the guild this invite belongs to.
Will be `builtins.None` for group DM invites.
"""
channel: typing.Optional[channels.PartialChannel] = attr.field(eq=False, hash=False, repr=False)
"""The partial object of the channel this invite targets.
Will be `builtins.None` for invite objects that are attached to gateway events,
in which case you should refer to `Invite.channel_id`.
"""
channel_id: snowflakes.Snowflake = attr.field(eq=False, hash=False, repr=True)
"""The ID of the channel this invite targets."""
inviter: typing.Optional[users.User] = attr.field(eq=False, hash=False, repr=False)
"""The object of the user who created this invite."""
target_type: typing.Union[TargetType, int, None] = attr.ib(eq=False, hash=False, repr=False)
"""The type of the target of this invite, if applicable."""
target_user: typing.Optional[users.User] = attr.field(eq=False, hash=False, repr=False)
"""The object of the user who this invite targets, if set."""
target_application: typing.Optional[applications.InviteApplication] = attr.ib(eq=False, hash=False, repr=False)
"""The embedded application this invite targets, if applicable."""
approximate_active_member_count: typing.Optional[int] = attr.field(eq=False, hash=False, repr=False)
"""The approximate amount of presences in this invite's guild.
This is only returned by the GET REST Invites endpoint.
"""
approximate_member_count: typing.Optional[int] = attr.field(eq=False, hash=False, repr=False)
"""The approximate amount of members in this invite's guild.
This is only returned by the GET Invites REST endpoint.
"""
expires_at: typing.Optional[datetime.datetime] = attr.field(eq=False, hash=False, repr=False)
"""When this invite will expire.
This field is only returned by the GET Invite REST endpoint and will be
returned as `builtins.None` by said endpoint if the invite doesn't have a set
expiry date. Other places will always return this as `builtins.None`.
"""Extends the base Invite object with metadata …
A representation of a guild/channel invite.
Helper class that provides a standard way to create an ABC using inheritance.
property app : traits.RESTAwareThe client application that models may use for procedures.
property approximate_active_member_count : Optional[int]The approximate amount of presences in this invite's guild.
This is only returned by the GET REST Invites endpoint.
property approximate_member_count : Optional[int]The approximate amount of members in this invite's guild.
This is only returned by the GET Invites REST endpoint.
property channel : Optional[channels.PartialChannel]The partial object of the channel this invite targets.
Will be None for invite objects that are attached to gateway events,
in which case you should refer to channel_id.
property channel_id : snowflakes.SnowflakeThe ID of the channel this invite targets.
property expires_at : Optional[datetime.datetime]When this invite will expire.
This field is only returned by the GET Invite REST endpoint and will be
returned as None by said endpoint if the invite doesn't have a set
expiry date. Other places will always return this as None.
property guild : Optional[InviteGuild]The partial object of the guild this invite belongs to.
Will be None for group DM invites and when attached to a gateway event;
for invites received over the gateway you should refer to guild_id.
property guild_id : Optional[snowflakes.Snowflake]The ID of the guild this invite belongs to.
Will be None for group DM invites.
property inviter : Optional[users.User]The object of the user who created this invite.
property target_application : Optional[applications.InviteApplication]The embedded application this invite targets, if applicable.
property target_type : Union[TargetType, int, None]The type of the target of this invite, if applicable.
property target_user : Optional[users.User]The object of the user who this invite targets, if set.
class InviteCode: ...A representation of a guild/channel invite.
class InviteCode(abc.ABC):
"""A representation of a guild/channel invite."""
__slots__: typing.Sequence[str] = ()
@property
@abc.abstractmethod
def code(self) -> str:
"""Return the code for this invite.
Returns
-------
builtins.str
The invite code that can be appended to a URL.
"""
def __str__(self) -> str:
return f"https://discord.gg/{self.code}"Represents an invite that's used to add users to a guild or group dm …
A special case invite object, that represents a guild's vanity url …
Helper class that provides a standard way to create an ABC using inheritance.
class InviteGuild (
*,
app: traits.RESTAware,
id: snowflakes.Snowflake,
icon_hash: Optional[str],
name: str,
features: Sequence[Union[guilds.GuildFeature, int]],
splash_hash: Optional[str],
banner_hash: Optional[str],
description: Optional[str],
verification_level: Union[guilds.GuildVerificationLevel, int],
vanity_url_code: Optional[str],
welcome_screen: Optional[guilds.WelcomeScreen],
nsfw_level: guilds.GuildNSFWLevel,
): ...Represents the partial data of a guild that is attached to invites.
Method generated by attrs for class InviteGuild.
class InviteGuild(guilds.PartialGuild):
"""Represents the partial data of a guild that is attached to invites."""
features: typing.Sequence[typing.Union[guilds.GuildFeature, int]] = attr.field(eq=False, hash=False, repr=False)
"""A list of the features in this guild."""
splash_hash: typing.Optional[str] = attr.field(eq=False, hash=False, repr=False)
"""The hash of the splash for the guild, if there is one."""
banner_hash: typing.Optional[str] = attr.field(eq=False, hash=False, repr=False)
"""The hash for the guild's banner.
This is only present if `hikari.guilds.GuildFeature.BANNER` is in the
`features` for this guild. For all other purposes, it is `builtins.None`.
"""
description: typing.Optional[str] = attr.field(eq=False, hash=False, repr=False)
"""The guild's description.
This is only present if certain `features` are set in this guild.
Otherwise, this will always be `builtins.None`. For all other purposes, it is `builtins.None`.
"""
verification_level: typing.Union[guilds.GuildVerificationLevel, int] = attr.field(eq=False, hash=False, repr=False)
"""The verification level required for a user to participate in this guild."""
vanity_url_code: typing.Optional[str] = attr.field(eq=False, hash=False, repr=True)
"""The vanity URL code for the guild's vanity URL.
This is only present if `hikari.guilds.GuildFeature.VANITY_URL` is in the
`features` for this guild. If not, this will always be `builtins.None`.
"""
welcome_screen: typing.Optional[guilds.WelcomeScreen] = attr.field(eq=False, hash=False, repr=False)
"""The welcome screen of a community guild shown to new members, if set."""
nsfw_level: guilds.GuildNSFWLevel = attr.field(eq=False, hash=False, repr=False)
"""The NSFW level of the guild."""
@property
def splash_url(self) -> typing.Optional[files.URL]:
"""Splash URL for the guild, if set."""
return self.make_splash_url()
def make_splash_url(self, *, ext: str = "png", size: int = 4096) -> typing.Optional[files.URL]:
"""Generate the guild's splash image URL, if set.
Parameters
----------
ext : builtins.str
The extension to use for this URL, defaults to `png`.
Supports `png`, `jpeg`, `jpg` and `webp`.
size : builtins.int
The size to set for the URL, defaults to `4096`.
Can be any power of two between 16 and 4096.
Returns
-------
typing.Optional[hikari.files.URL]
The URL to the splash, or `builtins.None` if not set.
Raises
------
builtins.ValueError
If `size` is not a power of two or not between 16 and 4096.
"""
if self.splash_hash is None:
return None
return routes.CDN_GUILD_SPLASH.compile_to_file(
urls.CDN_URL,
guild_id=self.id,
hash=self.splash_hash,
size=size,
file_format=ext,
)
@property
def banner_url(self) -> typing.Optional[files.URL]:
"""Banner URL for the guild, if set."""
return self.make_banner_url()
def make_banner_url(self, *, ext: typing.Optional[str] = None, size: int = 4096) -> typing.Optional[files.URL]:
"""Generate the guild's banner image URL, if set.
Parameters
----------
ext : typing.Optional[builtins.str]
The ext to use for this URL, defaults to `png` or `gif`.
Supports `png`, `jpeg`, `jpg`, `webp` and `gif` (when
animated).
If `builtins.None`, then the correct default extension is
determined based on whether the banner is animated or not.
size : builtins.int
The size to set for the URL, defaults to `4096`.
Can be any power of two between 16 and 4096.
Returns
-------
typing.Optional[hikari.files.URL]
The URL of the banner, or `builtins.None` if no banner is set.
Raises
------
builtins.ValueError
If `size` is not a power of two or not between 16 and 4096.
"""
if self.banner_hash is None:
return None
if ext is None:
if self.banner_hash.startswith("a_"):
ext = "gif"
else:
ext = "png"
return routes.CDN_GUILD_BANNER.compile_to_file(
urls.CDN_URL,
guild_id=self.id,
hash=self.banner_hash,
size=size,
file_format=ext,
)Base object for any partial guild objects …
Mixin for a class that enforces uniqueness by a snowflake ID.
Helper class that provides a standard way to create an ABC using inheritance.
property created_at : datetime.datetimeWhen the object was created.
property description : Optional[str]The guild's description.
This is only present if certain features are set in this guild.
Otherwise, this will always be None. For all other purposes, it is None.
property features : Sequence[Union[GuildFeature, int]]A list of the features in this guild.
property nsfw_level : GuildNSFWLevelThe NSFW level of the guild.
property shard_id : Optional[int]Return the ID of the shard this guild is served by.
This may return None if the application does not have a gateway
connection.
property splash_hash : Optional[str]The hash of the splash for the guild, if there is one.
property splash_url : Optional[files.URL]Splash URL for the guild, if set.
property vanity_url_code : Optional[str]The vanity URL code for the guild's vanity URL.
This is only present if VANITY_URL is in the
features for this guild. If not, this will always be None.
property verification_level : Union[GuildVerificationLevel, int]The verification level required for a user to participate in this guild.
property welcome_screen : Optional[WelcomeScreen]The welcome screen of a community guild shown to new members, if set.
async def ban(
user: snowflakes.SnowflakeishOr[users.PartialUser],
*,
delete_message_days: undefined.UndefinedOr[int] = UNDEFINED,
reason: undefined.UndefinedOr[str] = UNDEFINED,
) -> None: ...
Inherited from:
PartialGuild.ban
Ban the given user from this guild.
user : Snowflakeish[PartialUser]delete_message_days : UndefinedNoneOr[int]reason : UndefinedOr[str]BadRequestErrorForbiddenErrorBAN_MEMBERS permission.UnauthorizedErrorNotFoundErrorRateLimitTooLongErrormax_rate_limit when making a request.RateLimitedErrorInternalServerErrorasync def create_category(
name: str,
*,
position: undefined.UndefinedOr[int] = UNDEFINED,
permission_overwrites: undefined.UndefinedOr[Sequence[channels_.PermissionOverwrite]] = UNDEFINED,
reason: undefined.UndefinedOr[str] = UNDEFINED,
) -> GuildCategory: ...
Inherited from:
PartialGuild.create_category
Create a category in the guild.
name : strposition : UndefinedOr[int]permission_overwrites : UndefinedOr[Sequence[PermissionOverwrite]]reason : UndefinedOr[str]GuildCategoryBadRequestErrorForbiddenErrorMANAGE_CHANNEL permission.UnauthorizedErrorNotFoundErrorRateLimitTooLongErrormax_rate_limit when making a request.RateLimitedErrorInternalServerErrorasync def create_news_channel(
name: str,
*,
position: undefined.UndefinedOr[int] = UNDEFINED,
topic: undefined.UndefinedOr[str] = UNDEFINED,
nsfw: undefined.UndefinedOr[bool] = UNDEFINED,
rate_limit_per_user: undefined.UndefinedOr[time.Intervalish] = UNDEFINED,
permission_overwrites: undefined.UndefinedOr[Sequence[channels_.PermissionOverwrite]] = UNDEFINED,
category: undefined.UndefinedOr[snowflakes.SnowflakeishOr[channels_.GuildCategory]] = UNDEFINED,
reason: undefined.UndefinedOr[str] = UNDEFINED,
) -> GuildNewsChannel: ...
Inherited from:
PartialGuild.create_news_channel
Create a news channel in the guild.
name : strposition : UndefinedOr[int]topic : UndefinedOr[str]nsfw : UndefinedOr[bool]rate_limit_per_user : UndefinedOr[Intervalish]permission_overwrites : UndefinedOr[Sequence[PermissionOverwrite]]category : UndefinedOr[SnowflakeishOr[GuildCategory]]reason : UndefinedOr[str]GuildNewsChannelBadRequestErrorForbiddenErrorMANAGE_CHANNEL permission.UnauthorizedErrorNotFoundErrorRateLimitTooLongErrormax_rate_limit when making a request.RateLimitedErrorInternalServerErrorasync def create_stage_channel(
name: str,
*,
position: undefined.UndefinedOr[int] = UNDEFINED,
user_limit: undefined.UndefinedOr[int] = UNDEFINED,
bitrate: undefined.UndefinedOr[int] = UNDEFINED,
permission_overwrites: undefined.UndefinedOr[Sequence[channels_.PermissionOverwrite]] = UNDEFINED,
region: undefined.UndefinedOr[Union[voices_.VoiceRegion, str]] = UNDEFINED,
category: undefined.UndefinedOr[snowflakes.SnowflakeishOr[channels_.GuildCategory]] = UNDEFINED,
reason: undefined.UndefinedOr[str] = UNDEFINED,
) -> channels_.GuildStageChannel: ...
Inherited from:
PartialGuild.create_stage_channel
Create a stage channel in the guild.
name : strposition : UndefinedOr[int]user_limit : UndefinedOr[int]bitrate : UndefinedOr[int]permission_overwrites : UndefinedOr[Sequence[PermissionOverwrite]]region : UndefinedOr[Union[VoiceRegion, str]]None here will set it to "auto" mode where the used
region will be decided based on the first person who connects to it
when it's empty.category : UndefinedOr[SnowflakeishOr[GuildCategory]]reason : UndefinedOr[str]GuildStageChannelBadRequestErrorForbiddenErrorMANAGE_CHANNEL permission.UnauthorizedErrorNotFoundErrorRateLimitTooLongErrormax_rate_limit when making a request.RateLimitedErrorInternalServerErrorasync def create_sticker(
name: str,
tag: str,
image: files.Resourceish,
*,
description: undefined.UndefinedOr[str] = UNDEFINED,
reason: undefined.UndefinedOr[str] = UNDEFINED,
) -> stickers.GuildSticker: ...
Inherited from:
PartialGuild.create_sticker
Create a sticker in a guild.
name : strtag : strimage : ResourceishThe 320x320 image for the sticker. Maximum upload size is 500kb. This can be a still or an animated PNG or a Lottie.
Note
Lottie support is only available for verified and partnered servers.
description : UndefinedOr[str]reason : UndefinedOr[str]GuildStickerBadRequestErrorForbiddenErrorMANAGE_EMOJIS_AND_STICKERS in the server.NotFoundErrorUnauthorizedErrorRateLimitTooLongErrormax_rate_limit when making a request.RateLimitedErrorInternalServerErrorasync def create_text_channel(
name: str,
*,
position: undefined.UndefinedOr[int] = UNDEFINED,
topic: undefined.UndefinedOr[str] = UNDEFINED,
nsfw: undefined.UndefinedOr[bool] = UNDEFINED,
rate_limit_per_user: undefined.UndefinedOr[time.Intervalish] = UNDEFINED,
permission_overwrites: undefined.UndefinedOr[Sequence[channels_.PermissionOverwrite]] = UNDEFINED,
category: undefined.UndefinedOr[snowflakes.SnowflakeishOr[channels_.GuildCategory]] = UNDEFINED,
reason: undefined.UndefinedOr[str] = UNDEFINED,
) -> GuildTextChannel: ...
Inherited from:
PartialGuild.create_text_channel
Create a text channel in the guild.
name : strposition : UndefinedOr[int]topic : UndefinedOr[str]nsfw : UndefinedOr[bool]rate_limit_per_user : UndefinedOr[Intervalish]permission_overwrites : UndefinedOr[Sequence[PermissionOverwrite]]category : UndefinedOr[SnowflakeishOr[GuildCategory]]reason : UndefinedOr[str]GuildTextChannelBadRequestErrorForbiddenErrorMANAGE_CHANNEL permission.UnauthorizedErrorNotFoundErrorRateLimitTooLongErrormax_rate_limit when making a request.RateLimitedErrorInternalServerErrorasync def create_voice_channel(
name: str,
*,
position: undefined.UndefinedOr[int] = UNDEFINED,
user_limit: undefined.UndefinedOr[int] = UNDEFINED,
bitrate: undefined.UndefinedOr[int] = UNDEFINED,
video_quality_mode: undefined.UndefinedOr[Union[channels_.VideoQualityMode, int]] = UNDEFINED,
permission_overwrites: undefined.UndefinedOr[Sequence[channels_.PermissionOverwrite]] = UNDEFINED,
region: undefined.UndefinedOr[Union[voices_.VoiceRegion, str]] = UNDEFINED,
category: undefined.UndefinedOr[snowflakes.SnowflakeishOr[channels_.GuildCategory]] = UNDEFINED,
reason: undefined.UndefinedOr[str] = UNDEFINED,
) -> channels_.GuildVoiceChannel: ...
Inherited from:
PartialGuild.create_voice_channel
Create a voice channel in a guild.
guild : SnowflakeishOr[PartialGuild]name : strposition : UndefinedOr[int]user_limit : UndefinedOr[int]bitrate : UndefinedOr[int]video_quality_mode : UndefinedOr[Union[VideoQualityMode, int]]permission_overwrites : UndefinedOr[Sequence[PermissionOverwrite]]region : UndefinedOr[Union[VoiceRegion, str]]None here will set it to "auto" mode where the used
region will be decided based on the first person who connects to it
when it's empty.category : UndefinedOr[SnowflakeishOr[GuildCategory]]reason : UndefinedOr[str]GuildVoiceChannelBadRequestErrorForbiddenErrorMANAGE_CHANNEL permission.UnauthorizedErrorNotFoundErrorRateLimitTooLongErrormax_rate_limit when making a request.RateLimitedErrorInternalServerErrorasync def delete_channel(
channel: snowflakes.SnowflakeishOr[channels_.GuildChannel],
) -> GuildChannel: ...
Inherited from:
PartialGuild.delete_channel
Delete a channel in the guild.
Note
This method can also be used for deleting guild categories as well.
channel : SnowflakeishOr[GuildChannel]GuildChannelForbiddenErrorMANAGE_CHANNEL permission in the channel.NotFoundErrorRateLimitTooLongErrormax_rate_limit when making a request.RateLimitedErrorInternalServerErrorNote
For Public servers, the set 'Rules' or 'Guidelines' channels and the 'Public Server Updates' channel cannot be deleted.
async def delete_sticker(
sticker: snowflakes.SnowflakeishOr[stickers.PartialSticker],
*,
reason: undefined.UndefinedOr[str] = UNDEFINED,
) -> None: ...
Inherited from:
PartialGuild.delete_sticker
Delete a sticker in a guild.
sticker : SnowflakeishOr[PartialSticker]reason : UndefinedOr[str]ForbiddenErrorMANAGE_EMOJIS_AND_STICKERS in the server.NotFoundErrorUnauthorizedErrorRateLimitTooLongErrormax_rate_limit when making a request.RateLimitedErrorInternalServerErrorasync def edit(
*,
name: undefined.UndefinedOr[str] = UNDEFINED,
verification_level: undefined.UndefinedOr[GuildVerificationLevel] = UNDEFINED,
default_message_notifications: undefined.UndefinedOr[GuildMessageNotificationsLevel] = UNDEFINED,
explicit_content_filter_level: undefined.UndefinedOr[GuildExplicitContentFilterLevel] = UNDEFINED,
afk_channel: undefined.UndefinedOr[snowflakes.SnowflakeishOr[channels_.GuildVoiceChannel]] = UNDEFINED,
afk_timeout: undefined.UndefinedOr[time.Intervalish] = UNDEFINED,
icon: undefined.UndefinedNoneOr[files.Resourceish] = UNDEFINED,
owner: undefined.UndefinedOr[snowflakes.SnowflakeishOr[users.PartialUser]] = UNDEFINED,
splash: undefined.UndefinedNoneOr[files.Resourceish] = UNDEFINED,
banner: undefined.UndefinedNoneOr[files.Resourceish] = UNDEFINED,
system_channel: undefined.UndefinedNoneOr[snowflakes.SnowflakeishOr[channels_.GuildTextChannel]] = UNDEFINED,
rules_channel: undefined.UndefinedNoneOr[snowflakes.SnowflakeishOr[channels_.GuildTextChannel]] = UNDEFINED,
public_updates_channel: undefined.UndefinedNoneOr[snowflakes.SnowflakeishOr[channels_.GuildTextChannel]] = UNDEFINED,
preferred_locale: undefined.UndefinedOr[Union[str, locales.Locale]] = UNDEFINED,
reason: undefined.UndefinedOr[str] = UNDEFINED,
) -> RESTGuild: ...
Inherited from:
PartialGuild.edit
Edits the guild.
name : UndefinedOr[str]verification_level : UndefinedOr[GuildVerificationLevel]default_message_notifications : UndefinedOr[GuildMessageNotificationsLevel]explicit_content_filter_level : UndefinedOr[GuildExplicitContentFilterLevel]afk_channel : UndefinedOr[SnowflakeishOr[GuildVoiceChannel]]afk_timeout to
be set to work.afk_timeout : UndefinedOr[Intervalish]icon : UndefinedOr[Resourceish]ANIMATED_ICON feature.owner : UndefinedOr[SnowflakeishOr[PartialUser]]]If provided, the new guild owner.
Warning
You need to be the owner of the server to use this.
splash : UndefinedNoneOr[Resourceish]INVITE_SPLASH feature.banner : UndefinedNoneOr[Resourceish]BANNER feature.system_channel : UndefinedNoneOr[SnowflakeishOr[GuildTextChannel]]rules_channel : UndefinedNoneOr[SnowflakeishOr[GuildTextChannel]]public_updates_channel : UndefinedNoneOr[SnowflakeishOr[GuildTextChannel]]preferred_locale : UndefinedNoneOr[str]reason : UndefinedOr[str]RESTGuildBadRequestErrorForbiddenErrorMANAGE_GUILD permission or if you tried to
pass ownership without being the server owner.UnauthorizedErrorNotFoundErrorRateLimitTooLongErrormax_rate_limit when making a request.RateLimitedErrorInternalServerErrorasync def edit_sticker(
sticker: snowflakes.SnowflakeishOr[stickers.PartialSticker],
*,
name: undefined.UndefinedOr[str] = UNDEFINED,
description: undefined.UndefinedOr[str] = UNDEFINED,
tag: undefined.UndefinedOr[str] = UNDEFINED,
reason: undefined.UndefinedOr[str] = UNDEFINED,
) -> GuildSticker: ...
Inherited from:
PartialGuild.edit_sticker
Edit a sticker in a guild.
sticker : SnowflakeishOr[PartialSticker]name : UndefinedOr[str]description : UndefinedOr[str]tag : UndefinedOr[str]reason : UndefinedOr[str]GuildStickerBadRequestErrorForbiddenErrorMANAGE_EMOJIS_AND_STICKERS in the server.NotFoundErrorUnauthorizedErrorRateLimitTooLongErrormax_rate_limit when making a request.RateLimitedErrorInternalServerErrorasync def fetch_emoji(
emoji: snowflakes.SnowflakeishOr[emojis_.CustomEmoji],
) -> emojis_.KnownCustomEmoji: ...
Inherited from:
PartialGuild.fetch_emoji
Fetch an emoji from the guild.
emoji : SnowflakeishOr[CustomEmoji]CustomEmoji
or the ID of an existing emoji.KnownCustomEmojiNotFoundErrorUnauthorizedErrorRateLimitTooLongErrormax_rate_limit when making a request.RateLimitedErrorInternalServerErrorasync def fetch_emojis() -> Sequence[emojis_.KnownCustomEmoji]: ...
Inherited from:
PartialGuild.fetch_emojis
Fetch the emojis of the guild.
Sequence[KnownCustomEmoji]NotFoundErrorUnauthorizedErrorRateLimitTooLongErrormax_rate_limit when making a request.RateLimitedErrorInternalServerErrorasync def fetch_roles() -> Sequence[Role]: ...
Inherited from:
PartialGuild.fetch_roles
Fetch the roles of the guild.
UnauthorizedErrorRateLimitTooLongErrormax_rate_limit when making a request.RateLimitedErrorInternalServerErrorasync def fetch_self() -> RESTGuild: ...
Inherited from:
PartialGuild.fetch_self
Fetch the guild.
RESTGuildForbiddenErrorNotFoundErrorUnauthorizedErrorRateLimitTooLongErrormax_rate_limit when making a request.RateLimitedErrorInternalServerErrorasync def fetch_sticker(
sticker: snowflakes.SnowflakeishOr[stickers.PartialSticker],
) -> GuildSticker: ...
Inherited from:
PartialGuild.fetch_sticker
Fetch a sticker from the guild.
sticker : snowflakes.SnowflakeishOr[PartialSticker]GuildStickerForbiddenErrorNotFoundErrorUnauthorizedErrorRateLimitTooLongErrormax_rate_limit when making a request.RateLimitedErrorInternalServerErrorasync def fetch_stickers() -> Sequence[GuildSticker]: ...
Inherited from:
PartialGuild.fetch_stickers
Fetch the stickers of the guild.
Sequence[GuildSticker]ForbiddenErrorNotFoundErrorUnauthorizedErrorRateLimitTooLongErrormax_rate_limit when making a request.RateLimitedErrorInternalServerErrorasync def kick(
user: snowflakes.SnowflakeishOr[users.PartialUser],
*,
reason: undefined.UndefinedOr[str] = UNDEFINED,
) -> None: ...
Inherited from:
PartialGuild.kick
Kicks the given user from this guild.
user : Snowflakeish[PartialUser]reason : UndefinedOr[str]BadRequestErrorForbiddenErrorKICK_MEMBERS permission.UnauthorizedErrorNotFoundErrorRateLimitTooLongErrormax_rate_limit when making a request.RateLimitedErrorInternalServerErrordef make_icon_url(
*,
ext: Optional[str] = None,
size: int = 4096,
) -> Optional[files.URL]: ...
Inherited from:
PartialGuild.make_icon_url
Generate the guild's icon URL, if set.
ext : Optional[str]The extension to use for this URL, defaults to png or gif.
Supports png, jpeg, jpg, webp and gif (when
animated).
If None, then the correct default extension is
determined based on whether the icon is animated or not.
size : int4096.
Can be any power of two between 16 and 4096.ValueErrorsize is not a power of two or not between 16 and 4096.def make_splash_url(
*,
ext: str = 'png',
size: int = 4096,
) -> Optional[files.URL]: ...Generate the guild's splash image URL, if set.
ext : strpng.
Supports png, jpeg, jpg and webp.size : int4096.
Can be any power of two between 16 and 4096.ValueErrorsize is not a power of two or not between 16 and 4096.def make_splash_url(self, *, ext: str = "png", size: int = 4096) -> typing.Optional[files.URL]:
"""Generate the guild's splash image URL, if set.
Parameters
----------
ext : builtins.str
The extension to use for this URL, defaults to `png`.
Supports `png`, `jpeg`, `jpg` and `webp`.
size : builtins.int
The size to set for the URL, defaults to `4096`.
Can be any power of two between 16 and 4096.
Returns
-------
typing.Optional[hikari.files.URL]
The URL to the splash, or `builtins.None` if not set.
Raises
------
builtins.ValueError
If `size` is not a power of two or not between 16 and 4096.
"""
if self.splash_hash is None:
return None
return routes.CDN_GUILD_SPLASH.compile_to_file(
urls.CDN_URL,
guild_id=self.id,
hash=self.splash_hash,
size=size,
file_format=ext,
)async def unban(
user: snowflakes.SnowflakeishOr[users.PartialUser],
*,
reason: undefined.UndefinedOr[str] = UNDEFINED,
) -> None: ...
Inherited from:
PartialGuild.unban
Unban the given user from this guild.
user : Snowflakeish[PartialUser]reason : UndefinedOr[str]BadRequestErrorForbiddenErrorBAN_MEMBERS permission.UnauthorizedErrorNotFoundErrorRateLimitTooLongErrormax_rate_limit when making a request.RateLimitedErrorInternalServerErrorclass InviteWithMetadata (
*,
app: traits.RESTAware,
code: str,
guild: Optional[InviteGuild],
guild_id: Optional[snowflakes.Snowflake],
channel: Optional[channels.PartialChannel],
channel_id: snowflakes.Snowflake,
inviter: Optional[users.User],
target_type: Union[TargetType, int, None],
target_user: Optional[users.User],
target_application: Optional[applications.InviteApplication],
approximate_active_member_count: Optional[int],
approximate_member_count: Optional[int],
uses: int,
max_uses: Optional[int],
max_age: Optional[datetime.timedelta],
is_temporary: bool,
created_at: datetime.datetime,
expires_at: Optional[datetime.datetime],
): ...Extends the base Invite object with metadata.
The metadata is only returned when getting an invite with guild permissions, rather than it's code.
Method generated by attrs for class InviteWithMetadata.
class InviteWithMetadata(Invite):
"""Extends the base `Invite` object with metadata.
The metadata is only returned when getting an invite with
guild permissions, rather than it's code.
"""
uses: int = attr.field(eq=False, hash=False, repr=True)
"""The amount of times this invite has been used."""
max_uses: typing.Optional[int] = attr.field(eq=False, hash=False, repr=True)
"""The limit for how many times this invite can be used before it expires.
If set to `builtins.None` then this is unlimited.
"""
# TODO: can we use a non-None value to represent infinity here somehow, or
# make a timedelta that is infinite for comparisons?
max_age: typing.Optional[datetime.timedelta] = attr.field(eq=False, hash=False, repr=False)
"""The timedelta of how long this invite will be valid for.
If set to `builtins.None` then this is unlimited.
"""
is_temporary: bool = attr.field(eq=False, hash=False, repr=True)
"""Whether this invite grants temporary membership."""
created_at: datetime.datetime = attr.field(eq=False, hash=False, repr=False)
"""When this invite was created."""
expires_at: typing.Optional[datetime.datetime]
"""When this invite will expire.
If this invite doesn't have a set expiry then this will be `builtins.None`.
"""
@property
def uses_left(self) -> typing.Optional[int]:
"""Return the number of uses left for this invite.
Returns
-------
typing.Optional[builtins.int]
The number of uses left for this invite. This will be `builtins.None`
if the invite has unlimited uses.
"""
if self.max_uses:
return self.max_uses - self.uses
return NoneRepresents an invite that's used to add users to a guild or group dm …
A representation of a guild/channel invite.
Helper class that provides a standard way to create an ABC using inheritance.
property app : traits.RESTAwareThe client application that models may use for procedures.
property approximate_active_member_count : Optional[int]The approximate amount of presences in this invite's guild.
This is only returned by the GET REST Invites endpoint.
property approximate_member_count : Optional[int]The approximate amount of members in this invite's guild.
This is only returned by the GET Invites REST endpoint.
property channel : Optional[channels.PartialChannel]The partial object of the channel this invite targets.
Will be None for invite objects that are attached to gateway events,
in which case you should refer to channel_id.
property channel_id : snowflakes.SnowflakeThe ID of the channel this invite targets.
property created_at : datetime.datetimeWhen this invite was created.
property expires_at : Optional[datetime.datetime]When this invite will expire.
If this invite doesn't have a set expiry then this will be None.
property guild : Optional[InviteGuild]The partial object of the guild this invite belongs to.
Will be None for group DM invites and when attached to a gateway event;
for invites received over the gateway you should refer to guild_id.
property guild_id : Optional[snowflakes.Snowflake]The ID of the guild this invite belongs to.
Will be None for group DM invites.
property inviter : Optional[users.User]The object of the user who created this invite.
property is_temporary : boolWhether this invite grants temporary membership.
property max_age : Optional[datetime.timedelta]The timedelta of how long this invite will be valid for.
If set to None then this is unlimited.
property max_uses : Optional[int]The limit for how many times this invite can be used before it expires.
If set to None then this is unlimited.
property target_application : Optional[applications.InviteApplication]The embedded application this invite targets, if applicable.
property target_type : Union[TargetType, int, None]The type of the target of this invite, if applicable.
property target_user : Optional[users.User]The object of the user who this invite targets, if set.
class TargetType (
value: Any,
): ...The target of the invite.
class TargetType(int, enums.Enum):
"""The target of the invite."""
STREAM = 1
"""This invite is targeting a "Go Live" stream."""
EMBEDDED_APPLICATION = 2
"""This invite is targeting an embedded application."""int([x]) -> integer int(x, base=10) -> integer …
Clone of Python's enum.Enum implementation …
property valueReturn the value of the enum member.
const EMBEDDED_APPLICATION = 2This invite is targeting an embedded application.
const STREAM = 1This invite is targeting a "Go Live" stream.
class VanityURL (
*,
app: traits.RESTAware,
code: str,
uses: int,
): ...A special case invite object, that represents a guild's vanity url.
Method generated by attrs for class VanityURL.
class VanityURL(InviteCode):
"""A special case invite object, that represents a guild's vanity url."""
app: traits.RESTAware = attr.field(
repr=False, eq=False, hash=False, metadata={attr_extensions.SKIP_DEEP_COPY: True}
)
"""The client application that models may use for procedures."""
code: str = attr.field(hash=True, repr=True)
"""The code for this invite."""
uses: int = attr.field(eq=False, hash=False, repr=True)
"""The amount of times this invite has been used."""A representation of a guild/channel invite.
Helper class that provides a standard way to create an ABC using inheritance.
property app : traits.RESTAwareThe client application that models may use for procedures.