1+ """
2+ The MIT License (MIT)
3+
4+ Copyright (c) 2015-present Rapptz
5+
6+ Permission is hereby granted, free of charge, to any person obtaining a
7+ copy of this software and associated documentation files (the "Software"),
8+ to deal in the Software without restriction, including without limitation
9+ the rights to use, copy, modify, merge, publish, distribute, sublicense,
10+ and/or sell copies of the Software, and to permit persons to whom the
11+ Software is furnished to do so, subject to the following conditions:
12+
13+ The above copyright notice and this permission notice shall be included in
14+ all copies or substantial portions of the Software.
15+
16+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
17+ OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
21+ FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
22+ DEALINGS IN THE SOFTWARE.
23+ """
24+
25+ from __future__ import annotations
26+
27+ from typing import TYPE_CHECKING , List , Union , overload
28+ from .utils import _get_as_snowflake , get
29+ from .partial_emoji import _EmojiTag
30+
31+ if TYPE_CHECKING :
32+ from .types .welcome_screen import (
33+ WelcomeScreen as WelcomeScreenPayload ,
34+ WelcomeScreenChannel as WelcomeScreenChannelPayload ,
35+ )
36+ from .guild import Guild
37+ from .abc import Snowflake
38+ from .partial_emoji import PartialEmoji
39+ from .emoji import Emoji
40+
41+ __all__ = (
42+ 'WelcomeScreen' ,
43+ 'WelcomeScreenChannel' ,
44+ )
45+
46+ class WelcomeScreenChannel :
47+ """Represents a welcome channel displayed on :class:`WelcomeScreen`
48+
49+ .. versionadded:: 2.0
50+
51+ Attributes
52+ ----------
53+
54+ channel: :class:`abc.Snowflake`
55+ The channel that is being referenced.
56+ description: :class:`str`
57+ The description of channel that is shown on the welcome screen.
58+ emoji: :class:`Union[Emoji, PartialEmoji, str]`
59+ The emoji of channel that is shown on welcome screen.
60+ """
61+ def __init__ (self , channel : Snowflake , description : str , emoji : Union [Emoji , PartialEmoji , str ]):
62+ self .channel = channel
63+ self .description = description
64+ self .emoji = emoji
65+
66+ def __repr__ (self ):
67+ return f'WelcomeScreenChannel(channel={ self .channel } { self .description }
68+
69+ def to_dict (self ) -> WelcomeScreenChannelPayload :
70+ dict_ : WelcomeScreenChannelPayload = {
71+ 'channel_id' : self .channel .id ,
72+ 'description' : self .description ,
73+ 'emoji_id' : None ,
74+ 'emoji_name' : None ,
75+ }
76+
77+ if isinstance (self .emoji , _EmojiTag ):
78+ # custom guild emoji
79+ dict_ ['emoji_id' ] = self .emoji .id # type: ignore
80+ dict_ ['emoji_name' ] = self .emoji .name # type: ignore
81+ else :
82+ # unicode emoji or None
83+ dict_ ['emoji_name' ] = self .emoji
84+ dict_ ['emoji_id' ] = None # type: ignore
85+
86+ return dict_
87+
88+
89+ @classmethod
90+ def _from_dict (cls , data : WelcomeScreenChannelPayload , guild : Guild ) -> WelcomeChannel :
91+ channel_id = _get_as_snowflake (data , 'channel_id' )
92+ channel = guild .get_channel (channel_id )
93+ description = data .get ('description' )
94+ _emoji_id = _get_as_snowflake (data , 'emoji_id' )
95+ _emoji_name = data .get ('emoji_name' )
96+
97+ if _emoji_id :
98+ # custom guild emoji
99+ emoji = get (guild .emojis , id = _emoji_id )
100+ else :
101+ # unicode emoji or None
102+ emoji = _emoji_name
103+
104+ return cls (channel = channel , description = description , emoji = emoji ) # type: ignore
105+
106+
107+
108+ class WelcomeScreen :
109+ """Represents the welcome screen of a guild.
110+
111+ .. versionadded:: 2.0
112+
113+ Attributes
114+ ----------
115+
116+ description: :class:`str`
117+ The description text displayed on the welcome screen.
118+ welcome_channels: List[:class:`WelcomeScreenChannel`]
119+ A list of channels displayed on welcome screen.
120+ """
121+
122+ def __init__ (self , data : WelcomeScreenPayload , guild : Guild ):
123+ self ._guild = guild
124+ self ._update (data )
125+
126+ def __repr__ (self ):
127+ return f'<WelcomeScreen description={ self .description } { self .welcome_channels }
128+
129+ def _update (self , data : WelcomeScreenPayload ):
130+ self .description : str = data .get ('description' )
131+ self .welcome_channels : List [WelcomeScreenChannel ] = [WelcomeScreenChannel ._from_dict (channel , self ._guild ) for channel in data .get ('welcome_channels' , [])]
132+
133+
134+ @property
135+ def enabled (self ) -> bool :
136+ """:class:`bool`: Indicates whether the welcome screen is enabled or not."""
137+ return 'WELCOME_SCREEN_ENABLED' in self ._guild .features
138+
139+ @property
140+ def guild (self ) -> Guild :
141+ """:class:`Guild`: The guild this welcome screen belongs to."""
142+ return self ._guild
143+
144+
145+ @overload
146+ async def edit (
147+ self ,
148+ * ,
149+ description : Optional [str ] = ...,
150+ welcome_channels : Optional [List [WelcomeChannel ]] = ...,
151+ enabled : Optional [bool ] = ...,
152+ ) -> None :
153+ ...
154+
155+ @overload
156+ async def edit (self ) -> None :
157+ ...
158+
159+ async def edit (self , ** options ):
160+ """|coro|
161+
162+ Edits the welcome screen.
163+
164+ You must have the :attr:`~Permissions.manage_guild` permission in the
165+ guild to do this.
166+
167+ Usage: ::
168+ rules_channel = guild.get_channel(12345678)
169+ announcements_channel = guild.get_channel(87654321)
170+ custom_emoji = utils.get(guild.emojis, name='loudspeaker')
171+ await welcome_screen.edit(
172+ description='This is a very cool community server!',
173+ welcome_channels=[
174+ WelcomeChannel(channel=rules_channel, description='Read the rules!', emoji='👨🏫'),
175+ WelcomeChannel(channel=announcements_channel, description='Watch out for announcements!', emoji=custom_emoji),
176+ ]
177+ )
178+
179+ .. note::
180+ Welcome channels can only accept custom emojis if :attr:`~Guild.premium_tier` is level 2 or above.
181+
182+ Parameters
183+ ------------
184+
185+ description: Optional[:class:`str`]
186+ The new description of welcome screen.
187+ welcome_channels: Optional[List[:class:`WelcomeChannel`]]
188+ The welcome channels. The order of the channels would be same as the passed list order.
189+ enabled: Optional[:class:`bool`]
190+ Whether the welcome screen should be displayed.
191+
192+ Raises
193+ -------
194+
195+ HTTPException
196+ Editing the welcome screen failed somehow.
197+ Forbidden
198+ You don't have permissions to edit the welcome screen.
199+ NotFound
200+ This welcome screen does not exist.
201+
202+ """
203+
204+ welcome_channels = options .get ('welcome_channels' , [])
205+ welcome_channels_data = []
206+
207+ for channel in welcome_channels :
208+ if not isinstance (channel , WelcomeScreenChannel ):
209+ raise TypeError ('welcome_channels parameter must be a list of WelcomeScreenChannel.' )
210+
211+ welcome_channels_data .append (channel .to_dict ())
212+
213+ options ['welcome_channels' ] = welcome_channels_data
214+
215+ if options :
216+ new = await self ._guild ._state .http .edit_welcome_screen (self ._guild .id , options )
217+ self ._update (new )
218+
219+ return self
0 commit comments