perses-api-sdk 0.1.0__py3-none-any.whl

perses_api/__init__.py

@@ -0,0 +1,36 @@
+from .model import APIModel
+from .api import Api
+from .project import Project
+from .dashboard import Dashboard
+from .ephemeral_dashboard import EphemeralDashboard
+from .datasource import ProjectDatasource, GlobalDatasource
+from .variable import ProjectVariable, GlobalVariable
+from .role import ProjectRole, GlobalRole
+from .role_binding import ProjectRoleBinding, GlobalRoleBinding
+from .secret import ProjectSecret, GlobalSecret
+from .user import User
+from .plugin import Plugin
+from .migrate import Migrate
+from .validate import Validate
+
+__all__ = [
+    "APIModel",
+    "Api",
+    "Project",
+    "Dashboard",
+    "EphemeralDashboard",
+    "ProjectDatasource",
+    "GlobalDatasource",
+    "ProjectVariable",
+    "GlobalVariable",
+    "ProjectRole",
+    "GlobalRole",
+    "ProjectRoleBinding",
+    "GlobalRoleBinding",
+    "ProjectSecret",
+    "GlobalSecret",
+    "User",
+    "Plugin",
+    "Migrate",
+    "Validate",
+]

perses_api/_base.py

@@ -0,0 +1,136 @@
+from __future__ import annotations
+
+import logging
+
+from .api import Api
+from .model import APIModel, RequestsMethods
+
+
+class ResourceBase:
+    """The class includes all necessary base methods to access dual-scoped Perses resources
+
+    Args:
+        perses_api_model (APIModel): Inject a Perses API model object that includes all necessary values and information
+
+    Attributes:
+        api (Api): This is where we store the api
+    """
+
+    def __init__(self, perses_api_model: APIModel):
+        self.api = Api(perses_api_model)
+
+    def _base_path(self) -> str:
+        """The method returns the base API path for the resource type
+
+        Raises:
+            NotImplementedError: Subclasses must implement this method
+
+        Returns:
+            str: The base API path
+        """
+        raise NotImplementedError
+
+    def _get_all(self, name: str = None) -> list:
+        """The method includes a functionality to retrieve all resources, optionally filtered by name
+
+        Args:
+            name (str): Specify a name to filter the results (default None)
+
+        Raises:
+            Exception: Unspecified error by executing the API call
+
+        Returns:
+            list: A list of resource dicts
+        """
+        path = self._base_path()
+        if name:
+            path = f"{path}?name={name}"
+        result = self.api.call_the_api(path)
+        if not isinstance(result, list):
+            logging.error(f"Failed to retrieve resources from {self._base_path()}.")
+            raise Exception(result)
+        return result
+
+    def _get_one(self, name: str) -> dict:
+        """The method includes a functionality to retrieve a single resource by name
+
+        Args:
+            name (str): Specify the name of the resource to retrieve
+
+        Raises:
+            ValueError: Missed specifying a necessary value
+            Exception: Unspecified error by executing the API call
+
+        Returns:
+            dict: The resource dict
+        """
+        if not name:
+            raise ValueError("name must not be empty")
+        result = self.api.call_the_api(f"{self._base_path()}/{name}")
+        if not isinstance(result, dict):
+            logging.error(f"Failed to retrieve resource: {name}")
+            raise Exception(result)
+        return result
+
+    def _create(self, body) -> dict:
+        """The method includes a functionality to create a new resource
+
+        Args:
+            body (BaseModel): Specify the resource body as a Pydantic model instance
+
+        Raises:
+            Exception: Unspecified error by executing the API call
+
+        Returns:
+            dict: The created resource dict
+        """
+        result = self.api.call_the_api(
+            self._base_path(),
+            method=RequestsMethods.POST,
+            json_complete=body.model_dump_json(by_alias=True, exclude_none=True),
+        )
+        if not isinstance(result, dict):
+            logging.error(f"Failed to create resource at {self._base_path()}.")
+            raise Exception(result)
+        return result
+
+    def _update(self, name: str, body) -> dict:
+        """The method includes a functionality to update an existing resource by name
+
+        Args:
+            name (str): Specify the name of the resource to update
+            body (BaseModel): Specify the updated resource body as a Pydantic model instance
+
+        Raises:
+            ValueError: Missed specifying a necessary value
+            Exception: Unspecified error by executing the API call
+
+        Returns:
+            dict: The updated resource dict
+        """
+        if not name:
+            raise ValueError("name must not be empty")
+        result = self.api.call_the_api(
+            f"{self._base_path()}/{name}",
+            method=RequestsMethods.PUT,
+            json_complete=body.model_dump_json(by_alias=True, exclude_none=True),
+        )
+        if not isinstance(result, dict):
+            logging.error(f"Failed to update resource: {name}")
+            raise Exception(result)
+        return result
+
+    def _delete(self, name: str) -> None:
+        """The method includes a functionality to delete a resource by name
+
+        Args:
+            name (str): Specify the name of the resource to delete
+
+        Raises:
+            ValueError: Missed specifying a necessary value
+        """
+        if not name:
+            raise ValueError("name must not be empty")
+        self.api.call_the_api(
+            f"{self._base_path()}/{name}", method=RequestsMethods.DELETE
+        )

