orionis 0.692.0__tar.gz → 0.694.0__tar.gz

{orionis-0.692.0/orionis.egg-info → orionis-0.694.0}/PKG-INFO

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

{orionis-0.692.0 → orionis-0.694.0}/orionis/metadata/framework.py

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

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

@@ -0,0 +1,110 @@
+from typing import Any, Dict
+from abc import ABC, abstractmethod
+
+class IEnv(ABC):
+
+    @classmethod
+    @abstractmethod
+    def get(cls, key: str, default: Any = None) -> Any:
+        """
+        Retrieves the value of the specified environment variable.
+
+        Parameters
+        ----------
+        key : str
+            The name of the environment variable to retrieve. Must be a valid
+            environment variable name (uppercase, numbers, underscores).
+        default : Any, optional
+            The value to return if the environment variable is not found. 
+            Can be any type (str, int, bool, list, etc.). Defaults to None.
+
+        Returns
+        -------
+        Any
+            The value of the environment variable if it exists, automatically
+            parsed to its appropriate Python type (str, int, float, bool, list, dict, etc.),
+            otherwise the default value.
+        """
+        pass
+
+    @classmethod
+    @abstractmethod
+    def set(cls, key: str, value: str, type: str = None) -> bool:
+        """
+        Sets the value of an environment variable in the .env file.
+
+        Parameters
+        ----------
+        key : str
+            The name of the environment variable to set. Must follow the pattern:
+            uppercase letters, numbers, and underscores only, starting with a letter.
+            Example: 'DATABASE_URL', 'MAX_CONNECTIONS', 'FEATURE_FLAGS'
+        value : str
+            The value to assign to the environment variable.
+        type : str, optional
+            Optional type hint for explicit type casting. Supported types:
+            - 'str': String values
+            - 'int': Integer values
+            - 'float': Floating-point values
+            - 'bool': Boolean values (true/false)
+            - 'list': List/array values
+            - 'dict': Dictionary/object values
+            - 'tuple': Tuple values
+            - 'set': Set values
+            - 'base64': Base64 encoded values
+            - 'path': File system path values
+            Defaults to None (automatic type detection).
+
+        Returns
+        -------
+        bool
+            True if the environment variable was set successfully, False otherwise.
+        """
+        pass
+
+    @classmethod
+    @abstractmethod
+    def unset(cls, key: str) -> bool:
+        """
+        Removes the specified environment variable from the .env file.
+
+        Parameters
+        ----------
+        key : str
+            The name of the environment variable to remove.
+
+        Returns
+        -------
+        bool
+            True if the environment variable was removed successfully, False otherwise.
+        """
+        pass
+
+    @classmethod
+    @abstractmethod
+    def all(cls) -> Dict[str, Any]:
+        """
+        Retrieves all environment variables as a dictionary.
+
+        Returns
+        -------
+        dict of str to Any
+            A dictionary containing all environment variables loaded by DotEnv.
+        """
+        pass
+
+    @classmethod
+    @abstractmethod
+    def reload(cls) -> bool:
+        """
+        Reload environment variables from the .env file.
+
+        This method forces a refresh of all environment variables from the .env file,
+        useful when the file has been modified externally.
+
+        Returns
+        -------
+        bool
+            True if the reload was successful, False otherwise.
+        """
+        pass

{orionis-0.692.0 → orionis-0.694.0}/orionis/services/environment/core/dot_env.py

@@ -352,3 +352,45 @@ class DotEnv(metaclass=Singleton):
         # Return the original string if parsing fails
         except (ValueError, SyntaxError):
             return value_str
+
+    def reload(self) -> bool:
+        """
+        Reload environment variables from the `.env` file into the current process environment.
+
+        This method forces a refresh of all environment variables from the `.env` file,
+        which is useful when the file has been modified externally and the changes need to be
+        reflected in the running process.
+
+        Returns
+        -------
+        bool
+            Returns True if the environment variables were successfully reloaded from the `.env` file.
+            Raises OrionisEnvironmentException if an error occurs during the reload process.
+
+        Raises
+        ------
+        OrionisEnvironmentException
+            If an error occurs while reloading environment variables from the `.env` file.
+
+        Notes
+        -----
+        Ensures thread safety during the reload operation by acquiring a lock.
+        Uses the `load_dotenv` function with `override=True` to update existing environment variables.
+        """
+        try:
+            # Ensure thread-safe operation during the reload process
+            with self._lock:
+
+                # Reload environment variables from the .env file into the process environment,
+                # overriding any existing values in os.environ
+                load_dotenv(self.__resolved_path, override=True)
+
+                # Indicate successful operation
+                return True
+
+        except Exception as e:
+
+            # Raise a general error for any exceptions during reload
+            raise OrionisEnvironmentException(
+                f"An error occurred while reloading environment variables: {e}"
+            )

