orionis 0.246.0__py3-none-any.whl → 0.247.0__py3-none-any.whl

orionis/luminate/services/environment/contracts/env.py

@@ -0,0 +1,93 @@
+from typing import Any, Dict, Optional
+from abc import ABC, abstractmethod
+
+class IEnv(ABC):
+    """Interface contract for environment management operations."""
+
+    @staticmethod
+    @abstractmethod
+    def get(key: str, default: Optional[Any] = None) -> Any:
+        """
+        Retrieves an environment variable's value.
+
+        Args:
+            key: Environment variable name
+            default: Default value if key doesn't exist
+
+        Returns:
+            The parsed value or default if not found
+        """
+        pass
+
+    @staticmethod
+    @abstractmethod
+    def set(key: str, value: str) -> bool:
+        """
+        Sets an environment variable.
+
+        Args:
+            key: Environment variable name
+            value: Value to set
+
+        Returns:
+            True if successful, False otherwise
+        """
+        pass
+
+    @staticmethod
+    @abstractmethod
+    def unset(key: str) -> bool:
+        """
+        Removes an environment variable.
+
+        Args:
+            key: Environment variable name
+
+        Returns:
+            True if successful, False otherwise
+        """
+        pass
+
+    @staticmethod
+    @abstractmethod
+    def all() -> Dict[str, Any]:
+        """
+        Retrieves all environment variables.
+
+        Returns:
+            Dictionary of all key-value pairs
+        """
+        pass
+
+    @staticmethod
+    @abstractmethod
+    def destroy() -> bool:
+        """
+        Clears the entire environment.
+
+        Returns:
+            True if successful, False otherwise
+        """
+        pass
+
+    @staticmethod
+    @abstractmethod
+    def toJson() -> str:
+        """
+        Serializes environment to JSON.
+
+        Returns:
+            JSON string representation
+        """
+        pass
+
+    @staticmethod
+    @abstractmethod
+    def toBase64() -> str:
+        """
+        Encodes environment to Base64.
+
+        Returns:
+            Base64 encoded string
+        """
+        pass

orionis/luminate/services/environment/dot_env.py

