orionis 0.492.0__tar.gz → 0.493.0__tar.gz

{orionis-0.492.0/orionis.egg-info → orionis-0.493.0}/PKG-INFO

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

{orionis-0.492.0 → orionis-0.493.0}/orionis/console/base/scheduler.py

@@ -27,15 +27,9 @@ class BaseScheduler(IBaseScheduler):
         None
             This method does not return any value. It is intended to be overridden
             by subclasses to specify scheduled tasks.
-
-        Notes
-        -----
-        Subclasses should implement this method to add specific tasks to the scheduler
-        using the provided `schedule` object. This method enforces that each subclass
-        defines its own scheduled tasks.
         """
-        # Raise an error to enforce implementation in subclasses
-        raise NotImplementedError("The 'tasks' method must be implemented in the subclass.")
+        # Placeholder for task registration logic
+        pass
 
     def onStarted(self):
         """

{orionis-0.492.0 → orionis-0.493.0}/orionis/console/kernel.py

@@ -103,8 +103,7 @@ class KernelCLI(IKernelCLI):
         except BaseException as e:
 
             # Catch any exceptions that occur during command handling
-            self.__catch.report(e)
-            self.__catch.renderCLI(args, e)
+            self.__catch.exception(self, args, e)
 
             # Exit the process with a non-zero status code to indicate an error
             sys.exit(1)

orionis-0.492.0/orionis/failure/catch.py → orionis-0.493.0/orionis/failure/base/handler.py

@@ -1,51 +1,17 @@
 from typing import Any, List
 from orionis.console.output.contracts.console import IConsole
-from orionis.failure.contracts.catch import ICatch
+from orionis.failure.contracts.handler import IBaseExceptionHandler
 from orionis.failure.entities.throwable import Throwable
-from orionis.foundation.contracts.application import IApplication
 from orionis.services.log.contracts.log_service import ILogger
 
-class Catch(ICatch):
+class BaseExceptionHandler(IBaseExceptionHandler):
 
     # Exceptions that should not be caught by the handler
     dont_cathc: List[type[BaseException]] = [
-        #...
+        # Add specific exceptions that should not be caught
+        # Example: OrionisContainerException
     ]
 
-    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.
-        """
-
-        # Retrieve the console output service from the application container
-        self.console: IConsole = app.make('x-orionis.console.output.console')
-
-        # Retrieve the logger service from the application container
-        self.logger: ILogger = app.make('x-orionis.services.log.log_service')
-
     def destructureException(self, e: BaseException) -> Throwable:
         """
         Converts an exception into a structured `Throwable` object containing detailed information.
@@ -74,31 +40,19 @@ class Catch(ICatch):
             traceback=getattr(e, '__traceback__', None)     # The traceback object, if available
         )
 
-    def report(self, exception: BaseException) -> Any:
+    def report (self, exception: BaseException, log: ILogger) -> Any:
         """
-        Logs and returns a destructured representation of an exception.
+        Report or log an exception.
 
         Parameters
         ----------
         exception : BaseException
-            The exception instance to be reported.
+            The exception instance that was caught.
 
         Returns
         -------
-        Throwable
-            A destructured representation of the exception, containing its type, message, arguments, and traceback.
-
-        Raises
-        ------
-        TypeError
-            If the provided exception is not an instance of BaseException.
-
-        Notes
-        -----
-        This method logs the exception details using the configured logger and returns a structured
-        representation of the exception for further processing.
+        None
         """
-
         # Ensure the provided object is an exception
         if not isinstance(exception, BaseException):
             raise TypeError(f"Expected BaseException, got {type(exception).__name__}")
@@ -111,38 +65,24 @@ class Catch(ICatch):
             return
 
         # Log the exception details
-        self.logger.error(f"[{throwable.classtype.__name__}] {throwable.message}")
+        log.error(f"[{throwable.classtype.__name__}] {throwable.message}")
 
         # Return the structured exception
         return throwable
 
