Add on_purchased_paid_media decorator

compiler/docs/compiler.py

@@ -570,6 +570,7 @@ def get_title_list(s: str) -> list:
             MessageReactionCountUpdated
             ChatBoostUpdated
             ShippingOption
+            PurchasedPaidMedia
         """,
         bot_commands="""
         Bot commands

pyrogram/dispatcher.py

@@ -40,7 +40,8 @@
     UpdateUserStatus, UpdateBotInlineQuery, UpdateMessagePoll,
     UpdateBotInlineSend, UpdateChatParticipant, UpdateChannelParticipant,
     UpdateBotChatInviteRequester, UpdateStory, UpdateBotShippingQuery, UpdateBotMessageReaction,
-    UpdateBotMessageReactions, UpdateBotChatBoost, UpdateBusinessBotCallbackQuery
+    UpdateBotMessageReactions, UpdateBotChatBoost, UpdateBusinessBotCallbackQuery,
+    UpdateBotPurchasedPaidMedia
 )
 
 log = logging.getLogger(__name__)
@@ -63,6 +64,7 @@ class Dispatcher:
     MESSAGE_REACTION_UPDATES = (UpdateBotMessageReaction,)
     MESSAGE_REACTION_COUNT_UPDATES = (UpdateBotMessageReactions,)
     CHAT_BOOST_UPDATES = (UpdateBotChatBoost,)
+    PURCHASED_PAID_MEDIA_UPDATES = (UpdateBotPurchasedPaidMedia,)
 
     def __init__(self, client: "pyrogram.Client"):
         self.client = client
@@ -184,6 +186,12 @@ async def chat_boost_parser(update, users, chats):
                 ChatBoostHandler
             )
 
+        async def purchased_paid_media_parser(update, users, chats):
+            return (
+                pyrogram.types.PurchasedPaidMedia._parse(self.client, update, users),
+                ChatBoostHandler
+            )
+
         self.update_parsers = {
             Dispatcher.NEW_MESSAGE_UPDATES: message_parser,
             Dispatcher.EDIT_MESSAGE_UPDATES: edited_message_parser,
@@ -200,7 +208,8 @@ async def chat_boost_parser(update, users, chats):
             Dispatcher.SHIPPING_QUERY_UPDATES: shipping_query_parser,
             Dispatcher.MESSAGE_REACTION_UPDATES: message_reaction_parser,
             Dispatcher.MESSAGE_REACTION_COUNT_UPDATES: message_reaction_count_parser,
-            Dispatcher.CHAT_BOOST_UPDATES: chat_boost_parser
+            Dispatcher.CHAT_BOOST_UPDATES: chat_boost_parser,
+            Dispatcher.PURCHASED_PAID_MEDIA_UPDATES: purchased_paid_media_parser,
         }
 
         self.update_parsers = {key: value for key_tuple, value in self.update_parsers.items() for key in key_tuple}

pyrogram/handlers/__init__.py

@@ -30,6 +30,7 @@
 from .message_reaction_handler import MessageReactionHandler
 from .poll_handler import PollHandler
 from .pre_checkout_query_handler import PreCheckoutQueryHandler
+from .purchased_paid_media_handler import PurchasedPaidMediaHandler
 from .raw_update_handler import RawUpdateHandler
 from .shipping_query_handler import ShippingQueryHandler
 from .story_handler import StoryHandler

pyrogram/handlers/purchased_paid_media_handler.py