@@ -0,0 +1,293 @@
+import ast
+import os
+from pathlib import Path
+from typing import Any, Optional, Union
+from dotenv import dotenv_values, load_dotenv, set_key, unset_key
+from orionis.luminate.patterns.singleton import Singleton
+
+class DotEnv(metaclass=Singleton):
+    """
+    DotEnv is a singleton class for managing environment variables using a `.env` file.
+    This class provides methods to load, get, set, unset, and list environment variables,
+    with automatic serialization and deserialization of common Python data types.
+    It ensures that changes to the `.env` file are reflected in the current process's
+    environment variables and vice versa.
+    """
+
+    def __init__(self, path: str = None) -> None:
+        """
+        Initializes the environment service by resolving the path to the `.env` file, ensuring its existence,
+        and loading environment variables from it.
+        Args:
+            path (str, optional): The path to the `.env` file. If not provided, defaults to a `.env` file
+                in the current working directory.
+        Raises:
+            OSError: If the `.env` file cannot be created when it does not exist.
+        """
+
+        # Path to the `.env` file - If no path is provided, use the default path
+        if path:
+            self._resolved_path = Path(path).expanduser().resolve()
+        else:
+            self._resolved_path = Path(os.getcwd()) / ".env"
+
+        # Ensure that the `.env` file exists
+        if not self._resolved_path.exists():
+            self._resolved_path.touch()
+
+        # Load environment variables from the `.env` file
+        load_dotenv(self._resolved_path)
+
+    def destroy(self) -> bool:
+        """
+        Deletes the `.env` file at the resolved path.
+        Returns:
+            bool: True if the `.env` file was successfully deleted, False if the file did not exist.
+        """
+
+        # Deletes the `.env` file and returns True if it was successfully deleted.
+        if self._resolved_path.exists():
+            os.remove(self._resolved_path)
+            return True
+        return False
+
+    def get(self, key: str, default: Optional[Any] = None) -> Any:
+        """
+        Retrieve the value of an environment variable.
+        This method attempts to fetch the value of the specified environment variable `key`
+        from a `.env` file. If the variable is not found in the `.env` file, it falls back
+        to the system environment variables. If the variable is still not found, the provided
+        `default` value is returned.
+        Args:
+            key (str): The name of the environment variable to retrieve.
+            default (Optional[Any], optional): The value to return if the environment variable is not found. Defaults to None.
+        Returns:
+            Any: The value of the environment variable, parsed if found; otherwise, the `default` value.
+        """
+
+        # Gets the value of an environment variable from the `.env` file or from system environment variables.
+        value = dotenv_values(self._resolved_path).get(key)
+        if value is None:
+            value = os.getenv(key)
+
+        # If the value is not found, return the default value
+        return self.__parseValue(value) if value is not None else default
+
+    def set(self, key: str, value: Union[str, int, float, bool, list, dict]) -> bool:
+        """
+        Sets the value of an environment variable in both the `.env` file and the current system environment.
+        Args:
+            key (str): The name of the environment variable to set.
+            value (Union[str, int, float, bool, list, dict]): The value to assign to the environment variable.
+                The value will be serialized before being written to the `.env` file.
+        Notes:
+            - The value is serialized for storage in the `.env` file.
+            - The environment variable is also set in the current process's environment, making it immediately available.
+        """
+
+        # Serializes and sets the value of an environment variable in the `.env` file.
+        serialized_value = self.__serializeValue(value)
+
+        # Sets the value in the `.env` file
+        set_key(str(self._resolved_path), key, serialized_value)
+
+        # Also sets the value in the system environment variables
+        # so that it is available in the current environment.
+        # This is useful if you need to access the environment variable immediately
+        os.environ[key] = str(value)
+
+        # Return True to indicate that the operation was successful
+        return True
+
+    def unset(self, key: str) -> bool:
+        """
+        Removes an environment variable from both the `.env` file and the current system environment.
+        Args:
+            key (str): The name of the environment variable to remove.
+        This method updates the `.env` file by removing the specified key and also ensures
+        that the variable is no longer present in the current process's environment variables.
+        """
+
+        # Removes an environment variable from the `.env` file and from the system environment.
+        unset_key(str(self._resolved_path), key)
+
+        # Also removes the environment variable from the system
+        # so that it is not available in the current environment.
+        os.environ.pop(key, None)
+
+        # Return True to indicate that the operation was successful
+        return True
+
+    def all(self) -> dict:
+        """
+        Returns all environment variables from the `.env` file as a dictionary.
+
+        Reads the environment variables from the resolved `.env` file path, parses each value
+        using the `__parseValue` method, and returns a dictionary mapping variable names to their
+        parsed values.
+
+        Returns:
+            dict: A dictionary containing all environment variables and their parsed values.
+        """
+
+        # Returns all environment variables from the `.env` file as a dictionary,
+        # parsing the values using __parseValue.
+        raw_values = dotenv_values(self._resolved_path)
+        return {k: self.__parseValue(v) for k, v in raw_values.items()}
+
+    def toJson(self) -> str:
+        """
+        Converts the environment variables from the `.env` file into a JSON string.
+
+        This method retrieves all environment variables, parses their values using the
+        `__parseValue` method, and returns a JSON string representation of the resulting dictionary.
+
+        Returns:
+            str: A JSON string representing all environment variables and their parsed values.
+        """
+
+        # Converts the environment variables to a JSON string.
+        import json
+        return json.dumps(self.all(), indent=4)
+
+    def toBase64(self) -> str:
+        """
+        Converts the environment variables from the `.env` file into a Base64 encoded string.
+
+        This method retrieves all environment variables, parses their values using the
+        `__parseValue` method, and returns a Base64 encoded string representation of the resulting dictionary.
+
+        Returns:
+            str: A Base64 encoded string representing all environment variables and their parsed values.
+        """
+
+        # Converts the environment variables to a Base64 encoded string.
+        import base64
+        import json
+        return base64.b64encode(json.dumps(self.all()).encode()).decode()
+
+    def __parseValue(self, value: Any) -> Any:
+        """
+        Parses a given value and attempts to convert it into an appropriate Python data type.
+        The function handles the following conversions:
+            - Returns None for None, empty strings, or string representations of null values ('none', 'null', 'nan').
+            - Returns the value unchanged if it is already a primitive type (bool, int, float).
+            - Converts string representations of booleans ('true', 'false') to their respective boolean values.
+            - Converts string representations of integers and floats to their respective numeric types.
+            - Attempts to evaluate the string as a Python literal (e.g., lists, dicts, tuples).
+            - Returns the original string if no conversion is possible.
+        Args:
+            value (Any): The value to parse.
+        Returns:
+            Any: The parsed value in its appropriate Python data type, or the original string if no conversion is possible.
+        """
+
+        # Parses a string value into a Python data type.
+        if value is None:
+            return None
+
+        # If it is already a primitive type, return it
+        if isinstance(value, (bool, int, float)):
+            return value
+
+        value_str = str(value).strip()
+
+        # Special cases: empty or representations of None
+        if not value_str or value_str.lower() in {'none', 'null', 'nan'}:
+            return None
+
+        # Booleans
+        if value_str.lower() == 'true':
+            return True
+        if value_str.lower() == 'false':
+            return False
+
+        # Try to convert to int
+        try:
+            if value_str.isdigit() or (value_str.startswith('-') and value_str[1:].isdigit()):
+                return int(value_str)
+        except Exception:
+            pass
+
+        # Try to convert to float
+        try:
+            float_val = float(value_str)
+            # Avoid converting strings like '1e10' to float if it is not really a number
+            if '.' in value_str or 'e' in value_str.lower():
+                return float_val
+        except Exception:
+            pass
+
+        # Try to evaluate as Python literal (lists, dicts, etc.)
+        try:
+            return ast.literal_eval(value_str)
+        except Exception:
+            pass
+
+        # If all else fails, return the original string
+        return value_str
+
+    def __serializeValue(self, value: Any) -> str:
+        """
+        Serializes a Python value into a string suitable for storing in a `.env` file.
+        Supported types:
+            - None: serialized as the string "None"
+            - str: returned as-is
+            - bool: converted to "true" or "false"
+            - int, float: converted to their string representation
+            - list, dict: converted to their string representation using repr()
+        Raises:
+            TypeError: If the value is an instance of a custom class or an unsupported type (e.g., set, tuple).
+        Args:
+            value (Any): The value to serialize.
+        Returns:
+            str: The serialized string representation of the value.
+        """
+
+        # if it is None, return "None"
+        # This is useful to avoid problems when saving None in the .env file
+        if value is None:
+            return "None"
+
+        # If it is a string, return it as is
+        if isinstance(value, str):
+            return value
+
+        # If it is a boolean, convert it to string
+        if isinstance(value, bool):
+            return str(value).lower()
+
+        # If it is a number, convert it to string
+        if isinstance(value, int):
+            return str(value)
+
+        # If is a float, convert it to string
+        if isinstance(value, float):
+            value = str(value)
+            if 'e' in value or 'E' in value:
+                raise ValueError('scientific notation is not supported, use a string instead')
+            return value
+
+        # If it is a list or dictionary, convert them to string
+        if isinstance(value, (list, dict)):
+            return repr(value)
+
+        # If it is an object of a custom class, raise an error
+        # This is useful to avoid problems when saving class instances in the .env file
+        if hasattr(value, '__dict__'):
+            raise TypeError(f"Type {type(value).__name__} is not serializable for .env")
+
+        # If it is an unsupported data type, raise an error
+        # This is useful to avoid problems when saving unsupported data types in the .env file
+        # such as sets, tuples, etc.
+        if not isinstance(value, (list, dict, bool, int, float, str)):
+            raise TypeError(f"Type {type(value).__name__} is not serializable for .env")
+
+        # Serializes a Python data type into a string for storing in the `.env` file.
+        # Only allows simple serializable types and not class instances.
+        if isinstance(value, (list, dict, bool, int, float, str)):
+            # Prevent serializing instances of custom classes
+            if type(value).__module__ != "builtins" and not isinstance(value, str):
+                raise TypeError(f"Type {type(value).__name__} is not serializable for .env")
+            return repr(value) if not isinstance(value, str) else value
+        raise TypeError(f"Type {type(value).__name__} is not serializable for .env")

