orionis 0.286.0__py3-none-any.whl → 0.288.0__py3-none-any.whl

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/services/environment/contracts/env.py

@@ -1,36 +1,47 @@
-from typing import Any, Dict, Optional
+from typing import Any, Dict
 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:
+    def get(key: str, default: 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
+        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) -> bool:
+    def set(key: str, value: str, type: str = None) -> bool:
         """
-        Sets an environment variable.
-
-        Args:
-            key: Environment variable name
-            value: Value to set
-
-        Returns:
-            True if successful, False otherwise
+        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
 
@@ -38,13 +49,17 @@ class IEnv(ABC):
     @abstractmethod
     def unset(key: str) -> bool:
         """
-        Removes an environment variable.
+        Remove the specified environment variable from the .env file.
 
-        Args:
-            key: Environment variable name
+        Parameters
+        ----------
+        key : str
+            The name of the environment variable to remove.
 
-        Returns:
-            True if successful, False otherwise
+        Returns
+        -------
+        bool
+            True if the variable was successfully removed, False otherwise.
         """
         pass
 
@@ -52,31 +67,11 @@ class IEnv(ABC):
     @abstractmethod
     def all() -> Dict[str, Any]:
         """
-        Retrieves all environment variables.
-
-        Returns:
-            Dictionary of all key-value pairs
-        """
-        pass
-
-    @staticmethod
-    @abstractmethod
-    def toJson() -> str:
-        """
-        Serializes environment to JSON.
-
-        Returns:
-            JSON string representation
-        """
-        pass
-
-    @staticmethod
-    @abstractmethod
-    def toBase64() -> str:
-        """
-        Encodes environment to Base64.
+        Retrieve all environment variables as a dictionary.
 
-        Returns:
-            Base64 encoded string
+        Returns
+        -------
+        dict of str to Any
+            A dictionary containing all environment variables loaded by DotEnv.
         """
         pass

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/services/environment/dot_env.py

@@ -1,247 +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.value_exception import OrionisEnvironmentValueException
+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):
-    """
-    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.
-    """
 
+    # Thread-safe singleton instance lock
     _lock = threading.RLock()
 
     def __init__(self, path: str = None) -> None:
         """
-        Initializes the environment service by resolving the path to the `.env` file, ensuring its existence,
+        Initialize 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.
-        """
-
-        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)
-
-    def get(self, key: str, default: Optional[Any] = None, is_path:bool=False) -> Any:
-        """
-        Retrieve the value of an environment variable by key.
-
-        This method first attempts to fetch the value from the dotenv file specified by
-        `self._resolved_path`. If the key is not found in the dotenv file, it falls back
-        to the system environment variables. If the key is not found in either location,
-        the provided `default` value is returned.
-
-        The returned value is parsed using the internal `__parseValue` method if found.
-
-        Args:
-            key (str): The name of the environment variable to retrieve.
-            default (Optional[Any], optional): The value to return if the key is not found.
-                Defaults to None.
-            is_path (bool, optional): If True, the value is treated as a file path and backslashes are replaced with forward slashes.
-                This is useful for Windows paths. Defaults to False.
-
-        Returns:
-            Any: The parsed value of the environment variable, or the default if not found.
-        """
-        with self._lock:
-            value = dotenv_values(self._resolved_path).get(key)
-            if value is None:
-                value = os.getenv(key)
-            return self.__parseValue(value, is_path) if value is not None else default
-
-    def set(self, key: str, value: Union[str, int, float, bool, list, dict], is_path:bool=False) -> bool:
-        """
-        Sets an environment variable with the specified key and value.
-
-        This method serializes the given value and updates both the .env file and the current process's environment variables.
-
-        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. Supported types include string, integer, float, boolean, list, and dictionary.
-            is_path (bool, optional): If True, the value is treated as a file path and backslashes are replaced with forward slashes.
-            This is useful for Windows paths. Defaults to False.
 
-        Returns:
-            bool: True if the environment variable was successfully set.
-        """
-
-        with self._lock:
-            serialized_value = self.__serializeValue(value, is_path)
-            set_key(str(self._resolved_path), key, serialized_value)
-            os.environ[key] = str(value)
-            return True
+        Parameters
+        ----------
+        path : str, optional
+            Path to the `.env` file. If not provided, defaults to a `.env` file
+            in the current working directory.
 
-    def unset(self, key: str) -> bool:
+        Raises
+        ------
+        OSError
+            If the `.env` file cannot be created when it does not exist.
         """
-        Removes the specified environment variable from both the .env file and the current process environment.
+        try:
+            with self._lock:
+                if path:
+                    self._resolved_path = Path(path).expanduser().resolve()
+                else:
+                    self._resolved_path = Path(os.getcwd()) / ".env"
 
-        Args:
-            key (str): The name of the environment variable to unset.
+                if not self._resolved_path.exists():
+                    self._resolved_path.touch()
 
