Merge pull request #149 from MerleLiuKun/feat-usage

Feat usage

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/api.py

@@ -451,6 +451,7 @@ def _get(
                 errors=[md.Error.new_from_json_dict(err) for err in errors]
                 if errors is not None
                 else None,
+                _json=resp_json,
             )
             return res
 
@@ -3257,3 +3258,34 @@ def create_conversation(
             if return_json
             else md.DirectMessageCreateResponse.new_from_json_dict(data["data"])
         )
+
+    def get_usage_tweets(
+        self,
+        *,
+        days: Optional[int] = None,
+        usage_fields: Optional[Union[str, List, Tuple]] = None,
+        return_json: bool = False,
+    ) -> Union[dict, md.Response]:
+        """
+        Get the Tweet usage within the context of a project
+
+        Note: This need OAuth2.0 App-only auth.
+
+        :param days: The number of days for which you need the Tweet usage for. Up to 90 days.
+        :param usage_fields: Fields for the usage.
+        :param return_json: Type for returned data. If you set True JSON data will be returned.
+        :return: Usage data response.
+        """
+        args = {
+            "days": days,
+            "usage.fields": enf_comma_separated(
+                name="usage_fields",
+                value=usage_fields,
+            ),
+        }
+        return self._get(
+            url=f"{self.BASE_URL_V2}/usage/tweets",
+            params=args,
+            cls=md.Usage,
+            return_json=return_json,
+        )

pytwitter/models/__init__.py

@@ -9,4 +9,5 @@
 from .list import *  # noqa
 from .stream import *  # noqa
 from .dm_event import *  # noqa
+from .usage import *  # noqa
 from .ext import *  # noqa

pytwitter/models/base.py

@@ -29,5 +29,5 @@ def new_from_json_dict(
             return None
         c = cls.from_dict(data, infer_missing=infer_missing)
         # save origin data
-        cls._json = data
+        c._json = data
         return c

pytwitter/models/ext.py

@@ -19,6 +19,7 @@
     ComplianceJob,
     StreamRule,
     TwitterList,
+    Usage,
 )
 
 
@@ -110,6 +111,7 @@ class Response:
             ComplianceJob,
             TwitterList,
             DirectMessageEvent,
+            Usage,
             List[User],
             List[Tweet],
             List[Media],
@@ -126,3 +128,5 @@ class Response:
     includes: Optional[Includes] = field(default=None, repr=False)
     meta: Optional[Meta] = field(default=None, repr=False)
     errors: Optional[List[Error]] = field(default=None, repr=False)
+    # inline field to keep origin response json data
+    _json: Optional[dict] = field(default=None, repr=False)

pytwitter/models/usage.py

@@ -0,0 +1,40 @@
+"""
+    Usage object
+    Refer:https://developer.twitter.com/en/docs/twitter-api/usage/tweets/api-reference/get-usage-tweets
+"""
+
+from dataclasses import dataclass, field
+from typing import Optional, List
+
+from .base import BaseModel
+
+
+@dataclass
+class UsageUsage(BaseModel):
+    date: Optional[str] = field(default=None)
+    usage: Optional[str] = field(default=None)
+
+
+@dataclass
+class DailyProjectUsage(BaseModel):
+    project_id: Optional[str] = field(default=None)
+    usage: Optional[List[UsageUsage]] = field(default=None, repr=False)
+
+
+@dataclass
+class DailyClientAppUsage(BaseModel):
+    client_app_id: Optional[str] = field(default=None)
+    usage_result_count: Optional[int] = field(default=None)
+    usage: Optional[List[UsageUsage]] = field(default=None, repr=False)
+
+
+@dataclass
+class Usage(BaseModel):
+    cap_reset_day: Optional[int] = field(default=None)
+    project_id: Optional[str] = field(default=None)
+    project_cap: Optional[str] = field(default=None)
+    project_usage: Optional[str] = field(default=None)
+    daily_project_usage: Optional[DailyProjectUsage] = field(default=None, repr=False)
+    daily_client_app_usage: Optional[List[DailyClientAppUsage]] = field(
+        default=None, repr=False
+    )

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"}}