@@ -0,0 +1,49 @@
+#  Pyrogram - Telegram MTProto API Client Library for Python
+#  Copyright (C) 2017-present Dan <https://github.com/delivrance>
+#
+#  This file is part of Pyrogram.
+#
+#  Pyrogram is free software: you can redistribute it and/or modify
+#  it under the terms of the GNU Lesser General Public License as published
+#  by the Free Software Foundation, either version 3 of the License, or
+#  (at your option) any later version.
+#
+#  Pyrogram 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 General Public License for more details.
+#
+#  You should have received a copy of the GNU Lesser General Public License
+#  along with Pyrogram.  If not, see <http://www.gnu.org/licenses/>.
+
+from typing import Callable
+
+from .handler import Handler
+
+
+class PurchasedPaidMediaHandler(Handler):
+    """The PurchasedPaidMedia handler class. Used to handle purchased paid medias.
+    It is intended to be used with :meth:`~pyrogram.Client.add_handler`
+
+    For a nicer way to register this handler, have a look at the
+    :meth:`~pyrogram.Client.on_purchased_paid_media` decorator.
+
+    Parameters:
+        callback (``Callable``):
+            Pass a function that will be called when a paid media purchased. It takes *(client, update)*
+            as positional arguments (look at the section below for a detailed description).
+
+        filters (:obj:`Filters`):
+            Pass one or more filters to allow only a subset of updates to be passed
+            in your callback function.
+
+    Other parameters:
+        client (:obj:`~pyrogram.Client`):
+            The Client itself, useful when you want to call other API methods inside the handler.
+
+        update (:obj:`~pyrogram.types.PurchasedPaidMedia`):
+            Information about who bought paid media.
+    """
+
+    def __init__(self, callback: Callable, filters=None):
+        super().__init__(callback, filters)

pyrogram/methods/decorators/__init__.py

@@ -30,6 +30,7 @@
 from .on_message import OnMessage
 from .on_poll import OnPoll
 from .on_pre_checkout_query import OnPreCheckoutQuery
+from .on_purchased_paid_media import OnPurchasedPaidMedia
 from .on_raw_update import OnRawUpdate
 from .on_shipping_query import OnShippingQuery
 from .on_user_status import OnUserStatus
@@ -54,6 +55,7 @@ class Decorators(
     OnChatMemberUpdated,
     OnChatJoinRequest,
     OnStory,
-    OnPreCheckoutQuery
+    OnPreCheckoutQuery,
+    OnPurchasedPaidMedia
 ):
     pass

pyrogram/methods/decorators/on_purchased_paid_media.py

@@ -0,0 +1,62 @@
+#  Pyrogram - Telegram MTProto API Client Library for Python
+#  Copyright (C) 2017-present Dan <https://github.com/delivrance>
+#
+#  This file is part of Pyrogram.
+#
+#  Pyrogram is free software: you can redistribute it and/or modify
+#  it under the terms of the GNU Lesser General Public License as published
+#  by the Free Software Foundation, either version 3 of the License, or
+#  (at your option) any later version.
+#
+#  Pyrogram 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 General Public License for more details.
+#
+#  You should have received a copy of the GNU Lesser General Public License
+#  along with Pyrogram.  If not, see <http://www.gnu.org/licenses/>.
+
+from typing import Callable
+
+import pyrogram
+from pyrogram.filters import Filter
+
+
+class OnPurchasedPaidMedia:
+    def on_purchased_paid_media(
+        self=None,
+        filters=None,
+        group: int = 0
+    ) -> Callable:
+        """Decorator for handling purchased paid media.
+
+        This does the same thing as :meth:`~pyrogram.Client.add_handler` using the
+        :obj:`~pyrogram.handlers.PurchasedPaidMediaHandler`.
+
+        .. include:: /_includes/usable-by/bots.rst
+
+        Parameters:
+            filters (:obj:`~pyrogram.filters`, *optional*):
+                Pass one or more filters to allow only a subset of updates to be passed in your function.
+
+            group (``int``, *optional*):
+                The group identifier, defaults to 0.
+        """
+
+        def decorator(func: Callable) -> Callable:
+            if isinstance(self, pyrogram.Client):
+                self.add_handler(pyrogram.handlers.MessageReactionHandler(func, filters), group)
+            elif isinstance(self, Filter) or self is None:
+                if not hasattr(func, "handlers"):
+                    func.handlers = []
+
+                func.handlers.append(
+                    (
+                        pyrogram.handlers.MessageReactionHandler(func, self),
+                        group if filters is None else filters
+                    )
+                )
+
+            return func
+
+        return decorator

pyrogram/methods/messages/send_paid_media.py

