orionis 0.533.0__tar.gz → 0.535.0__tar.gz

{orionis-0.533.0/orionis.egg-info → orionis-0.535.0}/PKG-INFO

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

{orionis-0.533.0 → orionis-0.535.0}/orionis/console/tasks/schedule.py

@@ -37,6 +37,7 @@ from orionis.console.exceptions import CLIOrionisRuntimeError
 from orionis.console.exceptions.cli_orionis_value_error import CLIOrionisValueError
 from orionis.failure.contracts.catch import ICatch
 from orionis.foundation.contracts.application import IApplication
+from orionis.services.asynchrony.coroutines import Coroutine
 from orionis.services.log.contracts.log_service import ILogger
 
 class Schedule(ISchedule):
@@ -478,44 +479,13 @@ class Schedule(ISchedule):
             # If is Callable
             if callable(listener):
 
+                # Invoke the listener, handling both coroutine and regular functions
                 try:
 
-                    # If the listener is a coroutine, handle it properly
-                    if asyncio.iscoroutinefunction(listener):
+                    # Use Coroutine to handle both sync and async listeners
+                    Coroutine(listener).invoke(event_data, self)
 
-                        try:
-
-                            # Try to get the current running event loop
-                            loop = asyncio.get_running_loop()
-
-                            # Schedule the coroutine as a task in the current loop
-                            loop.create_task(listener(event_data, self))
-
-                        except RuntimeError:
-
-                            # No running event loop, create a new one
-                            try:
-
-                                # Create and run the coroutine in a new event loop
-                                asyncio.run(listener(event_data, self))
-
-                            except Exception as e:
-
-                                # Handle exceptions during coroutine execution
-                                error_msg = f"Failed to run async listener for '{scheduler_event}': {str(e)}"
-                                self.__logger.error(error_msg)
-                                raise CLIOrionisRuntimeError(error_msg) from e
-
-                    else:
-
-                        # Call the regular listener function directly
-                        listener(event_data, self)
-
-                except Exception as e:
-
-                    # Re-raise CLIOrionisRuntimeError exceptions
-                    if isinstance(e, CLIOrionisRuntimeError):
-                        raise e
+                except BaseException as e:
 
                     # Construct and log error message
                     error_msg = f"An error occurred while invoking the listener for event '{scheduler_event}': {str(e)}"
@@ -588,45 +558,14 @@ class Schedule(ISchedule):
                     # Retrieve the method from the listener
                     listener_method = getattr(listener, scheduler_event)
 
+                    # Invoke the listener method, handling both coroutine and regular functions
                     try:
 
-                        # If the listener_method is a coroutine, handle it properly
-                        if asyncio.iscoroutinefunction(listener_method):
-
-                            try:
-
-                                # Try to get the current running event loop
-                                loop = asyncio.get_running_loop()
-
-                                # Schedule the coroutine as a task in the current loop
-                                loop.create_task(listener_method(event_data, self))
-
-                            except RuntimeError:
-
-                                # No running event loop, create a new one
-                                try:
-
-                                    # Create and run the coroutine in a new event loop
-                                    asyncio.run(listener_method(event_data, self))
-
-                                except Exception as e:
-
-                                    # Handle exceptions during coroutine execution
-                                    error_msg = f"Failed to run async listener_method for '{scheduler_event}': {str(e)}"
-                                    self.__logger.error(error_msg)
-                                    raise CLIOrionisRuntimeError(error_msg) from e
-
-                        else:
-
-                            # Call the regular listener_method function directly
-                            listener_method(event_data, self)
+                        # Use Coroutine to handle both sync and async listener methods
+                        Coroutine(listener_method).invoke(event_data, self)
 
                     except Exception as e:
 
-                        # Re-raise CLIOrionisRuntimeError exceptions
-                        if isinstance(e, CLIOrionisRuntimeError):
-                            raise e
-
                         # Construct and log error message
                         error_msg = f"An error occurred while invoking the listener_method for event '{scheduler_event}': {str(e)}"
                         self.__logger.error(error_msg)