{orionis-0.692.0 → orionis-0.694.0}/orionis/services/environment/dynamic/caster.py

@@ -483,6 +483,8 @@ class EnvironmentCaster(IEnvironmentCaster):
         """
         Converts the internal value to a string representation with the integer type hint prefix.
 
+        Now supports conversion from string values to integers for better usability.
+
         Returns
         -------
         str
@@ -492,20 +494,33 @@ class EnvironmentCaster(IEnvironmentCaster):
         Raises
         ------
         OrionisEnvironmentValueError
-            If the internal value is not an integer.
+            If the internal value cannot be converted to an integer.
         """
 
-        # Check if the internal value is an integer before conversion
-        if not isinstance(self.__value_raw, int):
+        # If the internal value is already an integer, use it directly
+        if isinstance(self.__value_raw, int):
+            return f"{self.__type_hint}:{str(self.__value_raw)}"
+
+        # If the internal value is a string, try to convert it to an integer
+        if isinstance(self.__value_raw, str):
+            try:
+                # Strip whitespace and attempt conversion
+                converted_value = int(self.__value_raw.strip())
+                return f"{self.__type_hint}:{str(converted_value)}"
+            except ValueError:
+                raise OrionisEnvironmentValueError(
+                    f"Cannot convert string '{self.__value_raw}' to integer. Value must be a valid integer representation."
+                )
 
-            # Raise an error if the value is not an integer
+        # For other types, try direct conversion
+        try:
+            converted_value = int(self.__value_raw)
+            return f"{self.__type_hint}:{str(converted_value)}"
+        except (ValueError, TypeError):
             raise OrionisEnvironmentValueError(
-                f"Value must be an integer to convert to int, got {type(self.__value_raw).__name__} instead."
+                f"Value must be convertible to integer, got {type(self.__value_raw).__name__} with value '{self.__value_raw}'."
             )
 
-        # Return the formatted string with type hint and integer value
-        return f"{self.__type_hint}:{str(self.__value_raw)}"
-
     def __parseFloat(self):
         """
         Convert the internal raw value to a float.
@@ -539,6 +554,8 @@ class EnvironmentCaster(IEnvironmentCaster):
         """
         Converts the internal value to a string representation with the float type hint prefix.
 
+        Now supports conversion from string values to floats for better usability.
+
         Returns
         -------
         str
@@ -548,20 +565,33 @@ class EnvironmentCaster(IEnvironmentCaster):
         Raises
         ------
         OrionisEnvironmentValueError
-            If the internal value is not a float.
+            If the internal value cannot be converted to a float.
         """
 
-        # Ensure the internal value is a float before conversion
-        if not isinstance(self.__value_raw, float):
+        # If the internal value is already a float, use it directly
+        if isinstance(self.__value_raw, float):
+            return f"{self.__type_hint}:{str(self.__value_raw)}"
+
+        # If the internal value is a string, try to convert it to a float
+        if isinstance(self.__value_raw, str):
+            try:
+                # Strip whitespace and attempt conversion
+                converted_value = float(self.__value_raw.strip())
+                return f"{self.__type_hint}:{str(converted_value)}"
+            except ValueError:
+                raise OrionisEnvironmentValueError(
+                    f"Cannot convert string '{self.__value_raw}' to float. Value must be a valid floating-point representation."
+                )
 
-            # Raise an error if the value is not a float
+        # For other types (like int), try direct conversion
+        try:
+            converted_value = float(self.__value_raw)
+            return f"{self.__type_hint}:{str(converted_value)}"
+        except (ValueError, TypeError):
             raise OrionisEnvironmentValueError(
-                f"Value must be a float to convert to float, got {type(self.__value_raw).__name__} instead."
+                f"Value must be convertible to float, got {type(self.__value_raw).__name__} with value '{self.__value_raw}'."
             )
 
-        # Return the formatted string with type hint and float value
-        return f"{self.__type_hint}:{str(self.__value_raw)}"
-
     def __parseBool(self):
         """
         Convert the internal raw value to a boolean.
@@ -601,6 +631,8 @@ class EnvironmentCaster(IEnvironmentCaster):
         """
         Convert the internal value to a string representation with the boolean type hint prefix.
 
+        Now supports conversion from string values to booleans for better usability.
+
         Returns
         -------
         str
@@ -610,20 +642,37 @@ class EnvironmentCaster(IEnvironmentCaster):
         Raises
         ------
         OrionisEnvironmentValueError
-            If the internal value is not a boolean.
+            If the internal value cannot be converted to a boolean.
         """
 
-        # Ensure the internal value is a boolean before conversion
-        if not isinstance(self.__value_raw, bool):
+        # If the internal value is already a boolean, use it directly
+        if isinstance(self.__value_raw, bool):
+            return f"{self.__type_hint}:{str(self.__value_raw).lower()}"
 
