carbonarc 1.0.0__tar.gz

carbonarc-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Carbon Arc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

carbonarc-1.0.0/PKG-INFO

@@ -0,0 +1,56 @@
+Metadata-Version: 2.3
+Name: carbonarc
+Version: 1.0.0
+Summary: Carbon Arc - Python Package
+License: MIT
+Author: Carbon Arc
+Author-email: support@carbonarc.co
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 2
+Classifier: Programming Language :: Python :: 2.7
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.4
+Classifier: Programming Language :: Python :: 3.5
+Classifier: Programming Language :: Python :: 3.6
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: Click (>=8.1.7,<9.0.0)
+Requires-Dist: beautifulsoup4 (>=4.12.2,<5.0.0)
+Requires-Dist: pandas (>=2.2.3,<3.0.0)
+Requires-Dist: requests (>=2.31.0,<3.0.0)
+Project-URL: Repository, https://github.com/Carbon-Arc/carbonarc.git
+Description-Content-Type: text/markdown
+
+# Carbon Arc - Python Package
+
+Client for [Carbon Arc](https://carbonarc.co/), an Insights Exchange Platform.
+
+## Usage
+
+**Installation**
+
+```bash
+pip install carbonarc
+```
+
+**Quick Start**
+
+Initialize the API client with authentication.
+
+```python
+from carbonarc import CarbonArcClient
+
+client = CarbonArcClient(token="<token>") # retrieve token from account
+```
+
+## Resources
+
+- [Tutorials](https://github.com/Carbon-Arc/carbonarc-tutorials)
+- [Docs](https://docs.carbonarc.co/)
+- [App](https://app.carbonarc.co/)
+- [API](https://api.carbonarc.co/)

carbonarc-1.0.0/README.md

@@ -0,0 +1,28 @@
+# Carbon Arc - Python Package
+
+Client for [Carbon Arc](https://carbonarc.co/), an Insights Exchange Platform.
+
+## Usage
+
+**Installation**
+
+```bash
+pip install carbonarc
+```
+
+**Quick Start**
+
+Initialize the API client with authentication.
+
+```python
+from carbonarc import CarbonArcClient
+
+client = CarbonArcClient(token="<token>") # retrieve token from account
+```
+
+## Resources
+
+- [Tutorials](https://github.com/Carbon-Arc/carbonarc-tutorials)
+- [Docs](https://docs.carbonarc.co/)
+- [App](https://app.carbonarc.co/)
+- [API](https://api.carbonarc.co/)

carbonarc-1.0.0/pyproject.toml

@@ -0,0 +1,35 @@
+[tool.poetry]
+name = "carbonarc"
+version = "1.0.0"
+description = "Carbon Arc - Python Package"
+authors = ["Carbon Arc <support@carbonarc.co>"]
+readme = "README.md"
+packages = [{include = "carbonarc", from = "src"}, {include = "carbonarc_cli", from = "src"}]
+license = "MIT License"
+repository = "https://github.com/Carbon-Arc/carbonarc.git"
+python = "^3.9"
+
+[tool.poetry.dependencies]
+requests = "^2.31.0"
+pandas = "^2.2.3"
+beautifulsoup4 = "^4.12.2"
+Click = "^8.1.7"
+
+[tool.poetry.scripts]
+carbonarc = "carbonarc_cli.cli:cli"
+
+[tool.setuptools.package-data]
+carbonarc = ["carbonarc/*"]
+carbonarc_cli = ["carbonarc_cli/*"]
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^7.4.0"
+pytest-mock = "^3.11.1"
+black = "^23.7.0"
+isort = "^5.12.0"
+mypy = "^1.5.0"
+types-requests = "^2.31.0"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"

carbonarc-1.0.0/src/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-1.0.0/src/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-1.0.0/src/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-1.0.0/src/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-1.0.0/src/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-1.0.0/src/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-1.0.0/src/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)