pygeai 0.1.6__py3-none-any.whl → 0.6.0b15__py3-none-any.whl

pygeai/core/services/rest.py

@@ -1,26 +1,36 @@
 import json
-
+from typing import Optional, List, Dict
 import requests as req
-import logging
+from pygeai import logger
+from pygeai.core.common.exceptions import InvalidResponseException
+from pygeai.core.services.response import ResponseMock
 
-logger = logging.getLogger(__name__)
+FAILED_REQUEST_RESPONSE = ResponseMock(
+    status_code=0,
+    content=json.dumps({"error": "Unknown error occurred"}),
+    url=None,
+    reason="Unknown Error"
+)
 
 
 class ApiService:
     """
-    Generic service for interacting with RESTful APIs.
+    Generic service for interacting with REST APIs.
 
     :param base_url: str - The base URL of the API.
-    :param username: str - Optional username for authentication.
-    :param password: str - Optional password for authentication.
-    :param token: str - Optional token for authentication.
+    :param username: str - Username for basic authentication (optional).
+    :param password: str - Password for basic authentication (optional).
+    :param token: str - Bearer token for authentication (optional).
+    :param project_id: str - Project ID for OAuth authentication (optional, keyword-only).
     """
 
-    def __init__(self, base_url, username: str = None, password: str = None, token: str = None):
+    def __init__(self, base_url, username: str = None, password: str = None, token: str = None, *,
+                 project_id: str = None):
         self._base_url = base_url
         self._username = username
         self._password = password
         self._token = token
+        self._project_id = project_id
 
     @property
     def base_url(self):
@@ -38,74 +48,194 @@ class ApiService:
     def token(self):
         return self._token
 
-    def get(self, endpoint: str, params: dict = None, headers: dict = None):
+    @token.setter
+    def token(self, token: str):
+        self._token = token
+
+    @property
+    def project_id(self):
+        return self._project_id
+
+    @project_id.setter
+    def project_id(self, project_id: str):
+        self._project_id = project_id
+
+    def get(self, endpoint: str, params: dict = None, headers: dict = None, verify: bool = True):
         """
         Sends a GET request to the specified API endpoint.
 
-        :param endpoint: str - The API endpoint to send the request to.
-        :param params: dict - Optional query parameters for the request.
-        :param headers: dict - Optional headers for the request.
-        :return: Response object from the GET request.
+        This method constructs the full URL by appending the endpoint to the base URL and sends a GET request
+        using the provided query parameters and headers. Authentication is applied if username/password or token
+        is provided.
+
+        :param endpoint: str - The API endpoint to send the request to (relative to the base URL).
+        :param params: dict, optional - Query parameters to include in the request.
+        :param headers: dict, optional - Additional headers to include in the request.
+        :param verify: bool - Whether to verify SSL certificates (default: True).
+        :return: Response - The response object from the GET request.
+        :raises InvalidResponseException: If an error occurs during the request execution.
         """
+        response = FAILED_REQUEST_RESPONSE
         try:
-            base_url = self.base_url
-
-            url = f"{base_url}/{endpoint}"
+            url = self._add_endpoint_to_url(endpoint)
 