-            # Raise an error if the value is not a boolean
+        # If the internal value is a string, try to convert it to a boolean
+        if isinstance(self.__value_raw, str):
+            # Strip whitespace and check common boolean representations
+            str_value = self.__value_raw.strip().lower()
+
+            if str_value in ('true', '1', 'yes', 'on', 'enabled'):
+                return f"{self.__type_hint}:true"
+            elif str_value in ('false', '0', 'no', 'off', 'disabled'):
+                return f"{self.__type_hint}:false"
+            else:
+                raise OrionisEnvironmentValueError(
+                    f"Cannot convert string '{self.__value_raw}' to boolean. "
+                    f"Valid representations: true/false, 1/0, yes/no, on/off, enabled/disabled."
+                )
+
+        # For other types, try direct conversion using Python's truthiness
+        try:
+            boolean_value = bool(self.__value_raw)
+            return f"{self.__type_hint}:{str(boolean_value).lower()}"
+        except Exception:
             raise OrionisEnvironmentValueError(
-                f"Value must be a boolean to convert to bool, got {type(self.__value_raw).__name__} instead."
+                f"Value must be convertible to boolean, got {type(self.__value_raw).__name__} with value '{self.__value_raw}'."
             )
 
-        # Return the formatted string with type hint and boolean value in lowercase
-        return f"{self.__type_hint}:{str(self.__value_raw).lower()}"
-
     def __parseList(self):
         """
         Parses the internal raw value and converts it to a Python list.

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

@@ -0,0 +1,189 @@
+from orionis.services.environment.contracts.env import IEnv
+from orionis.services.environment.core.dot_env import DotEnv
+from typing import Any, Dict
+
+class Env(IEnv):
+
+    # Shared singleton instance for DotEnv
+    _dotenv_instance = None
+
+    @classmethod
+    def _getSingletonInstance(cls):
+        """
+        Retrieve the shared DotEnv singleton instance.
+
+        This method ensures that only one instance of DotEnv is created and reused
+        throughout the Env class. If the instance does not exist, it will be created.
+
+        Returns
+        -------
+        DotEnv
+            The shared DotEnv instance used for environment variable operations.
+        """
+
+        # Check if the singleton instance has already been created
+        if cls._dotenv_instance is None:
+            # Create a new DotEnv instance if it does not exist
+            cls._dotenv_instance = DotEnv()
+        # Return the existing or newly created DotEnv instance
+        return cls._dotenv_instance
+
+    @classmethod
+    def get(cls, key: str, default: Any = None) -> Any:
+        """
+        Retrieve the value of an environment variable by its key.
+
+        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. Defaults to None.
+
+        Returns
+        -------
+        Any
+            The value of the environment variable if it exists, otherwise the provided default value.
+        """
+
+        # Get the shared DotEnv singleton instance to access environment variables
+        dotenv = cls._getSingletonInstance()
+
+        # Return the value for the specified key, or the default if the key is not present
+        return dotenv.get(key, default)
+
+    @classmethod
+    def set(cls, key: str, value: str, type: str = None) -> bool:
+        """
+        Set or update an environment variable in the .env file.
+
+        Parameters
+        ----------
+        key : str
+            The name of the environment variable to set or update.
+        value : str
+            The value to assign to the environment variable.
+        type : str, optional
+            Type hint for the variable. Supported types include 'str', 'int', 'float',
+            'bool', 'list', 'dict', 'tuple', 'set', 'base64', and 'path'. Defaults to None.
+
+        Returns
+        -------
+        bool
+            Returns True if the environment variable was set or updated successfully,
+            otherwise returns False.
+        """
+
+        # Retrieve the shared DotEnv singleton instance to access environment variable operations
+        dotenv = cls._getSingletonInstance()
+
+        # Set the environment variable with the specified key, value, and optional type hint
+        return dotenv.set(key, value, type)
+
+    @classmethod
+    def unset(cls, key: str) -> bool:
+        """
+        Remove an environment variable from the .env file.
+
+        Parameters
+        ----------
+        key : str
+            The name of the environment variable to remove.
+
+        Returns
+        -------
+        bool
+            True if the environment variable was removed successfully, False otherwise.
+        """
+
+        # Retrieve the shared DotEnv singleton instance to access environment variable operations
+        dotenv = cls._getSingletonInstance()
+
+        # Attempt to remove the environment variable with the specified key
+        return dotenv.unset(key)
+
+    @classmethod
+    def all(cls) -> Dict[str, Any]:
+        """
+        Retrieve all environment variables as a dictionary.
+
+        This method accesses the shared DotEnv singleton instance and returns all loaded
+        environment variables in a dictionary format. It is useful for inspecting the
+        current environment configuration.
+
+        Returns
+        -------
+        dict of str to Any
+            A dictionary containing all environment variables loaded by DotEnv.
+        """
+
+        # Retrieve the shared DotEnv singleton instance to access environment variables
+        dotenv = cls._getSingletonInstance()
+
+        # Return all environment variables as a dictionary
+        return dotenv.all()
+
+    @staticmethod
+    def isVirtual() -> bool:
+        """
+        Check if the current Python interpreter is running inside a virtual environment.
+
+        This method detects whether the Python process is executing within a virtual environment
+        by inspecting environment variables, configuration files, and interpreter prefixes.
+
+        Returns
+        -------
+        bool
+            Returns True if the interpreter is running inside a virtual environment, otherwise False.
+        """
+
+        import sys
+        import os
+        from pathlib import Path
+
+        # Check for the 'VIRTUAL_ENV' environment variable, which is set by virtualenv
+        if 'VIRTUAL_ENV' in os.environ:
+            return True
+
+        # Search for 'pyvenv.cfg' in the parent directories of the Python executable (used by venv)
+        executable = Path(sys.executable).resolve()
+        for parent in executable.parents:
+
+            # If 'pyvenv.cfg' exists in any parent directory, it's likely a venv
+            if (parent / 'pyvenv.cfg').exists():
+                return True
+
+        # Compare sys.prefix and sys.base_prefix to detect venv or virtualenv usage
+        if hasattr(sys, 'base_prefix') and sys.prefix != sys.base_prefix:
+            return True
+
+        # If none of the checks indicate a virtual environment, return False
+        return False
+
+    @classmethod
+    def reload(cls) -> bool:
+        """
+        Reload environment variables from the .env file.
+
+        This method resets the DotEnv singleton instance and reloads all environment variables
+        from the .env file. It is useful when the .env file has been modified externally and
+        the latest values need to be reflected in the application.
+
+        Returns
+        -------
+        bool
+            True if the environment variables were reloaded successfully, False otherwise.
+        """
+
+        # Reset the singleton instance to ensure a fresh reload of environment variables
+        cls._dotenv_instance = None
+
+        # Create a new DotEnv instance and load the .env file
+        dotenv = cls._getSingletonInstance()
+
+        # Attempt to reload environment variables from the .env file
+        try:
+            return dotenv.reload()
+        except Exception:
+            # Return False if an error occurs during reload
+            return False

{orionis-0.692.0 → orionis-0.694.0}/orionis/services/environment/helpers/functions.py

@@ -1,9 +1,9 @@
 from typing import Any
-from orionis.services.environment.core.dot_env import DotEnv
+from orionis.services.environment.env import Env
 
 def env(key: str, default: Any = None) -> Any:
     """
