orionis 0.535.0__tar.gz → 0.537.0__tar.gz

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

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

{orionis-0.535.0 → orionis-0.537.0}/orionis/console/contracts/event.py

@@ -5,24 +5,32 @@ from orionis.console.enums.event import Event as EventEntity
 
 class IEvent(ABC):
 
-    @abstractmethod
-    def toEntity(
-        self
-    ) -> EventEntity:
+    def misfireGraceTime(
+        self,
+        seconds: int = 60
+    ) -> 'IEvent':
         """
-        Retrieve the event details as an EventEntity instance.
+        Set the misfire grace time for the event.
 
-        This method gathers all relevant attributes of the current Event object,
-        such as its signature, arguments, purpose, random delay, start and end dates,
-        and trigger, and returns them encapsulated in an EventEntity object.
+        This method allows you to specify a grace period (in seconds) during which
+        a missed execution of the event can still be executed. If the event is not
+        executed within this time frame after its scheduled time, it will be skipped.
+
+        Parameters
+        ----------
+        seconds : int
+            The number of seconds to allow for a misfire grace period. Must be a positive integer.
 
         Returns
         -------
-        EventEntity
-            An EventEntity instance containing the event's signature, arguments,
-            purpose, random delay, start date, end date, and trigger.
+        Event
+            Returns the current instance of the Event to allow method chaining.
+
+        Raises
+        ------
+        CLIOrionisValueError
+            If the provided seconds is not a positive integer.
         """
