orionis 0.691.0__tar.gz → 0.693.0__tar.gz

{orionis-0.691.0/orionis.egg-info → orionis-0.693.0}/PKG-INFO

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

{orionis-0.691.0 → orionis-0.693.0}/orionis/metadata/framework.py

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

orionis-0.693.0/orionis/services/asynchrony/contracts/coroutines.py

@@ -0,0 +1,77 @@
+import asyncio
+from abc import ABC, abstractmethod
+from typing import TypeVar, Union
+
+T = TypeVar("T")
+
+class ICoroutine(ABC):
+
+    @abstractmethod
+    def invoke(self, *args, **kwargs) -> Union[T, asyncio.Task, None]:
+        """
+        Invokes the wrapped coroutine or callable function with the provided arguments.
+
+        This method determines whether the target is a coroutine or a regular callable,
+        and executes it accordingly. It adapts to the current event loop context,
+        handling both synchronous and asynchronous execution. Exceptions are wrapped
+        with context information for easier debugging.
+
+        Parameters
+        ----------
+        *args : tuple
+            Positional arguments to pass to the callable function.
+        **kwargs : dict
+            Keyword arguments to pass to the callable function.
+
+        Returns
+        -------
+        Union[T, asyncio.Task, None]
+            The result of the coroutine if executed synchronously, an asyncio.Task if scheduled
+            for asynchronous execution, or None if the callable is not a coroutine function.
+
+        Raises
+        ------
+        OrionisCoroutineException
+            If an error occurs during coroutine execution.
+        RuntimeError
+            If an error occurs during callable execution that is not coroutine-related.
+
+        Notes
+        -----
+        - Only callable objects can be invoked with this method.
+        - For coroutine functions, execution context is automatically detected.
+        - Non-coroutine callables are executed directly and return None.
+        - Exceptions are wrapped with appropriate context information.
+        """
+        # This method should be implemented by subclasses to handle invocation logic.
+        pass
+
+    @abstractmethod
+    def run(self) -> Union[T, asyncio.Future]:
+        """
+        Executes the wrapped coroutine, adapting to the current event loop context.
+
+        This method determines whether to execute the coroutine synchronously or schedule it
+        asynchronously based on the presence of an active event loop. It ensures that the coroutine
+        is executed in the most appropriate manner for the current context, handling event loop
+        issues gracefully.
+
+        Returns
+        -------
+        Union[T, asyncio.Future]
+            The result of the coroutine if executed synchronously, or an asyncio.Future if scheduled
+            for asynchronous execution.
+
+        Raises
+        ------
+        RuntimeError
+            If the coroutine cannot be executed due to event loop issues.
+
+        Notes
+        -----
+        - Executes synchronously if called outside an active event loop and returns the result.
+        - Schedules asynchronously if called within an active event loop and returns a Future.
+        - Automatically detects the execution context and chooses the appropriate strategy.
+        """
+        # This method should be implemented by subclasses to handle coroutine execution logic.
+        pass

{orionis-0.691.0 → orionis-0.693.0}/orionis/services/asynchrony/coroutines.py

@@ -10,28 +10,25 @@ class Coroutine(ICoroutine):
 
     def __init__(self, func: Union[TypingCoroutine[Any, Any, T], Callable[..., TypingCoroutine[Any, Any, T]]]) -> None:
         """
-        Initialize a Coroutine wrapper for managing and executing coroutine objects.
+        Initializes a Coroutine wrapper to manage and execute coroutine objects or functions.
 
-        This constructor accepts either a coroutine object directly or a callable that
-        returns a coroutine when invoked. The wrapped coroutine can later be executed
-        using the run() method with automatic context detection.
+        This constructor accepts either a coroutine object or a callable that returns a coroutine.
+        The wrapped coroutine or function can be executed later using the run() or invoke() methods.
 
         Parameters
         ----------
         func : Union[TypingCoroutine[Any, Any, T], Callable[..., TypingCoroutine[Any, Any, T]]]
-            The coroutine object to be wrapped and managed, or a callable that returns
-            a coroutine. This will be stored internally for later execution.
+            The coroutine object or a callable that returns a coroutine to be managed.
 
         Returns
         -------
         None
-            This is a constructor method and does not return any value.
+            This method does not return any value.
 
         Notes
         -----
-        - The coroutine type validation is performed during execution in the run() method,
-          not during initialization.
-        - Both coroutine objects and coroutine functions are accepted as valid input.
+        - Type validation is deferred until execution.
+        - Accepts both coroutine objects and coroutine functions.
         """
 
         # Store the coroutine object or callable for later execution
