python-telegram-bot · Bibo-Joshi · Nov 3, 2024 · Nov 1, 2024
diff --git a/docs/source/telegram.payments-tree.rst b/docs/source/telegram.payments-tree.rst
@@ -28,4 +28,5 @@ Your bot can accept payments from Telegram users. Please see the `introduction t
     telegram.transactionpartnerfragment
     telegram.transactionpartnerother
     telegram.transactionpartnertelegramads
+    telegram.transactionpartnertelegramapi
     telegram.transactionpartneruser
diff --git a/docs/source/telegram.transactionpartnerfragment.rst b/docs/source/telegram.transactionpartnerfragment.rst
@@ -4,4 +4,4 @@ TransactionPartnerFragment
 .. autoclass:: telegram.TransactionPartnerFragment
     :members:
     :show-inheritance:
-    :inherited-members: TelegramObject
+    :inherited-members: TransactionPartner
diff --git a/docs/source/telegram.transactionpartnerother.rst b/docs/source/telegram.transactionpartnerother.rst
@@ -4,4 +4,4 @@ TransactionPartnerOther
 .. autoclass:: telegram.TransactionPartnerOther
     :members:
     :show-inheritance:
-    :inherited-members: TelegramObject
+    :inherited-members: TransactionPartner
diff --git a/docs/source/telegram.transactionpartnertelegramads.rst b/docs/source/telegram.transactionpartnertelegramads.rst
@@ -4,4 +4,4 @@ TransactionPartnerTelegramAds
 .. autoclass:: telegram.TransactionPartnerTelegramAds
     :members:
     :show-inheritance:
-    :inherited-members: TelegramObject
+    :inherited-members: TransactionPartner
diff --git a/docs/source/telegram.transactionpartnertelegramapi.rst b/docs/source/telegram.transactionpartnertelegramapi.rst
@@ -0,0 +1,7 @@
+TransactionPartnerTelegramApi
+=============================
+
+.. autoclass:: telegram.TransactionPartnerTelegramApi
+    :members:
+    :show-inheritance:
+    :inherited-members: TransactionPartner
diff --git a/docs/source/telegram.transactionpartneruser.rst b/docs/source/telegram.transactionpartneruser.rst
@@ -4,4 +4,4 @@ TransactionPartnerUser
 .. autoclass:: telegram.TransactionPartnerUser
     :members:
     :show-inheritance:
-    :inherited-members: TelegramObject
+    :inherited-members: TransactionPartner
diff --git a/telegram/__init__.py b/telegram/__init__.py
@@ -235,6 +235,7 @@
     "TransactionPartnerFragment",
     "TransactionPartnerOther",
     "TransactionPartnerTelegramAds",
+    "TransactionPartnerTelegramApi",
     "TransactionPartnerUser",
     "Update",
     "User",
@@ -471,6 +472,7 @@
     TransactionPartnerFragment,
     TransactionPartnerOther,
     TransactionPartnerTelegramAds,
+    TransactionPartnerTelegramApi,
     TransactionPartnerUser,
 )
 from ._payment.successfulpayment import SuccessfulPayment

diff --git a/telegram/_payment/stars.py b/telegram/_payment/stars.py
@@ -218,12 +218,14 @@ class TransactionPartner(TelegramObject):
 
     FRAGMENT: Final[str] = constants.TransactionPartnerType.FRAGMENT
     """:const:`telegram.constants.TransactionPartnerType.FRAGMENT`"""
-    USER: Final[str] = constants.TransactionPartnerType.USER
-    """:const:`telegram.constants.TransactionPartnerType.USER`"""
     OTHER: Final[str] = constants.TransactionPartnerType.OTHER
     """:const:`telegram.constants.TransactionPartnerType.OTHER`"""
     TELEGRAM_ADS: Final[str] = constants.TransactionPartnerType.TELEGRAM_ADS
     """:const:`telegram.constants.TransactionPartnerType.TELEGRAM_ADS`"""
+    TELEGRAM_API: Final[str] = constants.TransactionPartnerType.TELEGRAM_API
+    """:const:`telegram.constants.TransactionPartnerType.TELEGRAM_API`"""
+    USER: Final[str] = constants.TransactionPartnerType.USER
+    """:const:`telegram.constants.TransactionPartnerType.USER`"""
 
     def __init__(self, type: str, *, api_kwargs: Optional[JSONDict] = None) -> None:
         super().__init__(api_kwargs=api_kwargs)
@@ -258,8 +260,9 @@ def de_json(
         _class_mapping: dict[str, type[TransactionPartner]] = {
             cls.FRAGMENT: TransactionPartnerFragment,
             cls.USER: TransactionPartnerUser,
-            cls.OTHER: TransactionPartnerOther,
             cls.TELEGRAM_ADS: TransactionPartnerTelegramAds,
+            cls.TELEGRAM_API: TransactionPartnerTelegramApi,
+            cls.OTHER: TransactionPartnerOther,
         }
 
         if cls is TransactionPartner and data.get("type") in _class_mapping:
@@ -421,6 +424,35 @@ def __init__(self, *, api_kwargs: Optional[JSONDict] = None) -> None:
         self._freeze()
 
 
+class TransactionPartnerTelegramApi(TransactionPartner):
+    """Describes a transaction with payment for
+    `paid broadcasting <https://core.telegram.org/bots/api#paid-broadcasts>`_.
+
+    Objects of this class are comparable in terms of equality. Two objects of this class are
+    considered equal, if their :attr:`request_count` is equal.
+
+    .. versionadded:: NEXT.VERSION
+
+    Args:
+        request_count (:obj:`int`): The number of successful requests that exceeded regular limits
+            and were therefore billed.
+
+    Attributes:
+        type (:obj:`str`): The type of the transaction partner,
+            always :tg-const:`telegram.TransactionPartner.TELEGRAM_API`.
+        request_count (:obj:`int`): The number of successful requests that exceeded regular limits
+            and were therefore billed.
+    """
+
+    __slots__ = ("request_count",)
+
+    def __init__(self, request_count: int, *, api_kwargs: Optional[JSONDict] = None) -> None:
+        super().__init__(type=TransactionPartner.TELEGRAM_API, api_kwargs=api_kwargs)
+        with self._unfrozen():
+            self.request_count: int = request_count
+            self._id_attrs = (self.request_count,)
+
+
 class StarTransaction(TelegramObject):
     """Describes a Telegram Star transaction.
 