-    def renderCLI(self, args: List[str], exception: BaseException) -> Any:
+    def renderCLI(self, args: List[str], exception: BaseException, log: ILogger, console: IConsole) -> Any:
         """
-        Renders a CLI-friendly error message for a given exception.
+        Render the exception message for CLI output.
 
         Parameters
         ----------
-        args : list
-            The list of command-line arguments that were passed to the CLI.
         exception : BaseException
-            The exception instance to be rendered.
+            The exception instance that was caught.
 
         Returns
         -------
         None
-            This method does not return any value.
-
-        Raises
-        ------
-        TypeError
-            If the provided exception is not an instance of BaseException.
-
-        Notes
-        -----
-        This method logs the error message using the configured logger and outputs
-        the exception traceback to the console for user visibility.
         """
-
         # Ensure the provided object is an exception
         if not isinstance(exception, BaseException):
             raise TypeError(f"Expected BaseException, got {type(exception).__name__}")
@@ -155,9 +95,9 @@ class Catch(ICatch):
             return
 
         # Log the CLI error message with arguments
-        self.logger.error(f"CLI Error: {throwable.message} (Args: {args})")
+        log.error(f"CLI Error: {throwable.message} (Args: {args})")
 
         # Output the exception traceback to the console
-        self.console.newLine()
-        self.console.exception(exception)
-        self.console.newLine()
+        console.newLine()
+        console.exception(exception)
+        console.newLine()

orionis-0.493.0/orionis/failure/catch.py

@@ -0,0 +1,93 @@
+from typing import Any, List
+from orionis.console.kernel import KernelCLI
+from orionis.console.output.contracts.console import IConsole
+from orionis.failure.contracts.catch import ICatch
+from orionis.failure.contracts.handler import IBaseExceptionHandler
+from orionis.foundation.contracts.application import IApplication
+from orionis.services.log.contracts.log_service import ILogger
+
+class Catch(ICatch):
+
+    # Exceptions that should not be caught by the handler
+    dont_cathc: List[type[BaseException]] = [
+        #...
+    ]
+
+    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.
+        """
+
+        # Retrieve the console output service from the application container
+        self.__console: IConsole = app.make('x-orionis.console.output.console')
+
+        # Retrieve the logger service from the application container
+        self.__logger: ILogger = app.make('x-orionis.services.log.log_service')
+
+        # 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.
+        """
+
+        # Report the exception using the application's exception handler and logger
+        self.__exception_handler.report(
+            exception=e,
+            log=self.__logger
+        )
+
+        # If a kernel is provided, render the exception details to the CLI
+        if isinstance(kernel, KernelCLI):
+            return self.__exception_handler.renderCLI(
+                args=request,
+                exception=e,
+                log=self.__logger,
+                console=self.__console
+            )

orionis-0.493.0/orionis/failure/contracts/catch.py

