Application and entities that are used to describe invites on Discord.

This module

Expand source code
Browse git
# -*- 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

Classes

dataclass Invite

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[TargetTypeintNone],
    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.

Expand source code
Browse git
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`.
    """
Subclasses
dataclass InviteWithMetadata

Extends the base Invite object with metadata …

Method resolution order
dataclass Invite
That's this class!
abstract trait class InviteCode

A representation of a guild/channel invite.

extern class abc.ABC

Helper class that provides a standard way to create an ABC using inheritance.

Variables and properties
property apptraits.RESTAware

The client application that models may use for procedures.

property approximate_active_member_countOptional[int]

The approximate amount of presences in this invite's guild.

This is only returned by the GET REST Invites endpoint.

property approximate_member_countOptional[int]

The approximate amount of members in this invite's guild.

This is only returned by the GET Invites REST endpoint.

property channelOptional[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_idsnowflakes.Snowflake

The ID of the channel this invite targets.

property codestr

The code for this invite.

property expires_atOptional[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 guildOptional[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_idOptional[snowflakes.Snowflake]

The ID of the guild this invite belongs to.

Will be None for group DM invites.

property inviterOptional[users.User]

The object of the user who created this invite.

property target_applicationOptional[applications.InviteApplication]

The embedded application this invite targets, if applicable.

property target_typeUnion[TargetType, int, None]

The type of the target of this invite, if applicable.

property target_userOptional[users.User]

The object of the user who this invite targets, if set.

class InviteCode

class InviteCode: ...

A representation of a guild/channel invite.

Expand source code
Browse git
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}"
Subclasses
dataclass Invite

Represents an invite that's used to add users to a guild or group dm …

dataclass VanityURL

A special case invite object, that represents a guild's vanity url …

Method resolution order
abstract trait class InviteCode
That's this class!
extern class abc.ABC

Helper class that provides a standard way to create an ABC using inheritance.

Variables and properties
abstract property codestr

Return the code for this invite.

Returns

str
The invite code that can be appended to a URL.

dataclass InviteGuild

class InviteGuild (
    *,
    app: traits.RESTAware,
    id: snowflakes.Snowflake,
    icon_hash: Optional[str],
    name: str,
    features: Sequence[Union[guilds.GuildFeatureint]],
    splash_hash: Optional[str],
    banner_hash: Optional[str],
    description: Optional[str],
    verification_level: Union[guilds.GuildVerificationLevelint],
    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.

Expand source code
Browse git
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,
        )
Method resolution order
dataclass InviteGuild
That's this class!
dataclass PartialGuild

Base object for any partial guild objects …

abstract class Unique

Mixin for a class that enforces uniqueness by a snowflake ID.

extern class abc.ABC

Helper class that provides a standard way to create an ABC using inheritance.

Variables and properties
property appRESTAware

The client application that models may use for procedures.

property banner_hash : Optional[str]

The hash for the guild's banner.

This is only present if BANNER is in the features for this guild. For all other purposes, it is None.

property banner_urlOptional[files.URL]

Banner URL for the guild, if set.

property created_atdatetime.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[GuildFeatureint]]

A list of the features in this guild.

property icon_hash : Optional[str]

The hash for the guild icon, if there is one.

property icon_urlOptional[files.URL]

Icon URL for the guild, if set; otherwise None.

property idSnowflake

The ID of this entity.

property namestr

The name of the guild.

property nsfw_levelGuildNSFWLevel

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_urlOptional[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[GuildVerificationLevelint]

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.

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

Parameters

user : Snowflakeish[PartialUser]
The user to ban from the guild

Other Parameters

delete_message_days : UndefinedNoneOr[int]
If provided, the number of days to delete messages for. This must be between 0 and 7.
reason : UndefinedOr[str]
If provided, the reason that will be recorded in the audit logs. Maximum of 512 characters.

Raises

BadRequestError
If any of the fields that are passed have an invalid value.
ForbiddenError
If you are missing the BAN_MEMBERS permission.
UnauthorizedError
If you are unauthorized to make the request (invalid/missing token).
NotFoundError
If the guild or user are not found.
RateLimitTooLongError
Raised in the event that a rate limit occurs that is longer than max_rate_limit when making a request.
RateLimitedError
Usually, Hikari will handle and retry on hitting rate-limits automatically. This includes most bucket-specific rate-limits and global rate-limits. In some rare edge cases, however, Discord implements other undocumented rules for rate-limiting, such as limits per attribute. These cannot be detected or handled normally by Hikari due to their undocumented nature, and will trigger this exception if they occur.
InternalServerError
If an internal error occurs on Discord while handling the request.
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.

Parameters

name : str
The channels name. Must be between 2 and 1000 characters.

Other Parameters

position : UndefinedOr[int]
If provided, the position of the category.
permission_overwrites : UndefinedOr[Sequence[PermissionOverwrite]]
If provided, the permission overwrites for the category.
reason : UndefinedOr[str]
If provided, the reason that will be recorded in the audit logs. Maximum of 512 characters.

Returns

GuildCategory
The created category.

Raises

BadRequestError
If any of the fields that are passed have an invalid value.
ForbiddenError
If you are missing the MANAGE_CHANNEL permission.
UnauthorizedError
If you are unauthorized to make the request (invalid/missing token).
NotFoundError
If the guild is not found.
RateLimitTooLongError
Raised in the event that a rate limit occurs that is longer than max_rate_limit when making a request.
RateLimitedError
Usually, Hikari will handle and retry on hitting rate-limits automatically. This includes most bucket-specific rate-limits and global rate-limits. In some rare edge cases, however, Discord implements other undocumented rules for rate-limiting, such as limits per attribute. These cannot be detected or handled normally by Hikari due to their undocumented nature, and will trigger this exception if they occur.
InternalServerError
If an internal error occurs on Discord while handling the request.
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.

Parameters

name : str
The channels name. Must be between 2 and 1000 characters.

Other Parameters

position : UndefinedOr[int]
If provided, the position of the channel (relative to the category, if any).
topic : UndefinedOr[str]
If provided, the channels topic. Maximum 1024 characters.
nsfw : UndefinedOr[bool]
If provided, whether to mark the channel as NSFW.
rate_limit_per_user : UndefinedOr[Intervalish]
If provided, the amount of seconds a user has to wait before being able to send another message in the channel. Maximum 21600 seconds.
permission_overwrites : UndefinedOr[Sequence[PermissionOverwrite]]
If provided, the permission overwrites for the channel.
category : UndefinedOr[SnowflakeishOr[GuildCategory]]
The category to create the channel under. This may be the object or the ID of an existing category.
reason : UndefinedOr[str]
If provided, the reason that will be recorded in the audit logs. Maximum of 512 characters.

Returns

GuildNewsChannel
The created channel.

Raises

BadRequestError
If any of the fields that are passed have an invalid value.
ForbiddenError
If you are missing the MANAGE_CHANNEL permission.
UnauthorizedError
If you are unauthorized to make the request (invalid/missing token).
NotFoundError
If the guild is not found.
RateLimitTooLongError
Raised in the event that a rate limit occurs that is longer than max_rate_limit when making a request.
RateLimitedError
Usually, Hikari will handle and retry on hitting rate-limits automatically. This includes most bucket-specific rate-limits and global rate-limits. In some rare edge cases, however, Discord implements other undocumented rules for rate-limiting, such as limits per attribute. These cannot be detected or handled normally by Hikari due to their undocumented nature, and will trigger this exception if they occur.
InternalServerError
If an internal error occurs on Discord while handling the request.
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.

Parameters

name : str
The channel's name. Must be between 2 and 1000 characters.

Other Parameters

position : UndefinedOr[int]
If provided, the position of the channel (relative to the category, if any).
user_limit : UndefinedOr[int]
If provided, the maximum users in the channel at once. Must be between 0 and 99 with 0 meaning no limit.
bitrate : UndefinedOr[int]
If provided, the bitrate for the channel. Must be between 8000 and 96000 or 8000 and 128000 for VIP servers.
permission_overwrites : UndefinedOr[Sequence[PermissionOverwrite]]
If provided, the permission overwrites for the channel.
region : UndefinedOr[Union[VoiceRegion, str]]
If provided, the voice region to for this channel. Passing 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]]
The category to create the channel under. This may be the object or the ID of an existing category.
reason : UndefinedOr[str]
If provided, the reason that will be recorded in the audit logs. Maximum of 512 characters.

Returns

GuildStageChannel
The created channel.

Raises

BadRequestError
If any of the fields that are passed have an invalid value.
ForbiddenError
If you are missing the MANAGE_CHANNEL permission.
UnauthorizedError
If you are unauthorized to make the request (invalid/missing token).
NotFoundError
If the guild is not found.
RateLimitTooLongError
Raised in the event that a rate limit occurs that is longer than max_rate_limit when making a request.
RateLimitedError
Usually, Hikari will handle and retry on hitting rate-limits automatically. This includes most bucket-specific rate-limits and global rate-limits. In some rare edge cases, however, Discord implements other undocumented rules for rate-limiting, such as limits per attribute. These cannot be detected or handled normally by Hikari due to their undocumented nature, and will trigger this exception if they occur.
InternalServerError
If an internal error occurs on Discord while handling the request.
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.

Parameters

name : str
The name for the sticker.
tag : str
The tag for the sticker.
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.

Other Parameters

description : UndefinedOr[str]
If provided, the description of the sticker.
reason : UndefinedOr[str]
If provided, the reason that will be recorded in the audit logs. Maximum of 512 characters.

Returns

GuildSticker
The created sticker.

Raises

BadRequestError
If any of the fields that are passed have an invalid value or if there are no more spaces for the sticker in the guild.
ForbiddenError
If you are missing MANAGE_EMOJIS_AND_STICKERS in the server.
NotFoundError
If the guild is not found.
UnauthorizedError
If you are unauthorized to make the request (invalid/missing token).
RateLimitTooLongError
Raised in the event that a rate limit occurs that is longer than max_rate_limit when making a request.
RateLimitedError
Usually, Hikari will handle and retry on hitting rate-limits automatically. This includes most bucket-specific rate-limits and global rate-limits. In some rare edge cases, however, Discord implements other undocumented rules for rate-limiting, such as limits per attribute. These cannot be detected or handled normally by Hikari due to their undocumented nature, and will trigger this exception if they occur.
InternalServerError
If an internal error occurs on Discord while handling the request.
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.

Parameters

name : str
The channels name. Must be between 2 and 1000 characters.

Other Parameters

position : UndefinedOr[int]
If provided, the position of the channel (relative to the category, if any).
topic : UndefinedOr[str]
If provided, the channels topic. Maximum 1024 characters.
nsfw : UndefinedOr[bool]
If provided, whether to mark the channel as NSFW.
rate_limit_per_user : UndefinedOr[Intervalish]
If provided, the amount of seconds a user has to wait before being able to send another message in the channel. Maximum 21600 seconds.
permission_overwrites : UndefinedOr[Sequence[PermissionOverwrite]]
If provided, the permission overwrites for the channel.
category : UndefinedOr[SnowflakeishOr[GuildCategory]]
The category to create the channel under. This may be the object or the ID of an existing category.
reason : UndefinedOr[str]
If provided, the reason that will be recorded in the audit logs. Maximum of 512 characters.

Returns

GuildTextChannel
The created channel.

Raises

BadRequestError
If any of the fields that are passed have an invalid value.
ForbiddenError
If you are missing the MANAGE_CHANNEL permission.
UnauthorizedError
If you are unauthorized to make the request (invalid/missing token).
NotFoundError
If the guild is not found.
RateLimitTooLongError
Raised in the event that a rate limit occurs that is longer than max_rate_limit when making a request.
RateLimitedError
Usually, Hikari will handle and retry on hitting rate-limits automatically. This includes most bucket-specific rate-limits and global rate-limits. In some rare edge cases, however, Discord implements other undocumented rules for rate-limiting, such as limits per attribute. These cannot be detected or handled normally by Hikari due to their undocumented nature, and will trigger this exception if they occur.
InternalServerError
If an internal error occurs on Discord while handling the request.
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.

Parameters

guild : SnowflakeishOr[PartialGuild]
The guild to create the channel in. This may be the object or the ID of an existing guild.
name : str
The channels name. Must be between 2 and 1000 characters.

Other Parameters

position : UndefinedOr[int]
If provided, the position of the channel (relative to the category, if any).
user_limit : UndefinedOr[int]
If provided, the maximum users in the channel at once. Must be between 0 and 99 with 0 meaning no limit.
bitrate : UndefinedOr[int]
If provided, the bitrate for the channel. Must be between 8000 and 96000 or 8000 and 128000 for VIP servers.
video_quality_mode : UndefinedOr[Union[VideoQualityMode, int]]
If provided, the new video quality mode for the channel.
permission_overwrites : UndefinedOr[Sequence[PermissionOverwrite]]
If provided, the permission overwrites for the channel.
region : UndefinedOr[Union[VoiceRegion, str]]
If provided, the voice region to for this channel. Passing 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]]
The category to create the channel under. This may be the object or the ID of an existing category.
reason : UndefinedOr[str]
If provided, the reason that will be recorded in the audit logs. Maximum of 512 characters.

Returns

GuildVoiceChannel
The created channel.

Raises

BadRequestError
If any of the fields that are passed have an invalid value.
ForbiddenError
If you are missing the MANAGE_CHANNEL permission.
UnauthorizedError
If you are unauthorized to make the request (invalid/missing token).
NotFoundError
If the gui ld is not found.
RateLimitTooLongError
Raised in the event that a rate limit occurs that is longer than max_rate_limit when making a request.
RateLimitedError
Usually, Hikari will handle and retry on hitting rate-limits automatically. This includes most bucket-specific rate-limits and global rate-limits. In some rare edge cases, however, Discord implements other undocumented rules for rate-limiting, such as limits per attribute. These cannot be detected or handled normally by Hikari due to their undocumented nature, and will trigger this exception if they occur.
InternalServerError
If an internal error occurs on Discord while handling the request.
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.

Parameters

channel : SnowflakeishOr[GuildChannel]
The channel or category to delete. This may be the object or the ID of an existing channel.

Returns

GuildChannel
Object of the channel or category that was deleted.

Raises

hikari.errors.UnauthorizedError, or close a DM.
If you are unauthorized to make the request (invalid/missing token).
ForbiddenError
If you are missing the MANAGE_CHANNEL permission in the channel.
NotFoundError
If the channel is not found.
RateLimitTooLongError
Raised in the event that a rate limit occurs that is longer than max_rate_limit when making a request.
RateLimitedError
Usually, Hikari will handle and retry on hitting rate-limits automatically. This includes most bucket-specific rate-limits and global rate-limits. In some rare edge cases, however, Discord implements other undocumented rules for rate-limiting, such as limits per attribute. These cannot be detected or handled normally by Hikari due to their undocumented nature, and will trigger this exception if they occur.
InternalServerError
If an internal error occurs on Discord while handling the request.

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.

Parameters

sticker : SnowflakeishOr[PartialSticker]
The sticker to delete. This can be a sticker object or the ID of an existing sticker.

Other Parameters

reason : UndefinedOr[str]
If provided, the reason that will be recorded in the audit logs. Maximum of 512 characters.

Raises

ForbiddenError
If you are missing MANAGE_EMOJIS_AND_STICKERS in the server.
NotFoundError
If the guild or the sticker are not found.
UnauthorizedError
If you are unauthorized to make the request (invalid/missing token).
RateLimitTooLongError
Raised in the event that a rate limit occurs that is longer than max_rate_limit when making a request.
RateLimitedError
Usually, Hikari will handle and retry on hitting rate-limits automatically. This includes most bucket-specific rate-limits and global rate-limits. In some rare edge cases, however, Discord implements other undocumented rules for rate-limiting, such as limits per attribute. These cannot be detected or handled normally by Hikari due to their undocumented nature, and will trigger this exception if they occur.
InternalServerError
If an internal error occurs on Discord while handling the request.
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.

Parameters

name : UndefinedOr[str]
If provided, the new name for the guild.
verification_level : UndefinedOr[GuildVerificationLevel]
If provided, the new verification level.
default_message_notifications : UndefinedOr[GuildMessageNotificationsLevel]
If provided, the new default message notifications level.
explicit_content_filter_level : UndefinedOr[GuildExplicitContentFilterLevel]
If provided, the new explicit content filter level.
afk_channel : UndefinedOr[SnowflakeishOr[GuildVoiceChannel]]
If provided, the new afk channel. Requires afk_timeout to be set to work.
afk_timeout : UndefinedOr[Intervalish]
If provided, the new afk timeout.
icon : UndefinedOr[Resourceish]
If provided, the new guild icon. Must be a 1024x1024 image or can be an animated gif when the guild has the 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]
If provided, the new guild splash. Must be a 16:9 image and the guild must have the INVITE_SPLASH feature.
banner : UndefinedNoneOr[Resourceish]
If provided, the new guild banner. Must be a 16:9 image and the guild must have the BANNER feature.
system_channel : UndefinedNoneOr[SnowflakeishOr[GuildTextChannel]]
If provided, the new system channel.
rules_channel : UndefinedNoneOr[SnowflakeishOr[GuildTextChannel]]
If provided, the new rules channel.
public_updates_channel : UndefinedNoneOr[SnowflakeishOr[GuildTextChannel]]
If provided, the new public updates channel.
preferred_locale : UndefinedNoneOr[str]
If provided, the new preferred locale.
reason : UndefinedOr[str]
If provided, the reason that will be recorded in the audit logs. Maximum of 512 characters.

Returns

RESTGuild
The edited guild.

Raises

BadRequestError
If any of the fields that are passed have an invalid value. Or you are missing the
ForbiddenError
If you are missing the MANAGE_GUILD permission or if you tried to pass ownership without being the server owner.
UnauthorizedError
If you are unauthorized to make the request (invalid/missing token).
NotFoundError
If the guild is not found.
RateLimitTooLongError
Raised in the event that a rate limit occurs that is longer than max_rate_limit when making a request.
RateLimitedError
Usually, Hikari will handle and retry on hitting rate-limits automatically. This includes most bucket-specific rate-limits and global rate-limits. In some rare edge cases, however, Discord implements other undocumented rules for rate-limiting, such as limits per attribute. These cannot be detected or handled normally by Hikari due to their undocumented nature, and will trigger this exception if they occur.
InternalServerError
If an internal error occurs on Discord while handling the request.
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.

Parameters

sticker : SnowflakeishOr[PartialSticker]
The sticker to edit. This can be a sticker object or the ID of an existing sticker.

Other Parameters

name : UndefinedOr[str]
If provided, the new name for the sticker.
description : UndefinedOr[str]
If provided, the new description for the sticker.
tag : UndefinedOr[str]
If provided, the new sticker tag.
reason : UndefinedOr[str]
If provided, the reason that will be recorded in the audit logs. Maximum of 512 characters.

Returns

GuildSticker
The edited sticker.

Raises

BadRequestError
If any of the fields that are passed have an invalid value.
ForbiddenError
If you are missing MANAGE_EMOJIS_AND_STICKERS in the server.
NotFoundError
If the guild or the sticker are not found.
UnauthorizedError
If you are unauthorized to make the request (invalid/missing token).
RateLimitTooLongError
Raised in the event that a rate limit occurs that is longer than max_rate_limit when making a request.
RateLimitedError
Usually, Hikari will handle and retry on hitting rate-limits automatically. This includes most bucket-specific rate-limits and global rate-limits. In some rare edge cases, however, Discord implements other undocumented rules for rate-limiting, such as limits per attribute. These cannot be detected or handled normally by Hikari due to their undocumented nature, and will trigger this exception if they occur.
InternalServerError
If an internal error occurs on Discord while handling the request.
async def fetch_emoji(
    emoji: snowflakes.SnowflakeishOr[emojis_.CustomEmoji],
) -> emojis_.KnownCustomEmoji: ...

Inherited from: PartialGuild.fetch_emoji

Fetch an emoji from the guild.

Parameters

emoji : SnowflakeishOr[CustomEmoji]
The emoji to fetch. This can be a CustomEmoji or the ID of an existing emoji.

Returns

KnownCustomEmoji
The requested emoji.

Raises

NotFoundError
If the guild or the emoji are not found.
UnauthorizedError
If you are unauthorized to make the request (invalid/missing token).
RateLimitTooLongError
Raised in the event that a rate limit occurs that is longer than max_rate_limit when making a request.
RateLimitedError
Usually, Hikari will handle and retry on hitting rate-limits automatically. This includes most bucket-specific rate-limits and global rate-limits. In some rare edge cases, however, Discord implements other undocumented rules for rate-limiting, such as limits per attribute. These cannot be detected or handled normally by Hikari due to their undocumented nature, and will trigger this exception if they occur.
InternalServerError
If an internal error occurs on Discord while handling the request.
async def fetch_emojis() -> Sequence[emojis_.KnownCustomEmoji]: ...

Inherited from: PartialGuild.fetch_emojis

Fetch the emojis of the guild.

Returns

Sequence[KnownCustomEmoji]
The requested emojis.

Raises

NotFoundError
If the guild is not found.
UnauthorizedError
If you are unauthorized to make the request (invalid/missing token).
RateLimitTooLongError
Raised in the event that a rate limit occurs that is longer than max_rate_limit when making a request.
RateLimitedError
Usually, Hikari will handle and retry on hitting rate-limits automatically. This includes most bucket-specific rate-limits and global rate-limits. In some rare edge cases, however, Discord implements other undocumented rules for rate-limiting, such as limits per attribute. These cannot be detected or handled normally by Hikari due to their undocumented nature, and will trigger this exception if they occur.
InternalServerError
If an internal error occurs on Discord while handling the request.
async def fetch_roles() -> Sequence[Role]: ...

Inherited from: PartialGuild.fetch_roles

Fetch the roles of the guild.

Returns

Sequence[Role]
The requested roles.

Raises

UnauthorizedError
If you are unauthorized to make the request (invalid/missing token). hikari.errors.NotFoundError If the guild is not found.
RateLimitTooLongError
Raised in the event that a rate limit occurs that is longer than max_rate_limit when making a request.
RateLimitedError
Usually, Hikari will handle and retry on hitting rate-limits automatically. This includes most bucket-specific rate-limits and global rate-limits. In some rare edge cases, however, Discord implements other undocumented rules for rate-limiting, such as limits per attribute. These cannot be detected or handled normally by Hikari due to their undocumented nature, and will trigger this exception if they occur.
InternalServerError
If an internal error occurs on Discord while handling the request.
async def fetch_self() -> RESTGuild: ...

Inherited from: PartialGuild.fetch_self

Fetch the guild.

Returns

RESTGuild
The requested guild.

Raises

ForbiddenError
If you are not part of the guild.
NotFoundError
If the guild is not found.
UnauthorizedError
If you are unauthorized to make the request (invalid/missing token).
RateLimitTooLongError
Raised in the event that a rate limit occurs that is longer than max_rate_limit when making a request.
RateLimitedError
Usually, Hikari will handle and retry on hitting rate-limits automatically. This includes most bucket-specific rate-limits and global rate-limits. In some rare edge cases, however, Discord implements other undocumented rules for rate-limiting, such as limits per attribute. These cannot be detected or handled normally by Hikari due to their undocumented nature, and will trigger this exception if they occur.
InternalServerError
If an internal error occurs on Discord while handling the request.
async def fetch_sticker(
    sticker: snowflakes.SnowflakeishOr[stickers.PartialSticker],
) -> GuildSticker: ...

Inherited from: PartialGuild.fetch_sticker

Fetch a sticker from the guild.

Parameters

sticker : snowflakes.SnowflakeishOr[PartialSticker]
The sticker to fetch. This can be a sticker object or the ID of an existing sticker.

Returns

GuildSticker
The requested sticker.

Raises

ForbiddenError
If you are not part of the server.
NotFoundError
If the guild or the sticker are not found.
UnauthorizedError
If you are unauthorized to make the request (invalid/missing token).
RateLimitTooLongError
Raised in the event that a rate limit occurs that is longer than max_rate_limit when making a request.
RateLimitedError
Usually, Hikari will handle and retry on hitting rate-limits automatically. This includes most bucket-specific rate-limits and global rate-limits. In some rare edge cases, however, Discord implements other undocumented rules for rate-limiting, such as limits per attribute. These cannot be detected or handled normally by Hikari due to their undocumented nature, and will trigger this exception if they occur.
InternalServerError
If an internal error occurs on Discord while handling the request.
async def fetch_stickers() -> Sequence[GuildSticker]: ...

Inherited from: PartialGuild.fetch_stickers

Fetch the stickers of the guild.

Returns

Sequence[GuildSticker]
The requested stickers.

Raises

ForbiddenError
If you are not part of the server.
NotFoundError
If the guild is not found.
UnauthorizedError
If you are unauthorized to make the request (invalid/missing token).
RateLimitTooLongError
Raised in the event that a rate limit occurs that is longer than max_rate_limit when making a request.
RateLimitedError
Usually, Hikari will handle and retry on hitting rate-limits automatically. This includes most bucket-specific rate-limits and global rate-limits. In some rare edge cases, however, Discord implements other undocumented rules for rate-limiting, such as limits per attribute. These cannot be detected or handled normally by Hikari due to their undocumented nature, and will trigger this exception if they occur.
InternalServerError
If an internal error occurs on Discord while handling the request.
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.

Parameters

user : Snowflakeish[PartialUser]
The user to kick from the guild

Other Parameters

reason : UndefinedOr[str]
If provided, the reason that will be recorded in the audit logs. Maximum of 512 characters.

Raises

BadRequestError
If any of the fields that are passed have an invalid value.
ForbiddenError
If you are missing the KICK_MEMBERS permission.
UnauthorizedError
If you are unauthorized to make the request (invalid/missing token).
NotFoundError
If the guild or user are not found.
RateLimitTooLongError
Raised in the event that a rate limit occurs that is longer than max_rate_limit when making a request.
RateLimitedError
Usually, Hikari will handle and retry on hitting rate-limits automatically. This includes most bucket-specific rate-limits and global rate-limits. In some rare edge cases, however, Discord implements other undocumented rules for rate-limiting, such as limits per attribute. These cannot be detected or handled normally by Hikari due to their undocumented nature, and will trigger this exception if they occur.
InternalServerError
If an internal error occurs on Discord while handling the request.
def make_banner_url(
    *,
    ext: str = 'png',
    size: int = 4096,
) -> Optional[files.URL]: ...

Generate the guild's banner image URL, if set.

Parameters

ext : str
The extension to use for this URL, defaults to png. Supports png, jpeg, jpg and webp.
size : int
The size to set for the URL, defaults to 4096. Can be any power of two between 16 and 4096.

Returns

Optional[URL]
The URL of the banner, or None if no banner is set.

Raises

ValueError
If size is not a power of two or not between 16 and 4096.
Expand source code
Browse git
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,
    )
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.

Parameters

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
The size to set for the URL, defaults to 4096. Can be any power of two between 16 and 4096.

Returns

Optional[URL]
The URL to the resource, or None if no icon is set.

Raises

ValueError
If 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.

Parameters

ext : str
The extension to use for this URL, defaults to png. Supports png, jpeg, jpg and webp.
size : int
The size to set for the URL, defaults to 4096. Can be any power of two between 16 and 4096.

Returns

Optional[URL]
The URL to the splash, or None if not set.

Raises

ValueError
If size is not a power of two or not between 16 and 4096.
Expand source code
Browse git
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.

Parameters

user : Snowflakeish[PartialUser]
The user to unban from the guild

Other Parameters

reason : UndefinedOr[str]
If provided, the reason that will be recorded in the audit logs. Maximum of 512 characters.

Raises

BadRequestError
If any of the fields that are passed have an invalid value.
ForbiddenError
If you are missing the BAN_MEMBERS permission.
UnauthorizedError
If you are unauthorized to make the request (invalid/missing token).
NotFoundError
If the guild or user are not found.
RateLimitTooLongError
Raised in the event that a rate limit occurs that is longer than max_rate_limit when making a request.
RateLimitedError
Usually, Hikari will handle and retry on hitting rate-limits automatically. This includes most bucket-specific rate-limits and global rate-limits. In some rare edge cases, however, Discord implements other undocumented rules for rate-limiting, such as limits per attribute. These cannot be detected or handled normally by Hikari due to their undocumented nature, and will trigger this exception if they occur.
InternalServerError
If an internal error occurs on Discord while handling the request.

dataclass InviteWithMetadata

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[TargetTypeintNone],
    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.

Expand source code
Browse git
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
Method resolution order
dataclass InviteWithMetadata
That's this class!
dataclass Invite

Represents an invite that's used to add users to a guild or group dm …

abstract trait class InviteCode

A representation of a guild/channel invite.

extern class abc.ABC

Helper class that provides a standard way to create an ABC using inheritance.

Variables and properties
property apptraits.RESTAware

The client application that models may use for procedures.

property approximate_active_member_countOptional[int]

The approximate amount of presences in this invite's guild.

This is only returned by the GET REST Invites endpoint.

property approximate_member_countOptional[int]

The approximate amount of members in this invite's guild.

This is only returned by the GET Invites REST endpoint.

property channelOptional[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_idsnowflakes.Snowflake

The ID of the channel this invite targets.

property codestr

The code for this invite.

property created_atdatetime.datetime

When this invite was created.

property expires_atOptional[datetime.datetime]

When this invite will expire.

If this invite doesn't have a set expiry then this will be None.

property guildOptional[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_idOptional[snowflakes.Snowflake]

The ID of the guild this invite belongs to.

Will be None for group DM invites.

property inviterOptional[users.User]

The object of the user who created this invite.

property is_temporarybool

Whether this invite grants temporary membership.

property max_ageOptional[datetime.timedelta]

The timedelta of how long this invite will be valid for.

If set to None then this is unlimited.

property max_usesOptional[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_applicationOptional[applications.InviteApplication]

The embedded application this invite targets, if applicable.

property target_typeUnion[TargetType, int, None]

The type of the target of this invite, if applicable.

property target_userOptional[users.User]

The object of the user who this invite targets, if set.

property usesint

The amount of times this invite has been used.

property uses_left : Optional[int]

Return the number of uses left for this invite.

Returns

Optional[int]
The number of uses left for this invite. This will be None if the invite has unlimited uses.

enum TargetType

class TargetType (
    value: Any,
): ...

The target of the invite.

Expand source code
Browse git
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."""
Method resolution order
enum TargetType
That's this class!
extern class int

int([x]) -> integer int(x, base=10) -> integer …

enum Enum

Clone of Python's enum.Enum implementation …

Variables and properties
property namestr

Return the name of the enum member as a str.

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.

dataclass VanityURL

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.

Expand source code
Browse git
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."""
Method resolution order
dataclass VanityURL
That's this class!
abstract trait class InviteCode

A representation of a guild/channel invite.

extern class abc.ABC

Helper class that provides a standard way to create an ABC using inheritance.

Variables and properties
property apptraits.RESTAware

The client application that models may use for procedures.

property codestr

The code for this invite.

property usesint

The amount of times this invite has been used.