@@ -39,11 +36,12 @@ class Coroutine(ICoroutine):
 
     def invoke(self, *args, **kwargs) -> Union[T, asyncio.Task, None]:
         """
-        Invoke the callable coroutine function with the provided arguments.
+        Invokes the callable coroutine function or regular function with the provided arguments.
 
-        This method executes a callable coroutine function or regular function with the given
-        arguments and keyword arguments. It automatically detects the execution context and
-        handles both synchronous and asynchronous execution appropriately.
+        This method executes a callable coroutine function or a regular function using the given
+        positional and keyword arguments. It automatically detects whether the function is asynchronous
+        and adapts execution to the current event loop context. Exceptions are handled and wrapped
+        appropriately.
 
         Parameters
         ----------
@@ -55,77 +53,67 @@ class Coroutine(ICoroutine):
         Returns
         -------
         Union[T, asyncio.Task, None]
-            - T: The result of the coroutine if executed synchronously
-            - asyncio.Task: A task object if scheduled for asynchronous execution
-            - None: If the callable is not a coroutine function
+            The result of the coroutine if executed synchronously,
+            an asyncio.Task if scheduled for asynchronous execution,
+            or the result of a regular callable.
 
         Raises
         ------
         OrionisCoroutineException
             If an error occurs during coroutine execution.
         RuntimeError
-            If an error occurs during callable execution that is not coroutine-related.
+            If an unexpected error occurs during callable execution.
 
         Notes
         -----
-        - Only callable objects can be invoked with this method
-        - For coroutine functions, execution context is automatically detected
-        - Non-coroutine callables are executed directly and return None
-        - Exceptions are wrapped with appropriate context information
-
-        Examples
-        --------
-        >>> async def my_coro(x, y):
-        ...     return x + y
-        >>> coro = Coroutine(my_coro)
-        >>> result = coro.invoke(1, 2)  # Returns Task or result depending on context
+        - Only callable objects can be invoked with this method.
+        - For coroutine functions, execution context is automatically detected.
+        - Non-coroutine callables are executed directly.
+        - Exceptions are wrapped with appropriate context information.
         """
+
+        # Ensure the stored object is callable before invocation
         if not callable(self.__func):
             raise OrionisCoroutineException(
                 f"Cannot invoke non-callable object of type {type(self.__func).__name__}"
             )
 
         try:
-
             # Check if the callable is a coroutine function
             if asyncio.iscoroutinefunction(self.__func):
 
-                # Create the coroutine object
+                # Create the coroutine object using provided arguments
                 coroutine_obj = self.__func(*args, **kwargs)
 
                 try:
-
-                    # Check if we're inside a running event loop
+                    # Attempt to get the currently running event loop
                     loop = asyncio.get_running_loop()
+
+                    # Schedule the coroutine for asynchronous execution and return the Task
                     return loop.create_task(coroutine_obj)
 
                 except RuntimeError:
+                    # No running event loop; execute the coroutine synchronously
 
-                    # No running event loop, execute synchronously
                     try:
-
                         # Use asyncio.run to execute the coroutine and return its result
                         return asyncio.run(coroutine_obj)
 
                     except Exception as e:
-
-                        # Wrap and raise any exceptions that occur during execution
+                        # Wrap and raise any exceptions that occur during synchronous execution
                         raise OrionisCoroutineException(
                             f"Failed to execute coroutine synchronously: {str(e)}"
                         ) from e
 
             else:
-
-                # Execute regular callable directly
+                # Execute regular callable directly and return its result
                 return self.__func(*args, **kwargs)
 
         except OrionisCoroutineException:
-
-            # Re-raise our custom exceptions as-is
+            # Re-raise custom exceptions as-is
             raise
 
         except Exception as e:
-
             # Wrap and raise any other exceptions that occur during invocation
             raise RuntimeError(
                 f"Unexpected error during callable invocation: {str(e)}"
@@ -133,15 +121,22 @@ class Coroutine(ICoroutine):
 
     def run(self) -> Union[T, asyncio.Future]:
         """
-        Executes the wrapped coroutine, adapting to the current event loop context.
+        Executes the wrapped coroutine, adapting execution to the current event loop context.
+
+        This method determines whether to execute the coroutine synchronously or schedule it
+        for asynchronous execution based on the presence of an active event loop. It validates
+        that the stored object is a coroutine before execution.
 
         Returns
         -------
-        T or asyncio.Future
-            The result of the coroutine if executed synchronously, or an asyncio.Future if scheduled asynchronously.
+        Union[T, asyncio.Future]
+            The result of the coroutine if executed synchronously, or an asyncio.Future if scheduled
+            for asynchronous execution.
 
         Raises
         ------
+        OrionisCoroutineException
+            If the stored object is not a coroutine.
         RuntimeError
             If the coroutine cannot be executed due to event loop issues.
 

orionis-0.693.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.691.0 → orionis-0.693.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.691.0 → orionis-0.693.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.