orionis 0.644.0__tar.gz → 0.645.0__tar.gz

{orionis-0.644.0/orionis.egg-info → orionis-0.645.0}/PKG-INFO

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

{orionis-0.644.0 → orionis-0.645.0}/orionis/console/contracts/console.py

@@ -450,4 +450,55 @@ class IConsole(ABC):
         message : Optional[str], optional
             The error message to print before exiting.
         """
+        pass
+
+    @abstractmethod
+    def dump(
+        self,
+        *args,
+        show_types: bool = True,
+        show_index: bool = False,
+        expand_all: bool = True,
+        max_depth: int | None = None,
+        module_path: str | None = None,
+        line_number: int | None = None,
+        force_exit: bool = False,
+        redirect_output: bool = False,
+        insert_line: bool = False
+    ) -> Optional[str]:
+        """
+        Displays formatted debug information for one or more variables using Rich, and optionally exports the output as HTML.
+
+        Parameters
+        ----------
+        *args : Any
+            One or more objects to be displayed for debugging.
+        show_types : bool, optional
+            If True, displays the type of each argument in the panel title. Default is True.
+        show_index : bool, optional
+            If True, shows an index number for each argument. Default is False.
+        expand_all : bool, optional
+            If True, expands all nested data structures. Default is True.
+        max_depth : int or None, optional
+            Maximum depth for nested structures. If None, no limit is applied. Default is None.
+        module_path : str or None, optional
+            Overrides the module path shown in the header. If None, uses the caller's module path.
+        line_number : int or None, optional
+            Overrides the line number shown in the header. If None, uses the caller's line number.
+        force_exit : bool, optional
+            If True, terminates the program after dumping. Default is False.
+        redirect_output : bool, optional
+            If True, temporarily restores stdout/stderr to their original streams during output. Default is False.
+        insert_line : bool, optional
+            If True, inserts a blank line before and after the dump output for better readability. Default
+
+        Returns
+        -------
+        Optional[str]
+            An HTML string containing the formatted output if successful, or None if caller information is unavailable.
+
+        Notes
+        -----
+        This method uses the Rich library to display variables in a visually enhanced format, including type and index information if specified. It can also export the output as HTML for further use.
+        """
         pass

orionis-0.645.0/orionis/console/contracts/dumper.py

@@ -0,0 +1,92 @@
+from abc import ABC, abstractmethod
+from typing import Any
+
+class IDumper(ABC):
+
+    @abstractmethod
+    def dd(
+        self,
+        *args: Any,
+        show_types: bool = False,
+        show_index: bool = False,
+        expand_all: bool = True,
+        max_depth: int | None = None,
+        module_path: str = None,
+        line_number: int = None
+    ) -> None:
+        """
+        Dump the provided variables to the console and terminate execution.
+
+        This method outputs the given variables to the console using the configured
+        console instance, then immediately stops program execution. It provides several
+        options to customize the output, such as displaying types, indices, expanding
+        all nested structures, and limiting the depth of expansion. The output can also
+        include information about the module path and line number where the method was called.
+
+        Parameters
+        ----------
+        *args : Any
+            The variables to be dumped to the console.
+        show_types : bool, optional
+            Whether to display the type of each variable (default is False).
+        show_index : bool, optional
+            Whether to display the index for each variable in the output (default is False).
+        expand_all : bool, optional
+            Whether to expand all nested structures in the output (default is True).
+        max_depth : int or None, optional
+            The maximum depth to which nested structures should be expanded (default is None, meaning no limit).
+        module_path : str or None, optional
+            The path of the module from which the method is called (default is None).
+        line_number : int or None, optional
+            The line number in the source code where the method is called (default is None).
+
+        Returns
+        -------
+        None
+            This method does not return any value. It outputs the dump information to the console and terminates execution.
+        """
+        pass
+
+    @abstractmethod
+    def dump(
+        self,
+        *args: Any,
+        show_types: bool = False,
+        show_index: bool = False,
+        expand_all: bool = True,
+        max_depth: int | None = None,
+        module_path: str = None,
+        line_number: int = None
+    ) -> None:
+        """
+        Dump the provided variables to the console for debugging purposes.
+
+        This method outputs the given variables to the console using the configured
+        console instance. It provides several options to customize the output, such as
+        displaying types, indices, expanding all nested structures, and limiting the
+        depth of expansion. The output can also include information about the module
+        path and line number where the dump was called.
+
+        Parameters
+        ----------
+        *args : Any
+            The variables to be dumped to the console.
+        show_types : bool, optional
+            Whether to display the type of each variable (default is False).
+        show_index : bool, optional
+            Whether to display the index for each variable in the output (default is False).
+        expand_all : bool, optional
+            Whether to expand all nested structures in the output (default is True).
+        max_depth : int or None, optional
+            The maximum depth to which nested structures should be expanded (default is None, meaning no limit).
+        module_path : str or None, optional
+            The path of the module from which the dump is called (default is None).
+        line_number : int or None, optional
+            The line number in the source code where the dump is called (default is None).
+
+        Returns
+        -------
+        None
+            This method does not return any value. It outputs the dump information to the console.
+        """
+        pass

orionis-0.645.0/orionis/console/debug/dumper.py

@@ -0,0 +1,149 @@
+from typing import Any
+from orionis.console.contracts.console import IConsole
+from orionis.console.contracts.dumper import IDumper
+
+class Dumper(IDumper):
+
+    def __init__(self, console: IConsole) -> None:
+        """
+        Initialize the Debug class with a console instance.
+
+        This constructor sets up the Debug utility by assigning the provided
+        console instance, which will be used for dumping variable output to
+        the console. The console must implement the IConsole interface.
+
+        Parameters
+        ----------
+        console : IConsole
+            An instance of a console that implements the IConsole interface.
+            This console will be used for outputting debug information.
+
+        Returns
+        -------
+        None
+            This method does not return any value.
+        """
+
+        self.__console = console
+
+    def dd(
+        self,
+        *args: Any,
+        show_types: bool = False,
+        show_index: bool = False,
+        expand_all: bool = True,
+        max_depth: int | None = None,
+        module_path: str = None,
+        line_number: int = None,
+        insert_line: bool = False
+    ) -> None:
+        """
+        Dump the provided variables to the console and terminate execution.
+
+        This method outputs the given variables to the console using the configured
+        console instance, then immediately stops program execution. It provides several
+        options to customize the output, such as displaying types, indices, expanding
+        all nested structures, and limiting the depth of expansion. The output can also
+        include information about the module path and line number where the method was called.
+
+        Parameters
+        ----------
+        *args : Any
+            The variables to be dumped to the console.
+        show_types : bool, optional
+            Whether to display the type of each variable (default is False).
+        show_index : bool, optional
+            Whether to display the index for each variable in the output (default is False).
+        expand_all : bool, optional
+            Whether to expand all nested structures in the output (default is True).
+        max_depth : int or None, optional
+            The maximum depth to which nested structures should be expanded (default is None, meaning no limit).
+        module_path : str or None, optional
+            The path of the module from which the method is called (default is None).
+        line_number : int or None, optional
+            The line number in the source code where the method is called (default is None).
+        insert_line : bool, optional
+            Whether to insert a separating line before the dump output (default is False).
+
+        Returns
+        -------
+        None
+            This method does not return any value. It outputs the dump information to the console and terminates execution.
+        """
+
+        # Call the console's dump method with the provided arguments and options.
+        # force_exit is set to True to terminate execution after dumping.
+        # redirect_output is set to True to ensure output is redirected appropriately.
+        self.__console.dump(
+            *args,
+            show_types=show_types,
+            show_index=show_index,
+            expand_all=expand_all,
+            max_depth=max_depth,
+            module_path=module_path,
+            line_number=line_number,
+            force_exit=True,
+            redirect_output=True,
+            insert_line=insert_line
+        )
+
+    def dump(
+        self,
+        *args: Any,
+        show_types: bool = False,
+        show_index: bool = False,
+        expand_all: bool = True,
+        max_depth: int | None = None,
+        module_path: str = None,
+        line_number: int = None,
+        insert_line: bool = False
+    ) -> None:
+        """
+        Dump the provided variables to the console for debugging purposes.
+
+        This method outputs the given variables to the console using the configured
+        console instance. It provides several options to customize the output, such as
+        displaying types, indices, expanding all nested structures, and limiting the
+        depth of expansion. The output can also include information about the module
+        path and line number where the dump was called.
+
+        Parameters
+        ----------
+        *args : Any
+            The variables to be dumped to the console.
+        show_types : bool, optional
+            Whether to display the type of each variable (default is False).
+        show_index : bool, optional
+            Whether to display the index for each variable in the output (default is False).
+        expand_all : bool, optional
+            Whether to expand all nested structures in the output (default is True).
+        max_depth : int or None, optional
+            The maximum depth to which nested structures should be expanded (default is None, meaning no limit).
+        module_path : str or None, optional
+            The path of the module from which the dump is called (default is None).
+        line_number : int or None, optional
+            The line number in the source code where the dump is called (default is None).
+        insert_line : bool, optional
+            Whether to insert a separating line before the dump output (default is False).
+
+        Returns
+        -------
+        None
+            This method does not return any value. It outputs the dump information to the console.
+        """
+
+        # Call the console's dump method with the provided arguments and options.
+        # force_exit is set to False to continue execution after dumping.
+        # redirect_output is set to True to ensure output is redirected appropriately.
+        self.__console.dump(
+            *args,
+            show_types=show_types,
+            show_index=show_index,
+            expand_all=expand_all,
+            max_depth=max_depth,
+            module_path=module_path,
+            line_number=line_number,
+            force_exit=False,
+            redirect_output=True,
+            insert_line=insert_line
+        )

{orionis-0.644.0 → orionis-0.645.0}/orionis/console/output/console.py

@@ -1,7 +1,14 @@
 import datetime
 import getpass
+import inspect
 import os
 import sys
+from typing import Optional
+from rich.console import Console as RichConsole
+from rich.panel import Panel
+from rich.pretty import Pretty
+from rich.theme import Theme
+from rich.traceback import Traceback
 from orionis.console.contracts.console import IConsole
 from orionis.console.enums.styles import ANSIColors
 
@@ -511,9 +518,6 @@ class Console(IConsole):
         -----
         This method prints the exception type, message, and a detailed stack trace.
         """