@@ -0,0 +1,32 @@
+from abc import ABC, abstractmethod
+from typing import Any
+
+class ICatch(ABC):
+
+    @abstractmethod
+    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.
+        """

orionis-0.493.0/orionis/failure/contracts/handler.py

@@ -0,0 +1,38 @@
+from abc import abstractmethod
+from typing import Any, List
+from orionis.console.output.contracts.console import IConsole
+from orionis.services.log.contracts.log_service import ILogger
+
+class IBaseExceptionHandler:
+
+    @abstractmethod
+    def report (self, exception: BaseException, log: ILogger) -> Any:
+        """
+        Report or log an exception.
+
+        Parameters
+        ----------
+        exception : BaseException
+            The exception instance that was caught.
+
+        Returns
+        -------
+        None
+        """
+        pass
+
+    @abstractmethod
+    def renderCLI(self, args: List[str], exception: BaseException, log: ILogger, console: IConsole) -> Any:
+        """
+        Render the exception message for CLI output.
+
+        Parameters
+        ----------
+        exception : BaseException
+            The exception instance that was caught.
+
+        Returns
+        -------
+        None
+        """
+        pass

{orionis-0.492.0 → orionis-0.493.0}/orionis/foundation/application.py

@@ -2,9 +2,12 @@ import asyncio
 import time
 from pathlib import Path
 from typing import Any, List, Type
+from orionis.console.base.contracts.scheduler import IBaseScheduler
 from orionis.console.base.scheduler import BaseScheduler
 from orionis.container.container import Container
 from orionis.container.contracts.service_provider import IServiceProvider
+from orionis.failure.base.handler import BaseExceptionHandler
+from orionis.failure.contracts.handler import IBaseExceptionHandler
 from orionis.foundation.config.app.entities.app import App
 from orionis.foundation.config.auth.entities.auth import Auth
 from orionis.foundation.config.cache.entities.cache import Cache
@@ -117,6 +120,9 @@ class Application(Container, IApplication):
             # Property to store the scheduler instance
             self.__scheduler: BaseScheduler = None
 
+            # Property to store the exception handler class
+            self.__exception_handler: Type[BaseExceptionHandler] = None
+
             # Flag to prevent re-initialization
             self.__initialized = True
 
@@ -383,9 +389,88 @@ class Application(Container, IApplication):
     # for complex and unique application requirements, supporting advanced customization
     # of every subsystem as needed.
 
+    def setExceptionHandler(
+        self,
+        handler: IBaseExceptionHandler
+    ) -> 'Application':
+        """
+        Register a custom exception handler class for the application.
+
+        This method allows you to specify a custom exception handler class that
+        inherits from BaseExceptionHandler. The handler class will be used to
+        manage exceptions raised within the application, including reporting and
+        rendering error messages. The provided handler must be a class (not an
+        instance) and must inherit from BaseExceptionHandler.
+
+        Parameters
+        ----------
+        handler : Type[BaseExceptionHandler]
+            The exception handler class to be used by the application. Must be a
+            subclass of BaseExceptionHandler.
+
+        Returns
+        -------
+        Application
+            The current Application instance, allowing for method chaining.
+
+        Raises
+        ------
+        OrionisTypeError
+            If the provided handler is not a class or is not a subclass of BaseExceptionHandler.
+
+        Notes
+        -----
+        The handler is stored internally and will be instantiated when needed.
+        This method does not instantiate the handler; it only registers the class.
+        """
+
+        # Ensure the provided handler is a subclass of BaseExceptionHandler
+        if not issubclass(handler, BaseExceptionHandler):
+            raise OrionisTypeError(f"Expected BaseExceptionHandler subclass, got {type(handler).__name__}")
+
+        # Store the handler class in the application for later use
+        self.__exception_handler = handler
+
+        # Return the application instance for method chaining
+        return self
+
+    def getExceptionHandler(
+        self
+    ) -> IBaseExceptionHandler:
+        """
+        Retrieve the currently registered exception handler instance.
+
+        This method returns an instance of the exception handler that has been set using
+        the `setExceptionHandler` method. If no custom handler has been set, it returns
+        a default `BaseExceptionHandler` instance. The returned object is responsible
+        for handling exceptions within the application, including reporting and rendering
+        error messages.
+
+        Returns
+        -------
+        BaseExceptionHandler
+            An instance of the currently registered exception handler. If no handler
+            has been set, returns a default `BaseExceptionHandler` instance.
+
+        Notes
+        -----
+        This method always returns an instance (not a class) of the exception handler.
+        If a custom handler was registered, it is instantiated and returned; otherwise,
+        a default handler is used.
+        """
+
+        # Check if an exception handler has been set
+        if self.__exception_handler is None:
+
+            # Return the default exception handler instance
+            return BaseExceptionHandler()
+
+        # Instantiate and return the registered exception handler
+        return self.__exception_handler()
+
     def setScheduler(
         self,
-        scheduler: BaseScheduler
+        scheduler: IBaseScheduler
     ) -> 'Application':
         """
         Register a custom scheduler class for the application.
@@ -430,7 +515,7 @@ class Application(Container, IApplication):
 
     def getScheduler(
         self
-    ) -> BaseScheduler:
+    ) -> IBaseScheduler:
         """
         Retrieve the currently registered scheduler instance.
 
@@ -450,8 +535,7 @@ class Application(Container, IApplication):
 
         # Check if a scheduler has been set
         if self.__scheduler is None:
-            from orionis.console.default.scheduler import Scheduler as DefaultScheduler
-            return DefaultScheduler()
+            return BaseScheduler()
 
         # Return the registered scheduler instance
         return self.__scheduler()

{orionis-0.492.0 → orionis-0.493.0}/orionis/foundation/contracts/application.py

@@ -2,6 +2,7 @@ from abc import abstractmethod
 from pathlib import Path
 from typing import Any, List, Type
 from orionis.console.base.scheduler import BaseScheduler
+from orionis.failure.contracts.handler import IBaseExceptionHandler
 from orionis.foundation.config.roots.paths import Paths
 from orionis.container.contracts.service_provider import IServiceProvider
 from orionis.container.contracts.container import IContainer
@@ -93,6 +94,68 @@ class IApplication(IContainer):
         """
         pass
 
