feat(usage): ✅ Add tests and docs for usage tweets

Author: MerleLiuKun

README.rst

@@ -124,6 +124,9 @@ Now covers these features:
     - Direct Messages lookup
     - Manage Direct Messages
 
+- Usage
+    - Tweets
+
 - Media Upload
     - Media Simple upload
     - Media Chunked upload

docs/docs/usage/usage/tweets.md

@@ -0,0 +1,21 @@
+The Usage API in the Twitter API v2 allows developers to programmatically retrieve their project usage. Using thie endpoint, developers can keep a track and monitor of the number of Tweets they have pulled for a given billing cycle.
+
+You can learn more about the Usage API in the [docs](https://developer.twitter.com/en/docs/twitter-api/usage/tweets/introduction).
+
+!!! tip "Note"
+    
+        The Usage API need `OAuth 2.0 App-only`.
+
+### Get usage
+
+Get the Tweet usage within the context of a project
+
+```python
+from pytwitter import Api
+
+api = Api(bearer_token='your bearer token')
+
+resp = api.get_usage_tweets(days=10, usage_fields=["daily_client_app_usage", "daily_project_usage"])
+print(resp.data)
+# Usage(cap_reset_day=28, project_id='123456789', project_cap='50000000', project_usage='11910737',...)
+```

docs/mkdocs.yml

@@ -68,6 +68,8 @@ nav:
       - Direct Messages:
           - Direct Messages lookup: usage/direct-messages/direct-messages-lookup.md
           - Manage Direct Messages: usage/direct-messages/manage-direct-messages.md
+      - Usage:
+          - Tweets: usage/usage/tweets.md
       - Steaming: usage/streaming.md
   - Changelog: CHANGELOG.md
 

pytwitter/rate_limit.py

@@ -364,6 +364,12 @@ def get_limit(self, auth_type, method="GET"):
     LIMIT_APP_GET=200,
 )
 
+USAGE_TWEETS = Endpoint(
+    resource="/usage/tweets",
+    regex=re.compile(r"/usage/tweets"),
+    LIMIT_APP_GET=50,
+)
+
 MEDIA_UPLOAD = Endpoint(
     resource="/media/upload.json",
     regex=re.compile(r"/media/upload.json"),
@@ -425,6 +431,7 @@ def get_limit(self, auth_type, method="GET"):
     DM_MESSAGE_TO_PARTICIPANT,
     DM_MESSAGE_TO_CONVERSATION,
     DM_CONVERSATIONS,
+    USAGE_TWEETS,
     MEDIA_UPLOAD,
 ]
 

testdata/apis/usage/usage_tweets_resp.json

@@ -0,0 +1 @@
+{"data":{"cap_reset_day":28,"project_cap":"50000000","project_id":"123457578435","project_usage":"11174038"}}

tests/apis/test_usage.py

@@ -0,0 +1,17 @@
+"""
+    tests for usage api
+"""
+
+import responses
+
+
+@responses.activate
+def test_get_usage_tweets(api, helpers):
+    responses.add(
+        responses.GET,
+        url=f"https://api.twitter.com/2/usage/tweets",
+        json=helpers.load_json_data("testdata/apis/usage/usage_tweets_resp.json"),
+    )
+
+    resp = api.get_usage_tweets()
+    assert resp.data.cap_reset_day == 28