orionis/luminate/services/environment/env.py

@@ -0,0 +1,77 @@
+from orionis.luminate.services.environment.contracts.env import IEnv
+from orionis.luminate.services.environment.dot_env import DotEnv
+from typing import Any, Optional, Dict
+
+def env(key: str, default: Any = None) -> Any:
+    """
+    Helper function to retrieve the value of an environment variable by key.
+    """
+    return DotEnv().get(key, default)
+
+class Env(IEnv):
+    """
+    Env is a utility class that provides static methods for managing environment variables
+    using the DotEnv class. It allows getting, setting, unsetting, listing, destroying,
+    and serializing environment variables.
+    """
+
+    _dotenv_instance: Optional[DotEnv] = None
+
+    @classmethod
+    def _dotenv(cls) -> DotEnv:
+        if cls._dotenv_instance is None:
+            cls._dotenv_instance = DotEnv()
+        return cls._dotenv_instance
+
+    @staticmethod
+    def get(key: str, default: Any = None) -> Any:
+        """
+        Retrieve the value of an environment variable by key.
+        """
+        return Env._dotenv().get(key, default)
+
+    @staticmethod
+    def set(key: str, value: str) -> bool:
+        """
+        Sets the value of an environment variable.
+        """
+        return Env._dotenv().set(key, value)
+
+    @staticmethod
+    def unset(key: str) -> bool:
+        """
+        Removes the specified environment variable from the environment.
+        """
+        return Env._dotenv().unset(key)
+
+    @staticmethod
+    def all() -> Dict[str, Any]:
+        """
+        Retrieve all environment variables from the DotEnv instance.
+        """
+        return Env._dotenv().all()
+
+    @staticmethod
+    def destroy() -> bool:
+        """
+        Destroys the current environment by resetting the DotEnv instance.
+        """
+        if Env._dotenv_instance is not None:
+            result = Env._dotenv_instance.destroy()
+            Env._dotenv_instance = None
+            return result
+        return False
+
+    @staticmethod
+    def toJson() -> str:
+        """
+        Serializes the current environment variables managed by the DotEnv instance to a JSON-formatted string.
+        """
+        return Env._dotenv().toJson()
+
+    @staticmethod
+    def toBase64() -> str:
+        """
+        Converts the current environment variables to a Base64-encoded string.
+        """
+        return Env._dotenv().toBase64()

