orionis 0.420.0__py3-none-any.whl → 0.422.0__py3-none-any.whl

orionis/foundation/config/testing/entities/testing.py

@@ -66,7 +66,7 @@ class Testing(BaseEntity):
         default_factory = lambda : Workers().calculate(),
         metadata = {
             "description": "The maximum number of worker threads/processes to use when running tests in parallel.",
-            "default": Workers().calculate()
+            "default": lambda : Workers().calculate()
         }
     )
 
@@ -159,6 +159,7 @@ class Testing(BaseEntity):
     )
 
     def __post_init__(self):
+        super().__post_init__()
         """
         Validate and normalize configuration options after initialization.
 

orionis/metadata/framework.py

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

orionis/services/environment/contracts/{types.py → caster.py}

@@ -1,6 +1,6 @@
 from abc import ABC, abstractmethod
 
-class IEnvTypes(ABC):
+class IEnvironmentCaster(ABC):
 
     @abstractmethod
     def to(self, type_hint: str):
@@ -19,34 +19,6 @@ class IEnvTypes(ABC):
         """
         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):
         """

orionis/services/environment/core/dot_env.py

@@ -1,33 +1,35 @@
 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.services.environment.enums.cast_type import EnvCastType
+from orionis.services.environment.enums.value_type import EnvironmentValueType
 from orionis.services.environment.validators.key_name import ValidateKeyName
 from orionis.services.environment.validators.types import ValidateTypes
 from orionis.support.patterns.singleton import Singleton
-from orionis.services.environment.exceptions import OrionisEnvironmentValueException, OrionisEnvironmentValueError
-from orionis.services.environment.dynamic.types import EnvTypes
+from orionis.services.environment.dynamic.caster import EnvironmentCaster
 
 class DotEnv(metaclass=Singleton):
 
     # Thread-safe singleton instance lock
     _lock = threading.RLock()
 
-    def __init__(self, path: str = None) -> None:
+    def __init__(
+        self,
+        path: str = None
+    ) -> None:
         """
-        Initialize the DotEnv service by resolving and preparing the `.env` file.
+        Initialize the DotEnv service and prepare the `.env` file for environment variable management.
 
-        This method determines the path to the `.env` file, ensures its existence,
-        and loads environment variables from it into the current process environment.
+        This constructor determines the location of the `.env` file, ensures its existence,
+        and loads its contents into the current process environment. If a custom path is provided,
+        it is resolved and used; otherwise, a `.env` file in the current working directory is used.
 
         Parameters
         ----------
         path : str, optional
-            The path to the `.env` file. If not provided, defaults to a `.env` file
+            The path to the `.env` file. If not specified, defaults to a `.env` file
             in the current working directory.
 
         Returns
@@ -42,19 +44,19 @@ class DotEnv(metaclass=Singleton):
 
         Notes
         -----
-        - If the specified `.env` file does not exist, it will be created.
-        - Environment variables from the `.env` file are loaded into the process environment.
+        - Ensures thread safety during initialization.
+        - If the specified `.env` file does not exist, it is created automatically.
+        - Loads environment variables from the `.env` file into the process environment.
         """
-
         try:
 
-            # Use a thread-safe lock to ensure only one thread can execute this block at a time
+            # Ensure thread-safe initialization
             with self._lock:
 
-                # Defualt Environment file path
+                # Set default .env file path to current working directory
                 self.__resolved_path = Path(os.getcwd()) / ".env"
 
-                # If a path is provided, resolve it
+                # If a custom path is provided, resolve and use it
                 if path:
                     self.__resolved_path = Path(path).expanduser().resolve()
 
@@ -70,105 +72,67 @@ class DotEnv(metaclass=Singleton):
             # Raise an error if the .env file cannot be created or accessed
             raise OSError(f"Failed to create or access the .env file at {self.__resolved_path}: {e}")
 
-    def __parseValue(self, value: Any) -> Any:
+    def set(
+        self,
+        key: str,
+        value: Union[str, int, float, bool, list, dict, tuple, set],
+        type_hint: str | EnvironmentValueType = None
+    ) -> bool:
         """
-        Parse and convert the input value to an appropriate Python data type with enhanced features.
+        Set an environment variable in both the `.env` file and the current process environment.
+
+        This method serializes the provided value (optionally using a type hint), validates the key,
+        and updates the corresponding entry in the `.env` file as well as the process's environment
+        variables. Thread safety is ensured during the operation.
 
         Parameters
         ----------
