|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
"""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: Optional["Bot"] = None |
|
) -> Optional["Giveaway"]: |
|
"""See :meth:`telegram.TelegramObject.de_json`.""" |
|
data = cls._parse_data(data) |
|
|
|
if data is None: |
|
return None |
|
|
|
|
|
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: Optional["Bot"] = None |
|
) -> Optional["GiveawayWinners"]: |
|
"""See :meth:`telegram.TelegramObject.de_json`.""" |
|
data = cls._parse_data(data) |
|
|
|
if data is None: |
|
return None |
|
|
|
|
|
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: Optional["Bot"] = None |
|
) -> Optional["GiveawayCompleted"]: |
|
"""See :meth:`telegram.TelegramObject.de_json`.""" |
|
data = cls._parse_data(data) |
|
|
|
if data is None: |
|
return None |
|
|
|
|
|
from telegram._message import Message |
|
|
|
data["giveaway_message"] = Message.de_json(data.get("giveaway_message"), bot) |
|
|
|
return super().de_json(data=data, bot=bot) |
|
|