@@ -1081,52 +1020,99 @@ class Schedule(ISchedule):
         func: Callable[..., Awaitable[Any]]
     ) -> Callable[..., Any]:
         """
-        Wrap an asynchronous function to be called in a synchronous context.
+        Wrap an asynchronous function to be executed in a synchronous context.
 
-        This method takes an asynchronous function (a coroutine) and returns a synchronous
-        wrapper function that can be called in a non-async context. The wrapper function
-        ensures that the asynchronous function is executed within the appropriate event loop.
+        This method creates a synchronous wrapper around an asynchronous function (coroutine)
+        that enables its execution within non-async contexts. The wrapper leverages the
+        Coroutine utility class to handle the complexities of asyncio event loop management
+        and provides proper error handling with detailed logging and custom exception
+        propagation.
+
+        The wrapper is particularly useful when integrating asynchronous functions with
+        synchronous APIs or frameworks that do not natively support async operations,
+        such as the APScheduler job execution environment.
 
         Parameters
         ----------
         func : Callable[..., Awaitable[Any]]
-            The asynchronous function (coroutine) to be wrapped. This function should be
-            defined using the `async def` syntax and return an awaitable object.
+            The asynchronous function (coroutine) to be wrapped. This function must be
+            defined using the `async def` syntax and return an awaitable object. The
+            function can accept any number of positional and keyword arguments.
 
         Returns
         -------
         Callable[..., Any]
-            A synchronous wrapper function that can be called in a non-async context.
-            When invoked, this wrapper will execute the original asynchronous function
-            within the appropriate event loop.
+            A synchronous wrapper function that executes the original asynchronous
+            function and returns its result. The wrapper function accepts the same
+            arguments as the original async function and forwards them appropriately.
+            The return type depends on what the wrapped asynchronous function returns.
 
         Raises
         ------
         CLIOrionisRuntimeError
-            If the provided `func` is not an asynchronous function or execution fails.
+            If the asynchronous function execution fails or if the provided `func`
+            parameter is not a valid asynchronous function. The original exception
+            is wrapped to provide additional context for debugging.
+
+        Notes
+        -----
+        This method relies on the Coroutine utility class from the orionis.services.asynchrony
+        module to handle the execution of the wrapped asynchronous function. The wrapper
+        uses the instance logger for comprehensive error reporting and debugging information.
         """
 
         def sync_wrapper(*args, **kwargs) -> Any:
+            """
+            Synchronous wrapper function that executes asynchronous functions in a thread-safe manner.
+
+            This wrapper provides a uniform interface for executing asynchronous functions within
+            synchronous contexts by leveraging the Coroutine utility class. It handles the complexity
+            of managing async/await patterns and provides proper error handling with detailed logging
+            and custom exception propagation.
+
+            The wrapper is particularly useful when integrating asynchronous functions with
+            synchronous APIs or frameworks that do not natively support async operations.
+
+            Parameters
+            ----------
+            *args : tuple
+            Variable length argument list to pass to the wrapped asynchronous function.
+            These arguments are forwarded directly to the original function.
+            **kwargs : dict
+            Arbitrary keyword arguments to pass to the wrapped asynchronous function.
+            These keyword arguments are forwarded directly to the original function.
+
+            Returns
+            -------
+            Any
+            The return value from the executed asynchronous function. The type depends
+            on what the wrapped function returns and can be any Python object.
+
+            Raises
+            ------
+            CLIOrionisRuntimeError
+            When the asynchronous function execution fails, wrapping the original
+            exception with additional context and error details for better debugging.
+
+            Notes
+            -----
+            This function relies on the Coroutine utility class to handle the execution
+            of the wrapped asynchronous function and uses the instance logger for comprehensive
+            error reporting and debugging information.
+            """
 
             try:
-
-                # Try to get the current event loop
-                try:
-
-                    # If we're already in an event loop, create a task
-                    loop = asyncio.get_running_loop()
-                    task = loop.create_task(func(*args, **kwargs))
-                    return task
-
-                except RuntimeError:
-
-                    # No running loop, so we can run the coroutine directly
-                    return asyncio.run(func(*args, **kwargs))
+                # Execute the asynchronous function using the Coroutine utility class
+                # The Coroutine class handles the event loop management and async execution
+                return Coroutine(func).invoke(*args, **kwargs)
 
             except Exception as e:
 
-                # Log the error and re-raise
+                # Log the error with detailed information for debugging purposes
                 self.__logger.error(f"Error executing async function: {str(e)}")
+
+                # Re-raise the exception wrapped in a custom exception type
+                # This provides better error context and maintains the original stack trace
                 raise CLIOrionisRuntimeError(f"Failed to execute async function: {str(e)}") from e
 
         # Return the synchronous wrapper function

{orionis-0.533.0 → orionis-0.535.0}/orionis/failure/catch.py

@@ -1,9 +1,11 @@
 from typing import Any
 from orionis.console.kernel import KernelCLI
 from orionis.console.output.contracts.console import IConsole
+from orionis.console.tasks.schedule import Schedule
 from orionis.failure.contracts.catch import ICatch
 from orionis.failure.contracts.handler import IBaseExceptionHandler
 from orionis.foundation.contracts.application import IApplication