-        value : Any
-            The value to parse and convert.
+        key : str
+            The name of the environment variable to set. Must be a valid environment variable name.
+        value : Union[str, int, float, bool, list, dict, tuple, set]
+            The value to assign to the environment variable. Supported types include string, integer,
+            float, boolean, list, dictionary, tuple, and set.
+        type_hint : str or EnvironmentValueType, optional
+            An explicit type hint to guide serialization. If provided, the value is serialized
+            according to the specified type.
 
         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.
+        bool
+            Returns True if the environment variable was successfully set in both the `.env` file
+            and the current process environment.
 
         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 __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.
+        OrionisEnvironmentValueError
+            If the provided key is not a valid environment variable name.
         """
+        with self._lock:
+            # Validate the environment variable key name.
+            __key = ValidateKeyName(key)
 
-        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 a type hint is provided, validate and serialize the value accordingly.
+            if type_hint is not None:
+                __type = ValidateTypes(value, type_hint)
+                __value = self.__serializeValue(value, __type)
+            else:
+                # Serialize the value without a type hint.
+                __value = self.__serializeValue(value)
 
-        if isinstance(value, int, float):
-            return str(value)
+            # Set the environment variable in the .env file.
+            set_key(self.__resolved_path, __key, __value)
 
-        if isinstance(value, (list, dict, tuple, set)):
-            return repr(value)
+            # Update the environment variable in the current process environment.
+            os.environ[__key] = __value
 
-        return str(value)
+            # Indicate successful operation.
+            return True
 
-    def get(self, key: str, default: Optional[Any] = None) -> Any:
+    def get(
+        self,
+        key: str,
+        default: Optional[Any] = None
+    ) -> Any:
         """
         Get the value of an environment variable.
 
@@ -192,89 +156,213 @@ class DotEnv(metaclass=Singleton):
         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__}."
-                )
+            __key = ValidateKeyName(key)
 
             # Get the value from the .env file or the current environment.
-            value = dotenv_values(self.__resolved_path).get(key)
+            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)
+                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 set(self, key: str, value: Union[str, int, float, bool, list, dict, tuple, set], type_hint: str | EnvCastType = None) -> bool:
+    def unset(self, key: str) -> bool:
         """
-        Set an environment variable with the specified key and value.
+        Remove an environment variable from both the `.env` file and the current process environment.
 
-        Serializes the given value and updates both the .env file and the current process's environment variables.
+        This method deletes the specified environment variable from the resolved `.env` file
+        and removes it from the current process's environment variables. The operation is
+        performed in a thread-safe manner. The key is validated before removal.
 
         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).
+            The name of the environment variable to remove. Must be a valid environment variable name.
 
         Returns
         -------
         bool
-            True if the environment variable was successfully set.
+            Returns True if the environment variable was successfully removed from both the `.env` file
+            and the process environment. Returns True even if the variable does not exist.
+
+        Raises
+        ------
+        OrionisEnvironmentValueError
+            If the provided key is not a valid environment variable name.
+
+        Notes
+        -----
+        - The method is thread-safe.
+        - If the environment variable does not exist, the method has no effect and returns True.
         """
         with self._lock:
 
-            # Ensure name key is valid.
-            key = ValidateKeyName(key)
-            type = ValidateTypes(value, type_hint)
+            # Validate the environment variable key name.
+            validated_key = ValidateKeyName(key)
 
+            # Remove the key from the .env file.
+            unset_key(self.__resolved_path, validated_key)
 
+            # Remove the key from the current process environment, if present.
+            os.environ.pop(validated_key, None)
 
-            
-            # Serialize the value based on its type.
-            serialized_value = self.__serializeValue(value, type_hint)
+            # Indicate successful operation.
+            return True
 
-            # 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)
+    def all(self) -> dict:
+        """
+        Retrieve all environment variables from the resolved `.env` file as a dictionary.
 
-            # Return True to indicate success.
-            return True
+        This method reads all key-value pairs from the currently resolved `.env` file and
+        parses each value into its appropriate Python type using the internal `__parseValue`
+        method. The returned dictionary contains environment variable names as keys and their
+        parsed values as values.
 
-    def unset(self, key: str) -> bool:
+        Returns
+        -------
+        dict
+            A dictionary where each key is an environment variable name (str) and each value
+            is the parsed Python representation of the variable as determined by `__parseValue`.
+            If the `.env` file is empty, an empty dictionary is returned.
+
+        Notes
+        -----
+        - Thread safety is ensured during the read operation.
+        - Only variables present in the `.env` file are returned; variables set only in the
+          process environment are not included.
+        """
+        with self._lock:
+
+            # Read all raw key-value pairs from the .env file
+            raw_values = dotenv_values(self.__resolved_path)
+
+            # Parse each value and return as a dictionary
+            return {k: self.__parseValue(v) for k, v in raw_values.items()}
+
+    def __serializeValue(
+        self,
+        value: Any,
+        type_hint: str | EnvironmentValueType = None
+    ) -> str:
         """
-        Remove the specified environment variable from both the .env file and the current process environment.
+        Serialize a Python value into a string suitable for storage in a .env file.
+
+        This method converts the provided value into a string representation that can be
+        safely written to a .env file. If a type hint is provided, the value is serialized
+        according to the specified type using the EnvTypes utility. Otherwise, the method
+        infers the serialization strategy based on the value's type.
 
         Parameters
         ----------
-        key : str
-            The name of the environment variable to unset.
+        value : Any
+            The value to serialize. Supported types include None, str, int, float, bool,
+            list, dict, tuple, and set.
+        type_hint : str or EnvironmentValueType, optional
+            An explicit type hint to guide serialization. If provided, the value is
+            serialized using EnvTypes.
 
         Returns
         -------
-        bool
-            True if the operation was successful.
+        str
+            The serialized string representation of the input value, suitable for storage
+            in a .env file. Returns "null" for None values.
         """