-        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
+                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 all(self) -> dict:
+    def get(self, key: str, default: Optional[Any] = None) -> Any:
         """
-        Retrieves all environment variables from the resolved .env file.
-
-        Returns:
-            dict: A dictionary containing all environment variable key-value pairs,
-                  with values parsed using the internal __parseValue method.
+        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:
-            raw_values = dotenv_values(self._resolved_path)
-            return {k: self.__parseValue(v) for k, v in raw_values.items()}
 
-    def toJson(self) -> str:
-        """
-        Serializes all environment variables managed by this instance to a JSON-formatted string.
+            # Ensure the key is a string.
+            if not isinstance(key, str):
+                raise OrionisEnvironmentValueError(
+                    f"Key must be a string, got {type(key).__name__}."
+                )
 
-        Returns:
-            str: A JSON string representation of all environment variables, formatted with indentation for readability.
-        """
-        import json
-        with self._lock:
-            return json.dumps(self.all(), indent=4)
+            # Get the value from the .env file or the current environment.
+            value = dotenv_values(self._resolved_path).get(key)
 
-    def toBase64(self) -> str:
-        """
-        Serializes all environment variables to a JSON string and encodes it in Base64.
+            # If the value is not found in the .env file, check the current environment variables.
+            if value is None:
+                value = os.getenv(key)
 
-        Returns:
-            str: A Base64-encoded string representation of all environment variables.
-        """
-        import base64
-        import json
-        with self._lock:
-            return base64.b64encode(json.dumps(self.all()).encode()).decode()
+            # 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, is_path:bool=False) -> Any:
+    def __parseValue(self, value: Any) -> Any:
         """
-        Parses and converts the input value to an appropriate Python data type.
-
-        Args:
-            value (Any): The value to parse and convert.
-
-        Returns:
-            Any: The parsed value, which may be of type None, bool, int, float, or the original string.
-                - Returns None for None, empty strings, or strings like 'none', 'null', 'nan' (case-insensitive).
-                - Returns a boolean for 'true'/'false' strings (case-insensitive).
-                - 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).
-                - Returns the original string if no conversion is possible.
+        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
 
-        if isinstance(value, (bool, int, float)):
+        # 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()
-        if not value_str or value_str.lower() in {'none', 'null', 'nan'}:
-            return None
 
-        if value_str.lower() == 'true':
-            return True
+        # 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
 
-        if value_str.lower() == 'false':
-            return False
+        # 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')
 
-        if is_path:
-            return value_str.replace("\\", "/")
+        # 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:
-            if value_str.isdigit() or (value_str.startswith('-') and value_str[1:].isdigit()):
-                return int(value_str)
-        except Exception:
-            pass
+            return ast.literal_eval(value_str)
+        except (ValueError, SyntaxError):
+            return value_str
 
-        try:
-            float_val = float(value_str)
-            if '.' in value_str or 'e' in value_str.lower():
-                return float_val
-        except Exception:
-            pass
+    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:
 
-        try:
-            return ast.literal_eval(value_str)
-        except Exception:
-            pass
+            # 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'."
+                )
 
-        return value_str
+            # 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."
+                )
 
-    def __serializeValue(self, value: Any, is_path:bool=False) -> str:
-        """
-        Serializes a given value to a string suitable for storage in a .env file.
+            # 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)
 
-        Parameters:
-            value (Any): The value to serialize. Supported types are None, str, bool, int, float, list, and dict.
-            is_path (bool): If True, the value is treated as a file path and backslashes are replaced with forward slashes.
-            This is useful for Windows paths.
+            # 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)
 
-        Returns:
-            str: The serialized string representation of the value.
+            # Return True to indicate success.
+            return True
 
-        Raises:
-            OrionisEnvironmentValueException: If a float value is in scientific notation or  If the value's type is not serializable for .env files.
+    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 is_path:
-            return str(value).replace("\\", "/")
 
         if value is None:
-            return "None"
+            return "null"
+
+        if type_hint:
+            return EnvTypes(value).to(type_hint)
 
         if isinstance(value, str):
-            return value
+            return value.strip()
 
         if isinstance(value, bool):
             return str(value).lower()
 
-        if isinstance(value, int):
+        if isinstance(value, int, float):
             return str(value)
 
-        if isinstance(value, float):
-            value = str(value)
-            if 'e' in value or 'E' in value:
-                raise OrionisEnvironmentValueException('scientific notation is not supported, use a string instead')
-            return value
-
-        if isinstance(value, (list, dict)):
+        if isinstance(value, (list, dict, tuple, set)):
             return repr(value)
 
-        if hasattr(value, '__dict__'):
-            raise OrionisEnvironmentValueException(f"Type {type(value).__name__} is not serializable for .env")
+        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.
 
-        if not isinstance(value, (list, dict, bool, int, float, str)):
-            raise OrionisEnvironmentValueException(f"Type {type(value).__name__} is not serializable for .env")
+        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
 
-        if isinstance(value, (list, dict, bool, int, float, str)):
-            if type(value).__module__ != "builtins" and not isinstance(value, str):
-                raise OrionisEnvironmentValueException(f"Type {type(value).__name__} is not serializable for .env")
-            return repr(value) if not isinstance(value, str) else value
+    def all(self) -> dict:
+        """
+        Retrieve all environment variables from the resolved .env file.
 
-        raise OrionisEnvironmentValueException(f"Type {type(value).__name__} is not serializable for .env")
+        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()}