+from orionis.services.asynchrony.coroutines import Coroutine
 from orionis.services.log.contracts.log_service import ILogger
 import asyncio
 
@@ -135,7 +137,7 @@ class Catch(ICatch):
                 )
 
             # Check if the kernel is of type `KernelCLI` or `Any`
-            if isinstance(kernel, KernelCLI) or isinstance(kernel, Any):
+            if isinstance(kernel, KernelCLI) or isinstance(kernel, Schedule):
 
                 # Check if the `renderCLI` method is a coroutine function
                 if asyncio.iscoroutinefunction(self.__exception_handler.renderCLI):
@@ -158,5 +160,5 @@ class Catch(ICatch):
                         console=self.__console
                     )
 
-        # Run the handler
-        asyncio.run(handle())
+        # Execute the exception handling logic using the Coroutine wrapper
+        Coroutine(handle()).run()

{orionis-0.533.0 → orionis-0.535.0}/orionis/foundation/application.py

@@ -24,6 +24,7 @@ from orionis.foundation.config.testing.entities.testing import Testing
 from orionis.foundation.contracts.application import IApplication
 from orionis.foundation.exceptions import OrionisTypeError, OrionisRuntimeError, OrionisValueError
 from orionis.foundation.providers.logger_provider import LoggerProvider
+from orionis.services.asynchrony.coroutines import Coroutine
 from orionis.services.log.contracts.log_service import ILogger
 
 class Application(Container, IApplication):
@@ -342,7 +343,7 @@ class Application(Container, IApplication):
             # Register the provider in the container
             # Check if register is a coroutine function
             if asyncio.iscoroutinefunction(class_provider.register):
-                asyncio.run(class_provider.register())
+                Coroutine(class_provider.register).run()
             else:
                 class_provider.register()
 
@@ -379,7 +380,7 @@ class Application(Container, IApplication):
             if hasattr(provider, 'boot') and callable(getattr(provider, 'boot')):
                 # Check if boot is a coroutine function
                 if asyncio.iscoroutinefunction(provider.boot):
-                    asyncio.run(provider.boot())
+                    Coroutine(provider.boot).run()
                 else:
                     provider.boot()
 

{orionis-0.533.0 → orionis-0.535.0}/orionis/metadata/framework.py

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

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

@@ -0,0 +1,76 @@
+from abc import ABC, abstractmethod
+import asyncio
+from typing import TypeVar, Union
+
+T = TypeVar("T")
+
+class ICoroutine(ABC):
+
+    @abstractmethod
+    def invoke(self, *args, **kwargs) -> Union[T, asyncio.Task, None]:
+        """
+        Invoke the callable coroutine 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.
+
+        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]
+            - 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
+
+        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
+
+        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
+        """
+        pass
+
+    @abstractmethod
+    def run(self) -> Union[T, asyncio.Future]:
+        """
+        Executes the wrapped coroutine, adapting to the current event loop context.
+
+        Returns
+        -------
+        T or asyncio.Future
+            The result of the coroutine if executed synchronously, or an asyncio.Future if scheduled asynchronously.
+
+        Raises
+        ------
+        RuntimeError
+            If the coroutine cannot be executed due to event loop issues.
+
+        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.
+        """
+        pass

orionis-0.535.0/orionis/services/asynchrony/coroutines.py