-        from rich.console import Console as RichConsole
-        from rich.traceback import Traceback
-
         rc = RichConsole()
         tb = Traceback.from_exception(type(e), e, e.__traceback__, max_frames=1)
         rc.print(tb)
@@ -548,4 +552,132 @@ class Console(IConsole):
         try:
             sys.exit(0)
         except SystemExit:
-            os._exit(0)
+            os._exit(0)
+
+    def dump(
+        self,
+        *args,
+        show_types: bool = True,
+        show_index: bool = False,
+        expand_all: bool = True,
+        max_depth: int | None = None,
+        module_path: str | None = None,
+        line_number: int | None = None,
+        force_exit: bool = False,
+        redirect_output: bool = False,
+        insert_line: bool = False
+    ) -> Optional[str]:
+        """
+        Displays formatted debug information for one or more variables using Rich, and optionally exports the output as HTML.
+
+        Parameters
+        ----------
+        *args : Any
+            One or more objects to be displayed for debugging.
+        show_types : bool, optional
+            If True, displays the type of each argument in the panel title. Default is True.
+        show_index : bool, optional
+            If True, shows an index number for each argument. Default is False.
+        expand_all : bool, optional
+            If True, expands all nested data structures. Default is True.
+        max_depth : int or None, optional
+            Maximum depth for nested structures. If None, no limit is applied. Default is None.
+        module_path : str or None, optional
+            Overrides the module path shown in the header. If None, uses the caller's module path.
+        line_number : int or None, optional
+            Overrides the line number shown in the header. If None, uses the caller's line number.
+        force_exit : bool, optional
+            If True, terminates the program after dumping. Default is False.
+        redirect_output : bool, optional
+            If True, temporarily restores stdout/stderr to their original streams during output. Default is False.
+        insert_line : bool, optional
+            If True, inserts a blank line before and after the dump output for better readability. Default
+
+        Returns
+        -------
+        Optional[str]
+            An HTML string containing the formatted output if successful, or None if caller information is unavailable.
+
+        Notes
+        -----
+        This method uses the Rich library to display variables in a visually enhanced format, including type and index information if specified. It can also export the output as HTML for further use.
+        """
+
+        # Optionally redirect output to original stdout/stderr
+        if redirect_output:
+            original_stdout, original_stderr = sys.stdout, sys.stderr
+            sys.stdout, sys.stderr = sys.__stdout__, sys.__stderr__
+
+        try:
+
+            # Optionally insert a blank line before the dump output
+            if insert_line:
+                print()
+
+            # Create a custom Rich theme for styling the dump output
+            custom_theme = Theme({
+                "dump.index": "bold bright_blue",
+                "dump.type": "bold green",
+                "dump.rule": "bright_black",
+            })
+            console = RichConsole(theme=custom_theme, record=True)
+            width = console.size.width
+
+            # Retrieve caller frame information for header display
+            frame = inspect.currentframe()
+            if not frame or not frame.f_back:
+                return None
+            caller = inspect.getframeinfo(frame.f_back)
+            file_name = os.path.relpath(caller.filename, os.getcwd())
+            line = line_number or caller.lineno
+            module = module_path or os.path.splitext(file_name)[0].replace(os.sep, ".")
+
+            # Print header with module and line information
+            header = f"🐞 [white]Module([/white][bold blue]{module}[/bold blue][white]) [/white][grey70]#{line}[/grey70]"
+            console.print(header)
+
+            # Iterate over each argument and display it in a styled panel
+            for i, arg in enumerate(args):
+                var_title = ""
+                if show_index:
+                    var_title += f"[dump.index]#{i+1}[/dump.index] "
+                if show_types:
+                    var_title += f"[dump.type]{type(arg).__name__}[/dump.type]"
+
+                panel = Panel(
+                    Pretty(
+                        arg,
+                        indent_size=2,
+                        indent_guides=True,
+                        expand_all=expand_all,
+                        max_depth=max_depth,
+                        margin=1,
+                        insert_line=False,
+                    ),
+                    title=var_title if var_title else None,
+                    title_align="left" if var_title else None,
+                    border_style="dump.rule",
+                    width=min(int(width * 0.85), 120),
+                    padding=(0, 1),
+                )
+                console.print(panel)
+
+            # Optionally insert a blank line before the dump output
+            if insert_line:
+                print()
+
+            # Optionally terminate the program after dumping
+            if force_exit:
+                if redirect_output:
+                    os._exit(1)
+                else:
+                    sys.exit(1)
+
+            # Export the output as HTML and return it
+            return console.export_html(inline_styles=True)
+
+        finally:
+
+            # Restore stdout/stderr if they were redirected
+            if redirect_output:
+                sys.stdout, sys.stderr = original_stdout, original_stderr

