Merge pull request #31 from Ihor-Bilous/ISSUE-29

Fix issue #29. Add support of Emails Sandbox (Testing) API: Projects

Author: VladimirTaytor

.gitignore

@@ -8,6 +8,9 @@ dist/
 # IntelliJ's project specific settings
 .idea/
 
+# VSCode's project specific settings
+.vscode/
+
 # mypy
 .mypy_cache/
 

README.md

@@ -7,17 +7,17 @@
 
 This Python package offers integration with the [official API](https://api-docs.mailtrap.io/) for [Mailtrap](https://mailtrap.io).
 
-Quickly add email sending functionality to your Python application with Mailtrap.
+Add email sending functionality to your Python application quickly with Mailtrap.
 
 ## Compatibility with previous releases
 
-Versions of this package up to 1.0.1 were a different, unrelated project, that is now maintained as [Sendria](https://github.com/msztolcman/sendria). To continue using it, see [instructions](#information-for-version-1-users).
+Versions of this package up to 1.0.1 were different, unrelated project, that is now maintained as [Sendria](https://github.com/msztolcman/sendria). To continue using it, see [instructions](#information-for-version-1-users).
 
 ## Installation
 
 ### Prerequisites
 
-- Python version 3.6+
+- Python version 3.9+
 
 ### Install package
 
@@ -150,7 +150,7 @@ To setup virtual environments, run tests and linters use:
 tox
 ```
 
-It will create virtual environments with all installed dependencies for each available python interpreter (starting from `python3.6`) on your machine.
+It will create virtual environments with all installed dependencies for each available python interpreter (starting from `python3.9`) on your machine.
 By default, they will be available in `{project}/.tox/` directory. So, for instance, to activate `python3.11` environment, run the following:
 
 ```bash

examples/testing/projects.py

@@ -0,0 +1,29 @@
+from mailtrap import MailtrapClient
+from mailtrap.models.projects import Project
+
+API_TOKEN = "YOU_API_TOKEN"
+ACCOUNT_ID = "YOU_ACCOUNT_ID"
+
+client = MailtrapClient(token=API_TOKEN, account_id=ACCOUNT_ID)
+projects_api = client.testing_api.projects
+
+
+def list_projects() -> list[Project]:
+    return projects_api.get_list()
+
+
+def create_project(project_name: str) -> Project:
+    return projects_api.create(project_name=project_name)
+
+
+def update_project(project_id: str, new_name: str) -> Project:
+    return projects_api.update(project_id, new_name)
+
+
+def delete_project(project_id: str):
+    return projects_api.delete(project_id)
+
+
+if __name__ == "__main__":
+    projects = list_projects()
+    print(projects)

mailtrap/api/__init__.py

@@ -0,0 +1,39 @@
+from mailtrap.http import HttpClient
+from mailtrap.models.common import DeletedObject
+from mailtrap.models.projects import Project
+
+
+class ProjectsApi:
+    def __init__(self, client: HttpClient, account_id: str) -> None:
+        self._account_id = account_id
+        self._client = client
+
+    def get_list(self) -> list[Project]:
+        response = self._client.get(f"/api/accounts/{self._account_id}/projects")
+        return [Project(**project) for project in response]
+
+    def get_by_id(self, project_id: int) -> Project:
+        response = self._client.get(
+            f"/api/accounts/{self._account_id}/projects/{project_id}"
+        )
+        return Project(**response)
+
+    def create(self, project_name: str) -> Project:
+        response = self._client.post(
+            f"/api/accounts/{self._account_id}/projects",
+            json={"project": {"name": project_name}},
+        )
+        return Project(**response)
+
+    def update(self, project_id: int, project_name: str) -> Project:
+        response = self._client.patch(
+            f"/api/accounts/{self._account_id}/projects/{project_id}",
+            json={"project": {"name": project_name}},
+        )
+        return Project(**response)
+
+    def delete(self, project_id: int) -> DeletedObject:
+        response = self._client.delete(
+            f"/api/accounts/{self._account_id}/projects/{project_id}",
+        )
+        return DeletedObject(**response)

mailtrap/api/resources/__init__.py

@@ -0,0 +1,17 @@
+from typing import Optional
+
+from mailtrap.api.resources.projects import ProjectsApi
+from mailtrap.http import HttpClient
+
+
+class TestingApi:
+    def __init__(
+        self, client: HttpClient, account_id: str, inbox_id: Optional[str] = None
+    ) -> None:
+        self._account_id = account_id
+        self._inbox_id = inbox_id
+        self._client = client
+
+    @property
+    def projects(self) -> ProjectsApi:
+        return ProjectsApi(account_id=self._account_id, client=self._client)

mailtrap/api/resources/projects.py

@@ -1,12 +1,16 @@
 from typing import NoReturn
 from typing import Optional
 from typing import Union
+from typing import cast
 
 import requests
 
+from mailtrap.api.testing import TestingApi
+from mailtrap.config import GENERAL_HOST
 from mailtrap.exceptions import APIError
 from mailtrap.exceptions import AuthorizationError
 from mailtrap.exceptions import ClientConfigurationError
+from mailtrap.http import HttpClient
 from mailtrap.mail.base import BaseMail
 
 
@@ -23,17 +27,28 @@ def __init__(
         api_port: int = DEFAULT_PORT,
         bulk: bool = False,
         sandbox: bool = False,
+        account_id: Optional[str] = None,
         inbox_id: Optional[str] = None,
     ) -> None:
         self.token = token
         self.api_host = api_host
         self.api_port = api_port
         self.bulk = bulk
         self.sandbox = sandbox
+        self.account_id = account_id
         self.inbox_id = inbox_id
 
         self._validate_itself()
 
+    @property
+    def testing_api(self) -> TestingApi:
+        self._validate_account_id()
+        return TestingApi(
+            account_id=cast(str, self.account_id),
+            inbox_id=self.inbox_id,
+            client=HttpClient(host=GENERAL_HOST, headers=self.headers),
+        )
+
     def send(self, mail: BaseMail) -> dict[str, Union[bool, list[str]]]:
         response = requests.post(
             self.api_send_url, headers=self.headers, json=mail.api_data
@@ -98,3 +113,7 @@ def _validate_itself(self) -> None:
 
         if self.bulk and self.sandbox:
             raise ClientConfigurationError("bulk mode is not allowed in sandbox mode")
+
+    def _validate_account_id(self) -> None:
+        if not self.account_id:
+            raise ClientConfigurationError("`account_id` is required for Testing API")

mailtrap/api/testing.py

@@ -0,0 +1,3 @@
+GENERAL_HOST = "mailtrap.io"
+
+DEFAULT_REQUEST_TIMEOUT = 30  # in seconds

mailtrap/client.py

@@ -0,0 +1,92 @@
+from typing import Any
+from typing import NoReturn
+from typing import Optional
+
+from requests import Response
+from requests import Session
+
+from mailtrap.config import DEFAULT_REQUEST_TIMEOUT
+from mailtrap.exceptions import APIError
+from mailtrap.exceptions import AuthorizationError
+
+
+class HttpClient:
+    def __init__(
+        self,
+        host: str,
+        headers: Optional[dict[str, str]] = None,
+        timeout: int = DEFAULT_REQUEST_TIMEOUT,
+    ):
+        self._host = host
+        self._session = Session()
+        self._session.headers.update(headers or {})
+        self._timeout = timeout
+
+    def get(self, path: str, params: Optional[dict[str, Any]] = None) -> Any:
+        response = self._session.get(
+            self._url(path), params=params, timeout=self._timeout
+        )
+        return self._process_response(response)
+
+    def post(self, path: str, json: Optional[dict[str, Any]] = None) -> Any:
+        response = self._session.post(self._url(path), json=json, timeout=self._timeout)
+        return self._process_response(response)
+
+    def put(self, path: str, json: Optional[dict[str, Any]] = None) -> Any:
+        response = self._session.put(self._url(path), json=json, timeout=self._timeout)
+        return self._process_response(response)
+
+    def patch(self, path: str, json: Optional[dict[str, Any]] = None) -> Any:
+        response = self._session.patch(self._url(path), json=json, timeout=self._timeout)
+        return self._process_response(response)
+
+    def delete(self, path: str) -> Any:
+        response = self._session.delete(self._url(path), timeout=self._timeout)
+        return self._process_response(response)
+
+    def _url(self, path: str) -> str:
+        return f"https://{self._host}/{path.lstrip('/')}"
+
+    def _process_response(self, response: Response) -> Any:
+        if not response.ok:
+            self._handle_failed_response(response)
+        return response.json()
+
+    def _handle_failed_response(self, response: Response) -> NoReturn:
+        status_code = response.status_code
+        try:
+            data = response.json()
+        except ValueError as exc:
+            raise APIError(status_code, errors=["Unknown Error"]) from exc
+
+        errors = self._extract_errors(data)
+
+        if status_code == 401:
+            raise AuthorizationError(errors=errors)
+
+        raise APIError(status_code, errors=errors)
+
+    @staticmethod
+    def _extract_errors(data: dict[str, Any]) -> list[str]:
+        def flatten_errors(errors: Any) -> list[str]:
+            if isinstance(errors, list):
+                return [str(error) for error in errors]
+
+            if isinstance(errors, dict):
+                flat_errors = []
+                for key, value in errors.items():
+                    if isinstance(value, list):
+                        flat_errors.extend([f"{key}: {v}" for v in value])
+                    else:
+                        flat_errors.append(f"{key}: {value}")
+                return flat_errors
+
+            return [str(errors)]
+
+        if "errors" in data:
+            return flatten_errors(data["errors"])
+
+        if "error" in data:
+            return flatten_errors(data["error"])
+
+        return ["Unknown error"]