perses_api/api.py

@@ -0,0 +1,190 @@
+from __future__ import annotations
+
+import asyncio
+import base64
+import json
+import logging
+from typing import Any, Union
+
+import httpx
+
+from .model import APIModel, RequestsMethods
+
+
+class Api:
+    """The class includes all necessary methods to access the Perses API
+
+    Args:
+        perses_api_model (APIModel): Inject a Perses API model object that includes all necessary values and information
+
+    Attributes:
+        perses_api_model (APIModel): This is where we store the perses_api_model
+    """
+
+    def __init__(self, perses_api_model: APIModel):
+        self.perses_api_model = perses_api_model
+
+    def call_the_api(
+        self,
+        api_call: str,
+        method: RequestsMethods = RequestsMethods.GET,
+        json_complete: str = None,
+        response_status_code: bool = False,
+    ) -> Any:
+        """The method includes a functionality to execute a defined API call against the Perses endpoints
+
+        Args:
+            api_call (str): Specify the API call path relative to the host
+            method (RequestsMethods): Specify the HTTP method to use (default GET)
+            json_complete (str): Specify the JSON-serialised request body for POST and PUT requests (default None)
+            response_status_code (bool): Specify if the HTTP status code should be injected into the response dict (default False)
+
+        Raises:
+            ValueError: Missed specifying a necessary value
+            Exception: Unspecified error by executing the API call
+
+        Returns:
+            any: The API response as a parsed dict or list, or the raw httpx.Response for non-JSON responses
+        """
+        api_url = f"{self.perses_api_model.host}{api_call}"
+        headers = dict(self.perses_api_model.headers or {})
+
+        if self.perses_api_model.token:
+            headers["Authorization"] = f"Bearer {self.perses_api_model.token}"
+        elif self.perses_api_model.username and self.perses_api_model.password:
+            credentials = base64.b64encode(
+                f"{self.perses_api_model.username}:{self.perses_api_model.password}".encode()
+            ).decode("utf-8")
+            headers["Authorization"] = f"Basic {credentials}"
+
+        headers["Content-Type"] = "application/json"
+        headers["Accept"] = "application/json"
+
+        http = self.create_the_http_api_client(headers)
+
+        if self.perses_api_model.http2_support:
+
+            async def _run():
+                async with http:
+                    return self._check_the_api_call_response(
+                        await self._send_request(http, method, api_url, json_complete),
+                        response_status_code,
+                    )
+
+            return asyncio.run(_run())
+
+        response = self._send_request(http, method, api_url, json_complete)
+        return self._check_the_api_call_response(response, response_status_code)
+
+    def create_the_http_api_client(
+        self, headers: dict = None
+    ) -> Union[httpx.Client, httpx.AsyncClient]:
+        """The method includes a functionality to create the HTTP client based on the API model configuration
+
+        Args:
+            headers (dict): Specify the HTTP headers to attach to every request (default None)
+
+        Returns:
+            Union[httpx.Client, httpx.AsyncClient]: A configured sync or async httpx client
+        """
+        limits = httpx.Limits(max_connections=self.perses_api_model.num_pools)
+
+        if self.perses_api_model.http2_support:
+            transport = httpx.AsyncHTTPTransport(
+                retries=self.perses_api_model.retries,
+                http2=True,
+            )
+            return httpx.AsyncClient(
+                http2=True,
+                limits=limits,
+                timeout=self.perses_api_model.timeout,
+                headers=headers,
+                transport=transport,
+                verify=self.perses_api_model.ssl_context or True,
+                follow_redirects=self.perses_api_model.follow_redirects,
+            )
+
+        transport = httpx.HTTPTransport(
+            verify=self.perses_api_model.ssl_context or True,
+            retries=self.perses_api_model.retries,
+        )
+        return httpx.Client(
+            limits=limits,
+            timeout=self.perses_api_model.timeout,
+            headers=headers,
+            transport=transport,
+            verify=self.perses_api_model.ssl_context or True,
+            follow_redirects=self.perses_api_model.follow_redirects,
+        )
+
+    def _send_request(
+        self,
+        http: Union[httpx.Client, httpx.AsyncClient],
+        method: RequestsMethods,
+        api_url: str,
+        json_complete: str,
+    ) -> Any:
+        """The method includes a functionality to dispatch a single HTTP request using the provided client
+
+        Args:
+            http (Union[httpx.Client, httpx.AsyncClient]): Specify the httpx client to use for the request
+            method (RequestsMethods): Specify the HTTP method
+            api_url (str): Specify the fully-qualified request URL
+            json_complete (str): Specify the JSON-serialised request body for POST and PUT (default None)
+
+        Raises:
+            ValueError: Missed specifying a necessary value for POST or PUT requests
+
+        Returns:
+            any: The raw httpx response object
+        """
+        if method in (RequestsMethods.GET, RequestsMethods.DELETE):
+            return http.request(method.value, api_url)
+        if json_complete is None:
+            logging.error("Please define the json_complete.")
+            raise ValueError(f"json_complete is required for {method.value}")
+        return http.request(method.value, api_url, content=json_complete)
+
+    @staticmethod
+    def _check_the_api_call_response(
+        response: Any, response_status_code: bool = False
+    ) -> Any:
+        """The method includes a functionality to parse the API response and optionally inject the HTTP status code
+
+        Args:
+            response (any): Specify the raw httpx response object
+            response_status_code (bool): Specify if the HTTP status code should be injected into the response (default False)
+
+        Returns:
+            any: The parsed JSON response as dict or list, or the raw response for non-JSON bodies
+        """
+        if Api._check_if_valid_json(response.text):
+            json_response = json.loads(response.text)
+            if response_status_code:
+                if isinstance(json_response, dict):
+                    json_response["status"] = response.status_code
+                elif isinstance(json_response, list) and json_response:
+                    json_response[0]["status"] = response.status_code
+            return json_response
+        else:
+            if response_status_code:
+                return {"status": response.status_code, "data": response.text}
+            return response
+
+    @staticmethod
+    def _check_if_valid_json(response: str) -> bool:
+        """The method includes a functionality to check if the given string is valid JSON
+
+        Args:
+            response (str): Specify the string to validate
+
+        Returns:
+            bool: True if the string is valid JSON, False otherwise
+        """
+        if not response or response.strip() in ("", "null"):
+            return False
+        try:
+            json.loads(response)
+            return True
+        except (TypeError, ValueError):
+            return False