@@ -75,7 +75,7 @@ async def send_paid_media(
                 Media caption, 0-1024 characters after entities parsing.
 
             invoice_payload (``str``):
-                Bot specified invoice payload.
+                Bot-defined invoice payload, 1-128 bytes. This will not be displayed to the user, use for your internal processes.
 
             parse_mode (:obj:`~pyrogram.enums.ParseMode`, *optional*):
                 By default, texts are parsed using both Markdown and HTML styles.

pyrogram/types/bots_and_keyboards/__init__.py

@@ -43,6 +43,7 @@
 from .message_reaction_updated import MessageReactionUpdated
 from .order_info import OrderInfo
 from .pre_checkout_query import PreCheckoutQuery
+from .purchased_paid_media import PurchasedPaidMedia
 from .reply_keyboard_markup import ReplyKeyboardMarkup
 from .reply_keyboard_remove import ReplyKeyboardRemove
 from .request_channel_info import RequestChannelInfo
@@ -91,6 +92,7 @@
     "MessageReactionUpdated",
     "OrderInfo",
     "PreCheckoutQuery",
+    "PurchasedPaidMedia",
     "MenuButtonDefault",
     "SentWebAppMessage",
     "ShippingOption",

pyrogram/types/bots_and_keyboards/pre_checkout_query.py

@@ -41,7 +41,7 @@ class PreCheckoutQuery(Object, Update):
             Total price in the smallest units of the currency (integer, **not** float/double). For example, for a price of ``US$ 1.45`` pass ``amount = 145``. See the __exp__ parameter in `currencies.json <https://core.telegram.org/bots/payments/currencies.json>`_, it shows the number of digits past the decimal point for each currency (2 for the majority of currencies).
 
         invoice_payload (``str``):
-            Bot specified invoice payload.
+            Bot-defined invoice payload, 1-128 bytes. This will not be displayed to the user, use for your internal processes.
 
         shipping_option_id (``str``, *optional*):
             Identifier of the shipping option chosen by the user.

pyrogram/types/bots_and_keyboards/purchased_paid_media.py

@@ -0,0 +1,50 @@
+#  Pyrogram - Telegram MTProto API Client Library for Python
+#  Copyright (C) 2017-present Dan <https://github.com/delivrance>
+#
+#  This file is part of Pyrogram.
+#
+#  Pyrogram is free software: you can redistribute it and/or modify
+#  it under the terms of the GNU Lesser General Public License as published
+#  by the Free Software Foundation, either version 3 of the License, or
+#  (at your option) any later version.
+#
+#  Pyrogram 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 General Public License for more details.
+#
+#  You should have received a copy of the GNU Lesser General Public License
+#  along with Pyrogram.  If not, see <http://www.gnu.org/licenses/>.
+
+from pyrogram import raw, types
+
+from ..object import Object
+
+
+class PurchasedPaidMedia(Object):
+    """This object represents information about purchased paid media.
+
+    Parameters:
+        from_user (:obj:`~pyrogram.types.User`):
+            User who bought the paid media.
+
+        payload (``str``):
+            Bot-defined invoice payload, 1-128 bytes. This will not be displayed to the user, use for your internal processes.
+    """
+
+    def __init__(
+        self,
+        from_user: "types.User",
+        payload: str
+    ):
+        super().__init__()
+
+        self.from_user = from_user
+        self.payload = payload
+
+    @staticmethod
+    def _parse(client, purchased_media: "raw.types.UpdateBotPurchasedPaidMedia", users) -> "PurchasedPaidMedia":
+        return PurchasedPaidMedia(
+            from_user=types.User._parse(client, users.get(purchased_media.user_id)),
+            payload=purchased_media.payload
+        )

pyrogram/types/bots_and_keyboards/shipping_query.py

@@ -35,7 +35,7 @@ class ShippingQuery(Object, Update):
             User who sent the query.
 
         invoice_payload (``str``):
-            Bot specified invoice payload. Only available to the bot that received the payment.
+            Bot-defined invoice payload, 1-128 bytes. This will not be displayed to the user, use for your internal processes.
 
         shipping_address (:obj:`~pyrogram.types.ShippingAddress`):
             User specified shipping address. Only available to the bot that received the payment.