orionis 0.644.0__tar.gz → 0.646.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: orionis
-Version: 0.644.0
+Version: 0.646.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.646.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.646.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.646.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.646.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,151 @@ 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
+            console = RichConsole(
+                theme=Theme({
+                    "dump.index": "bold bright_blue",
+                    "dump.type": "bold green",
+                    "dump.rule": "bright_black",
+                }),
+                record=True
+            )
+            width = console.size.width
+
+            # If no module_path or line_number provided, get from caller
+            if not module_path or not line_number:
+
+                # Use inspect to get the caller's frame information
+                caller_frame = inspect.currentframe()
+
+                # If the frame is available, navigate back to the caller's frame
+                if caller_frame is not None:
+
+                    # Go back two frames to get the caller of the dump method
+                    caller_frame = caller_frame.f_back.f_back
+
+                    # If caller_frame is still valid, extract module and line number
+                    if caller_frame is not None:
+
+                        # If module_path or line_number not provided, get from caller
+                        if not module_path:
+                            module_path = caller_frame.f_globals.get("__name__", "unknown")
+                        if not line_number:
+                            line_number = caller_frame.f_lineno
+                else:
+
+                    #fallback if frame info is unavailable
+                    module_path = "unknown"
+                    line_number = '?'
+
+            # Print header with module and line information
+            header = f"🐞 [white]Module([/white][bold blue]{module_path}[/bold blue][white]) [/white][grey70]#{line_number}[/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.646.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.646.0}/orionis/metadata/framework.py

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

{orionis-0.644.0 → orionis-0.646.0}/orionis/support/facades/dumper.py

@@ -14,9 +14,9 @@ class Dumper(Facade):
         Returns
         -------
         str
-            The string "x-orionis.console.contracts.debug.IDebug", which is the binding key
+            The string "x-orionis.console.contracts.dumper.IDumper", which is the binding key
             used to identify and resolve the dumper service from the service container.
         """
 
         # Return the unique binding key for the dumper service in the container
-        return "x-orionis.console.contracts.debug.IDebug"
+        return "x-orionis.console.contracts.dumper.IDumper"

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

@@ -1,6 +1,6 @@
-from orionis.console.contracts.debug import IDebug
+from orionis.console.contracts.dumper import IDumper
 
-class Dumper(IDebug):
+class Dumper(IDumper):
     """
     A facade class that implements the IDebug interface for debugging operations.