orionis 0.691.0__py3-none-any.whl → 0.692.0__py3-none-any.whl

orionis/metadata/framework.py

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

orionis/services/asynchrony/contracts/coroutines.py

@@ -1,5 +1,5 @@
-from abc import ABC, abstractmethod
 import asyncio
+from abc import ABC, abstractmethod
 from typing import TypeVar, Union
 
 T = TypeVar("T")
@@ -9,11 +9,12 @@ class ICoroutine(ABC):
     @abstractmethod
     def invoke(self, *args, **kwargs) -> Union[T, asyncio.Task, None]:
         """
-        Invoke the callable coroutine function with the provided arguments.
+        Invokes the wrapped coroutine or callable 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 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
         ----------
@@ -25,9 +26,8 @@ class ICoroutine(ABC):
         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 None if the callable is not a coroutine function.
 
         Raises
         ------
@@ -38,18 +38,12 @@ class ICoroutine(ABC):
 
         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 and return None.
+        - Exceptions are wrapped with appropriate context information.
         """
+        # This method should be implemented by subclasses to handle invocation logic.
         pass
 
     @abstractmethod
@@ -57,10 +51,16 @@ class ICoroutine(ABC):
         """
         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
         -------
-        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
         ------
@@ -69,8 +69,9 @@ class ICoroutine(ABC):
 
         Notes
         -----
-        - If called outside an active event loop, the coroutine is executed synchronously and its result is returned.
-        - If called within an active event loop, the coroutine is scheduled for asynchronous execution and a Future is returned.
-        - The method automatically detects the execution context and chooses the appropriate execution strategy.
+        - 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/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.691.0.dist-info → orionis-0.692.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: orionis
-Version: 0.691.0
+Version: 0.692.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.dist-info → orionis-0.692.0.dist-info}/RECORD

@@ -207,13 +207,13 @@ orionis/foundation/providers/scheduler_provider.py,sha256=IrPQJwvQVLRm5Qnz0Cxon4
 orionis/foundation/providers/testing_provider.py,sha256=eI1p2lUlxl25b5Z487O4nmqLE31CTDb4c3Q21xFadkE,1615
 orionis/foundation/providers/workers_provider.py,sha256=GdHENYV_yGyqmHJHn0DCyWmWId5xWjD48e6Zq2PGCWY,1674
 orionis/metadata/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-orionis/metadata/framework.py,sha256=mozmW4PLxWofbBRZRC-v6uk1Xx8YNc-dYVsjFWv8DSc,4570
+orionis/metadata/framework.py,sha256=c_azWwfBHtPi_aEzE--SleVFIUrsRmLw-FkxDUdeqB4,4570
 orionis/metadata/package.py,sha256=s1JeGJPwdVh4jO3IOfmpwMuJ_oX6Vf9NL7jgPEQNf5Y,16050
 orionis/services/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 orionis/services/asynchrony/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-orionis/services/asynchrony/coroutines.py,sha256=M1o4Al5dk8BR85CWHHUgymVQaD_6PgirenQMeITUoZQ,6863
+orionis/services/asynchrony/coroutines.py,sha256=MUOi_ErAIMU_Jhc8hTLiqiRJTON1qpQpFjcZh4C328A,7038
 orionis/services/asynchrony/contracts/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-orionis/services/asynchrony/contracts/coroutines.py,sha256=Hjm-JOK-CjCDWa8sSaJZ7ccM_LxsVsYWFcYSSVciQ3U,2825
+orionis/services/asynchrony/contracts/coroutines.py,sha256=c6gJ_thUSuZBZC2EX49YNkeCVdmlimfgQRTWfFU2AwQ,3088
 orionis/services/asynchrony/exceptions/__init__.py,sha256=LXjn7TFOVBaHbPFtV87hZ3HvkTziFqtdvzLSnOZDQfc,100
 orionis/services/asynchrony/exceptions/asynchrony.py,sha256=2MbqDBA5uGtnlXSmJAs6-1Lb4b8cHDXCKrnyRyucby0,407
 orionis/services/encrypter/encrypter.py,sha256=iOR8_rgyye_Mdlp9OY9Zs9UlnA4sfWvItiDWP_7Q4Vg,4073
@@ -394,8 +394,8 @@ orionis/test/validators/workers.py,sha256=rWcdRexINNEmGaO7mnc1MKUxkHKxrTsVuHgbnI
 orionis/test/view/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 orionis/test/view/render.py,sha256=arysoswhkV2vUd2aVMZRPpmH317jaWbgjDpQ_AWQ5AE,5663
 orionis/test/view/report.stub,sha256=QLqqCdRoENr3ECiritRB3DO_MOjRQvgBh5jxZ3Hs1r0,28189
-orionis-0.691.0.dist-info/licenses/LICENCE,sha256=JhC-z_9mbpUrCfPjcl3DhDA8trNDMzb57cvRSam1avc,1463
-orionis-0.691.0.dist-info/METADATA,sha256=yYr4WLRPC_fk3XjhgdlK8XlE-A753XgIa0sOkdT58f8,4772
-orionis-0.691.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-orionis-0.691.0.dist-info/top_level.txt,sha256=lyXi6jArpqJ-0zzNqd_uwsH-z9TCEBVBL-pC3Ekv7hU,8
-orionis-0.691.0.dist-info/RECORD,,
+orionis-0.692.0.dist-info/licenses/LICENCE,sha256=JhC-z_9mbpUrCfPjcl3DhDA8trNDMzb57cvRSam1avc,1463
+orionis-0.692.0.dist-info/METADATA,sha256=_6p6doO8b55N05r25pBWoZR_XXKpA9DIoF_d6QV2_5U,4772
+orionis-0.692.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+orionis-0.692.0.dist-info/top_level.txt,sha256=lyXi6jArpqJ-0zzNqd_uwsH-z9TCEBVBL-pC3Ekv7hU,8
+orionis-0.692.0.dist-info/RECORD,,