Repository: python-telegram-bot/python-telegram-bot

Issue:
[Discussion] What is an attachment
We have the following string describing our attachment shortcut:
_If this message is neither a plain text message nor a status update_

and the following message attributes are set to it:

        * :class:`telegram.Audio`
        * :class:`telegram.Dice`
        * :class:`telegram.Contact`
        * :class:`telegram.Document`
        * :class:`telegram.Animation`
        * :class:`telegram.Game`
        * :class:`telegram.Invoice`
        * :class:`telegram.Location`
        * :class:`telegram.PassportData`
        * List[:class:`telegram.PhotoSize`]
        * :class:`telegram.Poll`
        * :class:`telegram.Sticker`
        * :class:`telegram.Story`
        * :class:`telegram.SuccessfulPayment`
        * :class:`telegram.Venue`
        * :class:`telegram.Video`
        * :class:`telegram.VideoNote`
        * :class:`telegram.Voice`


Now status update is not really defined in Telegram context. From my feeling for how I would use this method, I would describe it as "user generated message which is not a plain text message". This would however mean to remove SuccessfulPayment from this list.

On the other hand, if we stick to a definition which includes SuccessfulPayment, imo all service messages which link to an object should be included.




Discussion:
I agree, `SuccessfulPayment` does not belong there. 
the "user generated" in pools description makes sense to me. I guess narrowing down to "downloadable" (i.e. everything with a `file_id`) would be too harsh as e.g. locations & venues don't have that?
Yes no download there and for me they fit/should stay there
All right, sounds like a consensus. Pool, will you PR for the deprecation? Maybe also add the woring "user generated" or even "actively sent by the user" to the docstring?



Patch:
diff --git a/telegram/_message.py b/telegram/_message.py
index 5c45b9582a4..3cd654abbd9 100644
--- a/telegram/_message.py
+++ b/telegram/_message.py
@@ -1385,8 +1385,8 @@ def effective_attachment(
         Voice,
         None,
     ]:
-        """If this message is neither a plain text message nor a status update, this gives the
-        attachment that this message was sent with. This may be one of
+        """If the message is a user generated content which is not a plain text message, this
+        property is set to this content. It may be one of
 
         * :class:`telegram.Audio`
         * :class:`telegram.Dice`
@@ -1419,6 +1419,9 @@ def effective_attachment(
         .. versionchanged:: NEXT.VERSION
             :attr:`paid_media` is now also considered to be an attachment.
 
+        .. deprecated:: NEXT.VERSION
+            :attr:`successful_payment` will be removed in future major versions.
+
         """
         if not isinstance(self._effective_attachment, DefaultValue):
             return self._effective_attachment
@@ -1426,6 +1429,15 @@ def effective_attachment(
         for attachment_type in MessageAttachmentType:
             if self[attachment_type]:
                 self._effective_attachment = self[attachment_type]  # type: ignore[assignment]
+                if attachment_type == MessageAttachmentType.SUCCESSFUL_PAYMENT:
+                    warn(
+                        PTBDeprecationWarning(
+                            "NEXT.VERSION",
+                            "successful_payment will no longer be considered an attachment in"
+                            " future major versions",
+                        ),
+                        stacklevel=2,
+                    )
                 break
         else:
             self._effective_attachment = None


Test patch:
diff --git a/tests/test_message.py b/tests/test_message.py
index 6352845ffa2..9e575a99f45 100644
--- a/tests/test_message.py
+++ b/tests/test_message.py
@@ -2774,3 +2774,15 @@ async def make_assertion(*_, **kwargs):
 
         monkeypatch.setattr(message.get_bot(), "unpin_all_forum_topic_messages", make_assertion)
         assert await message.unpin_all_forum_topic_messages()
+
+    def test_attachement_successful_payment_deprecated(self, message, recwarn):
+        message.successful_payment = "something"
+        # kinda unnecessary to assert but one needs to call the function ofc so. Here we are.
+        assert message.effective_attachment == "something"
+        assert len(recwarn) == 1
+        assert (
+            "successful_payment will no longer be considered an attachment in future major "
+            "versions" in str(recwarn[0].message)
+        )
+        assert recwarn[0].category is PTBDeprecationWarning
+        assert recwarn[0].filename == __file__