-        pass
 
     @abstractmethod
     def purpose(

{orionis-0.535.0 → orionis-0.537.0}/orionis/console/enums/event.py

@@ -60,4 +60,10 @@ class Event:
     details: Optional[str] = None
 
     # Optional listener that implements IScheduleEventListener
-    listener: Optional[IScheduleEventListener] = None
+    listener: Optional[IScheduleEventListener] = None
+
+    # Maximum number of concurrent instances allowed for the event
+    max_instances: int = 1
+
+    # Grace time in seconds for misfired events
+    misfire_grace_time : Optional[int] = None

{orionis-0.535.0 → orionis-0.537.0}/orionis/console/tasks/event.py

@@ -77,6 +77,9 @@ class Event(IEvent):
         # Initialize the maximum instances attribute as None
         self.__max_instances: Optional[int] = None
 
+        # Initialize the misfire grace time attribute as None
+        self.__misfire_grace_time: Optional[int] = None
+
     def toEntity(
         self
     ) -> EventEntity:
@@ -128,6 +131,14 @@ class Event(IEvent):
         if self.__listener is not None and not issubclass(self.__listener, IScheduleEventListener):
             raise CLIOrionisValueError("Listener must implement IScheduleEventListener interface or be None.")
 
+        # Validate that max_instances is a positive integer if it is set
+        if self.__max_instances is not None and (not isinstance(self.__max_instances, int) or self.__max_instances <= 0):
+            raise CLIOrionisValueError("Max instances must be a positive integer or None.")
+
+        # Validate that misfire_grace_time is a positive integer if it is set
+        if self.__misfire_grace_time is not None and (not isinstance(self.__misfire_grace_time, int) or self.__misfire_grace_time <= 0):
+            raise CLIOrionisValueError("Misfire grace time must be a positive integer or None.")
+
         # Construct and return an EventEntity with the current event's attributes
         return EventEntity(
             signature=self.__signature,
@@ -138,9 +149,48 @@ class Event(IEvent):
             end_date=self.__end_date,
             trigger=self.__trigger,
             details=self.__details,
-            listener=self.__listener
+            listener=self.__listener,
+            max_instances=self.__max_instances,
+            misfire_grace_time=self.__misfire_grace_time
         )
 
+    def misfireGraceTime(
+        self,
+        seconds: int = 60
+    ) -> 'Event':
+        """
+        Set the misfire grace time for the event.
+
+        This method allows you to specify a grace period (in seconds) during which
+        a missed execution of the event can still be executed. If the event is not
+        executed within this time frame after its scheduled time, it will be skipped.
+
+        Parameters
+        ----------
+        seconds : int
+            The number of seconds to allow for a misfire grace period. Must be a positive integer.
+
+        Returns
+        -------
+        Event
+            Returns the current instance of the Event to allow method chaining.
+
+        Raises
+        ------
+        CLIOrionisValueError
+            If the provided seconds is not a positive integer.
+        """
+
+        # Validate that the seconds parameter is a positive integer
+        if not isinstance(seconds, int) or seconds <= 0:
+            raise CLIOrionisValueError("Misfire grace time must be a positive integer.")
+
+        # Set the internal misfire grace time attribute
+        self.__misfire_grace_time = seconds
+
+        # Return self to support method chaining
+        return self
+
     def purpose(
         self,
         purpose: str

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

@@ -482,8 +482,8 @@ class Schedule(ISchedule):
                 # Invoke the listener, handling both coroutine and regular functions
                 try:
 
-                    # Use Coroutine to handle both sync and async listeners
-                    Coroutine(listener).invoke(event_data, self)
+                    # Execute coroutine listeners using container's invoke method
+                    self.__app.invoke(listener, event_data, self)
 
                 except BaseException as e:
 
@@ -550,26 +550,13 @@ class Schedule(ISchedule):
 
                 # Initialize the listener if it's a class
                 if isinstance(listener, type):
-                    listener = listener()
+                    listener = self.__app.make(listener)
 
                 # Check if the listener has a method corresponding to the event type
                 if hasattr(listener, scheduler_event) and callable(getattr(listener, scheduler_event)):
 
-                    # Retrieve the method from the listener
-                    listener_method = getattr(listener, scheduler_event)
-
                     # Invoke the listener method, handling both coroutine and regular functions
-                    try:
-
-                        # Use Coroutine to handle both sync and async listener methods
-                        Coroutine(listener_method).invoke(event_data, self)
-
-                    except Exception as 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)
-                        raise CLIOrionisRuntimeError(error_msg) from e
+                    self.__app.call(listener, scheduler_event, event_data, self)
 
                 else:
 
@@ -707,7 +694,7 @@ class Schedule(ISchedule):
             and listener invocation for the job error event.
         """
         # Log an error message indicating that the job raised an exception
-        self.__logger.error(f"Task {event.job_id} raised an exception: {event.exception}")
+        self.__logger.error(f"Task '{event.job_id}' raised an exception: {event.exception}")
 
         # If a listener is registered for this job ID, invoke the listener with the event details
         job_event_data = self.__getTaskFromSchedulerById(event.job_id)
@@ -758,7 +745,7 @@ class Schedule(ISchedule):
         """
 
         # Log an informational message indicating that the job has been submitted
-        self.__logger.info(f"Task {event.job_id} submitted to executor.")
+        self.__logger.info(f"Task '{event.job_id}' submitted to executor.")
 
         # Create entity for job submitted event
         data_event = self.__getTaskFromSchedulerById(event.job_id, event.code)
@@ -793,7 +780,7 @@ class Schedule(ISchedule):
         """
 
         # Log an informational message indicating that the job has been executed
-        self.__logger.info(f"Task {event.job_id} executed.")
+        self.__logger.info(f"Task '{event.job_id}' executed.")
 
         # Create entity for job executed event
         data_event = self.__getTaskFromSchedulerById(event.job_id, event.code)
@@ -828,7 +815,7 @@ class Schedule(ISchedule):
         """
 
         # Log a warning indicating that the job was missed
-        self.__logger.warning(f"Task {event.job_id} was missed. It was scheduled to run at {event.scheduled_run_time}.")
+        self.__logger.warning(f"Task '{event.job_id}' was missed. It was scheduled to run at {event.scheduled_run_time}.")
 
         # Create entity for job missed event
         data_event = self.__getTaskFromSchedulerById(event.job_id, event.code)
@@ -863,7 +850,7 @@ class Schedule(ISchedule):
         """
 
         # Log an error message indicating that the job exceeded maximum instances
-        self.__logger.error(f"Task {event.job_id} exceeded maximum instances")
+        self.__logger.error(f"Task '{event.job_id}' exceeded maximum instances")
 
         # Create entity for job max instances event
         data_event = self.__getTaskFromSchedulerById(event.job_id, event.code)
@@ -897,7 +884,7 @@ class Schedule(ISchedule):
         """
 
         # Log the removal of the job
-        self.__logger.info(f"Task {event.job_id} has been removed.")
+        self.__logger.info(f"Task '{event.job_id}' has been removed.")
 
         # Create entity for job removed event
         data_event = self.__getTaskFromSchedulerById(event.job_id, event.code)
@@ -944,7 +931,9 @@ class Schedule(ISchedule):
                         trigger=entity.trigger,
                         id=signature,
                         name=signature,
-                        replace_existing=True
+                        replace_existing=True,
+                        max_instances=entity.max_instances,
+                        misfire_grace_time=entity.misfire_grace_time
                     )
 
                     # If a listener is associated with the event, register it