orionis-0.645.0/orionis/foundation/providers/dumper_provider.py

@@ -0,0 +1,29 @@
+from orionis.console.debug.dumper import Dumper
+from orionis.console.contracts.dumper import IDumper
+from orionis.container.providers.service_provider import ServiceProvider
+
+class DumperProvider(ServiceProvider):
+
+    def register(self) -> None:
+        """
+        Registers the Dumper service in the application container.
+
+        This method binds the `IDumper` interface to its concrete implementation, the `Dumper` class,
+        within the application's dependency injection container. The service is registered as
+        transient, ensuring that a new instance is created each time it is requested. An alias is
+        also assigned to the service for convenient retrieval throughout the application.
+
+        This registration allows the application to resolve dependencies related to dumping,
+        debugging, and console diagnostics by referencing the interface or its alias.
+
+        Returns
+        -------
+        None
+            This method does not return any value. It modifies the application's service registry
+            by registering the Dumper service.
+        """
+
+        # Register the Dumper service as a transient binding for the IDumper interface.
+        # Each request for IDumper will result in a new Dumper instance.
+        # The alias allows for easy retrieval of the service elsewhere in the application.
+        self.app.transient(IDumper, Dumper, alias="x-orionis.console.contracts.dumper.IDumper")

{orionis-0.644.0 → orionis-0.645.0}/orionis/metadata/framework.py

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