-            if self.username and self.password:
-                response = req.get(
-                    url=url,
-                    params=params,
-                    auth=(
+            with req.Session() as session:
+                if self.username and self.password:
+                    session.auth = (
                         self.username,
                         self.password
                     )
-                )
-            elif not headers and self.token:
-                headers = {
-                    "Authorization": f"Bearer {self.token}"
-                }
-                response = req.get(
-                    url=url,
-                    params=params,
-                    headers=headers
-                )
-            elif headers:
-                response = req.get(
+                elif self.token:
+                    headers = self._add_token_to_headers(headers)
+
+                session.verify = verify
+
+                response = session.get(
                     url=url,
                     params=params,
                     headers=headers
                 )
-            else:
-                response = req.get(
-                    url=url,
-                    params=params,
-                )
         except Exception as e:
             logger.error(f"Error sending GET request: {e}")
+            raise InvalidResponseException(f"Error sending GET request: {e}")
         else:
-            return response
+            logger.debug(f"GET request to URL: {response.url}")
 
-    def post(self, endpoint: str, data: dict, headers: dict = None, verify: bool = True):
+        return response
+
+    def post(self, endpoint: str, data: dict, headers: dict = None, verify: bool = True, form: bool = False):
         """
         Sends a POST request to the specified API endpoint.
 
-        :param endpoint: str - The API endpoint to send the request to.
+        This method constructs the full URL by appending the endpoint to the base URL and sends a POST request
+        with the provided data, either as JSON or form data. Authentication is applied if username/password or token
+        is provided.
+
+        :param endpoint: str - The API endpoint to send the request to (relative to the base URL).
         :param data: dict - The payload to include in the POST request.
-        :param headers: dict - Optional headers for the request.
-        :param verify: bool - Whether to verify SSL certificates. Defaults to True.
-        :return: Response object from the POST request.
+        :param headers: dict, optional - Additional headers to include in the request.
+        :param verify: bool - Whether to verify SSL certificates (default: True).
+        :param form: bool - Whether to send data as form data instead of JSON (default: False).
+        :return: Response - The response object from the POST request.
+        :raises InvalidResponseException: If an error occurs during the request execution.
         """
+        response = FAILED_REQUEST_RESPONSE
         try:
-            base_url = self.base_url
-            if not headers:
-                headers = {
-                    "Authorization": f"Bearer {self.token}"
-                }
-            else:
-                headers["Authorization"] = f"Bearer {self.token}"
+            url = self._add_endpoint_to_url(endpoint)
+
+            with req.Session() as session:
+                if self.username and self.password:
+                    session.auth = (
+                        self.username,
+                        self.password
+                    )
+                elif self.token:
+                    headers = self._add_token_to_headers(headers)
+
+                session.verify = verify
 
-            url = f"{base_url}/{endpoint}"
+                if form:
+                    response = session.post(
+                        url=url,
+                        data=data,
+                        headers=headers
+                    )
+                else:
+                    response = session.post(
+                        url=url,
+                        json=data,
+                        headers=headers
+                    )
+        except Exception as e:
+            logger.error(f"Error sending POST request: {e}")
+            raise InvalidResponseException(f"Error sending POST request: {e}")
+        else:
+            logger.debug(f"POST request to URL: {response.url}")
+
+        return response
+
+    def stream_post(
+            self,
+            endpoint: str,
+            data: dict,
+            headers: dict = None,
+            verify: bool = True,
+            form: bool = False
+    ):
+        """
+        Sends a streaming POST request to the specified API endpoint.
+
+        This method constructs the full URL by appending the endpoint to the base URL and sends a streaming POST
+        request with the provided data, either as JSON or form data. It yields chunks of the response as they are
+        received. Authentication is applied if username/password or token is provided.
+
+        :param endpoint: str - The API endpoint to send the request to (relative to the base URL).
+        :param data: dict - The payload to include in the POST request.
+        :param headers: dict, optional - Additional headers to include in the request.
+        :param verify: bool - Whether to verify SSL certificates (default: True).
+        :param form: bool - Whether to send data as form data instead of JSON (default: False).
+        :return: Generator[str] - Yields chunks of the streaming response as strings.
+        :raises InvalidResponseException: If an error occurs during the request execution or streaming.
+        """
+        try:
+            url = self._add_endpoint_to_url(endpoint)
+
+            with req.Session() as session:
+                if self.username and self.password:
+                    session.auth = (self.username, self.password)
+                elif self.token:
+                    headers = self._add_token_to_headers(headers)
+
+                session.verify = verify
+
+                if form:
+                    response = session.post(
+                        url=url,
+                        data=data,
+                        headers=headers,
+                        stream=True
+                    )
+                else:
+                    response = session.post(
+                        url=url,
+                        json=data,
+                        headers=headers,
+                        stream=True
+                    )
+
+                response.raise_for_status()
+                logger.debug(f"Streaming POST request to URL {response.url}")
+                for line in response.iter_lines(decode_unicode=True):
+                    if line:
+                        yield line
+
+        except Exception as e:
+            logger.error(f"Error sending streaming POST request: {e}")
+            raise InvalidResponseException(f"Error sending streaming POST request: {e}")
+
+    def post_file_binary(
+            self,
+            endpoint: str,
+            headers: dict = None,
+            verify: bool = True,
+            file=None
+    ):
+        """
+        Sends a POST request with a binary file to the specified API endpoint.
+
+        This method constructs the full URL by appending the endpoint to the base URL and sends a POST request
+        with the provided binary file data. Authentication is applied if username/password or token is provided.
+
+        :param endpoint: str - The API endpoint to send the request to (relative to the base URL).
+        :param headers: dict, optional - Additional headers to include in the request.
+        :param verify: bool - Whether to verify SSL certificates (default: True).
+        :param file: Binary file data to include in the request.
+        :return: Response - The response object from the POST request.
+        :raises InvalidResponseException: If an error occurs during the request execution.
+        """
+        response = FAILED_REQUEST_RESPONSE
+        try:
+            url = self._add_endpoint_to_url(endpoint)
 
             with req.Session() as session:
                 if self.username and self.password:
@@ -113,40 +243,95 @@ class ApiService:
                         self.username,
                         self.password
                     )
+                elif self.token:
+                    headers = self._add_token_to_headers(headers)
+
                 session.verify = verify
 
                 response = session.post(
                     url=url,
-                    json=data,
-                    headers=headers
+                    headers=headers,
+                    data=file
                 )
         except Exception as e:
-            logger.error(f"Error sending POST request: {e}")
+            logger.error(f"Error sending POST request with binary file: {e}")
+            raise InvalidResponseException(f"Error sending POST request with binary file: {e}")
         else:
-            return response
+            logger.debug(f"POST request with binary file to URL: {response.url}")
+
+        return response
+
+    def post_files_multipart(
+            self,
+            endpoint: str,
+            data: Optional[dict] = None,
+            headers: Optional[dict] = None,
+            verify: bool = True,
+            files: Optional[Dict[str, str]] = None,
+    ):
+        """
+        Sends a POST request with multipart files to the specified API endpoint.
+
+        This method constructs the full URL by appending the endpoint to the base URL and sends a POST request
+        with multipart form data, including files and optional additional data. Authentication is applied if
+        username/password or token is provided.
+
+        :param endpoint: str - The API endpoint to send the request to (relative to the base URL).
+        :param data: dict, optional - Additional form data to include in the request.
+        :param headers: dict, optional - Additional headers to include in the request.
+        :param verify: bool - Whether to verify SSL certificates (default: True).
+        :param files: Dict[str, str], optional - Dictionary of file names and their corresponding file paths or file-like objects.
+        :return: Response - The response object from the POST request.
+        :raises InvalidResponseException: If an error occurs during the request execution.
+        """
+        response = FAILED_REQUEST_RESPONSE
+        try:
+            url = self._add_endpoint_to_url(endpoint)
+
+            with req.Session() as session:
+                if self.username and self.password:
+                    session.auth = (
+                        self.username,
+                        self.password
+                    )
+                elif self.token:
+                    headers = self._add_token_to_headers(headers)
+
+                session.verify = verify
+
+                # headers["Content-Type"] = "multipart/form-data"
+
+                response = session.post(
+                    url=url,
+                    headers=headers,
+                    data=data,
+                    files=files
+                )
+        except Exception as e:
+            logger.error(f"Error sending POST request with files multipart: {e}")
+            raise InvalidResponseException(f"Error sending POST request with files multipart request: {e}")
+        else:
+            logger.debug(f"POST request with multipart files to URL: {response.url}")
+
+        return response
 
     def put(self, endpoint: str, data: dict, headers: dict = None, verify: bool = True):
         """
         Sends a PUT request to the specified API endpoint.
 
-        :param endpoint: str - The API endpoint to send the request to.
-        :param data: dict - The payload to include in the PUT request.
-        :param headers: dict - Optional headers for the request.
-        :param verify: bool - Whether to verify SSL certificates. Defaults to True.
-        :return: Response object from the PUT request.
+        This method constructs the full URL by appending the endpoint to the base URL and sends a PUT request
+        with the provided JSON data. Authentication is applied if username/password or token is provided.
+
+        :param endpoint: str - The API endpoint to send the request to (relative to the base URL).
+        :param data: dict - The payload to include in the PUT request (sent as JSON).
+        :param headers: dict, optional - Additional headers to include in the request.
+        :param verify: bool - Whether to verify SSL certificates (default: True).
+        :return: Response - The response object from the PUT request.
+        :raises InvalidResponseException: If an error occurs during the request execution.
         """
+        response = FAILED_REQUEST_RESPONSE
         try:
-            base_url = self.base_url
-            if not headers:
-                headers = {
-                    "Authorization": f"Bearer {self.token}",
-                    "Content-Type": "application/json"
-                }
-            else:
-                headers["Authorization"] = f"Bearer {self.token}"
-                headers["Content-Type"] = "application/json"
-
-            url = f"{base_url}/{endpoint}"
+            url = self._add_endpoint_to_url(endpoint)
 
             with req.Session() as session:
                 if self.username and self.password:
@@ -154,8 +339,13 @@ class ApiService:
                         self.username,
                         self.password
                     )