+    def setExceptionHandler(
+        self,
+        handler: IBaseExceptionHandler
+    ) -> 'IApplication':
+        """
+        Register a custom exception handler class for the application.
+
+        This method allows you to specify a custom exception handler class that
+        inherits from BaseHandlerException. The handler class will be used to
+        manage exceptions raised within the application, including reporting and
+        rendering error messages. The provided handler must be a class (not an
+        instance) and must inherit from BaseHandlerException.
+
+        Parameters
+        ----------
+        handler : Type[BaseHandlerException]
+            The exception handler class to be used by the application. Must be a
+            subclass of BaseHandlerException.
+
+        Returns
+        -------
+        Application
+            The current Application instance, allowing for method chaining.
+
+        Raises
+        ------
+        OrionisTypeError
+            If the provided handler is not a class or is not a subclass of BaseHandlerException.
+
+        Notes
+        -----
+        The handler is stored internally and will be instantiated when needed.
+        This method does not instantiate the handler; it only registers the class.
+        """
+        pass
+
+    def getExceptionHandler(
+        self
+    ) -> IBaseExceptionHandler:
+        """
+        Retrieve the currently registered exception handler instance.
+
+        This method returns an instance of the exception handler that has been set using
+        the `setExceptionHandler` method. If no custom handler has been set, it returns
+        a default `BaseHandlerException` instance. The returned object is responsible
+        for handling exceptions within the application, including reporting and rendering
+        error messages.
+
+        Returns
+        -------
+        BaseHandlerException
+            An instance of the currently registered exception handler. If no handler
+            has been set, returns a default `BaseHandlerException` instance.
+
+        Notes
+        -----
+        This method always returns an instance (not a class) of the exception handler.
+        If a custom handler was registered, it is instantiated and returned; otherwise,
+        a default handler is used.
+        """
+        pass
+
     @abstractmethod
     def setScheduler(
         self,

{orionis-0.492.0 → orionis-0.493.0}/orionis/metadata/framework.py

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

{orionis-0.492.0 → orionis-0.493.0/orionis.egg-info}/PKG-INFO

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

{orionis-0.492.0 → orionis-0.493.0}/orionis.egg-info/SOURCES.txt

@@ -39,8 +39,6 @@ orionis/console/contracts/reactor.py
 orionis/console/contracts/schedule.py
 orionis/console/core/__init__.py
 orionis/console/core/reactor.py
-orionis/console/default/__init__.py
-orionis/console/default/scheduler.py
 orionis/console/dumper/__init__.py
 orionis/console/dumper/dump.py
 orionis/console/dumper/contracts/__init__.py
@@ -106,8 +104,11 @@ orionis/container/validators/is_valid_alias.py
 orionis/container/validators/lifetime.py
 orionis/failure/__init__.py
 orionis/failure/catch.py
+orionis/failure/base/__init__.py
+orionis/failure/base/handler.py
 orionis/failure/contracts/__init__.py
 orionis/failure/contracts/catch.py
+orionis/failure/contracts/handler.py
 orionis/failure/entities/__init__.py
 orionis/failure/entities/throwable.py
 orionis/foundation/__init__.py

orionis-0.492.0/orionis/console/default/scheduler.py

@@ -1,27 +0,0 @@
-from orionis.console.base.scheduler import BaseScheduler
-from orionis.console.contracts.schedule import ISchedule
-
-class Scheduler(BaseScheduler):
-
-    def tasks(self, schedule: ISchedule):
-        """
-        Defines and registers scheduled tasks for the application.
-
-        Parameters
-        ----------
-        schedule : ISchedule
-            The schedule object used to define and register scheduled commands.
-
-        Returns
-        -------
-        None
-            This method does not return any value. It is intended to be overridden
-            by subclasses to specify scheduled tasks.
-
-        Notes
-        -----
-        Subclasses should implement this method to add specific tasks to the scheduler
-        using the provided `schedule` object. This method enforces that each subclass
-        defines its own scheduled tasks.
-        """
-        pass