orionis 0.285.0__py3-none-any.whl → 0.287.0__py3-none-any.whl

orionis/metadata/framework.py

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

orionis/services/asynchrony/contracts/coroutines.py

@@ -0,0 +1,24 @@
+from abc import ABC, abstractmethod
+import asyncio
+from typing import TypeVar, Union
+
+T = TypeVar("T")
+
+class ICoroutine(ABC):
+
+    @abstractmethod
+    def run(self) -> Union[T, asyncio.Future]:
+        """
+        Execute the wrapped coroutine.
+
+        Returns
+        -------
+        result : T or asyncio.Future
+            The result of the coroutine if run synchronously, or a Future if run in an event loop.
+
+        Notes
+        -----
+        - If called from outside an event loop, this method will run the coroutine synchronously.
+        - If called from within an event loop, it will schedule the coroutine and return a Future.
+        """
+        pass

orionis/services/asynchrony/coroutines.py

@@ -1,32 +1,71 @@
 import asyncio
-from typing import Any, Coroutine, TypeVar, Union
+from inspect import iscoroutine
+from typing import Any, Coroutine as TypingCoroutine, TypeVar, Union
+from orionis.services.asynchrony.contracts.coroutines import ICoroutine
 from orionis.services.asynchrony.exceptions.coroutine_exception import OrionisCoroutineException
 
 T = TypeVar("T")
 
-def run_coroutine(coro: Coroutine[Any, Any, T]) -> Union[T, asyncio.Future]:
+class Coroutine(ICoroutine):
     """
-    Executes the given coroutine object, adapting to the current execution context.
-    If there is an active event loop, it uses `asyncio.ensure_future` to schedule the coroutine.
-    If there is no active event loop, it uses `asyncio.run` to run the coroutine directly.
-    If the coroutine is already running, it returns a `Future` object that can be awaited.
+    Wrapper class for coroutine objects to facilitate execution in both synchronous
+    and asynchronous contexts.
 
     Parameters
     ----------
-    coro : Coroutine[Any, Any, T]
-        The coroutine object
+    func : Coroutine
+        The coroutine object to be wrapped.
+
+    Raises
+    ------
+    OrionisCoroutineException
+        If the provided object is not a coroutine.
     """
-    from inspect import iscoroutine
 
-    if not iscoroutine(coro):
-        raise OrionisCoroutineException("Expected a coroutine object.")
+    def __init__(self, func: TypingCoroutine[Any, Any, T]) -> None:
+        """
+        Initialize the Coroutine wrapper.
+
+        Parameters
+        ----------
+        func : Coroutine
+            The coroutine object to be wrapped.
+
+        Raises
+        ------
+        OrionisCoroutineException
+            If the provided object is not a coroutine.
+        """
+        if not iscoroutine(func):
+            raise OrionisCoroutineException(
+                f"Expected a coroutine object, but got {type(func).__name__}."
+            )
+        self.__func = func
+
+    def run(self) -> Union[T, asyncio.Future]:
+        """
+        Execute the wrapped coroutine.
+
+        Returns
+        -------
+        result : T or asyncio.Future
+            The result of the coroutine if run synchronously, or a Future if run in an event loop.
 
-    try:
-        loop = asyncio.get_running_loop()
-    except RuntimeError:
-        return asyncio.run(coro)
+        Notes
+        -----
+        - If called from outside an event loop, this method will run the coroutine synchronously.
+        - If called from within an event loop, it will schedule the coroutine and return a Future.
+        """
+        try:
+            # Get the current event loop
+            loop = asyncio.get_running_loop()
+        except RuntimeError:
+            # No running event loop, run synchronously
+            return asyncio.run(self.__func)
 
-    if loop.is_running():
-        return asyncio.ensure_future(coro)
-    else:
-        return loop.run_until_complete(coro)
+        if loop.is_running():
+            # Inside an event loop, schedule as a Future
+            return asyncio.ensure_future(self.__func)
+        else:
+            # No running loop, run synchronously
+            return loop.run_until_complete(self.__func)

orionis/services/asynchrony/exceptions/coroutine_exception.py

@@ -1,26 +1,19 @@
 class OrionisCoroutineException(Exception):
-    """
-    Exception raised for errors related to coroutine operations in the Orionis framework.
-    This exception is intended to signal issues encountered during asynchronous
-    operations, providing a clear and descriptive error message to facilitate debugging.
-        msg (str): A detailed message describing the cause of the exception.
-    Example:
-        raise OrionisCoroutineException("Coroutine execution failed due to timeout.")
-    """
 
     def __init__(self, msg: str):
         """
-        Initialize the exception with a custom error message.
-        Args:
-            msg (str): The error message describing the exception.
+        Parameters
+        ----------
+        msg : str
+            The error message describing the exception.
         """
         super().__init__(msg)
 
     def __str__(self) -> str:
         """
-        Return a string representation of the exception, including the class name and the first argument.
-
-        Returns:
-            str: A formatted string with the exception class name and its first argument.
+        Returns
+        -------
+        str
+            A formatted string with the exception class name and its first argument.
         """
         return f"{self.__class__.__name__}: {self.args[0]}"

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