From: Harmon <Harmon758@gmail.com>
Date: Sat, 10 Apr 2021 22:01:32 +0000 (-0500)
Subject: Update and improve documentation for API.send_direct_message
X-Git-Url: https://vcs.fsf.org/?a=commitdiff_plain;h=87a1b3fb3b641d0145eca9d4b664d5d52eb2c2a7;p=tweepy.git

Update and improve documentation for API.send_direct_message

Automatically use docstring for documentation
Improve method order
Add quick_reply_options and ctas parameters to documentation
Remove quick_reply_type parameter from documentation
---

diff --git a/docs/api.rst b/docs/api.rst
index f8975bf..9cc5739 100644
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -201,27 +201,7 @@ Sending and receiving events
 
 .. automethod:: API.get_direct_message
 
-
-.. method:: API.send_direct_message(recipient_id, text, [quick_reply_type], \
-                                    [attachment_type], [attachment_media_id])
-
-   Sends a new direct message to the specified user from the authenticating
-   user.
-
-   :param recipient_id: The ID of the user who should receive the direct
-                        message.
-   :param text: The text of your Direct Message. Max length of 10,000
-                characters.
-   :param quick_reply_type: The Quick Reply type to present to the user:
-
-                            * options - Array of Options objects (20 max).
-                            * text_input - Text Input object.
-                            * location - Location object.
-   :param attachment_type: The attachment type. Can be media or location.
-   :param attachment_media_id: A media id to associate with the message.
-                               A Direct Message may only reference a single
-                               media_id.
-   :rtype: :class:`DirectMessage` object
+.. automethod:: API.send_direct_message
 
 
 Account Methods
diff --git a/tweepy/api.py b/tweepy/api.py
index 6eafa25..f9af7d5 100644
--- a/tweepy/api.py
+++ b/tweepy/api.py
@@ -2251,6 +2251,57 @@ class API:
             ), id=id, **kwargs
         )
 
+    @payload('direct_message')
+    def send_direct_message(self, recipient_id, text, *, quick_reply_options=None,
+                            attachment_type=None, attachment_media_id=None,
+                            ctas=None, **kwargs):
+        """send_direct_message(recipient_id, text, *, quick_reply_options, \
+                               attachment_type, attachment_media_id, ctas)
+
+        Sends a new direct message to the specified user from the
+        authenticating user.
+
+        :param recipient_id: The ID of the user who should receive the direct
+                             message.
+        :param text: The text of your Direct Message. Max length of 10,000
+                     characters.
+        :param quick_reply_options: Array of Options objects (20 max).
+        :param attachment_type: The attachment type. Can be media or location.
+        :param attachment_media_id: A media id to associate with the message.
+                                    A Direct Message may only reference a
+                                    single media_id.
+        :param ctas: Array of 1-3 call-to-action (CTA) button objects
+
+        :rtype: :class:`DirectMessage` object
+
+        :reference: https://developer.twitter.com/en/docs/twitter-api/v1/direct-messages/sending-and-receiving/api-reference/new-event
+        """
+        json_payload = {
+            'event': {'type': 'message_create',
+                      'message_create': {
+                          'target': {'recipient_id': recipient_id},
+                          'message_data': {'text': text}
+                      }
+            }
+        }
+        message_data = json_payload['event']['message_create']['message_data']
+        if quick_reply_options is not None:
+            message_data['quick_reply'] = {
+                'type': 'options',
+                'options': quick_reply_options
+            }
+        if attachment_type is not None and attachment_media_id is not None:
+            message_data['attachment'] = {
+                'type': attachment_type,
+                'media': {'id': attachment_media_id}
+            }
+        if ctas is not None:
+            message_data['ctas'] = ctas
+        return self.request(
+            'POST', 'direct_messages/events/new',
+            json_payload=json_payload, **kwargs
+        )
+
     def media_upload(self, filename, *, file=None, chunked=False,
                      media_category=None, additional_owners=None, **kwargs):
         """ :reference: https://developer.twitter.com/en/docs/twitter-api/v1/media/upload-media/overview
@@ -2418,38 +2469,6 @@ class API:
             ), command='STATUS', media_id=media_id, upload_api=True, **kwargs
         )
 
-    @payload('direct_message')
-    def send_direct_message(self, recipient_id, text, *, quick_reply_options=None,
-                            attachment_type=None, attachment_media_id=None,
-                            ctas=None, **kwargs):
-        """ :reference: https://developer.twitter.com/en/docs/twitter-api/v1/direct-messages/sending-and-receiving/api-reference/new-event
-        """
-        json_payload = {
-            'event': {'type': 'message_create',
-                      'message_create': {
-                          'target': {'recipient_id': recipient_id},
-                          'message_data': {'text': text}
-                      }
-            }
-        }
-        message_data = json_payload['event']['message_create']['message_data']
-        if quick_reply_options is not None:
-            message_data['quick_reply'] = {
-                'type': 'options',
-                'options': quick_reply_options
-            }
-        if attachment_type is not None and attachment_media_id is not None:
-            message_data['attachment'] = {
-                'type': attachment_type,
-                'media': {'id': attachment_media_id}
-            }
-        if ctas is not None:
-            message_data['ctas'] = ctas
-        return self.request(
-            'POST', 'direct_messages/events/new',
-            json_payload=json_payload, **kwargs
-        )
-
     @payload('json')
     def rate_limit_status(self, **kwargs):
         """ :reference: https://developer.twitter.com/en/docs/twitter-api/v1/developer-utilities/rate-limit-status/api-reference/get-application-rate_limit_status