+                elif self.token:
+                    headers = self._add_token_to_headers(headers)
+
                 session.verify = verify
 
+                headers["Content-Type"] = "application/json"
+
                 response = session.put(
                     url=url,
                     json=data,
@@ -163,28 +353,29 @@ class ApiService:
                 )
         except Exception as e:
             logger.error(f"Error sending PUT request: {e}")
+            raise InvalidResponseException(f"Error sending PUT request: {e}")
         else:
-            return response
+            logger.debug(f"PUT request to URL: {response.url}")
 
-    def delete(self, endpoint: str, headers: dict = None, verify: bool = True):
+        return response
+
+    def delete(self, endpoint: str, headers: dict = None, data: dict = None, verify: bool = True):
         """
         Sends a DELETE request to the specified API endpoint.
 
-        :param endpoint: str - The API endpoint to send the request to.
-        :param headers: dict - Optional headers for the request.
-        :param verify: bool - Whether to verify SSL certificates. Defaults to True.
-        :return: Response object from the DELETE request.
+        This method constructs the full URL by appending the endpoint to the base URL and sends a DELETE request
+        with optional query parameters and headers. Authentication is applied if username/password or token is provided.
+
+        :param endpoint: str - The API endpoint to send the request to (relative to the base URL).
+        :param headers: dict, optional - Additional headers to include in the request.
+        :param data: dict, optional - Query parameters to include in the request.
+        :param verify: bool - Whether to verify SSL certificates (default: True).
+        :return: Response - The response object from the DELETE request.
+        :raises InvalidResponseException: If an error occurs during the request execution.
         """
