Merge pull request #113 from MerleLiuKun/feat-bookmarks

Feat bookmarks

Author: MerleLiuKun

README.rst

@@ -95,6 +95,7 @@ Now cover features:
     - Volume streams
     - Retweets
     - Likes
+    - Bookmarks
     - Hide replies
 
 - Users

docs/docs/usage/tweets/bookmarks.md

@@ -0,0 +1,32 @@
+Bookmarks are a core feature of the Twitter app that allows you to “save” Tweets and easily access them later. With these endpoints, you can retrieve, create, delete or build solutions to manage your Bookmarks via the API.  
+
+You can get more information for this at [docs](https://developer.twitter.com/en/docs/twitter-api/tweets/bookmarks/introduction)
+
+## Manage Bookmarks
+
+### Bookmark tweet
+
+Causes the user ID of an authenticated user identified in the path parameter to Bookmark the target Tweet provided in the request body.
+
+```python
+my_api.bookmark_tweet(user_id="1301152652357595137", tweet_id="1511645952418885636")
+# {'data': {'bookmarked': True}}
+```
+
+### Remove bookmark tweet
+
+Allows a user or authenticated user ID to remove a Bookmark of a Tweet.
+
+```python
+my_api.bookmark_tweet_remove(user_id="1301152652357595137", tweet_id="1511645952418885636")
+# {'data': {'bookmarked': False}}
+```
+
+## Bookmarks lookup
+
+Allows you to get information about a authenticated user’s 800 most recent bookmarked Tweets.
+
+```python
+my_api.get_bookmark_tweets(user_id="1301152652357595137")
+#  Response(data=[Tweet(id=1511645952418885636, text=https://t.co/Hl9Sa0uP9W)])
+```

docs/mkdocs.yml

@@ -37,21 +37,22 @@ nav:
       - Tweets:
           - Tweet Lookup: usage/tweets/tweet-lookup.md
           - Manage Tweets: usage/tweets/tweet-manage.md
-          - Quote Tweets: usage/tweets/qutoe_tweets.md
           - Timelines: usage/tweets/timelines.md
           - Search Tweets: usage/tweets/search_tweets.md
           - Tweet counts: usage/tweets/tweets_counts.md
-          - Hide replies: usage/tweets/hide_reply.md
           - Retweets: usage/tweets/retweet.md
+          - Quote Tweets: usage/tweets/qutoe_tweets.md
           - Likes: usage/tweets/likes.md
+          - Bookmarks: usage/tweets/bookmarks.md
+          - Hide replies: usage/tweets/hide_reply.md
       - Users:
           - Users Lookup: usage/users/user-lookup.md
           - Follows: usage/users/follows.md
           - Blocks: usage/users/blocks.md
           - Mutes: usage/users/mutes.md
       - Spaces:
           - Spaces Lookup: usage/spaces/spaces-lookup.md
-          - Spaces Search: usage/spaces/search.md
+          - Search Spaces: usage/spaces/search.md
       - Lists:
           - List lookup: usage/lists/list-lookup.md
           - Manage Lists: usage/lists/manage-lists.md

pytwitter/api.py

@@ -1194,6 +1194,97 @@ def unlike_tweet(self, user_id: str, tweet_id: str) -> dict:
         data = self._parse_response(resp=resp)
         return data
 
+    def get_bookmark_tweets(
+        self,
+        user_id: str,
+        *,
+        pagination_token: Optional[str] = None,
+        max_results: Optional[int] = None,
+        tweet_fields: Optional[Union[str, List, Tuple]] = None,
+        expansions: Optional[Union[str, List, Tuple]] = None,
+        user_fields: Optional[Union[str, List, Tuple]] = None,
+        media_fields: Optional[Union[str, List, Tuple]] = None,
+        place_fields: Optional[Union[str, List, Tuple]] = None,
+        poll_fields: Optional[Union[str, List, Tuple]] = None,
+        return_json: bool = False,
+    ) -> Union[dict, md.Response]:
+        """
+        Allows you to get information about an authenticated user’s 800 most recent bookmarked Tweets.
+
+        :param user_id: The user ID whose bookmark tweets you would like to retrieve.
+        :param expansions: Fields for the expansions.
+        :param pagination_token: Token for the pagination.
+        :param max_results: The maximum number of results to be returned per page. Number between 1 and the 1000.
+        By default, each page will return 100 results.
+        :param tweet_fields: Fields for the tweet object.
+        :param user_fields: Fields for the user object, Expansion required.
+        :param media_fields: Fields for the media object, Expansion required.
+        :param place_fields: Fields for the place object, Expansion required.
+        :param poll_fields: Fields for the poll object, Expansion required.
+        :param return_json: Type for returned data. If you set True JSON data will be returned.
+        :return:
+            - data: data for the tweets.
+            - includes: expansions data.
+            - meta: pagination details
+        """
+        args = {
+            "expansions": enf_comma_separated(name="expansions", value=expansions),
+            "tweet.fields": enf_comma_separated(
+                name="tweet_fields", value=tweet_fields
+            ),
+            "user.fields": enf_comma_separated(name="user_fields", value=user_fields),
+            "media.fields": enf_comma_separated(
+                name="media_fields", value=media_fields
+            ),
+            "place.fields": enf_comma_separated(
+                name="place_fields", value=place_fields
+            ),
+            "poll.fields": enf_comma_separated(name="poll_fields", value=poll_fields),
+            "max_results": max_results,
+            "pagination_token": pagination_token,
+        }
+        return self._get(
+            url=f"{self.BASE_URL_V2}/users/{user_id}/bookmarks",
+            params=args,
+            cls=md.Tweet,
+            multi=True,
+            return_json=return_json,
+        )
+
+    def bookmark_tweet(self, user_id, tweet_id: str) -> dict:
+        """
+        Causes the user ID of an authenticated user identified in the path parameter to Bookmark the target Tweet provided in the request body.
+
+        :param user_id: The user ID who you are liking a Tweet on behalf of.
+                It must match your user ID which authorize with the access token.
+        :param tweet_id: The ID of the Tweet that you would to bookmark.
+        :return: bookmark status data
+        """
+        resp = self._request(
+            url=f"{self.BASE_URL_V2}/users/{user_id}/bookmarks",
+            verb="POST",
+            json={"tweet_id": tweet_id},
+        )
+        data = self._parse_response(resp=resp)
+        return data
+
+    def bookmark_tweet_remove(self, user_id, tweet_id: str) -> dict:
+        """
+        Allows a user or authenticated user ID to remove a Bookmark of a Tweet.
+
+        :param user_id: The user ID who you are removing a Like of a Tweet on behalf of.
+                It must match your user ID which authorize with the access token.
+        :param tweet_id: The ID of the Tweet that you would remove bookmark.
+        :return: bookmark status data
+        """
+
+        resp = self._request(
+            url=f"{self.BASE_URL_V2}/users/{user_id}/bookmarks/{tweet_id}",
+            verb="DELETE",
+        )
+        data = self._parse_response(resp=resp)
+        return data
+
     def hidden_reply(self, tweet_id: str, hidden: Optional[bool] = True) -> dict:
         """
         Hide or un-hide a reply to a Tweet.

pytwitter/rate_limit.py

@@ -126,6 +126,17 @@ def get_limit(self, auth_type, method="GET"):
     regex=re.compile(r"/users/\d+/likes/\d+"),
     LIMIT_USER_POST=50,
 )
+USER_BOOKMARK_TWEET = Endpoint(
+    resource="/users/:id/bookmarks",
+    regex=re.compile(r"/users/\d+/bookmarks"),
+    LIMIT_USER_GET=180,
+    LIMIT_USER_POST=50,
+)
+USER_BOOKMARK_TWEET_REMOVE = Endpoint(
+    resource="/users/:id/bookmarks/:tweet_id",
+    regex=re.compile(r"/users/\d+/bookmarks/\d+"),
+    LIMIT_USER_DELETE=50,
+)
 TWEET_HIDDEN = Endpoint(
     resource="/tweets/:id/hidden",
     regex=re.compile(r"/tweets/\d+/hidden"),

testdata/apis/tweet/tweets_by_user_bookmark.json

@@ -0,0 +1 @@
+{"data":[{"created_at":"2021-02-18T17:12:47.000Z","source":"Twitter Web App","id":"1362449997430542337","text":"Honored to be the first developer to be featured in @TwitterDev's love fest 🥰♥️😍 https://t.co/g8TsPoZsij"},{"created_at":"2021-02-26T21:38:43.000Z","source":"Twitter Web App","id":"1365416026435854338","text":"We're so happy for our Official Partner @Brandwatch and their big news. https://t.co/3DwWBNSq0o https://t.co/bDUGbgPkKO"},{"created_at":"2020-08-20T16:41:00.000Z","source":"Twitter Web App","id":"1296487407475462144","text":"Check out this feature on @TwitterDev to learn more about how we're mining social media data to make sense of this evolving #publichealth crisis https://t.co/sIFLXRSvEX."},{"created_at":"2020-08-14T18:55:42.000Z","source":"Twitter for Android","id":"1294346980072624128","text":"I awake from five years of slumber https://t.co/OEPVyAFcfB"},{"created_at":"2020-07-14T21:38:10.000Z","source":"Twitter for  iPhone","id":"1283153843367206912","text":"@wongmjane Wish we could tell you more, but I’m only a teapot 👀"}],"meta":{"result_count":5,"next_token":"zldjwdz3w6sba13nbs0mbravfipbtqvbiqplg9h0p4k"}}

tests/apis/test_tweets.py

@@ -70,7 +70,7 @@ def test_get_tweets(api, helpers):
 
 
 @responses.activate
-def test_like_and_unlike_tweet(api_with_user, helpers):
+def test_like_and_unlike_tweet(api_with_user):
     user_id, tweet_id = "123456", "10987654321"
 
     responses.add(
@@ -125,6 +125,51 @@ def test_tweet_liking_users(api, helpers):
     assert resp_json["includes"]["tweets"][0]["id"] == "1383963809702846470"
 
 
+@responses.activate
+def test_get_user_bookmarks(api_with_user, helpers):
+    user_id = "2244994945"
+    tweets_data = helpers.load_json_data(
+        "testdata/apis/tweet/tweets_by_user_bookmark.json"
+    )
+    responses.add(
+        responses.GET,
+        url=f"https://api.twitter.com/2/users/{user_id}/bookmarks",
+        json=tweets_data,
+    )
+
+    resp = api_with_user.get_bookmark_tweets(
+        user_id=user_id,
+        max_results=5,
+        expansions="attachments.media_keys",
+        media_fields="type,duration_ms",
+    )
+    assert len(resp.data) == 5
+    assert resp.data[0].id == "1362449997430542337"
+
+
+@responses.activate
+def test_user_bookmark_tweet_or_remove_tweet(api_with_user):
+    user_id, tweet_id = "2244994945", "1228393702244134912"
+
+    responses.add(
+        responses.POST,
+        url=f"https://api.twitter.com/2/users/{user_id}/bookmarks",
+        json={"data": {"bookmarked": True}},
+    )
+
+    resp = api_with_user.bookmark_tweet(user_id=user_id, tweet_id=tweet_id)
+    assert resp["data"]["bookmarked"]
+
+    responses.add(
+        responses.DELETE,
+        url=f"https://api.twitter.com/2/users/{user_id}/bookmarks/{tweet_id}",
+        json={"data": {"bookmarked": False}},
+    )
+
+    resp = api_with_user.bookmark_tweet_remove(user_id=user_id, tweet_id=tweet_id)
+    assert not resp["data"]["bookmarked"]
+
+
 @responses.activate
 def test_get_tweet_quote_tweets(api, helpers):
     tweets_data = helpers.load_json_data(