orionis/luminate/services/paths/__init__.py

@@ -0,0 +1,9 @@
+from orionis.luminate.services.paths.resolver import Resolver
+
+__all__ = [
+    "Resolver",
+]
+__author__ = "Raúl Mauricio Uñate Castro"
+__description__ = (
+    "This module provides a Resolver class that is used to resolve paths in the Orionis Framework application. "
+)

orionis/luminate/services/paths/contracts/resolver.py

@@ -0,0 +1,67 @@
+from abc import ABC, abstractmethod
+from typing import Optional
+
+class IResolver(ABC):
+    """
+    Interface for a utility class that resolves file and directory paths relative to a base path.
+    """
+
+    @abstractmethod
+    def __init__(self, root_path: Optional[str] = None):
+        """
+        Initializes the resolver with an optional root path.
+
+        Parameters
+        ----------
+        root_path : str, optional
+            The root directory to resolve relative paths from.
+        """
+        pass
+
+    @abstractmethod
+    def relativePath(self, relative_path: str):
+        """
+        Resolves a relative path into an absolute one and validates its existence.
+
+        Parameters
+        ----------
+        relative_path : str
+            The relative path to resolve.
+
+        Returns
+        -------
+        ResolverInterface
+            The instance itself for method chaining.
+
+        Raises
+        ------
+        FileNotFoundError
+            If the resolved path does not exist.
+        ValueError
+            If the resolved path is neither a file nor a directory.
+        """
+        pass
+
+    @abstractmethod
+    def toString(self) -> str:
+        """
+        Returns the resolved path as a string.
+
+        Returns
+        -------
+        str
+            The resolved path.
+        """
+        pass
+
+    @abstractmethod
+    def __str__(self) -> str:
+        """
+        Returns the resolved path as a string (for print or str()).
+
+        Returns
+        -------
+        str
+            The resolved path.
+        """
+        pass