+        response = FAILED_REQUEST_RESPONSE
         try:
-            base_url = self.base_url
-            if not headers:
-                headers = {
-                    "Authorization": f"Bearer {self.token}"
-                }
-            else:
-                headers["Authorization"] = f"Bearer {self.token}"
-
-            url = f"{base_url}/{endpoint}"
+            url = self._add_endpoint_to_url(endpoint)
 
             with req.Session() as session:
                 if self.username and self.password:
@@ -192,14 +383,45 @@ class ApiService:
                         self.username,
                         self.password
                     )
+                elif self.token:
+                    headers = self._add_token_to_headers(headers)
+
                 session.verify = verify
 
                 response = session.delete(
                     url=url,
-                    headers=headers
+                    headers=headers,
+                    params=data
                 )
         except Exception as e:
             logger.error(f"Error sending DELETE request: {e}")
+            raise InvalidResponseException(f"Error sending DELETE request: {e}")
+        else:
+            logger.debug(f"DELETE request to URL: {response.url}")
+
+        return response
+
+    def _add_endpoint_to_url(self, endpoint: str):
+        clean_base_url = self.base_url.rstrip('/')
+        url = f"{clean_base_url}/{endpoint.lstrip('/')}" if self._has_valid_protocol(clean_base_url) else f"https://{clean_base_url}/{endpoint}"
+        return url
+
+    def _has_valid_protocol(self, url: str):
+        return url.startswith(('http://', 'https://'))
+
+    def _add_token_to_headers(self, headers: dict = None):
+        if not headers:
+            headers = {
+                "Authorization": f"Bearer {self.token}"
+            }
+        else:
+            if "Authorization" not in headers:
+                headers["Authorization"] = f"Bearer {self.token}"
+
+        if self.project_id and "ProjectId" not in headers:
+            headers["ProjectId"] = self.project_id
+            logger.debug(f"Added Authorization header with ProjectId: {self.project_id}")
         else:
-            return response
+            logger.debug("Added Authorization header")
 
+        return headers

pygeai/core/utils/console.py

