orionis 0.286.0__tar.gz → 0.288.0__tar.gz

{orionis-0.286.0/orionis.egg-info → orionis-0.288.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: orionis
-Version: 0.286.0
+Version: 0.288.0
 Summary: Orionis Framework – Elegant, Fast, and Powerful.
 Home-page: https://github.com/orionis-framework/framework
 Author: Raul Mauricio Uñate Castro

{orionis-0.286.0 → orionis-0.288.0}/orionis/metadata/framework.py

@@ -5,7 +5,7 @@
 NAME = "orionis"
 
 # Current version of the framework
-VERSION = "0.286.0"
+VERSION = "0.288.0"
 
 # Full name of the author or maintainer of the project
 AUTHOR = "Raul Mauricio Uñate Castro"

orionis-0.288.0/orionis/services/environment/contracts/env.py

@@ -0,0 +1,77 @@
+from typing import Any, Dict
+from abc import ABC, abstractmethod
+
+class IEnv(ABC):
+
+    @staticmethod
+    @abstractmethod
+    def get(key: str, default: Any = None) -> Any:
+        """
+        Retrieve the value of an environment variable by key.
+
+        Parameters
+        ----------
+        key : str
+            The name of the environment variable to retrieve.
+        default : Any, optional
+            The value to return if the key is not found. Default is None.
+
+        Returns
+        -------
+        Any
+            The value of the environment variable if found, otherwise the default value.
+        """
+        pass
+
+    @staticmethod
+    @abstractmethod
+    def set(key: str, value: str, type: str = None) -> bool:
+        """
+        Set an environment variable in the .env file.
+
+        Parameters
+        ----------
+        key : str
+            The name of the environment variable to set.
+        value : str
+            The value to assign to the environment variable.
+        type : str, optional
+            The type of the environment variable (e.g., 'str', 'int'). Default is None.
+
+        Returns
+        -------
+        bool
+            True if the variable was set successfully, False otherwise.
+        """
+        pass
+
+    @staticmethod
+    @abstractmethod
+    def unset(key: str) -> bool:
+        """
+        Remove the specified environment variable from the .env file.
+
+        Parameters
+        ----------
+        key : str
+            The name of the environment variable to remove.
+
+        Returns
+        -------
+        bool
+            True if the variable was successfully removed, False otherwise.
+        """
+        pass
+
+    @staticmethod
+    @abstractmethod
+    def all() -> Dict[str, Any]:
+        """
+        Retrieve all environment variables as a dictionary.
+
+        Returns
+        -------
+        dict of str to Any
+            A dictionary containing all environment variables loaded by DotEnv.
+        """
+        pass

orionis-0.288.0/orionis/services/environment/contracts/types.py

@@ -0,0 +1,70 @@
+from abc import ABC, abstractmethod
+
+class IEnvTypes(ABC):
+
+    @abstractmethod
+    def to(self, type_hint: str):
+        """
+        Set the type hint for the Type instance.
+
+        Parameters
+        ----------
+        type_hint : str
+            The type hint to set, which must be one of the valid options defined in OPTIONS.
+
+        Raises
+        ------
+        OrionisEnvironmentValueError
+            If the provided type hint is not one of the valid options.
+        """
+        pass
+
+    @abstractmethod
+    def hasValidTypeHint(self) -> bool:
+        """
+        Check if the type hint is valid.
+
+        Returns
+        -------
+        bool
+            True if the type hint is valid (exists in the OPTIONS set), False otherwise.
+        """
+        pass
+
+    @abstractmethod
+    def explode(self) -> tuple:
+        """
+        Returns a tuple containing the type hint and value string.
+
+        Returns
+        -------
+        tuple
+            A tuple (type_hint, value_str) where:
+                type_hint : str or None
+                    The extracted type hint in lowercase, or None if not provided.
+                value_str : str or None
+                    The extracted value string, or None if not provided.
+        """
+        pass
+
+    @abstractmethod
+    def get(self):
+        """
+        Returns the value corresponding to the specified type hint.
+
+        Checks if the provided type hint is valid and then dispatches the call to the appropriate
+        method for handling the type.
+
+        Supported type hints include: 'path:', 'str:', 'int:', 'float:', 'bool:', 'list:', 'dict:', 'tuple:', and 'set:'.
+
+        Returns
+        -------
+        Any
+            The value converted or processed according to the specified type hint.
+
+        Raises
+        ------
+        OrionisEnvironmentValueError
+            If the type hint is not one of the supported options.
+        """
+        pass

orionis-0.288.0/orionis/services/environment/dot_env.py

@@ -0,0 +1,269 @@
+import os
+import ast
+import re
+import threading
+from pathlib import Path
+from typing import Any, Optional, Union
+from dotenv import dotenv_values, load_dotenv, set_key, unset_key
+from orionis.patterns.singleton.meta_class import Singleton
+from orionis.services.environment.exceptions.environment_value_exception import OrionisEnvironmentValueException
+from orionis.services.environment.exceptions.environment_value_error import OrionisEnvironmentValueError
+from orionis.services.environment.types import EnvTypes
+
+class DotEnv(metaclass=Singleton):
+
+    # Thread-safe singleton instance lock
+    _lock = threading.RLock()
+
+    def __init__(self, path: str = None) -> None:
+        """
+        Initialize the environment service by resolving the path to the `.env` file, ensuring its existence,
+        and loading environment variables from it.
+
+        Parameters
+        ----------
+        path : str, optional
+            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.
+        """
+        try:
+            with self._lock:
+                if path:
+                    self._resolved_path = Path(path).expanduser().resolve()
+                else:
+                    self._resolved_path = Path(os.getcwd()) / ".env"
+
+                if not self._resolved_path.exists():
+                    self._resolved_path.touch()
+
+                load_dotenv(self._resolved_path)
+        except OSError as e:
+            raise OSError(f"Failed to create or access the .env file at {self._resolved_path}: {e}")
+
+    def get(self, key: str, default: Optional[Any] = None) -> Any:
+        """
+        Get the value of an environment variable.
+
+        Parameters
+        ----------
+        key : str
+            Name of the environment variable to retrieve.
+        default : Any, optional
+            Value to return if the key is not found. Default is None.
+
+        Returns
+        -------
+        Any
+            Parsed value of the environment variable, or `default` if not found.
+
+        Raises
+        ------
+        OrionisEnvironmentValueError
+            If `key` is not a string.
+        """
+        with self._lock:
+
+            # Ensure the key is a string.
+            if not isinstance(key, str):
+                raise OrionisEnvironmentValueError(
+                    f"Key must be a string, got {type(key).__name__}."
+                )
+
+            # Get the value from the .env file or the current environment.
+            value = dotenv_values(self._resolved_path).get(key)
+
+            # If the value is not found in the .env file, check the current environment variables.
+            if value is None:
+                value = os.getenv(key)
+
+            # Parse the value using the internal __parseValue method and return it
+            return self.__parseValue(value) if value is not None else default
+
+    def __parseValue(self, value: Any) -> Any:
+        """
+        Parse and convert the input value to an appropriate Python data type with enhanced features.
+
+        Parameters
+        ----------
+        value : Any
+            The value to parse and convert.
+
+        Returns
+        -------
+        Any
+            The parsed value, which may be of type None, bool, int, float, list, dict, or str.
+            - Returns None for None, empty strings, or strings like 'none', 'null', 'nan' (case-insensitive).
+            - Returns a boolean for 'true'/'false' strings (case-insensitive) or 1/0.
+            - Returns an int if the string represents an integer.
+            - Returns a float if the string represents a float.
+            - Attempts to evaluate the string as a Python literal (e.g., list, dict, tuple).
+            - Handles type hints via 'type:' prefix (e.g., 'int:42', 'bool:true').
+            - Returns the original string if no conversion is possible.
+
+        Raises
+        ------
+        OrionisEnvironmentValueException
+            If type conversion fails for explicitly typed values (e.g., 'abc::int').
+        """
+        # Early return for None
+        if value is None:
+            return None
+
+        # Return immediately if already a basic type
+        if isinstance(value, (bool, int, float, dict, list, tuple, set)):
+            return value
+
+        # Convert to string and clean
+        value_str = str(value).strip()
+
+        # Handle empty strings and common null representations
+        # This includes 'none', 'null', 'nan', 'nil' (case-insensitive)
+        if not value_str or value_str.lower() in {'none', 'null', 'nan', 'nil'}:
+            return None
+
+        # Boolean detection (without type hint)
+        lower_val = value_str.lower()
+        if lower_val in ('true', 'false', 'yes', 'no', 'on', 'off', '1', '0'):
+            return lower_val in ('true', 'yes', 'on', '1')
+
+        # Handle type hints using the Type class
+        hints = EnvTypes(value_str)
+        if hints.hasValidTypeHint():
+            return hints.get()
+
+        # Try parseing to literal types, if failed, return the original value
+        try:
+            return ast.literal_eval(value_str)
+        except (ValueError, SyntaxError):
+            return value_str
+
+    def set(self, key: str, value: Union[str, int, float, bool, list, dict, tuple, set], type_hint: str = None) -> bool:
+        """
+        Set an environment variable with the specified key and value.
+
+        Serializes the given value and updates both the .env file and the current process's environment variables.
+
+        Parameters
+        ----------
+        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. Supported types include string, integer, float, boolean, list, and dictionary.
+        type_hint : str, optional
+            The type of the value being set. If provided, it can be (path, str, int, float, bool, list, dict, tuple, set).
+
+        Returns
+        -------
+        bool
+            True if the environment variable was successfully set.
+        """
+        with self._lock:
+
+            # Ensure the key is a string.
+            if not isinstance(key, str) or not re.match(r'^[A-Z][A-Z0-9_]*$', key):
+                raise OrionisEnvironmentValueError(
+                    f"The environment variable name '{key}' is not valid. It must be an uppercase string, may contain numbers and underscores, and must always start with a letter. Example of a valid name: 'MY_ENV_VAR'."
+                )
+
+            # Ensure the value is a valid type.
+            if not isinstance(value, (str, int, float, bool, list, dict, tuple, set)):
+                raise OrionisEnvironmentValueError(
+                    f"Unsupported value type: {type(value).__name__}. Allowed types are str, int, float, bool, list, dict, tuple, set."
+                )
+
+            # Dinamically determine the type hint if not provided.
+            if isinstance(value, (int, float, bool, list, dict, tuple, set)) and not type_hint:
+                type_hint = type(value).__name__.lower()
+
+            # Validate the type hint if provided.
+            options = EnvTypes.options()
+            if type_hint and type_hint not in options:
+                raise OrionisEnvironmentValueException(f"Invalid type hint: {type_hint}. Allowed types are {str(options)}.")
+
+            # Serialize the value based on its type.
+            serialized_value = self.__serializeValue(value, type_hint)
+
+            # Set the environment variable in the .env file and the current process environment.
+            set_key(str(self._resolved_path), key, serialized_value)
+            os.environ[key] = str(value)
+
+            # Return True to indicate success.
+            return True
+
+    def __serializeValue(self, value: Any, type_hint: str = None) -> str:
+        """
+        Parameters
+        ----------
+        value : Any
+            The value to serialize.
+        type_hint : str, optional
+            An optional type hint to guide serialization.
+        Returns
+        -------
+        str
+            The serialized string representation of the value.
+        Notes
+        -----
+        - If `value` is None, returns "null".
+        - If `type_hint` is provided, uses `EnvTypes` to serialize.
+        - Uses `repr()` for lists, dicts, tuples, and sets.
+        - Falls back to `str()` for other types.
+        """
+
+        if value is None:
+            return "null"
+
+        if type_hint:
+            return EnvTypes(value).to(type_hint)
+
+        if isinstance(value, str):
+            return value.strip()
+
+        if isinstance(value, bool):
+            return str(value).lower()
+
+        if isinstance(value, int, float):
+            return str(value)
+
+        if isinstance(value, (list, dict, tuple, set)):
+            return repr(value)
+
+        return str(value)
+
+    def unset(self, key: str) -> bool:
+        """
+        Remove the specified environment variable from both the .env file and the current process environment.
+
+        Parameters
+        ----------
+        key : str
+            The name of the environment variable to unset.
+
+        Returns
+        -------
+        bool
+            True if the operation was successful.
+        """
+        with self._lock:
+            unset_key(str(self._resolved_path), key)
+            os.environ.pop(key, None)
+            return True
+
+    def all(self) -> dict:
+        """
+        Retrieve all environment variables from the resolved .env file.
+
+        Returns
+        -------
+        dict
+            Dictionary containing all environment variable key-value pairs,
+            with values parsed using the internal __parseValue method.
+        """
+        with self._lock:
+            raw_values = dotenv_values(self._resolved_path)
+            return {k: self.__parseValue(v) for k, v in raw_values.items()}

orionis-0.288.0/orionis/services/environment/env.py

@@ -0,0 +1,97 @@
+from orionis.services.environment.contracts.env import IEnv
+from orionis.services.environment.dot_env import DotEnv
+from typing import Any, Dict
+
+def env(key: str, default: Any = None) -> Any:
+    """
+    Retrieve the value of an environment variable.
+
+    Parameters
+    ----------
+    key : str
+        The name of the environment variable to retrieve.
+    default : Any, optional
+        The value to return if the environment variable is not found. Default is None.
+
+    Returns
+    -------
+    Any
+        The value of the environment variable if it exists, otherwise the default value.
+    """
+    dotenv = DotEnv()
+    return dotenv.get(key, default)
+
+class Env(IEnv):
+
+    @staticmethod
+    def get(key: str, default: Any = None) -> Any:
+        """
+        Retrieve the value of an environment variable by key.
+
+        Parameters
+        ----------
+        key : str
+            The name of the environment variable to retrieve.
+        default : Any, optional
+            The value to return if the key is not found. Default is None.
+
+        Returns
+        -------
+        Any
+            The value of the environment variable if found, otherwise the default value.
+        """
+        dotenv = DotEnv()
+        return dotenv.get(key, default)
+
+    @staticmethod
+    def set(key: str, value: str, type_hint: str = None) -> bool:
+        """
+        Set an environment variable in the .env file.
+
+        Parameters
+        ----------
+        key : str
+            The name of the environment variable to set.
+        value : str
+            The value to assign to the environment variable.
+        type_hint : str, optional
+            The type of the environment variable (e.g., 'str', 'int'). Default is None.
+
+        Returns
+        -------
+        bool
+            True if the variable was set successfully, False otherwise.
+        """
+        dotenv = DotEnv()
+        return dotenv.set(key, value, type_hint)
+
+    @staticmethod
+    def unset(key: str) -> bool:
+        """
+        Remove the specified environment variable from the .env file.
+
+        Parameters
+        ----------
+        key : str
+            The name of the environment variable to remove.
+
+        Returns
+        -------
+        bool
+            True if the variable was successfully removed, False otherwise.
+        """
+        dotenv = DotEnv()
+        return dotenv.unset(key)
+
+    @staticmethod
+    def all() -> Dict[str, Any]:
+        """
+        Retrieve all environment variables as a dictionary.
+
+        Returns
+        -------
+        dict of str to Any
+            A dictionary containing all environment variables loaded by DotEnv.
+        """
+        dotenv = DotEnv()
+        return dotenv.all()

orionis-0.286.0/orionis/services/paths/exceptions/path_value_exceptions.py → orionis-0.288.0/orionis/services/environment/exceptions/environment_value_error.py

@@ -1,18 +1,8 @@
-class OrionisPathValueException(Exception):
-    """
-    Exception raised when a file is not found in the Orionis framework.
-
-    Args:
-        msg (str): A detailed message describing the missing file.
-
-    Example:
-        raise OrionisFileNotFoundException("File 'config.yaml' not found.")
-    """
+class OrionisEnvironmentValueError(Exception):
 
     def __init__(self, msg: str):
         """
         Initializes the exception with a custom error message.
-
         Args:
             msg (str): The error message describing the exception.
         """
@@ -23,6 +13,6 @@ class OrionisPathValueException(Exception):
         Return a string representation of the exception, including the class name and the first argument.
 
         Returns:
-            str: A formatted string with the exception class name and the first argument.
+            str: A formatted string with the exception class name and its first argument.
         """
         return f"{self.__class__.__name__}: {self.args[0]}"

orionis-0.288.0/orionis/services/environment/exceptions/environment_value_exception.py

@@ -0,0 +1,23 @@
+class OrionisEnvironmentValueException(Exception):
+
+    def __init__(self, msg: str):
+        """
+        Exception raised for errors related to environment values.
+
+        Parameters
+        ----------
+        msg : str
+            The error message describing the exception.
+        """
+        super().__init__(msg)
+
+    def __str__(self) -> str:
+        """
+        Returns a string representation of the exception.
+
+        Returns
+        -------
+        str
+            A formatted string with the exception class name and its first argument.
+        """
+        return f"{self.__class__.__name__}: {self.args[0]}"