automizor 0.3.0__tar.gz → 0.4.0__tar.gz

{automizor-0.3.0/automizor.egg-info → automizor-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: automizor
-Version: 0.3.0
+Version: 0.4.0
 Summary: Python Automizor framework
 Home-page: https://github.com/automizor/automizor
 Author: Christian Fischer

automizor-0.4.0/automizor/__init__.py

@@ -0,0 +1 @@
+version = "0.4.0"

automizor-0.4.0/automizor/exceptions.py

@@ -0,0 +1,69 @@
+from requests import Response
+
+
+class AutomizorError(Exception):
+    def __init__(self, message, error=None):
+        if error:
+            message = f"{message}: {error}"
+        super().__init__(message)
+
+    def __str__(self):
+        return f"{self.args[0]}"
+
+    @classmethod
+    def from_response(cls, response: Response, message: str):
+        _STATUS_EXCEPTION_MAP = {
+            400: InvalidRequest,
+            401: Unauthorized,
+            403: Forbidden,
+            404: NotFound,
+            429: RateLimitExceeded,
+            500: InternalServerError,
+            502: BadGateway,
+            503: ServiceUnavailable,
+        }
+
+        try:
+            error = dict(response.json()).get("detail", "Unknown error.")
+        except Exception:  # pylint: disable=broad-except
+            error = response.text
+
+        return _STATUS_EXCEPTION_MAP.get(response.status_code, UnexpectedError)(
+            message, error
+        )
+
+
+class BadGateway(AutomizorError):
+    pass
+
+
+class Forbidden(AutomizorError):
+    pass
+
+
+class InternalServerError(AutomizorError):
+    pass
+
+
+class InvalidRequest(AutomizorError):
+    pass
+
+
+class NotFound(AutomizorError):
+    pass
+
+
+class RateLimitExceeded(AutomizorError):
+    pass
+
+
+class ServiceUnavailable(AutomizorError):
+    pass
+
+
+class Unauthorized(AutomizorError):
+    pass
+
+
+class UnexpectedError(AutomizorError):
+    pass

{automizor-0.3.0 → automizor-0.4.0}/automizor/job/__init__.py

@@ -1,6 +1,5 @@
 from functools import lru_cache
 
-from ._exceptions import AutomizorJobError
 from ._job import JSON
 
 
@@ -44,7 +43,6 @@ def set_result(name: str, value: JSON):
 
 
 __all__ = [
-    "AutomizorJobError",
     "get_context",
     "set_result",
 ]

{automizor-0.3.0 → automizor-0.4.0}/automizor/job/_job.py

@@ -4,7 +4,8 @@ from typing import Dict, List, Union
 
 import requests
 
-from ._exceptions import AutomizorJobError
+from automizor.exceptions import AutomizorError
+from automizor.utils import get_api_config, get_headers
 
 JSON = Union[str, int, float, bool, None, Dict[str, "JSON"], List["JSON"]]
 
@@ -30,8 +31,7 @@ class Job:
     To use this class effectively, ensure that the following environment variables are
     set in your environment:
 
-    - ``AUTOMIZOR_API_HOST``: The URL of the `Automizor API` host.
-    - ``AUTOMIZOR_API_TOKEN``: The authentication token for API access.
+    - ``AUTOMIZOR_AGENT_TOKEN``: The token for authenticating against the `Automizor API`.
     - ``AUTOMIZOR_CONTEXT_FILE``: The path to a local file containing job context, if used.
     - ``AUTOMIZOR_JOB_ID``: The identifier for the current job, used when fetching context via API.
 
@@ -50,18 +50,12 @@ class Job:
     """
 
     def __init__(self):
-        self._api_host = os.getenv("AUTOMIZOR_API_HOST")
-        self._api_token = os.getenv("AUTOMIZOR_API_TOKEN")
-        self._context_file = os.getenv("AUTOMIZOR_CONTEXT_FILE")
-        self._job_id = os.getenv("AUTOMIZOR_JOB_ID")
+        self._context_file = os.getenv("AUTOMIZOR_CONTEXT_FILE", None)
+        self._job_id = os.getenv("AUTOMIZOR_JOB_ID", None)
 
+        self.url, self.token = get_api_config()
         self.session = requests.Session()
-        self.session.headers.update(
-            {
-                "Authorization": f"Token {self._api_token}",
-                "Content-Type": "application/json",
-            }
-        )
+        self.session.headers.update(get_headers(self.token))
 
     def get_context(self) -> dict:
         """
@@ -73,8 +67,7 @@ class Job:
         This is useful in environments where direct access to the `Automizor API` is
         not possible or preferred.
         2. The `Automizor API`, using the job ID (`AUTOMIZOR_JOB_ID`) to fetch the specific
-        job context. This requires valid API host (`AUTOMIZOR_API_HOST`) and token
-        (`AUTOMIZOR_API_TOKEN`) settings.
+        job context.
 
         Returns:
             A dictionary containing the job context.
@@ -125,10 +118,14 @@ class Job:
             return json.load(file)
 
     def _read_job_context(self) -> dict:
-        url = f"https://{self._api_host}/api/v1/rpa/job/{self._job_id}/"
+        url = f"https://{self.url}/api/v1/rpa/job/{self._job_id}/"
         try:
             response = self.session.get(url, timeout=10)
             response.raise_for_status()
             return response.json().get("context", {})
+        except requests.HTTPError as exc:
+            raise AutomizorError.from_response(
+                exc.response, "Failed to get job context"
+            ) from exc
         except Exception as exc:
-            raise AutomizorJobError(f"Failed to get job context: {exc}") from exc
+            raise AutomizorError("Failed to get job context") from exc

automizor-0.4.0/automizor/storage/__init__.py

@@ -0,0 +1,179 @@
+import json
+import mimetypes
+from functools import lru_cache
+from pathlib import Path
+
+from ._storage import JSON
+
+
+@lru_cache
+def _get_storage():
+    from ._storage import Storage
+
+    return Storage()
+
+
+def list_assets() -> list[str]:
+    """
+    Retrieves a list of all asset names.
+
+    Returns:
+        A list of all asset names.
+    """
+
+    storage = _get_storage()
+    return storage.list_assets()
+
+
+def delete_asset(name: str) -> None:
+    """
+    Deletes the specified asset.
+
+    Parameters:
+        name: The name identifier of the asset to delete.
+    """
+
+    storage = _get_storage()
+    storage.delete_asset(name)
+
+
+def get_bytes(name: str) -> bytes:
+    """
+    Retrieves the specified asset as raw bytes.
+
+    Parameters:
+        name: The name identifier of the asset to retrieve.
+
+    Returns:
+        The raw byte content of the asset.
+    """
+
+    storage = _get_storage()
+    return storage.get_bytes(name)
+
+
+def get_file(name: str, path: str) -> str:
+    """
+    Downloads the specified asset and saves it to a file.
+
+    Parameters:
+        name: The name identifier of the asset to retrieve.
+        path: The filesystem path where the file will be saved.
+
+    Returns:
+        The path to the saved file, confirming the operation's success.
+    """
+
+    storage = _get_storage()
+    return storage.get_file(name, path)
+
+
+def get_json(name: str) -> JSON:
+    """
+    Retrieves the specified asset and parses it as JSON.
+
+    Parameters:
+        name: The name identifier of the asset to retrieve.
+
+    Returns:
+        The parsed JSON data, which can be a dict, list, or primitive data type.
+    """
+
+    storage = _get_storage()
+    return storage.get_json(name)
+
+
+def get_text(name: str) -> str:
+    """
+    Retrieves the specified asset as a text string.
+
+    Parameters:
+        name: The name identifier of the asset to retrieve.
+
+    Returns:
+        The content of the asset as a text string.
+    """
+
+    storage = _get_storage()
+    return storage.get_text(name)
+
+
+def set_bytes(name: str, data: bytes, content_type="application/octet-stream") -> None:
+    """
+    Uploads raw bytes as an asset.
+
+    Parameters:
+        name: The name identifier of the asset to upload.
+        data: The raw byte content to upload.
+        content_type: The MIME type of the asset.
+    """
+
+    storage = _get_storage()
+    storage.set_bytes(name, data, content_type)
+
+
+def set_file(name: str, path: str, content_type: str = None) -> None:
+    """
+    Uploads a file as an asset.
+
+    Parameters:
+        name: The name identifier of the asset to upload.
+        path: The filesystem path of the file to upload.
+        content_type: The MIME type of the asset.
+    """
+
+    content = Path(path).read_bytes()
+    if content_type is None:
+        content_type, _ = mimetypes.guess_type(path)
+        if content_type is None:
+            content_type = "application/octet-stream"
+
+    storage = _get_storage()
+    storage.set_bytes(name, content, content_type)
+
+
+def set_json(name: str, value: JSON, **kwargs) -> None:
+    """
+    Uploads JSON data as an asset.
+
+    Parameters:
+        name: The name identifier of the asset to upload.
+        value: The JSON data to upload.
+        kwargs: Additional keyword arguments to pass to json.dumps.
+    """
+
+    content = json.dumps(value, **kwargs).encode("utf-8")
+    content_type = "application/json"
+
+    storage = _get_storage()
+    storage.set_bytes(name, content, content_type)
+
+
+def set_text(name: str, text: str) -> None:
+    """
+    Uploads text content as an asset.
+
+    Parameters:
+        name: The name identifier of the asset to upload.
+        text: The text content to upload.
+    """
+
+    content = text.encode("utf-8")
+    content_type = "text/plain"
+
+    storage = _get_storage()
+    storage.set_bytes(name, content, content_type)
+
+
+__all__ = [
+    "list_assets",
+    "delete_asset",
+    "get_bytes",
+    "get_file",
+    "get_json",
+    "get_text",
+    "set_bytes",
+    "set_file",
+    "set_json",
+    "set_text",
+]

automizor-0.4.0/automizor/storage/_storage.py

@@ -0,0 +1,300 @@
+from typing import Dict, List, Union
+
+import requests
+
+from automizor.exceptions import AutomizorError, NotFound
+from automizor.utils import get_api_config, get_headers
+
+JSON = Union[str, int, float, bool, None, Dict[str, "JSON"], List["JSON"]]
+
+
+class Storage:
+    """
+    `Storage` is a class designed to interact with the `Automizor Platform` for managing
+    digital assets, facilitating the retrieval of files in various formats such as bytes,
+    files, JSON, and text. It leverages the `Automizor Storage API` to access and download
+    these assets securely.
+
+    This class utilizes environment variables for configuration, specifically for setting
+    up the API host and API token, which are essential for authenticating requests made
+    to the `Automizor Storage API`. These variables are typically configured by the
+    `Automizor Agent`.
+
+    To use this class effectively, ensure that the following environment variables are
+    set in your environment:
+
+    - ``AUTOMIZOR_AGENT_TOKEN``: The token for authenticating against the `Automizor API`.
+
+    Example usage:
+
+    .. code-block:: python
+
+        from automizor import storage
+
+        # To list all assets
+        asset_names = storage.list_assets()
+
+        # To delete an asset
+        storage.delete_asset("AssetName")
+
+        # Save an asset
+        storage.set_bytes("AssetName", b"Hello, World!")
+        storage.set_file("AssetName", "/path/to/file")
+        storage.set_json("AssetName", {"key": "value"})
+        storage.set_text("AssetName", "Hello, World!")
+
+        # Get an asset
+        bytes_data = storage.get_bytes("AssetName")
+        file_path = storage.get_file("AssetName", "/path/to/save/file")
+        json_data = storage.get_json("AssetName")
+        text_data = storage.get_text("AssetName")
+    """
+
+    def __init__(self):
+        self.url, self.token = get_api_config()
+        self.session = requests.Session()
+        self.session.headers.update(get_headers(self.token))
+
+    def list_assets(self) -> List[str]:
+        """
+        Retrieves a list of all asset names.
+
+        This function fetches the names of all assets stored in the storage service,
+        providing a convenient way to list and identify the available assets.
+
+        Returns:
+            A list of all asset names.
+        """
+        url = f"https://{self.url}/api/v1/storage/asset/"
+        asset_names = []
+
+        try:
+            while url:
+                response = self.session.get(url, timeout=10)
+                response.raise_for_status()
+                data = response.json()
+
+                for asset in data["results"]:
+                    asset_names.append(asset["name"])
+                url = data["next"]
+        except requests.HTTPError as exc:
+            raise AutomizorError.from_response(
+                exc.response, "Failed to list assets"
+            ) from exc
+        except Exception as exc:
+            raise AutomizorError("Failed to list assets") from exc
+        return asset_names
+
+    def delete_asset(self, name: str) -> None:
+        """
+        Deletes the specified asset.
+
+        This function deletes the asset identified by `name` from the storage service.
+        It is useful for removing assets that are no longer needed or should be cleaned
+        up to free up storage space.
+
+        Parameters:
+            name: The name identifier of the asset to delete.
+        """
+
+        url = f"https://{self.url}/api/v1/storage/asset/{name}/"
+        try:
+            response = self.session.delete(url, timeout=10)
+            response.raise_for_status()
+        except requests.HTTPError as exc:
+            raise AutomizorError.from_response(
+                exc.response, "Failed to delete asset"
+            ) from exc
+        except Exception as exc:
+            raise AutomizorError("Failed to delete asset") from exc
+
+    def get_bytes(self, name: str) -> bytes:
+        """
+        Retrieves the specified asset as raw bytes.
+
+        This function fetches the asset identified by `name` from the storage service
+        and returns it as a byte stream. It is useful for binary files or for data
+        that is intended to be processed or stored in its raw form.
+
+        Parameters:
+            name: The name identifier of the asset to retrieve.
+
+        Returns:
+            The raw byte content of the asset.
+        """
+
+        return self._download_file(name, mode="content")
+
+    def get_file(self, name: str, path: str) -> str:
+        """
+        Downloads the specified asset and saves it to a file.
+
+        This function fetches the asset identified by `name` and saves it directly
+        to the filesystem at the location specified by `path`. It is useful for
+        downloading files that need to be preserved in the file system, such as
+        documents, images, or other files.
+
+        Parameters:
+            name: The name identifier of the asset to retrieve.
+            path: The filesystem path where the file will be saved.
+
+        Returns:
+            The path to the saved file, confirming the operation's success.
+        """
+
+        content = self._download_file(name, mode="content")
+        with open(path, "wb") as file:
+            file.write(content)
+        return path
+
+    def get_json(self, name: str) -> JSON:
+        """
+        Retrieves the specified asset and parses it as JSON.
+
+        This function fetches the asset identified by `name` from the storage service
+        and parses it as JSON. It is useful for assets stored in JSON format, allowing
+        for easy access and manipulation of structured data.
+
+        Parameters:
+            name: The name identifier of the asset to retrieve.
+
+        Returns:
+            The parsed JSON data, which can be a dict, list, or primitive data type.
+        """
+
+        return self._download_file(name, mode="json")
+
+    def get_text(self, name: str) -> str:
+        """
+        Retrieves the specified asset as a text string.
+
+        This function fetches the asset identified by `name` from the storage service
+        and returns it as a text string. It is useful for text-based files, such as
+        configuration files, CSVs, or plain text documents.
+
+        Parameters:
+            name: The name identifier of the asset to retrieve.
+
+        Returns:
+            The content of the asset as a text string.
+        """
+
+        return self._download_file(name, mode="text")
+
+    def set_bytes(self, name: str, content: bytes, content_type: str) -> None:
+        """
+        Uploads the specified content as a new asset.
+
+        This function uploads the provided `content` as a new asset with the specified
+        `name`. It is useful for creating new assets or updating existing ones with
+        fresh content.
+
+        Parameters:
+            name: The name identifier of the asset to create.
+            content: The raw byte content of the asset.
+            content_type: The MIME type of the asset content.
+        """
+
+        try:
+            self._update_asset(name, content, content_type)
+        except NotFound:
+            self._create_asset(name, content, content_type)
+
+    def _create_asset(self, name: str, content: bytes, content_type: str) -> None:
+        """
+        Creates a new asset with the specified content.
+
+        This function creates a new asset with the specified `name` and `content` in the
+        storage service. It is useful for uploading new assets or updating existing ones
+        with fresh content.
+
+        Parameters:
+            name: The name identifier of the asset to create.
+            content: The raw byte content of the asset.
+            content_type: The MIME type of the asset content.
+        """
+
+        url = f"https://{self.url}/api/v1/storage/asset/"
+        try:
+            data = {
+                "content_type": content_type,
+                "name": name,
+            }
+            files = {"file": ("text.txt", content, content_type)}
+            response = self.session.post(url, files=files, data=data, timeout=10)
+            response.raise_for_status()
+        except requests.HTTPError as exc:
+            raise AutomizorError.from_response(
+                exc.response, "Failed to create asset"
+            ) from exc
+        except Exception as exc:
+            raise AutomizorError("Failed to create asset") from exc
+
+    def _download_file(self, name: str, mode: str = "content"):
+        url = self._get_asset_url(name)
+
+        try:
+            response = requests.get(url=url, timeout=10)
+            response.raise_for_status()
+
+            match mode:
+                case "content":
+                    return response.content
+                case "json":
+                    return response.json()
+                case "text":
+                    return response.text
+            raise RuntimeError(f"Invalid mode {mode}")
+        except requests.HTTPError as exc:
+            raise AutomizorError.from_response(
+                exc.response, "Failed to download asset"
+            ) from exc
+        except Exception as exc:
+            raise AutomizorError("Failed to download asset") from exc
+
+    def _get_asset_url(self, name: str) -> str:
+        url = f"https://{self.url}/api/v1/storage/asset/{name}/"
+        try:
+            response = self.session.get(url, timeout=10)
+            response.raise_for_status()
+
+            url = response.json().get("file")
+            if url:
+                return url
+            raise RuntimeError("Url not found")
+        except requests.HTTPError as exc:
+            raise AutomizorError.from_response(
+                exc.response, "Failed to get asset URL"
+            ) from exc
+        except Exception as exc:
+            raise AutomizorError("Failed to get asset URL") from exc
+
+    def _update_asset(self, name: str, content: bytes, content_type: str) -> None:
+        """
+        Updates the specified asset with new content.
+
+        This function updates the asset identified by `name` with fresh content
+        provided as `content`. It is useful for modifying existing assets without
+        creating a new asset, ensuring that the asset's content is up-to-date.
+
+        Parameters:
+            name: The name identifier of the asset to update.
+            content: The raw byte content of the asset.
+            content_type: The MIME type of the asset content.
+        """
+
+        url = f"https://{self.url}/api/v1/storage/asset/{name}/"
+        try:
+            data = {
+                "content_type": content_type,
+                "name": name,
+            }
+            files = {"file": ("text.txt", content, content_type)}
+            response = self.session.put(url, files=files, data=data, timeout=10)
+            response.raise_for_status()
+        except requests.HTTPError as exc:
+            raise AutomizorError.from_response(
+                exc.response, "Failed to update asset"
+            ) from exc
+        except Exception as exc:
+            raise AutomizorError("Failed to update asset") from exc

automizor-0.4.0/automizor/utils/__init__.py

@@ -0,0 +1,31 @@
+import os
+import platform
+
+from automizor import version
+from automizor.exceptions import AutomizorError
+
+OS_SYSTEM, OS_RELEASE, _ = platform.system_alias(
+    platform.system(), platform.release(), platform.version()
+)
+
+
+def get_api_config() -> tuple[str, str]:
+    token_string = os.getenv("AUTOMIZOR_AGENT_TOKEN")
+
+    if not token_string:
+        raise AutomizorError("AUTOMIZOR_AGENT_TOKEN is not set.")
+
+    try:
+        token, url = token_string.strip().split("@")
+    except ValueError as exc:
+        raise AutomizorError(
+            "AUTOMIZOR_AGENT_TOKEN is not in the correct format."
+        ) from exc
+    return url, token
+
+
+def get_headers(token: str) -> dict:
+    return {
+        "Authorization": f"Token {token}",
+        "User-Agent": f"Automizor/{version} {OS_SYSTEM}/{OS_RELEASE}",
+    }