{orionis-0.535.0 → orionis-0.537.0}/orionis/container/container.py

@@ -17,6 +17,8 @@ from orionis.services.introspection.callables.reflection import ReflectionCallab
 from orionis.services.introspection.concretes.reflection import ReflectionConcrete
 from orionis.services.introspection.dependencies.entities.argument import Argument
 from orionis.services.introspection.dependencies.entities.resolve_argument import ResolveArguments
+from orionis.services.introspection.dependencies.reflection import ReflectDependencies
+from orionis.services.introspection.instances.reflection import ReflectionInstance
 
 class Container(IContainer):
 
@@ -206,9 +208,72 @@ class Container(IContainer):
 
         try:
 
-            # Check if the callable is a coroutine function
-            result = fn(*args, **kwargs)
-            return self.__handleSyncAsyncResult(result)
+            # Count the total number of provided arguments
+            total_provided_args = len(args) + len(kwargs)
+
+            # Inspect the callable to determine its signature and parameters
+            dependencies = ReflectDependencies(fn).getCallableDependencies()
+            total_dependencies = len(dependencies.resolved) + len(dependencies.unresolved)
+
+            # If the callable does not require any dependencies, invoke directly
+            if total_dependencies == 0:
+                result = fn(*args, **kwargs)
+                return self.__handleSyncAsyncResult(result)
+
+            # If enough arguments are provided, invoke directly
+            if total_provided_args >= total_dependencies:
+                result = fn(*args, **kwargs)
+                return self.__handleSyncAsyncResult(result)
+
+            # If not enough arguments are provided, attempt to resolve missing dependencies
+            if total_provided_args < total_dependencies:
+
+                # New lists to hold the final arguments to pass to the callable
+                n_args = []
+                n_kwargs = {}
+
+                # Iterate through the function's required arguments in order
+                args_index = 0
+
+                # Iterate over all dependencies in the order they were defined
+                for name, dep in dependencies.ordered.items():
+
+                    # Check if the argument was provided positionally and hasn't been used yet
+                    if args_index < len(args) and name not in kwargs:
+
+                        # Add the positional argument to the new list
+                        n_args.append(args[args_index])
+
+                        # Move to the next positional argument
+                        args_index += 1
+
+                    # Check if the argument was provided as a keyword argument
+                    elif name in kwargs:
+
+                        # Add the keyword argument to the new dictionary
+                        n_kwargs[name] = kwargs[name]
+
+                        # Remove the argument from the original kwargs to avoid duplication
+                        del kwargs[name]
+
+                    # If not provided, attempt to resolve it from the container
+                    else:
+
+                        n_kwargs[name] = self.__resolveSingleDependency(
+                            getattr(fn, '__name__', str(fn)),
+                            name,
+                            dep
+                        )
+
+                # Add any remaining positional arguments that weren't mapped to specific parameters
+                n_args.extend(args[args_index:])
+
+                # Add any remaining keyword arguments that weren't processed
+                n_kwargs.update(kwargs)
+
+                # Invoke the function with the resolved arguments
+                result = fn(*n_args, **n_kwargs)
+                return self.__handleSyncAsyncResult(result)
 
         except TypeError as e:
 
@@ -219,8 +284,9 @@ class Container(IContainer):
 
             # Raise a more informative exception with the function name and signature
             raise OrionisContainerException(
-                f"Failed to invoke function [{function_name}] with the provided arguments: {e}\n"
-                f"Expected function signature: [{signature}]"
+                f"Failed to invoke function [{function_name}] with the provided arguments: {e}. "
+                f"Note that this may include a reference to the same 'self' object.\n"
+                f"Expected function signature: {function_name}{signature}"
             ) from e
 
     def transient(
@@ -2360,6 +2426,79 @@ class Container(IContainer):
                 f"Method '{method_name}' not found or not callable on instance '{type(instance).__name__}'."
             )
 
