Merge pull request #164 from MerleLiuKun/feat-trends

Feat trends

Author: MerleLiuKun

.gitignore

@@ -88,7 +88,7 @@ env.bak/
 venv.bak/
 
 # mkdocs documentation
-/site
+docs/site
 
 # mypy
 .mypy_cache/

README.rst

@@ -105,12 +105,18 @@ Now covers these features:
     - Blocks
     - Mutes
 
+- Usage
+    - Tweets
+
+- Trends
+
 - Spaces
     - Spaces lookup
     - Search Spaces
 
-- Compliance
-    - Batch compliance
+- Direct Messages
+    - Direct Messages lookup
+    - Manage Direct Messages
 
 - Lists
     - List lookup
@@ -120,12 +126,8 @@ Now covers these features:
     - List follows
     - Pinned Lists
 
-- Direct Messages
-    - Direct Messages lookup
-    - Manage Direct Messages
-
-- Usage
-    - Tweets
+- Compliance
+    - Batch compliance
 
 - Media Upload
     - Media Simple upload

docs/docs/usage/trends/trends.md

@@ -0,0 +1,13 @@
+The Trends lookup endpoint allow developers to get the Trends for a location, specified using the where-on-earth id (WOEID).
+
+**Note:** WOEID is a legacy identifier created by Yahoo and has been deprecated. X API uses the numeric value to identify town and country trend locations. 
+Reference our legacy [blog post](https://blog.twitter.com/engineering/en_us/a/2010/woeids-in-twitters-trends.html), or [archived data](https://archive.org/details/geoplanet_data_7.10.0.zip0.)
+
+### Get trends
+
+Get the trends for a location
+
+```python
+api.get_trends_by_woeid(woeid=1)
+# Response(data=[Trend(trend_name='#QuietOnSet', tweet_count=14060), Trend(trend_name='King Charles', tweet_count=42315), Trend(trend_name='Drake Bell', tweet_count=1234)])
+```

docs/mkdocs.yml

@@ -56,6 +56,8 @@ nav:
       - Spaces:
           - Spaces Lookup: usage/spaces/spaces-lookup.md
           - Search Spaces: usage/spaces/search.md
+      - Trends:
+          - Trends: usage/trends/trends.md
       - Lists:
           - List lookup: usage/lists/list-lookup.md
           - Manage Lists: usage/lists/manage-lists.md

pytwitter/api.py

@@ -2068,6 +2068,26 @@ def unmute_user(self, user_id: str, target_user_id: str) -> dict:
         data = self._parse_response(resp)
         return data
 
+    def get_trends_by_woeid(
+        self, woeid: int, return_json: bool = False
+    ) -> Union[dict, md.Response]:
+        """
+        Get the trends for a location.
+
+        :param woeid: The where-on-earth ID (woeid) for a location.
+        :param return_json: Type for returned data. If you set True JSON data will be returned.
+        :return:
+            - data: data for trends
+        """
+
+        return self._get(
+            url=f"{self.BASE_URL_V2}/trends/by/woeid/{woeid}",
+            params=None,
+            cls=md.Trend,
+            multi=True,
+            return_json=return_json,
+        )
+
     def get_space(
         self,
         space_id: str,

pytwitter/models/__init__.py

@@ -8,6 +8,7 @@
 from .space import *  # noqa
 from .list import *  # noqa
 from .stream import *  # noqa
+from .trend import *  # noqa
 from .dm_event import *  # noqa
 from .usage import *  # noqa
 from .ext import *  # noqa

pytwitter/models/ext.py

@@ -21,6 +21,7 @@
     StreamRule,
     TwitterList,
     Usage,
+    Trend,
 )
 
 
@@ -113,6 +114,7 @@ class Response:
             TwitterList,
             DirectMessageEvent,
             Usage,
+            Trend,
             List[User],
             List[Tweet],
             List[Media],
@@ -124,6 +126,7 @@ class Response:
             List[Space],
             List[ComplianceJob],
             List[DirectMessageEvent],
+            List[Trend],
         ]
     ]
     includes: Optional[Includes] = field(default=None, repr=False)

pytwitter/models/trend.py

@@ -0,0 +1,18 @@
+"""
+    Trend Object
+    Refer: https://developer.twitter.com/en/docs/twitter-api/trends/api-reference/get-trends-by-woeid
+"""
+
+from dataclasses import dataclass, field
+
+from .base import BaseModel
+
+
+@dataclass
+class Trend(BaseModel):
+    """
+    A class representing Trend object
+    """
+
+    trend_name: str = field(default=None)
+    tweet_count: int = field(default=None)

testdata/apis/trends/trends_resp.json

@@ -0,0 +1 @@
+{"data":[{"trend_name":"#TEZOSTUESDAY","tweet_count":14869},{"trend_name":"Copenhagen","tweet_count":13005},{"trend_name":"Roses","tweet_count":32193},{"trend_name":"Heroes","tweet_count":69798},{"trend_name":"Cedric","tweet_count":14259},{"trend_name":"#AskSonic","tweet_count":8908},{"trend_name":"Nelson","tweet_count":29841},{"trend_name":"#PSVARS","tweet_count":4915},{"trend_name":"Eddie","tweet_count":34139},{"trend_name":"Saliba","tweet_count":7191},{"trend_name":"Walters","tweet_count":8095},{"trend_name":"Bakayoko","tweet_count":1809},{"trend_name":"Bibby Stockholm","tweet_count":21021},{"trend_name":"Nwaneri","tweet_count":5783},{"trend_name":"Doncaster","tweet_count":3551},{"trend_name":"Kiwior","tweet_count":1535}]}

tests/apis/test_trends.py

@@ -0,0 +1,17 @@
+"""
+    tests for the trends api
+"""
+
+import responses
+
+
+@responses.activate
+def test_get_trends_by_woeid(api, helpers):
+    responses.add(
+        responses.GET,
+        url="https://api.twitter.com/2/trends/by/woeid/1",
+        json=helpers.load_json_data("testdata/apis/trends/trends_resp.json"),
+    )
+
+    resp = api.get_trends_by_woeid(1)
+    assert resp.data[0].trend_name == "#TEZOSTUESDAY"