diff --git a/telegram/constants.py b/telegram/constants.py
@@ -2592,12 +2592,18 @@ class TransactionPartnerType(StringEnum):
 
     FRAGMENT = "fragment"
     """:obj:`str`: Withdrawal transaction with Fragment."""
-    USER = "user"
-    """:obj:`str`: Transaction with a user."""
     OTHER = "other"
     """:obj:`str`: Transaction with unknown source or recipient."""
     TELEGRAM_ADS = "telegram_ads"
     """:obj:`str`: Transaction with Telegram Ads."""
+    TELEGRAM_API = "telegram_api"
+    """:obj:`str`: Transaction with with payment for
+    `paid broadcasting <https://core.telegram.org/bots/api#paid-broadcasts>`_.
+
+    ..versionadded:: NEXT.VERSION
+    """
+    USER = "user"
+    """:obj:`str`: Transaction with a user."""
 
 
 class ParseMode(StringEnum):

diff --git a/tests/test_stars.py b/tests/test_stars.py
@@ -36,6 +36,7 @@
     TransactionPartnerFragment,
     TransactionPartnerOther,
     TransactionPartnerTelegramAds,
+    TransactionPartnerTelegramApi,
     TransactionPartnerUser,
     User,
 )
@@ -78,11 +79,6 @@ def transaction_partner_user():
     )
 
 
-@pytest.fixture
-def transaction_partner_other():
-    return TransactionPartnerOther()
-
-
 def transaction_partner_fragment():
     return TransactionPartnerFragment(
         withdrawal_state=withdrawal_state_succeeded(),
@@ -114,8 +110,9 @@ def star_transactions():
     params=[
         TransactionPartner.FRAGMENT,
         TransactionPartner.OTHER,
-        TransactionPartner.USER,
         TransactionPartner.TELEGRAM_ADS,
+        TransactionPartner.TELEGRAM_API,
+        TransactionPartner.USER,
     ],
 )
 def tp_scope_type(request):
@@ -127,14 +124,16 @@ def tp_scope_type(request):
     params=[
         TransactionPartnerFragment,
         TransactionPartnerOther,
-        TransactionPartnerUser,
         TransactionPartnerTelegramAds,
+        TransactionPartnerTelegramApi,
+        TransactionPartnerUser,
     ],
     ids=[
         TransactionPartner.FRAGMENT,
         TransactionPartner.OTHER,
-        TransactionPartner.USER,
         TransactionPartner.TELEGRAM_ADS,
+        TransactionPartner.TELEGRAM_API,
+        TransactionPartner.USER,
     ],
 )
 def tp_scope_class(request):
