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.List[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: str = "png", size: int = 4096) -> typing.Optional[files.URL]:
"""Generate the guild's banner 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 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
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 None
class 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.RESTAware
The 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.Snowflake
The 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: str = "png", size: int = 4096) -> typing.Optional[files.URL]:
"""Generate the guild's banner 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 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
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.datetime
When 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 : GuildNSFWLevel
The 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]
BadRequestError
ForbiddenError
BAN_MEMBERS
permission.UnauthorizedError
NotFoundError
RateLimitTooLongError
max_rate_limit
when making a request.RateLimitedError
InternalServerError
async 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
: str
position
: UndefinedOr[int]
permission_overwrites
: UndefinedOr[Sequence[PermissionOverwrite]]
reason
: UndefinedOr[str]
GuildCategory
BadRequestError
ForbiddenError
MANAGE_CHANNEL
permission.UnauthorizedError
NotFoundError
RateLimitTooLongError
max_rate_limit
when making a request.RateLimitedError
InternalServerError
async 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
: str
position
: 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]
GuildNewsChannel
BadRequestError
ForbiddenError
MANAGE_CHANNEL
permission.UnauthorizedError
NotFoundError
RateLimitTooLongError
max_rate_limit
when making a request.RateLimitedError
InternalServerError
async 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
: str
position
: 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]
GuildStageChannel
BadRequestError
ForbiddenError
MANAGE_CHANNEL
permission.UnauthorizedError
NotFoundError
RateLimitTooLongError
max_rate_limit
when making a request.RateLimitedError
InternalServerError
async 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
: str
tag
: str
image
: Resourceish
The 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]
GuildSticker
BadRequestError
ForbiddenError
MANAGE_EMOJIS_AND_STICKERS
in the server.NotFoundError
UnauthorizedError
RateLimitTooLongError
max_rate_limit
when making a request.RateLimitedError
InternalServerError
async 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
: str
position
: 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]
GuildTextChannel
BadRequestError
ForbiddenError
MANAGE_CHANNEL
permission.UnauthorizedError
NotFoundError
RateLimitTooLongError
max_rate_limit
when making a request.RateLimitedError
InternalServerError
async 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
: str
position
: 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]
GuildVoiceChannel
BadRequestError
ForbiddenError
MANAGE_CHANNEL
permission.UnauthorizedError
NotFoundError
RateLimitTooLongError
max_rate_limit
when making a request.RateLimitedError
InternalServerError
async 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]
GuildChannel
ForbiddenError
MANAGE_CHANNEL
permission in the channel.NotFoundError
RateLimitTooLongError
max_rate_limit
when making a request.RateLimitedError
InternalServerError
Note
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]
ForbiddenError
MANAGE_EMOJIS_AND_STICKERS
in the server.NotFoundError
UnauthorizedError
RateLimitTooLongError
max_rate_limit
when making a request.RateLimitedError
InternalServerError
async 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]
RESTGuild
BadRequestError
ForbiddenError
MANAGE_GUILD
permission or if you tried to
pass ownership without being the server owner.UnauthorizedError
NotFoundError
RateLimitTooLongError
max_rate_limit
when making a request.RateLimitedError
InternalServerError
async 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]
GuildSticker
BadRequestError
ForbiddenError
MANAGE_EMOJIS_AND_STICKERS
in the server.NotFoundError
UnauthorizedError
RateLimitTooLongError
max_rate_limit
when making a request.RateLimitedError
InternalServerError
async 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.KnownCustomEmoji
NotFoundError
UnauthorizedError
RateLimitTooLongError
max_rate_limit
when making a request.RateLimitedError
InternalServerError
async def fetch_emojis() -> Sequence[emojis_.KnownCustomEmoji]: ...
Inherited from:
PartialGuild
.fetch_emojis
Fetch the emojis of the guild.
Sequence[KnownCustomEmoji]
NotFoundError
UnauthorizedError
RateLimitTooLongError
max_rate_limit
when making a request.RateLimitedError
InternalServerError
async def fetch_roles() -> Sequence[Role]: ...
Inherited from:
PartialGuild
.fetch_roles
Fetch the roles of the guild.
UnauthorizedError
RateLimitTooLongError
max_rate_limit
when making a request.RateLimitedError
InternalServerError
async def fetch_self() -> RESTGuild: ...
Inherited from:
PartialGuild
.fetch_self
Fetch the guild.
RESTGuild
ForbiddenError
NotFoundError
UnauthorizedError
RateLimitTooLongError
max_rate_limit
when making a request.RateLimitedError
InternalServerError
async def fetch_sticker(
sticker: snowflakes.SnowflakeishOr[stickers.PartialSticker],
) -> GuildSticker: ...
Inherited from:
PartialGuild
.fetch_sticker
Fetch a sticker from the guild.
sticker
: snowflakes.SnowflakeishOr[PartialSticker]
GuildSticker
ForbiddenError
NotFoundError
UnauthorizedError
RateLimitTooLongError
max_rate_limit
when making a request.RateLimitedError
InternalServerError
async def fetch_stickers() -> Sequence[GuildSticker]: ...
Inherited from:
PartialGuild
.fetch_stickers
Fetch the stickers of the guild.
Sequence[GuildSticker]
ForbiddenError
NotFoundError
UnauthorizedError
RateLimitTooLongError
max_rate_limit
when making a request.RateLimitedError
InternalServerError
async 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]
BadRequestError
ForbiddenError
KICK_MEMBERS
permission.UnauthorizedError
NotFoundError
RateLimitTooLongError
max_rate_limit
when making a request.RateLimitedError
InternalServerError
def 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
: int
4096
.
Can be any power of two between 16 and 4096.ValueError
size
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
: str
png
.
Supports png
, jpeg
, jpg
and webp
.size
: int
4096
.
Can be any power of two between 16 and 4096.ValueError
size
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]
BadRequestError
ForbiddenError
BAN_MEMBERS
permission.UnauthorizedError
NotFoundError
RateLimitTooLongError
max_rate_limit
when making a request.RateLimitedError
InternalServerError
class 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 None
Represents 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.RESTAware
The 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.Snowflake
The ID of the channel this invite targets.
property created_at : datetime.datetime
When 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 : bool
Whether 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 value
Return the value of the enum member.
const EMBEDDED_APPLICATION = 2
This invite is targeting an embedded application.
const STREAM = 1
This 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.RESTAware
The client application that models may use for procedures.