perses_api/dashboard.py

@@ -0,0 +1,148 @@
+from __future__ import annotations
+
+import logging
+
+from .api import Api
+from .model import APIModel, APIEndpoints, RequestsMethods
+from .model import Dashboard as DashboardModel
+
+
+class Dashboard:
+    """The class includes all necessary methods to access the Perses dashboards API
+
+    Args:
+        perses_api_model (APIModel): Inject a Perses API model object that includes all necessary values and information
+
+    Attributes:
+        api (Api): This is where we store the api
+    """
+
+    def __init__(self, perses_api_model: APIModel):
+        self.api = Api(perses_api_model)
+
+    def get_dashboards(self, project_name: str, name: str = None) -> list:
+        """The method includes a functionality to retrieve all dashboards within a project
+
+        Args:
+            project_name (str): Specify the name of the project to list dashboards for
+            name (str): Specify a name to filter the results (default None)
+
+        Raises:
+            ValueError: Missed specifying a necessary value
+            Exception: Unspecified error by executing the API call
+
+        Returns:
+            list: A list of dashboard dicts
+        """
+        if not project_name:
+            raise ValueError("project_name must not be empty")
+        path = APIEndpoints.DASHBOARDS.value.format(project=project_name)
+        if name:
+            path = f"{path}?name={name}"
+        result = self.api.call_the_api(path)
+        if not isinstance(result, list):
+            logging.error("Failed to retrieve dashboards.")
+            raise Exception(result)
+        return result
+
+    def get_dashboard(self, project_name: str, name: str) -> dict:
+        """The method includes a functionality to retrieve a single dashboard by name
+
+        Args:
+            project_name (str): Specify the name of the project the dashboard belongs to
+            name (str): Specify the name of the dashboard to retrieve
+
+        Raises:
+            ValueError: Missed specifying a necessary value
+            Exception: Unspecified error by executing the API call
+
+        Returns:
+            dict: The dashboard dict
+        """
+        if not project_name:
+            raise ValueError("project_name must not be empty")
+        if not name:
+            raise ValueError("name must not be empty")
+        result = self.api.call_the_api(
+            APIEndpoints.DASHBOARD.value.format(project=project_name, name=name)
+        )
+        if not isinstance(result, dict):
+            logging.error(f"Failed to retrieve dashboard: {name}")
+            raise Exception(result)
+        return result
+
+    def create_dashboard(self, project_name: str, dashboard: DashboardModel) -> dict:
+        """The method includes a functionality to create a new dashboard within a project
+
+        Args:
+            project_name (str): Specify the name of the project to create the dashboard in
+            dashboard (Dashboard): Specify the dashboard resource to create
+
+        Raises:
+            ValueError: Missed specifying a necessary value
+            Exception: Unspecified error by executing the API call
+
+        Returns:
+            dict: The created dashboard dict
+        """
+        if not project_name:
+            raise ValueError("project_name must not be empty")
+        result = self.api.call_the_api(
+            APIEndpoints.DASHBOARDS.value.format(project=project_name),
+            method=RequestsMethods.POST,
+            json_complete=dashboard.model_dump_json(by_alias=True, exclude_none=True),
+        )
+        if not isinstance(result, dict):
+            logging.error("Failed to create dashboard.")
+            raise Exception(result)
+        return result
+
+    def update_dashboard(
+        self, project_name: str, name: str, dashboard: DashboardModel
+    ) -> dict:
+        """The method includes a functionality to update an existing dashboard by name
+
+        Args:
+            project_name (str): Specify the name of the project the dashboard belongs to
+            name (str): Specify the name of the dashboard to update
+            dashboard (Dashboard): Specify the updated dashboard resource
+
+        Raises:
+            ValueError: Missed specifying a necessary value
+            Exception: Unspecified error by executing the API call
+
+        Returns:
+            dict: The updated dashboard dict
+        """
+        if not project_name:
+            raise ValueError("project_name must not be empty")
+        if not name:
+            raise ValueError("name must not be empty")
+        result = self.api.call_the_api(
+            APIEndpoints.DASHBOARD.value.format(project=project_name, name=name),
+            method=RequestsMethods.PUT,
+            json_complete=dashboard.model_dump_json(by_alias=True, exclude_none=True),
+        )
+        if not isinstance(result, dict):
+            logging.error(f"Failed to update dashboard: {name}")
+            raise Exception(result)
+        return result
+
+    def delete_dashboard(self, project_name: str, name: str) -> None:
+        """The method includes a functionality to delete a dashboard by name
+
+        Args:
+            project_name (str): Specify the name of the project the dashboard belongs to
+            name (str): Specify the name of the dashboard to delete
+
+        Raises:
+            ValueError: Missed specifying a necessary value
+        """
+        if not project_name:
+            raise ValueError("project_name must not be empty")
+        if not name:
+            raise ValueError("name must not be empty")
+        self.api.call_the_api(
+            APIEndpoints.DASHBOARD.value.format(project=project_name, name=name),
+            method=RequestsMethods.DELETE,
+        )

