carbonarc 1.0.0__py2.py3-none-any.whl

carbonarc/__init__.py

@@ -0,0 +1,13 @@
+try:
+    from importlib.metadata import version, PackageNotFoundError
+    try:
+        __version__ = version("carbonarc")
+    except PackageNotFoundError:
+        __version__ = "unkown"
+except ImportError:
+    __version__ = "unkown"
+
+from carbonarc.client import CarbonArcClient
+
+
+__all__ = ["CarbonArcClient"]

carbonarc/base/auth.py

@@ -0,0 +1,22 @@
+from requests.auth import AuthBase
+
+
+class TokenAuth(AuthBase):
+    """
+    Class for authenticating requests by user supplied token.
+    """
+
+    def __init__(self, token: str):
+        assert token, "Token must be a non-empty string."
+        self.auth_token = token
+
+    def __call__(self, r):
+        """
+        Override the default __call__ method for the AuthBase base class
+
+        More more info, see:
+        https://docs.python-requests.org/en/master/user/advanced/
+        """
+        auth_token = self.auth_token
+        r.headers["Authorization"] = "Bearer " + auth_token
+        return r

carbonarc/base/client.py

@@ -0,0 +1,44 @@
+import logging
+from typing import Literal
+
+from carbonarc.base.auth import TokenAuth
+from carbonarc.base.manager import HttpRequestManager
+
+
+class BaseAPIClient:
+    """
+    A client for interacting with the Carbon Arc API.
+    """
+
+    def __init__(
+        self, 
+        token: str,
+        host: str = "https://platform.carbonarc.co",
+        version: str = "v2"
+        ):
+        """
+        Initialize APIClient with an authentication token and user agent.
+        :param auth_token: The authentication token to be used for requests.
+        :param host: The base URL of the Carbon Arc API.
+        :param version: The API version to use.
+        """
+        
+        self.host = host
+        self.version = version
+        
+        self._logger = logging.getLogger(__name__)
+        
+        self.auth_token = TokenAuth(token)
+        self.request_manager = HttpRequestManager(auth_token=self.auth_token)
+
+    def _build_base_url(
+        self,
+        product: Literal["clients", "framework", "library", "ontology", "hub"],
+    ) -> str:
+        return self.host + f"/api/{self.version}/" + product
+    
+    def _get(self, url: str, **kwargs) -> dict:
+        return self.request_manager.get(url, **kwargs).json()
+
+    def _post(self, url: str, **kwargs) -> dict:
+        return self.request_manager.post(url, **kwargs).json()

carbonarc/base/exceptions.py

@@ -0,0 +1,32 @@
+class CarbonArcException(Exception):
+    """Base exception for all errors."""
+
+    def __init__(self, message, status_code=None, response=None):
+        self.message = message
+        self.status_code = status_code
+        self.response = response
+        super().__init__(self.message)
+
+
+class AuthenticationError(CarbonArcException):
+    """Raised when authentication fails."""
+    pass
+
+
+class NotFoundError(CarbonArcException):
+    """Raised when a resource is not found."""
+    pass
+
+
+class ValidationError(CarbonArcException):
+    """Raised when request validation fails."""
+    pass
+
+
+class RateLimitError(CarbonArcException):
+    """Raised when API rate limit is exceeded."""
+    pass
+
+class InvalidConfigurationError(CarbonArcException):
+    """Raised when the configuration is invalid."""
+    pass

carbonarc/base/manager.py