{orionis-0.644.0 → orionis-0.645.0}/orionis/support/facades/dumper.pyi

@@ -1,4 +1,4 @@
-from orionis.console.contracts.debug import IDebug
+from orionis.console.contracts.dumper import IDebug
 
 class Dumper(IDebug):
     """

orionis-0.645.0/orionis/test/output/dumper.py

@@ -0,0 +1,171 @@
+import sys
+from orionis.console.output.console import Console
+from orionis.test.contracts.dumper import ITestDumper
+
+class TestDumper(ITestDumper):
+
+    def __isTestCaseClass(self, value) -> bool:
+        """
+        Check if the provided value is an instance of a recognized test case class.
+
+        Parameters
+        ----------
+        value : object
+            The object to check for test case class membership.
+
+        Returns
+        -------
+        bool
+            True if `value` is an instance of AsyncTestCase, SyncTestCase, unittest.TestCase,
+            or unittest.IsolatedAsyncioTestCase. False otherwise or if an import error occurs.
+        """
+
+        # If the value is None, it cannot be a test case instance.
+        if value is None:
+            return False
+
+        try:
+
+            # Attempt to import the test case base classes.
+            from orionis.test.cases.asynchronous import AsyncTestCase
+            from orionis.test.cases.synchronous import SyncTestCase
+            import unittest
+
+            # Check if the value is an instance of either Orionis or native unittest test case class.
+            return isinstance(
+                value,
+                (
+                    AsyncTestCase,
+                    SyncTestCase,
+                    unittest.TestCase,
+                    unittest.IsolatedAsyncioTestCase
+                )
+            )
+
+        except Exception:
+
+            # If imports fail or any other exception occurs, return False.
+            return False
+
+    def __valuesToDump(self, args: tuple) -> tuple:
+        """
+        Filter out test case instances from the provided arguments.
+
+        Parameters
+        ----------
+        args : tuple
+            A tuple of objects to be filtered.
+
+        Returns
+        -------
+        tuple
+            A new tuple containing only the objects that are not instances of recognized
+            test case classes.
+        """
+
+        values: tuple = tuple()
+        for arg in args:
+            if not self.__isTestCaseClass(arg):
+                values += (arg,)
+
+        return values
+
+    def __tracebackInfo(self) -> tuple[str | None, int | None]:
+        """
+        Retrieve the module name and line number of the caller.
+
+        This method inspects the call stack to obtain the module name and line number
+        from which it was called. This information is useful for debugging and logging
+        purposes, as it provides context about where a function was invoked.
+
+        Returns
+        -------
+        tuple of (str or None, int or None)
+            A tuple containing the module name as a string and the line number as an integer.
+            If the information cannot be determined due to an error, returns (None, None).
+        """
+
+        try:
+
+            # Get the caller's frame from the call stack (1 level up)
+            caller_frame = sys._getframe(2)
+
+            # Retrieve the module name from the caller's global variables
+            module = caller_frame.f_globals.get("__name__", None)
+
+            # Retrieve the line number from the caller's frame
+            line_number = caller_frame.f_lineno
+
+            # Return the module name and line number
+            return (module, line_number)
+
+        except Exception:
+
+            # If any error occurs while retrieving the frame, return (None, None)
+            return (None, None)
+
+    def dd(self, *args) -> None:
+        """
+        Output debugging information and halt further execution.
+
+        Captures the caller's file and line number for context. Temporarily redirects
+        standard output and error streams to ensure correct display. If the first argument
+        is a recognized test case instance, it is skipped in the output. Raises a custom
+        runtime error if dumping fails.
+
+        Parameters
+        ----------
+        *args : tuple
+            Objects to be dumped.
+
+        Returns
+        -------
+        None
+        """
+
+        # Retrieve the caller's module and line number for context
+        module, line = self.__tracebackInfo()
+
+        # Filter out test case instances from the arguments
+        Console().dump(
+            *self.__valuesToDump(args),
+            module_path=module,
+            line_number=line,
+            force_exit=True,        # Halt execution after dumping
+            redirect_output=True,   # Redirect stdout/stderr for proper display
+            insert_line=True
+        )
+
+    def dump(self, *args) -> None:
+        """
+        Output debugging information without halting execution.
+
+        This method captures the caller's module and line number to provide context for the output.
+        It filters out any recognized test case instances from the provided arguments to avoid dumping
+        unnecessary or sensitive test case objects. The method then delegates the actual output operation
+        to the internal console, ensuring that standard output and error streams are redirected for
+        correct display. Unlike `dd`, this method does not terminate the program after dumping.
+
+        Parameters
+        ----------
+        *args : tuple
+            Objects to be dumped. Test case instances are automatically filtered out.
+
+        Returns
+        -------
+        None
+            This method does not return any value. It performs output as a side effect.
+        """
+
+        # Retrieve the caller's module and line number for context
+        module, line = self.__tracebackInfo()
+
+        # Filter out test case instances from the arguments and output the rest
+        Console().dump(
+            *self.__valuesToDump(args),
+            module_path=module,
+            line_number=line,
+            force_exit=False,      # Do not halt execution after dumping
+            redirect_output=True,  # Redirect stdout/stderr for proper display
+            insert_line=True
+        )