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

orionis/luminate/patterns/singleton/__init__.py

@@ -0,0 +1,10 @@
+from orionis.luminate.patterns.singleton.meta_class import Singleton
+
+__all__ = [
+    "Singleton",
+]
+__author__ = "Raúl Mauricio Uñate Castro"
+__description__ = (
+    "This module provides a singleton class to manage environment variables. "
+    "It allows setting, getting, and deleting environment variables."
+)

orionis/luminate/patterns/singleton/meta_class.py

@@ -0,0 +1,56 @@
+import threading
+import asyncio
+from typing import Dict, Type, Any, TypeVar
+
+T = TypeVar('T')
+
+class Singleton(type):
+    """
+    Thread-safe + Async-safe singleton metaclass.
+    Works for both synchronous and asynchronous contexts.
+    """
+
+    _instances: Dict[Type[T], T] = {}
+    _lock = threading.Lock()
+    _async_lock = asyncio.Lock()
+
+    def __call__(cls: Type[T], *args: Any, **kwargs: Any) -> T:
+        """
+        Creates and returns a singleton instance of the class.
+
+        If an instance of the class does not already exist, this method acquires a lock to ensure thread safety,
+        creates a new instance using the provided arguments, and stores it in the class-level _instances dictionary.
+        Subsequent calls return the existing instance.
+
+        Args:
+            *args: Positional arguments to pass to the class constructor.
+            **kwargs: Keyword arguments to pass to the class constructor.
+
+        Returns:
+            T: The singleton instance of the class.
+        """
+        if cls not in cls._instances:
+            with cls._lock:
+                if cls not in cls._instances:
+                    cls._instances[cls] = super().__call__(*args, **kwargs)
+        return cls._instances[cls]
+
+    async def __acall__(cls: Type[T], *args: Any, **kwargs: Any) -> T:
+        """
+        Asynchronously creates or retrieves a singleton instance of the class.
+
+        If an instance of the class does not exist, acquires an asynchronous lock to ensure thread safety,
+        creates the instance, and stores it. Subsequent calls return the existing instance.
+
+        Args:
+            *args: Positional arguments to pass to the class constructor.
+            **kwargs: Keyword arguments to pass to the class constructor.
+
+        Returns:
+            T: The singleton instance of the class.
+        """
+        if cls not in cls._instances:
+            async with cls._async_lock:
+                if cls not in cls._instances:
+                    cls._instances[cls] = super().__call__(*args, **kwargs)
+        return cls._instances[cls]

orionis/luminate/providers/commands/reactor_commands_service_provider.py

@@ -2,9 +2,9 @@ from orionis.luminate.contracts.services.commands.reactor_commands_service impor
 from orionis.luminate.contracts.services.config.config_service import IConfigService
 from orionis.luminate.contracts.services.log.log_service import ILogguerService
 from orionis.luminate.providers.service_provider import ServiceProvider
-from orionis.luminate.services.commands.reactor_commands_service import ReactorCommandsService
-from orionis.luminate.services.config.config_service import ConfigService
-from orionis.luminate.services.log.log_service import LogguerService
+from orionis.luminate.services_.commands.reactor_commands_service import ReactorCommandsService
+from orionis.luminate.services_.config.config_service import ConfigService
+from orionis.luminate.services_.log.log_service import LogguerService
 
 class ReactorCommandsServiceProvider(ServiceProvider):
 

orionis/luminate/providers/commands/scheduler_provider.py

@@ -1,6 +1,6 @@
 from orionis.luminate.contracts.services.commands.schedule_service import IScheduleService
 from orionis.luminate.providers.service_provider import ServiceProvider
-from orionis.luminate.services.commands.scheduler_service import ScheduleService
+from orionis.luminate.services_.commands.scheduler_service import ScheduleService
 
 class ScheduleServiceProvider(ServiceProvider):
 

orionis/luminate/providers/config/config_service_provider.py

@@ -1,6 +1,6 @@
 from orionis.luminate.contracts.services.config.config_service import IConfigService
 from orionis.luminate.providers.service_provider import ServiceProvider
-from orionis.luminate.services.config.config_service import ConfigService
+from orionis.luminate.services_.config.config_service import ConfigService
 
 class ConfigServiceProvider(ServiceProvider):
 

orionis/luminate/providers/environment/environment__service_provider.py

@@ -1,7 +1,7 @@
 from orionis.luminate.contracts.services.environment.environment_service import IEnvironmentService
 from orionis.luminate.providers.service_provider import ServiceProvider
-from orionis.luminate.services.environment.environment_service import EnvironmentService
-from orionis.luminate.services.files.path_resolver_service import PathResolverService
+from orionis.luminate.services_.environment.environment_service import EnvironmentService
+from orionis.luminate.services_.files.path_resolver_service import PathResolverService
 
 class EnvironmentServiceProvider(ServiceProvider):
 

orionis/luminate/providers/files/paths_provider.py

@@ -1,6 +1,6 @@
 from orionis.luminate.contracts.services.files.path_resolver_service import IPathResolverService
 from orionis.luminate.providers.service_provider import ServiceProvider
-from orionis.luminate.services.files.path_resolver_service import PathResolverService
+from orionis.luminate.services_.files.path_resolver_service import PathResolverService
 
 class PathResolverProvider(ServiceProvider):
 

orionis/luminate/providers/log/log_service_provider.py

@@ -1,8 +1,8 @@
 from orionis.luminate.contracts.services.config.config_service import IConfigService
 from orionis.luminate.contracts.services.log.log_service import ILogguerService
 from orionis.luminate.providers.service_provider import ServiceProvider
-from orionis.luminate.services.config.config_service import ConfigService
-from orionis.luminate.services.log.log_service import LogguerService
+from orionis.luminate.services_.config.config_service import ConfigService
+from orionis.luminate.services_.log.log_service import LogguerService
 
 class LogServiceProvider(ServiceProvider):
 

orionis/luminate/services/environment/__init__.py

@@ -0,0 +1,10 @@
+from orionis.luminate.services.environment.env import Env
+
+__all__ = [
+    "Env",
+]
+__author__ = "Raúl Mauricio Uñate Castro"
+__description__ = (
+    "This module provides a singleton class to manage environment variables. "
+    "It allows setting, getting, and deleting environment variables."
+)

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

@@ -0,0 +1,5 @@
+from orionis.luminate.services.environment.dot_env import DotEnv
+
+__all__ = [
+    "DotEnv",
+]

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. "
+)