Update and improve documentation for API.update_with_media

Automatically use docstring for documentation
Improve method order
Add possibly_sensitive and display_coordinates parameters to documentation
Remove auto_populate_reply_metadata and source parameters from documentation
Use deprecated directive
Improve parameter order in documentation

diff --git a/docs/api.rst b/docs/api.rst
index 1bb9e9110964d890eb3484cbbf98304f4dbf5c69..660ccf0d2be121c1b58edc3f8547f0b55fd5610e 100644 (file)
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -57,33 +57,7 @@ Post, retrieve, and engage with Tweets
 
 .. automethod:: API.update_status
 
-
-Status methods
---------------
-
-.. method:: API.update_with_media(filename, [status], \
-                                  [in_reply_to_status_id], \
-                                  [auto_populate_reply_metadata], [lat], \
-                                  [long], [source], [place_id], [file])
-
-   *Deprecated*: Use :func:`API.media_upload` instead. Update the authenticated
-   user's status. Statuses that are duplicates or too long will be silently
-   ignored.
-
-   :param filename: |filename|
-   :param status: The text of your status update.
-   :param in_reply_to_status_id: The ID of an existing status that the update
-                                 is in reply to.
-   :param auto_populate_reply_metadata: Whether to automatically include the
-                                        @mentions in the status metadata.
-   :param lat: The location's latitude that this tweet refers to.
-   :param long: The location's longitude that this tweet refers to.
-   :param source: Source of the update. Only supported by Identi.ca. Twitter
-                  ignores this parameter.
-   :param place_id: Twitter ID of location which is listed in the Tweet if
-                    geolocation is enabled for the user.
-   :param file: |file|
-   :rtype: :class:`Status` object
+.. automethod:: API.update_with_media
 
 
 User methods

diff --git a/tweepy/api.py b/tweepy/api.py
index d8f29c4fb79325764e5a500ae061259018a1c33a..86dfbd17438986db0684d20064638b792c8be4ac 100644 (file)
--- a/tweepy/api.py
+++ b/tweepy/api.py
@@ -760,6 +760,47 @@ class API:
             ), status=status, **kwargs
         )
 
+    @payload('status')
+    def update_with_media(self, status, filename, *, file=None, **kwargs):
+        """update_with_media(status, filename, *, file, possibly_sensitive, \
+                             in_reply_to_status_id, lat, long, place_id, \
+                             display_coordinates)
+
+        .. deprecated:: 3.7.0
+            Use :func:`API.media_upload` instead.
+        
+        Update the authenticated user's status. Statuses that are duplicates or
+        too long will be silently ignored.
+
+        :param status: The text of your status update.
+        :param filename: |filename|
+        :param file: |file|
+        :param possibly_sensitive: Set to true for content which may not be
+                                   suitable for every audience.
+        :param in_reply_to_status_id: The ID of an existing status that the update
+                                      is in reply to.
+        :param lat: The location's latitude that this tweet refers to.
+        :param long: The location's longitude that this tweet refers to.
+        :param place_id: Twitter ID of location which is listed in the Tweet if
+                         geolocation is enabled for the user.
+        :param display_coordinates: Whether or not to put a pin on the exact
+                                    coordinates a Tweet has been sent from.
+
+        :rtype: :class:`Status` object
+
+        :reference: https://developer.twitter.com/en/docs/twitter-api/v1/tweets/post-and-engage/api-reference/post-statuses-update_with_media
+        """
+        if file is not None:
+            files = {'media[]': (filename, file)}
+        else:
+            files = {'media[]': open(filename, 'rb')}
+        return self.request(
+            'POST', 'statuses/update_with_media', endpoint_parameters=(
+                'status', 'possibly_sensitive', 'in_reply_to_status_id',
+                'lat', 'long', 'place_id', 'display_coordinates'
+            ), status=status, files=files, **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
@@ -917,21 +958,6 @@ class API:
             upload_api=True, **kwargs
         )
 
-    @payload('status')
-    def update_with_media(self, status, filename, *, file=None, **kwargs):
-        """ :reference: https://developer.twitter.com/en/docs/twitter-api/v1/tweets/post-and-engage/api-reference/post-statuses-update_with_media
-        """
-        if file is not None:
-            files = {'media[]': (filename, file)}
-        else:
-            files = {'media[]': open(filename, 'rb')}
-        return self.request(
-            'POST', 'statuses/update_with_media', endpoint_parameters=(
-                'status', 'possibly_sensitive', 'in_reply_to_status_id',
-                'lat', 'long', 'place_id', 'display_coordinates'
-            ), status=status, files=files, **kwargs
-        )
-
     @payload('media')
     def get_media_upload_status(self, media_id, **kwargs):
         """ :reference: https://developer.twitter.com/en/docs/twitter-api/v1/media/upload-media/api-reference/get-media-upload-status