perses_api/datasource.py

@@ -0,0 +1,119 @@
+from __future__ import annotations
+
+from ._base import ResourceBase
+from .model import APIModel, APIEndpoints
+
+
+class DatasourceBase(ResourceBase):
+    """The class includes all necessary base methods to access the Perses datasources API
+
+    Args:
+        perses_api_model (APIModel): Inject a Perses API model object that includes all necessary values and information
+
+    Attributes:
+        api (Api): This is where we store the api
+    """
+
+    def get_datasources(self, name: str = None) -> list:
+        """The method includes a functionality to retrieve all datasources
+
+        Args:
+            name (str): Specify a name to filter the results (default None)
+
+        Raises:
+            Exception: Unspecified error by executing the API call
+
+        Returns:
+            list: A list of datasource dicts
+        """
+        return self._get_all(name)
+
+    def get_datasource(self, name: str) -> dict:
+        """The method includes a functionality to retrieve a single datasource by name
+
+        Args:
+            name (str): Specify the name of the datasource to retrieve
+
+        Raises:
+            ValueError: Missed specifying a necessary value
+            Exception: Unspecified error by executing the API call
+
+        Returns:
+            dict: The datasource dict
+        """
+        return self._get_one(name)
+
+    def create_datasource(self, datasource) -> dict:
+        """The method includes a functionality to create a new datasource
+
+        Args:
+            datasource (Datasource | GlobalDatasource): Specify the datasource resource to create
+
+        Raises:
+            Exception: Unspecified error by executing the API call
+
+        Returns:
+            dict: The created datasource dict
+        """
+        return self._create(datasource)
+
+    def update_datasource(self, name: str, datasource) -> dict:
+        """The method includes a functionality to update an existing datasource by name
+
+        Args:
+            name (str): Specify the name of the datasource to update
+            datasource (Datasource | GlobalDatasource): Specify the updated datasource resource
+
+        Raises:
+            ValueError: Missed specifying a necessary value
+            Exception: Unspecified error by executing the API call
+
+        Returns:
+            dict: The updated datasource dict
+        """
+        return self._update(name, datasource)
+
+    def delete_datasource(self, name: str) -> None:
+        """The method includes a functionality to delete a datasource by name
+
+        Args:
+            name (str): Specify the name of the datasource to delete
+
+        Raises:
+            ValueError: Missed specifying a necessary value
+        """
+        self._delete(name)
+
+
+class ProjectDatasource(DatasourceBase):
+    """The class includes all necessary methods to access the Perses project-scoped datasources API
+
+    Args:
+        perses_api_model (APIModel): Inject a Perses API model object that includes all necessary values and information
+        project_name (str): Specify the name of the project to scope datasource operations to
+
+    Attributes:
+        api (Api): This is where we store the api
+        project_name (str): This is where we store the project_name
+    """
+
+    def __init__(self, perses_api_model: APIModel, project_name: str):
+        super().__init__(perses_api_model)
+        self.project_name = project_name
+
+    def _base_path(self) -> str:
+        return APIEndpoints.DATASOURCES.value.format(project=self.project_name)
+
+
+class GlobalDatasource(DatasourceBase):
+    """The class includes all necessary methods to access the Perses global datasources API
+
+    Args:
+        perses_api_model (APIModel): Inject a Perses API model object that includes all necessary values and information
+
+    Attributes:
+        api (Api): This is where we store the api
+    """
+
+    def _base_path(self) -> str:
+        return APIEndpoints.GLOBAL_DATASOURCES.value