@@ -0,0 +1,85 @@
+import logging
+from http import HTTPStatus
+
+import requests
+from bs4 import BeautifulSoup
+from requests.auth import AuthBase
+
+from carbonarc import __version__
+from carbonarc.base.exceptions import AuthenticationError
+
+
+class HttpRequestManager:
+    """
+    This class is responsible for
+    making Http request calls
+    """
+
+    def __init__(
+        self, auth_token: AuthBase, user_agent: str = f"Python-APIClient/{__version__}"
+    ):
+        """
+        Initialize the HttpRequestManager with an authentication token and user agent.
+        :param auth_token: The authentication token to be used for requests.
+        :param user_agent: The user agent string to be used for requests.
+        """
+        if not isinstance(auth_token, AuthBase):
+            raise ValueError("auth_token must be an instance of requests.auth.AuthBase")
+
+        self.auth_token = auth_token
+        self._logger = logging.getLogger(__name__)
+        self.request_session = requests.Session()
+        self.request_session.headers.update(
+            {
+                "User-Agent": user_agent,
+                "Accept": "application/json",
+            }
+        )
+
+    def post(self, url, data=None, json=None, **kwargs) -> requests.Response:
+        return self._raise_for_status(
+            self.request_session.post(
+                url, auth=self.auth_token, data=data, json=json, **kwargs
+            )
+        )
+
+    def patch(self, url, data=None, json=None, **kwargs) -> requests.Response:
+        return self._raise_for_status(
+            self.request_session.patch(
+                url, auth=self.auth_token, data=data, json=json, **kwargs
+            )
+        )
+
+    def get(self, url, **kwargs) -> requests.Response:
+        return self._raise_for_status(
+            self.request_session.get(url, auth=self.auth_token, **kwargs)
+        )
+
+    def put(self, url, data=None, **kwargs) -> requests.Response:
+        return self._raise_for_status(
+            self.request_session.put(url, auth=self.auth_token, data=data, **kwargs)
+        )
+
+    def delete(self, url, **kwargs) -> requests.Response:
+        return self._raise_for_status(
+            self.request_session.delete(url, auth=self.auth_token, **kwargs)
+        )
+
+    def get_stream(self, url, **kwargs) -> requests.Response:
+        self.request_session.headers.update({"Accept": "application/octet-stream"})
+        return self._raise_for_status(
+            self.request_session.get(url, auth=self.auth_token, stream=True, **kwargs)
+        )
+
+    def _raise_for_status(self, response: requests.Response) -> requests.Response:
+        try:
+            response.raise_for_status()
+        except requests.exceptions.HTTPError as e:
+            if e.response.status_code == HTTPStatus.CONFLICT:
+                raise AuthenticationError("Conflict error")
+            if not bool(BeautifulSoup(e.response.text, "html.parser").find()):
+                self._logger.error(e.response.text)
+            else:
+                self._logger.debug(e.response.text)
+            raise
+        return response

carbonarc/base/utils.py

@@ -0,0 +1,36 @@
+import pandas as pd
+import datetime
+from typing import Union
+
+def timeseries_response_to_pandas(response: Union[dict, pd.DataFrame]) -> pd.DataFrame:
+    """
+    Convert a timeseries response to a pandas DataFrame.
+    :param response: The response object from the API.
+    :return: A pandas DataFrame containing the timeseries data.
+    """
+    if isinstance(response, pd.DataFrame):
+        response["date"] = pd.to_datetime(response["date"])
+        return response
+    elif isinstance(response, dict):
+        current_page_data = response["data"]
+        df = pd.DataFrame(current_page_data)
+        df["date"] = pd.to_datetime(df["date"])
+        return df
+    else:
+        raise ValueError("Response must be a dictionary or a pandas DataFrame")
+
+
+def is_valid_date(date_string: str) -> bool:
+    """
+    Checks if a string is a valid date in YYYY-MM-DD or YYYY-MM-DDTHH:MM:SS format.
+    :param date_string: The date string to check.
+    :return: True if the date string is valid, False otherwise.
+    """
+    formats = ['%Y-%m-%d', '%Y-%m-%dT%H:%M:%S']
+    for fmt in formats:
+        try:
+            datetime.datetime.strptime(date_string, fmt)
+            return True
+        except ValueError:
+            continue
+    return False

carbonarc/client.py

@@ -0,0 +1,31 @@
+from carbonarc.data import DataAPIClient
+from carbonarc.explorer import ExplorerAPIClient
+from carbonarc.hub import HubAPIClient
+from carbonarc.platform import PlatformAPIClient
+from carbonarc.ontology import OntologyAPIClient
+
+
+class CarbonArcClient:
+    """
+    A client for interacting with the Carbon Arc API.
+    """
+
+    def __init__(
+        self,
+        token: str,
+        host: str = "https://platform.carbonarc.co",
+        version: str = "v2",
+    ):
+        """
+        Initialize CarbonArcClient with an authentication token and user agent.
+        
+        Args:
+            token (str): The authentication token to be used for requests.
+            host (str): The base URL of the Carbon Arc API.
+            version (str): The API version to use.
+        """
+        self.data = DataAPIClient(token=token, host=host, version=version)
+        self.explorer = ExplorerAPIClient(token=token, host=host, version=version)
+        self.hub = HubAPIClient(token=token, host=host, version=version)
+        self.platform = PlatformAPIClient(token=token, host=host, version=version)
+        self.ontology = OntologyAPIClient(token=token, host=host, version=version)