orionis/luminate/services/paths/resolver.py

@@ -0,0 +1,83 @@
+import os
+from pathlib import Path
+from orionis.luminate.support.paths.contracts.resolver import IResolver
+
+class Resolver(IResolver):
+    """
+    A utility class for resolving file and directory paths relative to the project's root directory.
+    """
+
+    def __init__(self, root_path: str = None):
+        """
+        Initializes the Resolver instance with the project's root directory.
+
+        Parameters
+        ----------
+        root_path : str, optional
+            The root directory of the project. If not provided, it defaults to the current working directory.
+        """
+        self.base_path = Path(root_path).resolve() if root_path else Path(os.getcwd()).resolve()
+        self.resolved_path = None
+
+    def relativePath(self, relative_path: str) -> 'Resolver':
+        """
+        Resolves a given relative path to an absolute path and validates its existence.
+
+        This method combines the project's root directory with the provided relative path,
+        resolves it to an absolute path, and ensures it exists as either a directory or a file.
+
+        Parameters
+        ----------
+        relative_path : str
+            The relative path to a directory or file to be resolved.
+
+        Returns
+        -------
+        Resolver
+            The current instance of the Resolver class with the resolved path.
+
+        Raises
+        ------
+        FileNotFoundError
+            If the resolved path does not exist.
+        ValueError
+            If the resolved path is neither a valid directory nor a file.
+        """
+        # Combine the base path with the relative path and resolve it
+        resolved_path = (self.base_path / relative_path).resolve()
+
+        # Validate that the path exists
+        if not resolved_path.exists():
+            raise FileNotFoundError(f"The requested path does not exist: {resolved_path}")
+
+        # Validate that the path is either a directory or a file
+        if not (resolved_path.is_dir() or resolved_path.is_file()):
+            raise ValueError(f"The requested path is neither a valid directory nor a file: {resolved_path}")
+
+        # Store the resolved path in the instance variable
+        self.resolved_path = resolved_path
+
+        # Return the current instance
+        return self
+
+    def toString(self) -> str:
+        """
+        Returns the string representation of the resolved path.
+
+        Returns
+        -------
+        str
+            The resolved path as a string.
+        """
+        return str(self.resolved_path)
+
+    def __str__(self) -> str:
+        """
+        Returns the string representation of the resolved path.
+
+        Returns
+        -------
+        str
+            The resolved path as a string.
+        """
+        return str(self.resolved_path)

orionis/luminate/services/workers/__init__.py

@@ -0,0 +1,10 @@
+from orionis.luminate.services.workers.maximum_workers import MaximumWorkers
+
+__all__ = [
+    "MaximumWorkers",
+]
+__author__ = "Raúl Mauricio Uñate Castro"
+__description__ = (
+    "This module provides a class to calculate the maximum number of workers "
+    "that can be run on a machine based on its CPU and memory resources. "
+)

orionis/luminate/services/workers/maximum_workers.py

@@ -0,0 +1,36 @@
+import multiprocessing
+import math
+import psutil
+
+class MaximumWorkers:
+    """
+    Calculates the optimal number of workers a machine can handle based on CPU and memory resources.
+
+    This class estimates the maximum number of Uvicorn (or similar) workers by considering:
+    - The number of available CPU cores.
+    - The total system memory (RAM).
+    - The estimated memory usage per worker (configurable).
+
+    Parameters
+    ----------
+    ram_per_worker : float, optional
+        Estimated amount of RAM (in GB) that each worker will consume. Default is 0.5 GB.
+    """
+
+    def __init__(self, ram_per_worker: float = 0.5):
+        self._cpu_count = multiprocessing.cpu_count()
+        self._ram_total_gb = psutil.virtual_memory().total / (1024 ** 3)
+        self._ram_per_worker = ram_per_worker
+
+    def calculate(self) -> int:
+        """
+        Computes the maximum number of workers supported by the current machine.
+
+        Returns
+        -------
+        int
+            The recommended number of worker processes based on CPU and memory limits.
+        """
+        max_workers_by_cpu = self._cpu_count
+        max_workers_by_ram = math.floor(self._ram_total_gb / self._ram_per_worker)
+        return min(max_workers_by_cpu, max_workers_by_ram)