/
_giveaway.py
338 lines (282 loc) · 14.5 KB
/
_giveaway.py
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
#!/usr/bin/env python
#
# A library that provides a Python interface to the Telegram Bot API
# Copyright (C) 2015-2024
# Leandro Toledo de Souza <devs@python-telegram-bot.org>
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU Lesser Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU Lesser Public License for more details.
#
# You should have received a copy of the GNU Lesser Public License
# along with this program. If not, see [http://www.gnu.org/licenses/].
"""This module contains an objects that are related to Telegram giveaways."""
import datetime
from typing import TYPE_CHECKING, Optional, Sequence, Tuple
from telegram._chat import Chat
from telegram._telegramobject import TelegramObject
from telegram._user import User
from telegram._utils.argumentparsing import parse_sequence_arg
from telegram._utils.datetime import extract_tzinfo_from_defaults, from_timestamp
from telegram._utils.types import JSONDict
if TYPE_CHECKING:
from telegram import Bot, Message
class Giveaway(TelegramObject):
"""This object represents a message about a scheduled giveaway.
Objects of this class are comparable in terms of equality. Two objects of this class are
considered equal, if their :attr:`chats`, :attr:`winners_selection_date` and
:attr:`winner_count` are equal.
.. versionadded:: 20.8
Args:
chats (Tuple[:class:`telegram.Chat`]): The list of chats which the user must join to
participate in the giveaway.
winners_selection_date (:class:`datetime.datetime`): The date when the giveaway winner will
be selected. |datetime_localization|
winner_count (:obj:`int`): The number of users which are supposed to be selected as winners
of the giveaway.
only_new_members (:obj:`True`, optional): If :obj:`True`, only users who join the chats
after the giveaway started should be eligible to win.
has_public_winners (:obj:`True`, optional): :obj:`True`, if the list of giveaway winners
will be visible to everyone
prize_description (:obj:`str`, optional): Description of additional giveaway prize
country_codes (Sequence[:obj:`str`]): A list of two-letter ISO 3166-1 alpha-2
country codes indicating the countries from which eligible users for the giveaway must
come. If empty, then all users can participate in the giveaway. Users with a phone
number that was bought on Fragment can always participate in giveaways.
premium_subscription_month_count (:obj:`int`, optional): The number of months the Telegram
Premium subscription won from the giveaway will be active for.
Attributes:
chats (Sequence[:class:`telegram.Chat`]): The list of chats which the user must join to
participate in the giveaway.
winners_selection_date (:class:`datetime.datetime`): The date when the giveaway winner will
be selected. |datetime_localization|
winner_count (:obj:`int`): The number of users which are supposed to be selected as winners
of the giveaway.
only_new_members (:obj:`True`): Optional. If :obj:`True`, only users who join the chats
after the giveaway started should be eligible to win.
has_public_winners (:obj:`True`): Optional. :obj:`True`, if the list of giveaway winners
will be visible to everyone
prize_description (:obj:`str`): Optional. Description of additional giveaway prize
country_codes (Tuple[:obj:`str`]): Optional. A tuple of two-letter ISO 3166-1 alpha-2
country codes indicating the countries from which eligible users for the giveaway must
come. If empty, then all users can participate in the giveaway. Users with a phone
number that was bought on Fragment can always participate in giveaways.
premium_subscription_month_count (:obj:`int`): Optional. The number of months the Telegram
Premium subscription won from the giveaway will be active for.
"""
__slots__ = (
"chats",
"country_codes",
"has_public_winners",
"only_new_members",
"premium_subscription_month_count",
"prize_description",
"winner_count",
"winners_selection_date",
)
def __init__(
self,
chats: Sequence[Chat],
winners_selection_date: datetime.datetime,
winner_count: int,
only_new_members: Optional[bool] = None,
has_public_winners: Optional[bool] = None,
prize_description: Optional[str] = None,
country_codes: Optional[Sequence[str]] = None,
premium_subscription_month_count: Optional[int] = None,
*,
api_kwargs: Optional[JSONDict] = None,
):
super().__init__(api_kwargs=api_kwargs)
self.chats: Tuple[Chat, ...] = tuple(chats)
self.winners_selection_date: datetime.datetime = winners_selection_date
self.winner_count: int = winner_count
self.only_new_members: Optional[bool] = only_new_members
self.has_public_winners: Optional[bool] = has_public_winners
self.prize_description: Optional[str] = prize_description
self.country_codes: Tuple[str, ...] = parse_sequence_arg(country_codes)
self.premium_subscription_month_count: Optional[int] = premium_subscription_month_count
self._id_attrs = (
self.chats,
self.winners_selection_date,
self.winner_count,
)
self._freeze()
@classmethod
def de_json(cls, data: Optional[JSONDict], bot: "Bot") -> Optional["Giveaway"]:
"""See :obj:`telegram.TelegramObject.de_json`."""
data = cls._parse_data(data)
if data is None:
return None
# Get the local timezone from the bot if it has defaults
loc_tzinfo = extract_tzinfo_from_defaults(bot)
data["chats"] = tuple(Chat.de_list(data.get("chats"), bot))
data["winners_selection_date"] = from_timestamp(
data.get("winners_selection_date"), tzinfo=loc_tzinfo
)
return super().de_json(data=data, bot=bot)
class GiveawayCreated(TelegramObject):
"""This object represents a service message about the creation of a scheduled giveaway.
Currently holds no information.
"""
__slots__ = ()
def __init__(self, *, api_kwargs: Optional[JSONDict] = None):
super().__init__(api_kwargs=api_kwargs)
self._freeze()
class GiveawayWinners(TelegramObject):
"""This object represents a message about the completion of a giveaway with public winners.
Objects of this class are comparable in terms of equality. Two objects of this class are
considered equal, if their :attr:`chat`, :attr:`giveaway_message_id`,
:attr:`winners_selection_date`, :attr:`winner_count` and :attr:`winners` are equal.
.. versionadded:: 20.8
Args:
chat (:class:`telegram.Chat`): The chat that created the giveaway
giveaway_message_id (:obj:`int`): Identifier of the message with the giveaway in the chat
winners_selection_date (:class:`datetime.datetime`): Point in time when winners of the
giveaway were selected. |datetime_localization|
winner_count (:obj:`int`): Total number of winners in the giveaway
winners (Sequence[:class:`telegram.User`]): List of up to
:tg-const:`telegram.constants.GiveawayLimit.MAX_WINNERS` winners of the giveaway
additional_chat_count (:obj:`int`, optional): The number of other chats the user had to
join in order to be eligible for the giveaway
premium_subscription_month_count (:obj:`int`, optional): The number of months the Telegram
Premium subscription won from the giveaway will be active for
unclaimed_prize_count (:obj:`int`, optional): Number of undistributed prizes
only_new_members (:obj:`True`, optional): :obj:`True`, if only users who had joined the
chats after the giveaway started were eligible to win
was_refunded (:obj:`True`, optional): :obj:`True`, if the giveaway was canceled because the
payment for it was refunded
prize_description (:obj:`str`, optional): Description of additional giveaway prize
Attributes:
chat (:class:`telegram.Chat`): The chat that created the giveaway
giveaway_message_id (:obj:`int`): Identifier of the message with the giveaway in the chat
winners_selection_date (:class:`datetime.datetime`): Point in time when winners of the
giveaway were selected. |datetime_localization|
winner_count (:obj:`int`): Total number of winners in the giveaway
winners (Tuple[:class:`telegram.User`]): tuple of up to
:tg-const:`telegram.constants.GiveawayLimit.MAX_WINNERS` winners of the giveaway
additional_chat_count (:obj:`int`): Optional. The number of other chats the user had to
join in order to be eligible for the giveaway
premium_subscription_month_count (:obj:`int`): Optional. The number of months the Telegram
Premium subscription won from the giveaway will be active for
unclaimed_prize_count (:obj:`int`): Optional. Number of undistributed prizes
only_new_members (:obj:`True`): Optional. :obj:`True`, if only users who had joined the
chats after the giveaway started were eligible to win
was_refunded (:obj:`True`): Optional. :obj:`True`, if the giveaway was canceled because the
payment for it was refunded
prize_description (:obj:`str`): Optional. Description of additional giveaway prize
"""
__slots__ = (
"additional_chat_count",
"chat",
"giveaway_message_id",
"only_new_members",
"premium_subscription_month_count",
"prize_description",
"unclaimed_prize_count",
"was_refunded",
"winner_count",
"winners",
"winners_selection_date",
)
def __init__(
self,
chat: Chat,
giveaway_message_id: int,
winners_selection_date: datetime.datetime,
winner_count: int,
winners: Sequence[User],
additional_chat_count: Optional[int] = None,
premium_subscription_month_count: Optional[int] = None,
unclaimed_prize_count: Optional[int] = None,
only_new_members: Optional[bool] = None,
was_refunded: Optional[bool] = None,
prize_description: Optional[str] = None,
*,
api_kwargs: Optional[JSONDict] = None,
):
super().__init__(api_kwargs=api_kwargs)
self.chat: Chat = chat
self.giveaway_message_id: int = giveaway_message_id
self.winners_selection_date: datetime.datetime = winners_selection_date
self.winner_count: int = winner_count
self.winners: Tuple[User, ...] = tuple(winners)
self.additional_chat_count: Optional[int] = additional_chat_count
self.premium_subscription_month_count: Optional[int] = premium_subscription_month_count
self.unclaimed_prize_count: Optional[int] = unclaimed_prize_count
self.only_new_members: Optional[bool] = only_new_members
self.was_refunded: Optional[bool] = was_refunded
self.prize_description: Optional[str] = prize_description
self._id_attrs = (
self.chat,
self.giveaway_message_id,
self.winners_selection_date,
self.winner_count,
self.winners,
)
self._freeze()
@classmethod
def de_json(cls, data: Optional[JSONDict], bot: "Bot") -> Optional["GiveawayWinners"]:
"""See :obj:`telegram.TelegramObject.de_json`."""
data = cls._parse_data(data)
if data is None:
return None
# Get the local timezone from the bot if it has defaults
loc_tzinfo = extract_tzinfo_from_defaults(bot)
data["chat"] = Chat.de_json(data.get("chat"), bot)
data["winners"] = tuple(User.de_list(data.get("winners"), bot))
data["winners_selection_date"] = from_timestamp(
data.get("winners_selection_date"), tzinfo=loc_tzinfo
)
return super().de_json(data=data, bot=bot)
class GiveawayCompleted(TelegramObject):
"""This object represents a service message about the completion of a giveaway without public
winners.
Objects of this class are comparable in terms of equality. Two objects of this class are
considered equal, if their :attr:`winner_count` and :attr:`unclaimed_prize_count` are equal.
.. versionadded:: 20.8
Args:
winner_count (:obj:`int`): Number of winners in the giveaway
unclaimed_prize_count (:obj:`int`, optional): Number of undistributed prizes
giveaway_message (:class:`telegram.Message`, optional): Message with the giveaway that was
completed, if it wasn't deleted
Attributes:
winner_count (:obj:`int`): Number of winners in the giveaway
unclaimed_prize_count (:obj:`int`): Optional. Number of undistributed prizes
giveaway_message (:class:`telegram.Message`): Optional. Message with the giveaway that was
completed, if it wasn't deleted
"""
__slots__ = ("giveaway_message", "unclaimed_prize_count", "winner_count")
def __init__(
self,
winner_count: int,
unclaimed_prize_count: Optional[int] = None,
giveaway_message: Optional["Message"] = None,
*,
api_kwargs: Optional[JSONDict] = None,
):
super().__init__(api_kwargs=api_kwargs)
self.winner_count: int = winner_count
self.unclaimed_prize_count: Optional[int] = unclaimed_prize_count
self.giveaway_message: Optional["Message"] = giveaway_message
self._id_attrs = (
self.winner_count,
self.unclaimed_prize_count,
)
self._freeze()
@classmethod
def de_json(cls, data: Optional[JSONDict], bot: "Bot") -> Optional["GiveawayCompleted"]:
"""See :obj:`telegram.TelegramObject.de_json`."""
data = cls._parse_data(data)
if data is None:
return None
# Unfortunately, this needs to be here due to cyclic imports
from telegram._message import Message # pylint: disable=import-outside-toplevel
data["giveaway_message"] = Message.de_json(data.get("giveaway_message"), bot)
return super().de_json(data=data, bot=bot)