-        with self._lock:
-            unset_key(str(self.__resolved_path), key)
-            os.environ.pop(key, None)
-            return True
 
-    def all(self) -> dict:
+        # Handle None values explicitly
+        if value is None:
+            return "null"
+
+        # If a type hint is provided, use EnvTypes for serialization
+        if type_hint:
+
+            # Use EnvironmentCaster to handle type hints
+            return EnvironmentCaster(value).to(type_hint)
+
+        else:
+
+            # Serialize strings by stripping whitespace
+            if isinstance(value, str):
+                return value.strip()
+
+            # Serialize booleans as lowercase strings ("true" or "false")
+            if isinstance(value, bool):
+                return str(value).lower()
+
+            # Serialize integers and floats as strings
+            if isinstance(value, (int, float)):
+                return str(value)
+
+            # Serialize collections (list, dict, tuple, set) using repr
+            if isinstance(value, (list, dict, tuple, set)):
+                return repr(value)
+
+        # Fallback: convert any other type to string
+        return str(value)
+
+    def __parseValue(
+        self,
+        value: Any
+    ) -> Any:
         """
-        Retrieve all environment variables from the resolved .env file.
+        Parse a string or raw value from the .env file into its appropriate Python type.
+
+        This method attempts to convert the input value, which may be a string or already a Python object,
+        into its most suitable Python type. It handles common representations of null, booleans, and
+        attempts to parse collections and literals. If parsing fails, the original string is returned.
+
+        Parameters
+        ----------
+        value : Any
+            The value to parse, typically a string read from the .env file, but may also be a Python object.
 
         Returns
         -------
-        dict
-            Dictionary containing all environment variable key-value pairs,
-            with values parsed using the internal __parseValue method.
+        Any
+            The parsed Python value. Returns `None` for recognized null representations, a boolean for
+            "true"/"false" strings, a Python literal (list, dict, int, etc.) if possible, or the original
+            string if no conversion is possible.
+
+        Notes
+        -----
+        - Recognizes 'none', 'null', 'nan', 'nil' (case-insensitive) as null values.
+        - Attempts to use `EnvironmentCaster` for advanced type parsing.
+        - Falls back to `ast.literal_eval` for literal evaluation.
+        - Returns the original string if all parsing attempts fail.
         """
-        with self._lock:
-            raw_values = dotenv_values(self.__resolved_path)
-            return {k: self.__parseValue(v) for k, v in raw_values.items()}
+
+        # Early return for None values
+        if value is None:
+            return None
+
+        # Return immediately if already a basic Python type
+        if isinstance(value, (bool, int, float, dict, list, tuple, set)):
+            return value
+
+        # Convert the value to string for further processing
+        value_str = str(value)
+
+        # Handle empty strings and common null representations
+        # This includes 'none', 'null', 'nan', 'nil' (case-insensitive)
+        if not value_str or value_str.lower().strip() in {'none', 'null', 'nan', 'nil'}:
+            return None
+
+        # Boolean detection for string values (case-insensitive)
+        lower_val = value_str.lower().strip()
+        if lower_val in ('true', 'false'):
+            return lower_val == 'true'
+
+        # Attempt to parse using EnvironmentCaster for advanced types
+        # Try to detect if the value string starts with a known EnvironmentValueType prefix
+        env_type_prefixes = {str(e.value) for e in EnvironmentValueType}
+        if any(value_str.startswith(prefix) for prefix in env_type_prefixes):
+            return EnvironmentCaster(value_str).get()
+
+        # Attempt to parse using ast.literal_eval for Python literals
+        try:
+            return ast.literal_eval(value_str)
+
+        # Return the original string if parsing fails
+        except (ValueError, SyntaxError):
+            return value_str