@@ -0,0 +1,175 @@
+import asyncio
+from typing import Any, Callable, Coroutine as TypingCoroutine, TypeVar, Union
+from orionis.services.asynchrony.contracts.coroutines import ICoroutine
+from orionis.services.asynchrony.exceptions import OrionisCoroutineException
+from orionis.services.introspection.objects.types import Type
+
+T = TypeVar("T")
+
+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.
+
+        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.
+
+        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.
+
+        Returns
+        -------
+        None
+            This is a constructor method and 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.
+        """
+
+        # Store the coroutine object or callable for later execution
+        self.__func = func
+
+    def invoke(self, *args, **kwargs) -> Union[T, asyncio.Task, None]:
+        """
+        Invoke the callable coroutine 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.
+
+        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]
+            - 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
+
+        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
+
+        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
+        """
+        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
+                coroutine_obj = self.__func(*args, **kwargs)
+
+                try:
+
+                    # Check if we're inside a running event loop
+                    loop = asyncio.get_running_loop()
+                    return loop.create_task(coroutine_obj)
+
+                except RuntimeError:
+
+                    # 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
+                        raise OrionisCoroutineException(
+                            f"Failed to execute coroutine synchronously: {str(e)}"
+                        ) from e
+
+            else:
+
+                # Execute regular callable directly
+                return self.__func(*args, **kwargs)
+
+        except OrionisCoroutineException:
+
+            # Re-raise our 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)}"
+            ) from e
+
+    def run(self) -> Union[T, asyncio.Future]:
+        """
+        Executes the wrapped coroutine, adapting to the current event loop context.
+
+        Returns
+        -------
+        T or asyncio.Future
+            The result of the coroutine if executed synchronously, or an asyncio.Future if scheduled asynchronously.
+
+        Raises
+        ------
+        RuntimeError
+            If the coroutine cannot be executed due to event loop issues.
+
+        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.
+        """
+
+        # Validate that the provided object is a coroutine
+        if not Type(self.__func).isCoroutine():
+            raise OrionisCoroutineException(
+                f"Expected a coroutine object, but got {type(self.__func).__name__}."
+            )
+
+        # Attempt to get the currently running event loop
+        try:
+            loop = asyncio.get_running_loop()
+
+        # No running event loop; execute the coroutine synchronously and return its result
+        except RuntimeError:
+            return asyncio.run(self.__func)
+
+        # If inside an active event loop, schedule the coroutine and return a Future
+        if loop.is_running():
+            return asyncio.ensure_future(self.__func)
+
+        # If no event loop is running, execute the coroutine synchronously using the loop
+        else:
+            return loop.run_until_complete(self.__func)

{orionis-0.533.0 → orionis-0.535.0/orionis.egg-info}/PKG-INFO

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

{orionis-0.533.0 → orionis-0.535.0}/tests/services/asynchrony/test_services_asynchrony_coroutine.py

@@ -82,4 +82,4 @@ class TestServicesAsynchronyCoroutine(AsyncTestCase):
 
         # Assert that passing a non-coroutine raises OrionisCoroutineException
         with self.assertRaises(OrionisCoroutineException):
-            Coroutine(sample_no_coroutine())
+            Coroutine(sample_no_coroutine()).run()

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

@@ -1,28 +0,0 @@
-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 either synchronously or asynchronously, depending on the execution context.
-
-        Returns
-        -------
-        T or asyncio.Future
-            If called outside of an event loop, returns the result of the coroutine execution (type T).
-            If called within an event loop, returns an asyncio.Future representing the scheduled coroutine.
-
-        Notes
-        -----
-        - Executes the coroutine synchronously and returns its result when called outside an event loop.
-        - Schedules the coroutine for asynchronous execution and returns a Future when called inside an event loop.
-        - The caller is responsible for awaiting the Future if asynchronous execution is used.
-        """
-
-        # This method should be implemented by subclasses to handle coroutine execution.
-        pass

orionis-0.533.0/orionis/services/asynchrony/coroutines.py

@@ -1,70 +0,0 @@
-import asyncio
-from typing import Any, Coroutine as TypingCoroutine, TypeVar, Union
-from orionis.services.asynchrony.contracts.coroutines import ICoroutine
-from orionis.services.asynchrony.exceptions import OrionisCoroutineException
-from orionis.services.introspection.objects.types import Type
-
-T = TypeVar("T")
-
-class Coroutine(ICoroutine):
-
-    def __init__(self, func: TypingCoroutine[Any, Any, T]) -> None:
-        """
-        Wraps a coroutine object and validates its type.
-
-        Parameters
-        ----------
-        func : Coroutine
-            The coroutine object to be wrapped and managed.
-
-        Raises
-        ------
-        OrionisCoroutineException
-            If the provided object is not a coroutine.
-        """
-
-        # Validate that the provided object is a coroutine
-        if not Type(func).isCoroutine():
-            raise OrionisCoroutineException(
-                f"Expected a coroutine object, but got {type(func).__name__}."
-            )
-
-        # Store the coroutine object for later execution
-        self.__func = func
-
-    def run(self) -> Union[T, asyncio.Future]:
-        """
-        Executes the wrapped coroutine, adapting to the current event loop context.
-
-        Returns
-        -------
-        T or asyncio.Future
-            The result of the coroutine if executed synchronously, or an asyncio.Future if scheduled asynchronously.
-
-        Raises
-        ------
-        RuntimeError
-            If the coroutine cannot be executed due to event loop issues.
-
-        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.
-        """
-
-        # Attempt to get the currently running event loop
-        try:
-            loop = asyncio.get_running_loop()
-
-        # No running event loop; execute the coroutine synchronously and return its result
-        except RuntimeError:
-            return asyncio.run(self.__func)
-
-        # If inside an active event loop, schedule the coroutine and return a Future
-        if loop.is_running():
-            return asyncio.ensure_future(self.__func)
-
-        # If no event loop is running, execute the coroutine synchronously using the loop
-        else:
-            return loop.run_until_complete(self.__func)