-    Retrieves the value of an environment variable.
+    Retrieve the value of an environment variable using the Env facade.
 
     Parameters
     ----------
@@ -18,5 +18,5 @@ def env(key: str, default: Any = None) -> Any:
         The value of the environment variable if it exists, otherwise the specified default value.
     """
 
-    # Instantiate DotEnv and retrieve the environment variable by key
-    return DotEnv().get(key, default)
+    # Retrieve the environment variable using the Env singleton instance.
+    return Env.get(key, default)

{orionis-0.692.0 → orionis-0.694.0/orionis.egg-info}/PKG-INFO

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

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

@@ -1,77 +0,0 @@
-from typing import Any, Dict
-from abc import ABC, abstractmethod
-
-class IEnv(ABC):
-
-    @staticmethod
-    @abstractmethod
-    def get(key: str, default: Any = None) -> Any:
-        """
-        Retrieves the value of the specified 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. Defaults to None.
-
-        Returns
-        -------
-        Any
-            The value of the environment variable if it exists, otherwise the default value.
-        """
-        pass
-
-    @staticmethod
-    @abstractmethod
-    def set(key: str, value: str, type: str = None) -> bool:
-        """
-        Sets the value of 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'). Defaults to None.
-
-        Returns
-        -------
-        bool
-            True if the environment variable was set successfully, False otherwise.
-        """
-        pass
-
-    @staticmethod
-    @abstractmethod
-    def unset(key: str) -> bool:
-        """
-        Removes the specified environment variable from the .env file.
-
-        Parameters
-        ----------
-        key : str
-            The name of the environment variable to remove.
-
-        Returns
-        -------
-        bool
-            True if the environment variable was removed successfully, False otherwise.
-        """
-        pass
-
-    @staticmethod
-    @abstractmethod
-    def all() -> Dict[str, Any]:
-        """
-        Retrieves all environment variables as a dictionary.
-
-        Returns
-        -------
-        dict of str to Any
-            A dictionary containing all environment variables loaded by DotEnv.
-        """
-        pass