Merge pull request #3 from ScrapingAnt/feature/issue1-add-exceptions-handling

feature/issue1-add-exceptions-handling: added eroors, tests, imporoved README

Author: megabotan

README.md

@@ -5,8 +5,9 @@ Python applications. It  provides useful features like parameters encoding to im
 <!-- toc -->
 
 - [Quick Start](#quick-start)
-- [API key](#api-key)
+- [API token](#api-token)
 - [API Reference](#api-reference)
+- [Exceptions](#exceptions)
 - [Examples](#examples)
 
 <!-- tocstop -->
@@ -21,27 +22,25 @@ result = client.general_request('https://example.com')
 print(result.content)
 ```
 
-## API key
-In order to get API key you'll need to register at [ScrapingAnt Service](https://app.scrapingant.com)
+## API token
+In order to get API token you'll need to register at [ScrapingAnt Service](https://app.scrapingant.com)
 
 ## API Reference
 All public classes, methods and their parameters can be inspected in this API reference.
 
 <a name="ScrapingAntClient"></a>
 
-#### [](#ScrapingAntClient) `ScrapingAntClient(token)`
+#### [](#ScrapingAntClient) ScrapingAntClient(token)
 
+Main class of this library. 
 
-| Param | Type | Default |
-| --- | --- | --- |
-| token | <code>string</code> |  |
-
+| Param | Type  |
+| --- | --- |
+| token | <code>string</code> |
 
 * * *
 
-<a name="ScrapingAntClient+scrape"></a>
-
-### [](#ScrapingAntClient+scrape) `ScrapingAntClient.general_request(url, cookies, js_snippet, proxy_country, return_text)` ⇒ Response
+#### [](#ScrapingAntClient+general_request) `ScrapingAntClient.general_request(url, cookies, js_snippet, proxy_country, return_text)` ⇒ Response
 
 https://docs.scrapingant.com/request-response-format#available-parameters
 
@@ -57,7 +56,7 @@ https://docs.scrapingant.com/request-response-format#available-parameters
 
 * * *
 
-### [](#Cookie) Cookie
+#### [](#Cookie) Cookie
 Class defining cookie. Curently supports only name and value
 
 | Param | Type | 
@@ -67,25 +66,29 @@ Class defining cookie. Curently supports only name and value
 
 * * *
 
-### [](#ProxyCountry) ProxyCountry
+#### [](#ProxyCountry) ProxyCountry
 
 Enum containing all available proxy countries
 
 * * *
 
-### [](#Response) Response
+#### [](#Response) Response
 Class defining cookie. Curently supports only name and value
 
 | Param | Type |
 | --- | --- |
 | content | <code>string</code> |
 | cookies | <code>List[Cookie]</code> |
 
-* * *
+## [](#exceptions) Exceptions
 
-### [](#ScrapingantClientException) ScrapingantClientException
+`ScrapingantClientException` is base Exception class, used for all errors. 
 
-`ScrapingantClientException` is base Exception class, used for all errors.
+| Exception | Reason |
+| --- | --- |
+| ScrapingantInvalidTokenException | The API token is wrong or you have exceeded the API calls request limit 
+| ScrapingantInvalidInputException | Invalid value provided. Please, look into error message for more info |
+| ScrapingantInternalException | Something went wrong with the server side code. Try again later or contact ScrapingAnt support |
 
 * * *
 

scrapingant_client/__init__.py

@@ -1,13 +1,21 @@
 from scrapingant_client.client import ScrapingAntClient
 from scrapingant_client.constants import ProxyCountry
 from scrapingant_client.cookie import Cookie
-from scrapingant_client.errors import ScrapingantClientException
+from scrapingant_client.errors import (
+    ScrapingantClientException,
+    ScrapingantInvalidTokenException,
+    ScrapingantInvalidInputException,
+    ScrapingantInternalException,
+)
 from scrapingant_client.response import Response
 
 __all__ = [
     'ScrapingAntClient',
     'ProxyCountry',
     'Cookie',
     'ScrapingantClientException',
+    'ScrapingantInvalidTokenException',
+    'ScrapingantInvalidInputException',
+    'ScrapingantInternalException',
     'Response',
 ]

scrapingant_client/client.py

@@ -4,16 +4,20 @@
 
 import requests
 
-from scrapingant_client.constants import ProxyCountry
+from scrapingant_client.constants import ProxyCountry, SCRAPINGANT_API_BASE_URL
 from scrapingant_client.cookie import Cookie, cookies_list_to_string, cookies_list_from_string
+from scrapingant_client.errors import (
+    ScrapingantInvalidTokenException,
+    ScrapingantInvalidInputException,
+    ScrapingantInternalException,
+)
 from scrapingant_client.response import Response
 from scrapingant_client.utils import base64_encode_string
 
 
 class ScrapingAntClient:
     def __init__(self, token: str):
         self.token = token
-        self.scrapingant_api_base_url = 'https://api.scrapingant.com/v1'
         self.requests_session = requests.Session()
         user_agent = f'ScrapingAntClient ({sys.platform}; Python/{platform.python_version()});'
         self.requests_session.headers.update({
@@ -41,9 +45,15 @@ def general_request(
             request_data['return_text'] = True
 
         response = self.requests_session.post(
-            self.scrapingant_api_base_url + '/general',
+            SCRAPINGANT_API_BASE_URL + '/general',
             json=request_data,
         )
+        if response.status_code == 403:
+            raise ScrapingantInvalidTokenException()
+        elif response.status_code == 422:
+            raise ScrapingantInvalidInputException(response.text)
+        elif response.status_code == 500:
+            raise ScrapingantInternalException()
         json_response = response.json()
         content = json_response['content']
         cookies_string = json_response['cookies']

scrapingant_client/constants.py

@@ -1,5 +1,7 @@
 from enum import Enum
 
+SCRAPINGANT_API_BASE_URL = 'https://api.scrapingant.com/v1'
+
 
 class ProxyCountry(str, Enum):
     brasilia = 'br'

scrapingant_client/errors.py

@@ -1,3 +1,19 @@
 class ScrapingantClientException(Exception):
     """Base class for errors specific to the ScrapingAnt Client."""
     pass
+
+
+class ScrapingantInvalidTokenException(ScrapingantClientException):
+    def __init__(self):
+        message = 'API token is wrong or you have exceeded the API calls request limit'
+        super().__init__(message)
+
+
+class ScrapingantInvalidInputException(ScrapingantClientException):
+    pass
+
+
+class ScrapingantInternalException(ScrapingantClientException):
+    def __init__(self):
+        message = 'Something went wrong with the server side. Please try later or contact support'
+        super().__init__(message)

setup.py

@@ -5,7 +5,7 @@
 
 setuptools.setup(
     name="scrapingant-client",
-    version="0.1.0",
+    version="0.2.0",
     author="andrii.kovalenko",
     author_email="[email protected]",
     license='Apache-2.0',
@@ -32,6 +32,7 @@
         'dev': [
             'pytest>=6,<7',
             'flake8>=3,<4',
+            'responses>=0,<1'
         ]
     }
 )

tests/test_exceptions.py

@@ -0,0 +1,38 @@
+import pytest
+import responses
+
+from scrapingant_client import (
+    ScrapingAntClient,
+    ScrapingantInvalidTokenException,
+    ScrapingantInvalidInputException,
+    ScrapingantInternalException,
+)
+from scrapingant_client.constants import SCRAPINGANT_API_BASE_URL
+
+
+@responses.activate
+def test_invalid_token():
+    responses.add(responses.POST, SCRAPINGANT_API_BASE_URL + '/general',
+                  json={'detail': 'wrong token'}, status=403)
+    client = ScrapingAntClient(token='invalid_token')
+    with pytest.raises(ScrapingantInvalidTokenException):
+        client.general_request('example.com')
+
+
+@responses.activate
+def test_invalid_input():
+    responses.add(responses.POST, SCRAPINGANT_API_BASE_URL + '/general',
+                  json={'detail': 'wrong url'}, status=422)
+    client = ScrapingAntClient(token='some_token')
+    with pytest.raises(ScrapingantInvalidInputException) as e:
+        client.general_request('bad_url')
+    assert '{"detail": "wrong url"}' in str(e)
+
+
+@responses.activate
+def test_internal_server_error():
+    responses.add(responses.POST, SCRAPINGANT_API_BASE_URL + '/general',
+                  json={}, status=500)
+    client = ScrapingAntClient(token='some_token')
+    with pytest.raises(ScrapingantInternalException):
+        client.general_request('bad_url')