@@ -146,14 +145,16 @@ def tp_scope_class(request):
     params=[
         (TransactionPartnerFragment, TransactionPartner.FRAGMENT),
         (TransactionPartnerOther, TransactionPartner.OTHER),
-        (TransactionPartnerUser, TransactionPartner.USER),
         (TransactionPartnerTelegramAds, TransactionPartner.TELEGRAM_ADS),
+        (TransactionPartnerTelegramApi, TransactionPartner.TELEGRAM_API),
+        (TransactionPartnerUser, TransactionPartner.USER),
     ],
     ids=[
         TransactionPartner.FRAGMENT,
         TransactionPartner.OTHER,
-        TransactionPartner.USER,
         TransactionPartner.TELEGRAM_ADS,
+        TransactionPartner.TELEGRAM_API,
+        TransactionPartner.USER,
     ],
 )
 def tp_scope_class_and_type(request):
@@ -169,6 +170,7 @@ def transaction_partner(tp_scope_class_and_type):
             "invoice_payload": TransactionPartnerTestBase.invoice_payload,
             "withdrawal_state": TransactionPartnerTestBase.withdrawal_state.to_dict(),
             "user": TransactionPartnerTestBase.user.to_dict(),
+            "request_count": TransactionPartnerTestBase.request_count,
         },
         bot=None,
     )
@@ -382,6 +384,7 @@ class TransactionPartnerTestBase:
     withdrawal_state = withdrawal_state_succeeded()
     user = transaction_partner_user().user
     invoice_payload = "payload"
+    request_count = 42
 
 
 class TestTransactionPartnerWithoutRequest(TransactionPartnerTestBase):
@@ -400,11 +403,15 @@ def test_de_json(self, offline_bot, tp_scope_class_and_type):
             "invoice_payload": self.invoice_payload,
             "withdrawal_state": self.withdrawal_state.to_dict(),
             "user": self.user.to_dict(),
+            "request_count": self.request_count,
         }
         tp = TransactionPartner.de_json(json_dict, offline_bot)
-        assert set(tp.api_kwargs.keys()) == {"user", "withdrawal_state", "invoice_payload"} - set(
-            cls.__slots__
-        )
+        assert set(tp.api_kwargs.keys()) == {
+            "user",
+            "withdrawal_state",
+            "invoice_payload",
+            "request_count",
+        } - set(cls.__slots__)
 
         assert isinstance(tp, TransactionPartner)
         assert type(tp) is cls
@@ -414,6 +421,8 @@ def test_de_json(self, offline_bot, tp_scope_class_and_type):
         if "user" in cls.__slots__:
             assert tp.user == self.user
             assert tp.invoice_payload == self.invoice_payload
+        if "request_count" in cls.__slots__:
+            assert tp.request_count == self.request_count
 
         assert cls.de_json(None, offline_bot) is None
         assert TransactionPartner.de_json({}, offline_bot) is None
@@ -424,12 +433,14 @@ def test_de_json_invalid_type(self, offline_bot):
             "invoice_payload": self.invoice_payload,
             "withdrawal_state": self.withdrawal_state.to_dict(),
             "user": self.user.to_dict(),
+            "request_count": self.request_count,
         }
         tp = TransactionPartner.de_json(json_dict, offline_bot)
         assert tp.api_kwargs == {
             "withdrawal_state": self.withdrawal_state.to_dict(),
             "user": self.user.to_dict(),
             "invoice_payload": self.invoice_payload,
+            "request_count": self.request_count,
         }
 
         assert type(tp) is TransactionPartner
@@ -443,6 +454,7 @@ def test_de_json_subclass(self, tp_scope_class, offline_bot):
             "invoice_payload": self.invoice_payload,
             "withdrawal_state": self.withdrawal_state.to_dict(),
             "user": self.user.to_dict(),
+            "request_count": self.request_count,
         }
         assert type(tp_scope_class.de_json(json_dict, offline_bot)) is tp_scope_class
 
@@ -494,6 +506,14 @@ def test_equality(self, transaction_partner, offline_bot):
             assert c != f
             assert hash(c) != hash(f)
 
+        if hasattr(c, "request_count"):
+            json_dict = c.to_dict()
+            json_dict["request_count"] = 1
+            f = c.__class__.de_json(json_dict, offline_bot)
+
+            assert c != f
+            assert hash(c) != hash(f)
+
 
 class RevenueWithdrawalStateTestBase:
     date = datetime.datetime(2024, 1, 1, 0, 0, 0, 0, tzinfo=UTC)