feat(quotas): add quota route

Author: jguerreiro

.pre-commit-config.yaml

@@ -1,7 +1,7 @@
 default_stages: [commit]
 repos:
   - repo: https://github.com/ambv/black
-    rev: 21.5b0
+    rev: 21.5b1
     hooks:
       - id: black
         language_version: python3
@@ -18,7 +18,7 @@ repos:
       - id: mypy
 
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v3.4.0
+    rev: v4.0.1
     hooks:
       - id: check-json
       - id: check-added-large-files

Pipfile

@@ -1,15 +1,15 @@
 [[source]]
+name = "pypi"
 url = "https://pypi.python.org/simple"
 verify_ssl = true
-name = "pypi"
 
 [packages]
-pygitguardian = {editable = true,path = "."}
 marshmallow = ">=3.5"
+pygitguardian = {editable = true, path = "."}
 requests = ">=2"
 
 [dev-packages]
-black = "==21.5b0"
+black = "==21.5b1"
 coverage = "*"
 flake8 = "*"
 flake8-isort = "*"

Pipfile.lock

@@ -10,7 +10,7 @@
     DEFAULT_TIMEOUT,
     MULTI_DOCUMENT_LIMIT,
 )
-from .models import Detail, Document, MultiScanResult, ScanResult
+from .models import Detail, Document, MultiScanResult, QuotaResponse, ScanResult
 
 
 def load_detail(resp: Response) -> Detail:
@@ -244,3 +244,28 @@ def multi_content_scan(
         obj.status_code = resp.status_code
 
         return obj
+
+    def quota_overview(
+        self,
+        extra_headers: Optional[Dict[str, str]] = None,
+    ) -> Union[Detail, QuotaResponse]:
+        """
+        content_scan handles the /scan endpoint of the API
+
+        :param extra_headers: additional headers to add to the request
+        :return: Detail or Quota response and status code
+        """
+
+        resp = self.get(
+            endpoint="quotas",
+            extra_headers=extra_headers,
+        )
+
+        if is_ok(resp):
+            obj = QuotaResponse.SCHEMA.load(resp.json())
+        else:
+            obj = load_detail(resp)
+
+        obj.status_code = resp.status_code
+
+        return obj

pygitguardian/client.py

@@ -1,3 +1,4 @@
+from datetime import date
 from typing import ClassVar, Dict, List, Optional
 
 from marshmallow import (
@@ -367,3 +368,73 @@ def __str__(self):
                 ]
             ),
         )
+
+
+class QuotaSchema(Schema):
+    count = fields.Int()
+    limit = fields.Int()
+    remaining = fields.Int()
+    since = fields.Date()
+
+    @post_load
+    def make_quota(self, data, **kwargs):
+        return Quota(**data)
+
+
+class Quota(Base):
+    """
+    Quota describes a quota category in the GitGuardian API.
+    Allows you to check your current available quota.
+    Example:
+    {"count": 2,
+    "limit": 5000,
+    "remaining": 4998,
+    "since": "2021-04-18"}
+    """
+
+    SCHEMA = QuotaSchema()
+
+    def __init__(self, count: int, limit: int, remaining: int, since: date, **kwargs):
+        super().__init__()
+        self.count = count
+        self.limit = limit
+        self.remaining = remaining
+        self.since = since
+
+    def __repr__(self):
+        return (
+            "count:{0}, "
+            "limit:{1}, "
+            "remaining:{2}, "
+            "since:{3}".format(self.count, self.limit, self.remaining, repr(self.since))
+        )
+
+
+class QuotaResponseSchema(Schema):
+    content = fields.Nested(QuotaSchema)
+
+    @post_load
+    def make_quota_response(self, data, **kwargs):
+        return QuotaResponse(**data)
+
+
+class QuotaResponse(Base):
+    """
+    Quota describes a quota category in the GitGuardian API.
+    Allows you to check your current available quota.
+    Example:
+    {"content": {
+        "count": 2,
+        "limit": 5000,
+        "remaining": 4998,
+        "since": "2021-04-18"}}
+    """
+
+    SCHEMA = QuotaResponseSchema()
+
+    def __init__(self, content: Quota, **kwargs):
+        super().__init__()
+        self.content = content
+
+    def __repr__(self):
+        return "content:{0}".format(repr(self.content))

pygitguardian/models.py

@@ -0,0 +1,38 @@
+interactions:
+  - request:
+      body: null
+      headers:
+        Accept:
+          - "*/*"
+        Accept-Encoding:
+          - gzip, deflate
+        Connection:
+          - keep-alive
+        User-Agent:
+          - pygitguardian/1.1.3 (Linux;py3.9.5)
+      method: GET
+      uri: https://api.gitguardian.com/v1/quotas
+    response:
+      body:
+        string: '{"content": {"count": 2,"limit": 5000,"remaining": 4998,"since": "2021-04-18"}}'
+      headers:
+        Access-Control-Expose-Headers:
+          - X-App-Version
+        Connection:
+          - keep-alive
+        Content-Length:
+          - "79"
+        Content-Type:
+          - application/json
+        Date:
+          - Wed, 19 May 2021 15:57:19 GMT
+        Referrer-Policy:
+          - same-origin
+        Server:
+          - nginx
+        Strict-Transport-Security:
+          - max-age=31536000; includeSubDomains
+      status:
+        code: 200
+        message: OK
+version: 1

tests/cassettes/quota.yaml

@@ -1,5 +1,6 @@
 import json
-from typing import Dict, List, Optional, Type
+from datetime import date
+from typing import Any, Dict, List, Optional, Type
 from unittest.mock import Mock, patch
 
 import pytest
@@ -13,7 +14,7 @@
     DOCUMENT_SIZE_THRESHOLD_BYTES,
     MULTI_DOCUMENT_LIMIT,
 )
-from pygitguardian.models import Detail, MultiScanResult, ScanResult
+from pygitguardian.models import Detail, MultiScanResult, QuotaResponse, ScanResult
 
 from .conftest import base_uri, my_vcr
 
@@ -432,7 +433,7 @@ def test_content_not_ok():
 def test_content_scan(
     client: GGClient,
     name: str,
-    to_scan: Dict[str, str],
+    to_scan: Dict[str, Any],
     has_secrets: bool,
     has_policy_breaks: bool,
     policy_break_count: int,
@@ -505,7 +506,7 @@ def test_assert_content_type(client: GGClient):
 def test_extra_headers(
     request_mock: Mock,
     client: GGClient,
-    session_headers: Dict[str, str],
+    session_headers: Any,
     extra_headers: Optional[Dict[str, str]],
     expected_headers: Dict[str, str],
 ):
@@ -534,3 +535,23 @@ def test_extra_headers(
     assert request_mock.called
     _, kwargs = request_mock.call_args
     assert expected_headers == kwargs["headers"]
+
+
+def test_quota_overview(client: GGClient):
+    with my_vcr.use_cassette("quota.yaml"):
+        quota_response = client.quota_overview()
+        assert type(repr(quota_response)) == str
+        assert type(str(quota_response)) == str
+        assert quota_response.status_code == 200
+        if isinstance(quota_response, QuotaResponse):
+            assert quota_response.content.limit == 5000
+            assert quota_response.content.count == 2
+            assert quota_response.content.remaining == 4998
+            assert quota_response.content.since == date(2021, 4, 18)
+        else:
+            pytest.fail("returned should be a QuotaResponse")
+
+        assert type(quota_response.to_dict()) == dict
+        quota_response_json = quota_response.to_json()
+        assert type(quota_response_json) == str
+        assert type(json.loads(quota_response_json)) == dict