orionis 0.690.0__tar.gz → 0.692.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: orionis
-Version: 0.690.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.690.0 → orionis-0.692.0}/orionis/metadata/framework.py

@@ -1,11 +1,12 @@
 #---------------------------------------------------------------------------
 # Framework Metadata
 #---------------------------------------------------------------------------
+
 # Name of the framework
 NAME = "orionis"
 
 # Current version of the framework
-VERSION = "0.690.0"
+VERSION = "0.692.0"
 
 # Full name of the author or maintainer of the project
 AUTHOR = "Raul Mauricio Uñate Castro"
@@ -19,6 +20,7 @@ DESCRIPTION = "Orionis Framework – Elegant, Fast, and Powerful."
 #---------------------------------------------------------------------------
 # Project URLs
 #---------------------------------------------------------------------------
+
 # URL to the project's skeleton or template repository (for initial setup)
 SKELETON = "https://github.com/orionis-framework/skeleton"
 
@@ -34,12 +36,14 @@ API = "https://pypi.org/pypi/orionis/json"
 #---------------------------------------------------------------------------
 # Python Requirements
 #---------------------------------------------------------------------------
+
 # Minimum Python version required to run the project
 PYTHON_REQUIRES = ">=3.12"
 
 #---------------------------------------------------------------------------
 # Project Classifiers
 #---------------------------------------------------------------------------
+
 # List of classifiers that provide metadata about the project for PyPI and other tools.
 CLASSIFIERS = [
     'Development Status :: 3 - Alpha',
@@ -63,6 +67,7 @@ CLASSIFIERS = [
 #---------------------------------------------------------------------------
 # Project Keywords
 #---------------------------------------------------------------------------
+
 # List of keywords that describe the project and help with discoverability on package indexes.
 KEYWORDS = [
     "orionis",
@@ -76,6 +81,7 @@ KEYWORDS = [
 #---------------------------------------------------------------------------
 # Project Dependencies
 #---------------------------------------------------------------------------
+
 # List of required packages and their minimum versions.
 REQUIRES = [
     'apscheduler>=3.11.0',
@@ -89,22 +95,36 @@ REQUIRES = [
 #---------------------------------------------------------------------------
 # Function to retrieve the icon SVG code
 #---------------------------------------------------------------------------
+
 # This function reads the 'icon.svg' file from the current directory and returns its content.
 def icon():
     """
-    Returns the SVG code for the project's icon image.
+    Retrieve the SVG code for the project's icon image.
 
-    Reads the 'icon.svg' file from the current directory and returns its content.
+    This function reads the 'icon.svg' file located in the same directory as this module and returns its content as a string. If the file is not found or cannot be read, it returns None.
 
-    Returns:
-        str: SVG code as a string, or None if the file is not found.
+    Returns
+    -------
+    str or None
+        The SVG code as a string if the file is successfully read, otherwise None.
     """
     import os
 
-    path = os.path.join(os.path.dirname(__file__), 'icon.svg')
+    # Construct the absolute path to the 'icon.svg' file in the current directory
+    path = os.path.join(os.path.abspath(os.path.dirname(__file__)), 'icon.svg')
 
     try:
+
+        # Attempt to open and read the SVG file
         with open(path, 'r', encoding='utf-8') as f:
             return f.read()
-    except FileNotFoundError:
+
+    except OSError:
+
+        # Return None if the file is not found or unreadable
+        return None
+
+    except Exception:
+
+        # Return None for any other exceptions that may occur
         return None

orionis-0.692.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.690.0 → orionis-0.692.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.690.0 → orionis-0.692.0/orionis.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: orionis
-Version: 0.690.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.690.0/orionis/services/asynchrony/contracts/coroutines.py

@@ -1,76 +0,0 @@
-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