From: Harmon <Harmon758@gmail.com>
Date: Tue, 6 Apr 2021 22:33:16 +0000 (-0500)
Subject: Update and improve documentation for API.get_oembed
X-Git-Url: https://vcs.fsf.org/?a=commitdiff_plain;h=6aa56f34c430a02826f7b79fc18ced42680f14b2;p=tweepy.git

Update and improve documentation for API.get_oembed

Automatically use docstring for documentation
Improve method and documentation order
Improve formatting
---

diff --git a/docs/api.rst b/docs/api.rst
index 42ffbff..71f69ff 100644
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -35,6 +35,8 @@ Post, retrieve, and engage with Tweets
 
 .. automethod:: API.statuses_lookup
 
+.. automethod:: API.get_oembed
+
 .. method:: API.retweets_of_me([since_id], [max_id], [count], [page])
 
    Returns the 20 most recent tweets of the authenticated user that have been
@@ -211,69 +213,6 @@ Status methods
    :rtype: :class:`Status` object
 
 
-.. method:: API.get_oembed(url, [maxwidth], [hide_media], [hide_thread], \
-                           [omit_script], [align], [related], [lang], \
-                           [theme], [link_color], [widget_type], [dnt])
-
-   Returns a single Tweet, specified by either a Tweet web URL or the Tweet ID,
-   in an oEmbed-compatible format. The returned HTML snippet will be
-   automatically recognized as an Embedded Tweet when Twitter's widget
-   JavaScript is included on the page.
-
-   The oEmbed endpoint allows customization of the final appearance of an
-   Embedded Tweet by setting the corresponding properties in HTML markup to be
-   interpreted by Twitter's JavaScript bundled with the HTML response by
-   default. The format of the returned markup may change over time as Twitter
-   adds new features or adjusts its Tweet representation.
-
-   The Tweet fallback markup is meant to be cached on your servers for up to
-   the suggested cache lifetime specified in the ``cache_age``.
-
-   :param url: The URL of the Tweet to be embedded
-   :param maxwidth: The maximum width of a rendered Tweet in whole pixels. A
-                    supplied value under or over the allowed range will be
-                    returned as the minimum or maximum supported width
-                    respectively; the reset width value will be reflected in
-                    the returned ``width`` property. Note that Twitter does not
-                    support the oEmbed ``maxheight`` parameter. Tweets are
-                    fundamentally text, and are therefore of unpredictable
-                    height that cannot be scaled like an image or video.
-                    Relatedly, the oEmbed response will not provide a value for
-                    ``height``. Implementations that need consistent heights
-                    for Tweets should refer to the ``hide_thread`` and
-                    ``hide_media`` parameters below.
-   :param hide_media: When set to ``true``, ``"t"``, or ``1``, links in a
-                      Tweet are not expanded to photo, video, or link previews.
-   :param hide_thread: When set to ``true``, ``"t"``, or ``1``, a collapsed
-                       version of the previous Tweet in a conversation thread
-                       will not be displayed when the requested Tweet is in
-                       reply to another Tweet.
-   :param omit_script: When set to ``true``, ``"t"``, or ``1``, the
-                       ``<script>`` responsible for loading ``widgets.js`` will
-                       not be returned. Your webpages should include their own
-                       reference to ``widgets.js`` for use across all Twitter
-                       widgets including Embedded Tweets.
-   :param align: Specifies whether the embedded Tweet should be floated left,
-                 right, or center in the page relative to the parent element.
-   :param related: A comma-separated list of Twitter usernames related to your
-                   content. This value will be forwarded to Tweet action
-                   intents if a viewer chooses to reply, like, or retweet the
-                   embedded Tweet.
-   :param lang: Request returned HTML and a rendered Tweet in the specified
-                Twitter language supported by embedded Tweets.
-   :param theme: When set to ``dark``, the Tweet is displayed with light text
-                 over a dark background.
-   :param link_color: Adjust the color of Tweet text links with a hexadecimal
-                      color value.
-   :param widget_type: Set to ``video`` to return a Twitter Video embed for the
-                       given Tweet.
-   :param dnt: When set to ``true``, the Tweet and its embedded page on your
-               site are not used for purposes that include personalized
-               suggestions and personalized ads.
-
-   :rtype: :class:`JSON` object
-
-
 User methods
 ------------
 
diff --git a/tweepy/api.py b/tweepy/api.py
index 032c328..802f32c 100644
--- a/tweepy/api.py
+++ b/tweepy/api.py
@@ -396,6 +396,78 @@ class API:
             ), id=list_to_csv(id), **kwargs
         )
 
