hikari/templates.py
# -*- 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 guild templates on Discord."""
from __future__ import annotations
__all__: typing.Sequence[str] = ("Template", "TemplateGuild", "TemplateRole")
import typing
import attrs
from hikari import guilds
from hikari import undefined
from hikari.internal import attrs_extensions
if typing.TYPE_CHECKING:
import datetime
from hikari import channels as channels_
from hikari import colors
from hikari import permissions as permissions_
from hikari import snowflakes
from hikari import traits
from hikari import users
@attrs_extensions.with_copy
@attrs.define(hash=True, kw_only=True, weakref_slot=False)
class TemplateRole(guilds.PartialRole):
"""The partial role object attached to [`hikari.templates.Template`][]."""
permissions: permissions_.Permissions = attrs.field(eq=False, hash=False, repr=False)
"""The guild wide permissions this role gives to the members it's attached to.
This may be overridden by channel overwrites.
"""
color: colors.Color = attrs.field(eq=False, hash=False, repr=True)
"""The colour of this role.
This will be applied to a member's name in chat if it's their top coloured role.
"""
is_hoisted: bool = attrs.field(eq=False, hash=False, repr=True)
"""Whether this role is hoisting the members it's attached to in the member list.
members will be hoisted under their highest role where this is set to [`True`][].
"""
is_mentionable: bool = attrs.field(eq=False, hash=False, repr=False)
"""Whether this role can be mentioned by all regardless of permissions."""
@attrs_extensions.with_copy
@attrs.define(hash=True, kw_only=True, weakref_slot=False)
class TemplateGuild(guilds.PartialGuild):
"""The partial guild object attached to [`hikari.templates.Template`][]."""
description: typing.Optional[str] = attrs.field(eq=False, hash=False, repr=False)
"""The guild's description, if set."""
verification_level: typing.Union[guilds.GuildVerificationLevel, int] = attrs.field(eq=False, hash=False, repr=False)
"""The verification level needed for a user to participate in this guild."""
default_message_notifications: typing.Union[guilds.GuildMessageNotificationsLevel, int] = attrs.field(
eq=False, hash=False, repr=False
)
"""The default setting for message notifications in this guild."""
explicit_content_filter: typing.Union[guilds.GuildExplicitContentFilterLevel, int] = attrs.field(
eq=False, hash=False, repr=False
)
"""The setting for the explicit content filter in this guild."""
preferred_locale: str = attrs.field(eq=False, hash=False, repr=False)
"""The preferred locale to use for this guild.
This can only be change if [`hikari.guilds.GuildFeature.COMMUNITY`][] is in [`hikari.guilds.Guild.features`][]
for this guild and will otherwise default to `en-US`.
"""
afk_timeout: datetime.timedelta = attrs.field(eq=False, hash=False, repr=False)
"""Timeout for activity before a member is classed as AFK.
How long a voice user has to be AFK for before they are classed as being
AFK and are moved to the AFK channel ([`hikari.guilds.Guild.afk_channel_id`][]).
"""
roles: typing.Mapping[snowflakes.Snowflake, TemplateRole] = attrs.field(eq=False, hash=False, repr=False)
"""The roles in the guild.
!!! note
[`hikari.guilds.Role.id`][] will be a unique placeholder on all the role
objects found attached this template guild.
"""
channels: typing.Mapping[snowflakes.Snowflake, channels_.GuildChannel] = attrs.field(
eq=False, hash=False, repr=False
)
"""The channels for the guild.
!!! note
[`hikari.channels.GuildChannel.id`][] will be a unique placeholder on all
the channel objects found attached this template guild.
"""
afk_channel_id: typing.Optional[snowflakes.Snowflake] = attrs.field(eq=False, hash=False, repr=False)
"""The ID for the channel that AFK voice users get sent to.
If [`None`][], then no AFK channel is set up for this guild.
"""
system_channel_id: typing.Optional[snowflakes.Snowflake] = attrs.field(eq=False, hash=False, repr=False)
"""The ID of the system channel or [`None`][] if it is not enabled.
Welcome messages and Nitro boost messages may be sent to this channel.
"""
system_channel_flags: guilds.GuildSystemChannelFlag = attrs.field(eq=False, hash=False, repr=False)
"""Return flags for the guild system channel.
These are used to describe which notifications are suppressed.
"""
@attrs_extensions.with_copy
@attrs.define(hash=True, kw_only=True, weakref_slot=False)
class Template:
"""Represents a template used for creating guilds."""
app: traits.RESTAware = attrs.field(
repr=False, eq=False, hash=False, metadata={attrs_extensions.SKIP_DEEP_COPY: True}
)
"""Client application that models may use for procedures."""
code: str = attrs.field(hash=True, repr=True)
"""The template's unique ID."""
name: str = attrs.field(eq=False, hash=False, repr=True)
"""The template's name."""
description: typing.Optional[str] = attrs.field(eq=False, hash=False, repr=False)
"""The template's description."""
usage_count: int = attrs.field(eq=False, hash=False, repr=True)
"""The number of times the template has been used to create a guild."""
creator: users.User = attrs.field(eq=False, hash=False, repr=False)
"""The user who created the template."""
created_at: datetime.datetime = attrs.field(eq=False, hash=False, repr=True)
"""When the template was created."""
updated_at: datetime.datetime = attrs.field(eq=False, hash=False, repr=True)
"""When the template was last synced with the source guild."""
source_guild: TemplateGuild = attrs.field(eq=False, hash=False, repr=True)
"""The partial object of the guild this template is based on."""
is_unsynced: bool = attrs.field(eq=False, hash=False, repr=False)
"""Whether this template is missing changes from it's source guild."""
async def fetch_self(self) -> Template:
"""Fetch an up-to-date view of this template from the API.
Returns
-------
hikari.templates.Template
An up-to-date view of this template.
Raises
------
hikari.errors.UnauthorizedError
If you are unauthorized to make the request (invalid/missing token).
hikari.errors.NotFoundError
If the template is not found.
hikari.errors.RateLimitTooLongError
Raised in the event that a rate limit occurs that is
longer than `max_rate_limit` when making a request.
hikari.errors.InternalServerError
If an internal error occurs on Discord while handling the request.
"""
return await self.app.rest.fetch_template(self.code)
async def edit(
self,
*,
name: undefined.UndefinedOr[str] = undefined.UNDEFINED,
description: undefined.UndefinedNoneOr[str] = undefined.UNDEFINED,
) -> Template:
"""Modify a guild template.
Parameters
----------
name
The name to set for this template.
description
The description to set for the template.
Returns
-------
hikari.templates.Template
The object of the edited template.
Raises
------
hikari.errors.ForbiddenError
If you are not part of the guild.
hikari.errors.NotFoundError
If the guild is not found or you are missing the [`hikari.permissions.Permissions.MANAGE_GUILD`][] permission.
hikari.errors.UnauthorizedError
If you are unauthorized to make the request (invalid/missing token).
hikari.errors.RateLimitTooLongError
Raised in the event that a rate limit occurs that is longer than max_rate_limit when making a request.
hikari.errors.InternalServerError
If an internal error occurs on Discord while handling the request.
"""
return await self.app.rest.edit_template(self.source_guild, self, name=name, description=description)
async def delete(self) -> None:
"""Delete a guild template.
Raises
------
hikari.errors.ForbiddenError
If you are not part of the guild.
hikari.errors.NotFoundError
If the guild is not found or you are missing the [`hikari.permissions.Permissions.MANAGE_GUILD`][] permission.
hikari.errors.UnauthorizedError
If you are unauthorized to make the request (invalid/missing token).
hikari.errors.RateLimitTooLongError
Raised in the event that a rate limit occurs that is longer than max_rate_limit when making a request.
hikari.errors.InternalServerError
If an internal error occurs on Discord while handling the request.
"""
await self.app.rest.delete_template(self.source_guild, self)
async def sync(self) -> Template:
"""Sync a guild template.
Returns
-------
hikari.templates.Template
The object of the synced template.
Raises
------
hikari.errors.ForbiddenError
If you are not part of the guild or are missing the [`hikari.permissions.Permissions.MANAGE_GUILD`][] permission.
hikari.errors.NotFoundError
If the guild or template is not found.
hikari.errors.UnauthorizedError
If you are unauthorized to make the request (invalid/missing token).
hikari.errors.RateLimitTooLongError
Raised in the event that a rate limit occurs that is longer than max_rate_limit when making a request.
hikari.errors.InternalServerError
If an internal error occurs on Discord while handling the request.
"""
return await self.app.rest.sync_guild_template(self.source_guild.id, self.code)
async def create_guild(self, name: str, *, icon: undefined.UndefinedOr[str]) -> guilds.RESTGuild:
"""Make a guild from a template.
!!! note
This endpoint can only be used by bots in less than 10 guilds.
Parameters
----------
name
The new guilds name.
icon
If provided, the guild icon to set.
Must be a 1024x1024 image or can be an animated gif when the guild has the ANIMATED_ICON feature.
Returns
-------
hikari.guilds.RESTGuild
Object of the created guild.
Raises
------
hikari.errors.BadRequestError
If any of the fields that are passed have an invalid value or if you call this as a bot that’s in more than 10 guilds.
hikari.errors.UnauthorizedError
If you are unauthorized to make the request (invalid/missing token).
hikari.errors.RateLimitTooLongError
Raised in the event that a rate limit occurs that is longer than max_rate_limit when making a request.
hikari.errors.InternalServerError
If an internal error occurs on Discord while handling the request.
"""
return await self.app.rest.create_guild_from_template(self, name, icon=icon)
def __str__(self) -> str:
return f"https://discord.new/{self.code}"