@@ -0,0 +1,83 @@
+import sys
+from abc import ABC, abstractmethod
+
+
+class StreamWriter(ABC):
+    """
+    Abstract base class for custom stream writers.
+    """
+
+    @abstractmethod
+    def write_stdout(self, message: str = "", end: str = "\n"):
+        pass
+
+    @abstractmethod
+    def write_stderr(self, message: str = "", end: str = "\n"):
+        pass
+
+class ConsoleMeta(type):
+    def __getattr__(cls, name):
+        writer = cls._writer
+        attr = getattr(writer, name, None)
+        if callable(attr):
+            return attr
+        
+        def noop(*args, **kwargs):
+            pass
+        return noop
+
+class Console(metaclass=ConsoleMeta):
+    """
+    A utility class for writing messages to standard output and standard error streams.
+
+    This class provides static methods to write messages to `sys.stdout` and `sys.stderr`
+    with customizable end characters. It serves as a simple abstraction for console output
+    operations, ensuring consistent handling of messages in command-line applications.
+
+    Additionally, it allows setting a custom stream writer to override the default behavior,
+    enabling redirection of output to alternative targets such as loggers, files, or testing sinks.
+    """
+    class DefaultStreamWriter(StreamWriter):
+        """
+        Default StreamWriter that writes to sys.stdout and sys.stderr.
+        """
+        def write_stdout(self, message: str = "", end: str = "\n"):
+            sys.stdout.write(f"{message}{end}")
+            sys.stdout.flush()
+
+        def write_stderr(self, message: str = "", end: str = "\n"):
+            sys.stderr.write(f"{message}{end}")
+            sys.stderr.flush()
+
+    _writer: StreamWriter = DefaultStreamWriter()
+
+    @staticmethod
+    def write_stdout(message: str = "", end: str = "\n"):
+        """
+        Writes a message to the standard output stream (sys.stdout).
+
+        :param message: str - The message to write. Defaults to an empty string.
+        :param end: str - The string to append after the message. Defaults to a newline ('\n').
+        :return: None - No return value; output is written to sys.stdout.
+        """
+        Console._writer.write_stdout(message, end)
+
+    @staticmethod
+    def write_stderr(message: str = "", end: str = "\n"):
+        """
+        Writes a message to the standard error stream (sys.stderr).
+
+        :param message: str - The message to write. Defaults to an empty string.
+        :param end: str - The string to append after the message. Defaults to a newline ('\n').
+        :return: None - No return value; output is written to sys.stderr.
+        """
+        Console._writer.write_stderr(message, end)
+
+    @staticmethod
+    def set_writer(writer: StreamWriter):
+        """
+        Sets a custom StreamWriter to handle console output.
+
+        :param writer: StreamWriter - Implementation of the StreamWriter interface.
+        """
+        Console._writer = writer

pygeai/core/utils/parsers.py

@@ -0,0 +1,32 @@
+from json import JSONDecodeError
+
+from pygeai import logger
+from pygeai.core.common.exceptions import InvalidAPIResponseException
+
+
+def parse_json_response(response, operation: str, **context):
+    """
+    Parse JSON response with standardized error handling.
+
+    :param response: HTTP response object
+    :param operation: Description of operation (e.g., "get project API token")
+    :param context: Additional context (e.g., api_token_id="123")
+    :return: Parsed JSON response
+    :raises InvalidAPIResponseException: If JSON parsing fails
+    """
+    try:
+        return response.json()
+    except JSONDecodeError as e:
+        full_msg = f"Unable to {operation}"
+        if context:
+            if len(context) == 1:
+                # Single context value: append as 'value'
+                value = list(context.values())[0]
+                full_msg += f" '{value}'"
+            else:
+                # Multiple context values: format as (key1='value1', key2='value2')
+                context_str = ", ".join([f"{k}='{v}'" for k, v in context.items()])
+                full_msg += f" ({context_str})"
+
+        logger.error(f"{full_msg}: JSON parsing error (status {response.status_code}): {e}. Response: {response.text}")
+        raise InvalidAPIResponseException(f"{full_msg}: {response.text}")

pygeai/core/utils/validators.py

@@ -0,0 +1,10 @@
+from pygeai import logger
+from pygeai.core.common.exceptions import APIResponseError
+
+
+def validate_status_code(response):
+    if response.status_code >= 300:
+        logger.error(f"Invalid status code returned from the API endpoint: {response.text}")
+        raise APIResponseError(f"API returned an error: {response.text}")
+
+

pygeai/dbg/__init__.py

@@ -0,0 +1,3 @@
+from pygeai.dbg.debugger import Debugger, Breakpoint, debug_file, debug_module
+
+__all__ = ['Debugger', 'Breakpoint', 'debug_file', 'debug_module']