+    def invoke(
+        self,
+        fn: Callable,
+        *args,
+        **kwargs
+    ) -> Any:
+        """
+        Invokes a callable with automatic dependency injection and sync/async handling.
+
+        Parameters
+        ----------
+        fn : Callable
+            The callable to invoke.
+        *args : tuple
+            Positional arguments to pass to the callable.
+        **kwargs : dict
+            Keyword arguments to pass to the callable.
+
+        Returns
+        -------
+        Any
+            The result of the callable invocation.
+        """
+
+        # Validate that fn is indeed callable
+        if not callable(fn):
+            raise OrionisContainerException(
+                f"Provided fn '{getattr(fn, '__name__', str(fn))}' is not callable."
+            )
+
+        # Execute the callable with appropriate handling
+        return self.__executeMethod(fn, *args, **kwargs)
+
+    async def invokeAsync(
+        self,
+        fn: Callable,
+        *args,
+        **kwargs
+    ) -> Any:
+        """
+        Async version of invoke for when you're in an async context and need to await the result.
+
+        Parameters
+        ----------
+        fn : Callable
+            The callable to invoke.
+        *args : tuple
+            Positional arguments to pass to the callable.
+        **kwargs : dict
+            Keyword arguments to pass to the callable.
+
+        Returns
+        -------
+        Any
+            The result of the callable invocation, properly awaited if async.
+        """
+
+        # Validate that fn is indeed callable
+        if not callable(fn):
+            raise OrionisContainerException(
+                f"Provided fn '{getattr(fn, '__name__', str(fn))}' is not callable."
+            )
+
+        # Execute the callable with appropriate handling
+        result = self.__executeMethod(fn, *args, **kwargs)
+
+        # If the result is a coroutine, await it
+        if asyncio.iscoroutine(result):
+            return await result
+
+        # Otherwise, return the result directly
+        return result
+
     def __executeMethod(
         self,
         method: Callable,

{orionis-0.535.0 → orionis-0.537.0}/orionis/container/contracts/container.py

@@ -449,3 +449,55 @@ class IContainer(ABC):
             The result of the method call, properly awaited if async.
         """
         pass
+
+    @abstractmethod
+    def invoke(
+        self,
+        fn: Callable,
+        *args,
+        **kwargs
+    ) -> Any:
+        """
+        Invokes a callable with automatic dependency injection and sync/async handling.
+
+        Parameters
+        ----------
+        fn : Callable
+            The callable to invoke.
+        *args : tuple
+            Positional arguments to pass to the callable.
+        **kwargs : dict
+            Keyword arguments to pass to the callable.
+
+        Returns
+        -------
+        Any
+            The result of the callable invocation.
+        """
+        pass
+
+    @abstractmethod
+    async def invokeAsync(
+        self,
+        fn: Callable,
+        *args,
+        **kwargs
+    ) -> Any:
+        """
+        Async version of invoke for when you're in an async context and need to await the result.
+
+        Parameters
+        ----------
+        fn : Callable
+            The callable to invoke.
+        *args : tuple
+            Positional arguments to pass to the callable.
+        **kwargs : dict
+            Keyword arguments to pass to the callable.
+
+        Returns
+        -------
+        Any
+            The result of the callable invocation, properly awaited if async.
+        """
+        pass

{orionis-0.535.0 → orionis-0.537.0}/orionis/failure/base/handler.py

@@ -13,7 +13,7 @@ class BaseExceptionHandler(IBaseExceptionHandler):
         # Example: OrionisContainerException
     ]
 
-    async def destructureException(self, e: BaseException) -> Throwable:
+    async def destructureException(self, exception: BaseException) -> Throwable:
         """
         Converts an exception into a structured `Throwable` object containing detailed information.
 
@@ -35,13 +35,13 @@ class BaseExceptionHandler(IBaseExceptionHandler):
 
         # Create and return a Throwable object with detailed exception information
         return Throwable(
-            classtype=type(e),                              # The class/type of the exception
-            message=str(e),                                 # The exception message as a string
-            args=e.args,                                    # The arguments passed to the exception
-            traceback=getattr(e, '__traceback__', None)     # The traceback object, if available
+            classtype=type(exception),                              # The class/type of the exception
+            message=str(exception),                                 # The exception message as a string
+            args=exception.args,                                    # The arguments passed to the exception
+            traceback=getattr(exception, '__traceback__', None)     # The traceback object, if available
         )
 
-    async def shouldIgnoreException(self, e: BaseException) -> bool:
+    async def shouldIgnoreException(self, exception: BaseException) -> bool:
         """
         Determines if the exception should be ignored (not handled) by the handler.
 
@@ -57,11 +57,11 @@ class BaseExceptionHandler(IBaseExceptionHandler):
         """
 
         # Ensure the provided object is an exception
-        if not isinstance(e, BaseException):
-            raise TypeError(f"Expected BaseException, got {type(e).__name__}")
+        if not isinstance(exception, BaseException):
+            raise TypeError(f"Expected BaseException, got {type(exception).__name__}")
 
         # Convert the exception into a structured Throwable object
-        throwable = await self.destructureException(e)
+        throwable = await self.destructureException(exception)
 
         # Check if the exception type is in the list of exceptions to ignore
         return hasattr(self, 'dont_catch') and throwable.classtype in self.dont_catch

orionis-0.537.0/orionis/failure/catch.py

@@ -0,0 +1,82 @@
+from typing import Any
+from orionis.console.kernel import KernelCLI
+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
+
+class Catch(ICatch):
+
+    def __init__(self, app: IApplication) -> None:
+        """
+        Initializes the Catch handler with application services for console output and logging.
+
+        Parameters
+        ----------
+        app : IApplication
+            The application instance used to resolve required services.
+
+        Attributes
+        ----------
+        console : IConsole
+            Console output service obtained from the application for displaying messages and exceptions.
+        logger : ILogger
+            Logger service obtained from the application for logging errors and exceptions.
+
+        Returns
+        -------
+        None
+            This constructor does not return any value.
+
+        Notes
+        -----
+        The constructor retrieves the console and logger services from the application container
+        using their respective service keys. These services are used throughout the class for
+        error reporting and output.
+        """
+
+        # Store the application instance
+        self.__app: IApplication = app
+
+        # Retrieve the console output service from the application container
+        self.__exception_handler: IBaseExceptionHandler = app.getExceptionHandler()
+
+    def exception(self, kernel: Any, request: Any, e: BaseException) -> None:
+        """
+        Handles and reports exceptions that occur during CLI execution.
+
+        This method reports the provided exception using the application's exception handler and logger.
+        If a kernel instance is provided, it also renders the exception details to the CLI for user visibility.
+
+        Parameters
+        ----------
+        kernel : Any
+            The kernel instance associated with the CLI, or None if not available.
+        request : Any
+            The request or arguments associated with the CLI command.
+        e : BaseException
+            The exception instance to be handled.
+
+        Returns
+        -------
+        None
+            This method does not return any value. It performs side effects such as logging and output.
+
+        Notes
+        -----
+        The exception is always reported using the exception handler and logger.
+        If a valid kernel is provided, the exception details are rendered to the CLI.
+        """
+
+        # If there is no exception handler, return early
+        if self.__app.call(self.__exception_handler, 'shouldIgnoreException', exception=e):
+            return
+
+        # Report the exception using the exception handler and logger
+        self.__app.call(self.__exception_handler, 'report', exception=e)
+
+        # Check if the kernel is of type `KernelCLI` or `Any`
+        if isinstance(kernel, KernelCLI) or isinstance(kernel, Schedule):
+
+            # Render the exception details to the CLI using the exception handler
+            self.__app.call(self.__exception_handler, 'renderCLI', request=request, exception=e)

{orionis-0.535.0 → orionis-0.537.0}/orionis/failure/entities/throwable.py

@@ -1,6 +1,6 @@
 from dataclasses import dataclass
 
-@dataclass(kw_only=True)
+@dataclass(kw_only=True, frozen=True)
 class Throwable:
     """
     Represents a throwable entity (such as an exception or error) within the framework.

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

@@ -469,10 +469,10 @@ class Application(Container, IApplication):
         if self.__exception_handler is None:
 
             # Return the default exception handler instance
-            return BaseExceptionHandler()
+            return self.make(BaseExceptionHandler)
 
         # Instantiate and return the registered exception handler
-        return self.__exception_handler()
+        return self.make(self.__exception_handler)
 
     def setScheduler(
         self,

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

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

{orionis-0.535.0 → orionis-0.537.0}/orionis/services/introspection/dependencies/entities/resolve_argument.py

@@ -43,6 +43,9 @@ class ResolveArguments(BaseEntity):
     # Unresolved dependencies as a dictionary of names to Argument instances
     unresolved: Dict[str, Argument]
 
+    # All dependencies in the order they were defined
+    ordered: Dict[str, Argument]
+
     def __post_init__(self):
         """
         Validates the types and contents of the resolved and unresolved attributes.
@@ -79,4 +82,11 @@ class ResolveArguments(BaseEntity):
         if not isinstance(self.unresolved, dict):
             raise ReflectionTypeError(
                 f"'unresolved' must be a dict, got {type(self.unresolved).__name__}"
+            )
+
+        # Validate that the 'ordered' attribute is a dictionary type
+        # This ensures that all dependencies maintain the same structure as resolved ones
+        if not isinstance(self.ordered, dict):
+            raise ReflectionTypeError(
+                f"'ordered' must be a dict, got {type(self.ordered).__name__}"
             )