+    @payload('json')
+    def get_oembed(self, url, **kwargs):
+        """get_oembed(url, *, maxwidth, hide_media, hide_thread, omit_script, \
+                      align, related, lang, theme, link_color, widget_type, \
+                      dnt)
+
+        Returns a single Tweet, specified by either a Tweet web URL or the Tweet
+        ID, in an oEmbed-compatible format. The returned HTML snippet will be
+        automatically recognized as an Embedded Tweet when Twitter's widget
+        JavaScript is included on the page.
+
+        The oEmbed endpoint allows customization of the final appearance of an
+        Embedded Tweet by setting the corresponding properties in HTML markup
+        to be interpreted by Twitter's JavaScript bundled with the HTML
+        response by default. The format of the returned markup may change over
+        time as Twitter adds new features or adjusts its Tweet representation.
+
+        The Tweet fallback markup is meant to be cached on your servers for up
+        to the suggested cache lifetime specified in the ``cache_age``.
+
+        :param url: The URL of the Tweet to be embedded
+        :param maxwidth: The maximum width of a rendered Tweet in whole pixels.
+            A supplied value under or over the allowed range will be returned
+            as the minimum or maximum supported width respectively; the reset
+            width value will be reflected in the returned ``width`` property.
+            Note that Twitter does not support the oEmbed ``maxheight``
+            parameter. Tweets are fundamentally text, and are therefore of
+            unpredictable height that cannot be scaled like an image or video.
+            Relatedly, the oEmbed response will not provide a value for
+            ``height``. Implementations that need consistent heights for Tweets
+            should refer to the ``hide_thread`` and ``hide_media`` parameters
+            below.
+        :param hide_media: When set to ``true``, ``"t"``, or ``1``, links in a
+            Tweet are not expanded to photo, video, or link previews.
+        :param hide_thread: When set to ``true``, ``"t"``, or ``1``, a
+            collapsed version of the previous Tweet in a conversation thread
+            will not be displayed when the requested Tweet is in reply to
+            another Tweet.
+        :param omit_script: When set to ``true``, ``"t"``, or ``1``, the
+            ``<script>`` responsible for loading ``widgets.js`` will not be
+            returned. Your webpages should include their own reference to
+            ``widgets.js`` for use across all Twitter widgets including
+            Embedded Tweets.
+        :param align: Specifies whether the embedded Tweet should be floated
+            left, right, or center in the page relative to the parent element.
+        :param related: A comma-separated list of Twitter usernames related to
+            your content. This value will be forwarded to Tweet action intents
+            if a viewer chooses to reply, like, or retweet the embedded Tweet.
+        :param lang: Request returned HTML and a rendered Tweet in the
+                     specified Twitter language supported by embedded Tweets.
+        :param theme: When set to ``dark``, the Tweet is displayed with light
+                      text over a dark background.
+        :param link_color: Adjust the color of Tweet text links with a
+                           hexadecimal color value.
+        :param widget_type: Set to ``video`` to return a Twitter Video embed
+                            for the given Tweet.
+        :param dnt: When set to ``true``, the Tweet and its embedded page on
+            your site are not used for purposes that include personalized
+            suggestions and personalized ads.
+
+        :rtype: :class:`JSON` object
+
+        :reference: https://developer.twitter.com/en/docs/twitter-api/v1/tweets/post-and-engage/api-reference/get-statuses-oembed
+        """
+        return self.request(
+            'GET', 'statuses/oembed', endpoint_parameters=(
+                'url', 'maxwidth', 'hide_media', 'hide_thread', 'omit_script',
+                'align', 'related', 'lang', 'theme', 'link_color',
+                'widget_type', 'dnt'
+            ), url=url, require_auth=False, **kwargs
+        )
+
     @pagination(mode='id')
     @payload('status', list=True)
     def retweets_of_me(self, **kwargs):
@@ -679,18 +751,6 @@ class API:
             ), **kwargs
         )
 
-    @payload('json')
-    def get_oembed(self, url, **kwargs):
-        """ :reference: https://developer.twitter.com/en/docs/twitter-api/v1/tweets/post-and-engage/api-reference/get-statuses-oembed
-        """
-        return self.request(
-            'GET', 'statuses/oembed', endpoint_parameters=(
-                'url', 'maxwidth', 'hide_media', 'hide_thread', 'omit_script',
-                'align', 'related', 'lang', 'theme', 'link_color',
-                'widget_type', 'dnt'
-            ), url=url, require_auth=False, **kwargs
-        )
-
     @payload('user', list=True)
     def lookup_users(self, *, screen_name=None, user_id=None, **kwargs):
         """ :reference: https://developer.twitter.com/en/docs/twitter-api/v1/accounts-and-users/follow-search-get-users/api-reference/get-users-lookup