orionis 0.475.0__py3-none-any.whl → 0.476.0__py3-none-any.whl

orionis/console/contracts/reactor.py

@@ -1,57 +1,110 @@
 from abc import ABC, abstractmethod
-from typing import List, Optional
+from typing import Any, List, Optional
 
 class IReactor(ABC):
 
+    @abstractmethod
+    def info(self) -> List[dict]:
+        """
+        Retrieves a list of all registered commands with their metadata.
+
+        This method returns a list of dictionaries, each containing information about
+        a registered command, including its signature, description, and whether it has
+        timestamps enabled. This is useful for introspection and displaying available
+        commands to the user.
+
+        Returns
+        -------
+        List[dict]
+            A list of dictionaries representing the registered commands, where each dictionary
+            contains the command's signature, description, and timestamps status.
+        """
+        pass
+
     @abstractmethod
     def call(
         self,
         signature: str,
         args: Optional[List[str]] = None
-    ):
+    ) -> Optional[Any]:
         """
-        Executes a command by its signature with optional command-line arguments.
+        Executes a registered command synchronously by its signature, optionally passing command-line arguments.
 
-        This method retrieves a registered command by its signature, validates any provided
-        arguments against the command's argument parser, and executes the command's handle
-        method with the parsed arguments and application context.
+        This method retrieves a command from the internal registry using its unique signature,
+        validates and parses any provided arguments using the command's argument parser,
+        and then executes the command's `handle` method synchronously. It manages execution timing,
+        logging, and error handling, and returns any output produced by the command.
 
         Parameters
         ----------
         signature : str
             The unique signature identifier of the command to execute.
         args : Optional[List[str]], default None
-            Command-line arguments to pass to the command. If None, no arguments are provided.
+            List of command-line arguments to pass to the command. If None, no arguments are provided.
 
         Returns
         -------
-        None
-            This method does not return any value. The command's handle method is called
-            directly for execution.
+        Optional[Any]
+            The output produced by the command's `handle` method if execution is successful.
+            Returns None if the command does not produce a result or if an error occurs.
 
         Raises
         ------
-        ValueError
+        CLIOrionisValueError
             If the command with the specified signature is not found in the registry.
         SystemExit
-            If argument parsing fails due to invalid arguments provided.
+            If argument parsing fails due to invalid arguments provided (raised by argparse).
+        Exception
+            Propagates any exception raised during command execution after logging and error output.
+
+        Notes
+        -----
+        - Logs execution start, completion, and errors with timestamps if enabled.
+        - Handles argument parsing and injects parsed arguments into the command instance.
+        - All exceptions are logged and displayed in the console.
         """
         pass
 
     @abstractmethod
-    def info(self) -> List[dict]:
+    async def callAsync(
+        self,
+        signature: str,
+        args: Optional[List[str]] = None
+    ) -> Optional[Any]:
         """
-        Retrieves a list of all registered commands with their metadata.
+        Executes a registered command asynchronously by its signature, optionally passing command-line arguments.
 
-        This method returns a list of dictionaries, each containing information about
-        a registered command, including its signature, description, and whether it has
-        timestamps enabled. This is useful for introspection and displaying available
-        commands to the user.
+        This method locates a command in the internal registry using its unique signature,
+        validates and parses any provided arguments using the command's argument parser,
+        and then executes the command's `handle` method asynchronously. It manages execution timing,
+        logging, and error handling, and returns any output produced by the command.
+
+        Parameters
+        ----------
+        signature : str
+            The unique signature identifier of the command to execute.
+        args : Optional[List[str]], default None
+            List of command-line arguments to pass to the command. If None, no arguments are provided.
 
         Returns
         -------
-        List[dict]
-            A list of dictionaries representing the registered commands, where each dictionary
-            contains the command's signature, description, and timestamps status.
+        Optional[Any]
+            The output produced by the command's `handle` method if execution is successful.
+            Returns None if the command does not produce a result or if an error occurs.
+
+        Raises
+        ------
+        CLIOrionisValueError
+            If the command with the specified signature is not found in the registry.
+        SystemExit
+            If argument parsing fails due to invalid arguments provided (raised by argparse).
+        Exception
+            Propagates any exception raised during command execution after logging and error output.
+
+        Notes
+        -----
+        - Logs execution start, completion, and errors with timestamps if enabled.
+        - Handles argument parsing and injects parsed arguments into the command instance.
+        - All exceptions are logged and displayed in the console.
         """
         pass

orionis/console/core/reactor.py

@@ -1,19 +1,21 @@
 import argparse
 import os
 import re
-import time
 from pathlib import Path
-from typing import List, Optional
+from typing import Any, List, Optional
 from orionis.app import Orionis
 from orionis.console.args.argument import CLIArgument
 from orionis.console.base.command import BaseCommand
 from orionis.console.base.contracts.command import IBaseCommand
 from orionis.console.contracts.reactor import IReactor
+from orionis.console.enums.command import Command
+from orionis.console.exceptions import CLIOrionisValueError
 from orionis.console.output.contracts.console import IConsole
 from orionis.console.output.contracts.executor import IExecutor
 from orionis.foundation.contracts.application import IApplication
 from orionis.services.introspection.modules.reflection import ReflectionModule
 from orionis.services.log.contracts.log_service import ILogger
+from orionis.support.performance.contracts.counter import IPerformanceCounter
 
 class Reactor(IReactor):
 
@@ -60,7 +62,7 @@ class Reactor(IReactor):
         self.__root: str = str(Path.cwd())
 
         # Initialize the internal command registry as an empty dictionary
-        self.__commands: dict = {}
+        self.__commands: dict[str, Command] = {}
 
         # Automatically discover and load command classes from the console commands directory
         self.__loadCommands(str(self.__app.path('console_commands')), self.__root)
@@ -77,6 +79,9 @@ class Reactor(IReactor):
         # Initialize the logger service for logging command execution details
         self.__logger: ILogger = self.__app.make('x-orionis.services.log.log_service')
 
+        # Initialize the performance counter for measuring command execution time
+        self.__performance_counter: IPerformanceCounter = self.__app.make('x-orionis.support.performance.counter')
+
     def __loadCoreCommands(self) -> None:
         """
         Loads and registers core command classes provided by the Orionis framework.
@@ -127,13 +132,13 @@ class Reactor(IReactor):
             args = self.__ensureArguments(obj)
 
             # Register the command in the internal registry with all its metadata
-            self.__commands[signature] = {
-                "class": obj,
-                "timestamps": timestamp,
-                "signature": signature,
-                "description": description,
-                "args": args
-            }
+            self.__commands[signature] = Command(
+                obj=obj,
+                timestamps=timestamp,
+                signature=signature,
+                description=description,
+                args=args
+            )
 
     def __loadCommands(self, commands_path: str, root_path: str) -> None:
         """
@@ -208,13 +213,13 @@ class Reactor(IReactor):
                             args = self.__ensureArguments(obj)
 
                             # Add the command to the internal registry
-                            self.__commands[signature] = {
-                                "class": obj,
-                                "timestamps": timestamp,
-                                "signature": signature,
-                                "description": description,
-                                "args": args
-                            }
+                            self.__commands[signature] = Command(
+                                obj=obj,
+                                timestamps=timestamp,
+                                signature=signature,
+                                description=description,
+                                args=args
+                            )
 
     def __ensureTimestamps(self, obj: IBaseCommand) -> bool:
         """
@@ -403,6 +408,61 @@ class Reactor(IReactor):
         # Return the configured ArgumentParser
         return arg_parser
 
+    def __parseArgs(
+        self,
+        command: Command,
+        args: Optional[List[str]] = None
+    ) -> dict:
+        """
+        Parses command-line arguments for a given command using its internal ArgumentParser.
+
+        This method takes a command object and an optional list of command-line arguments,
+        and parses them into a dictionary of argument names and values. If the command
+        defines an ArgumentParser (i.e., expects arguments), the arguments are parsed
+        accordingly. If no arguments are expected or provided, an empty dictionary is returned.
+
+        Parameters
+        ----------
+        command : Command
+            The command object containing the argument parser and metadata.
+        args : Optional[List[str]], default None
+            A list of command-line arguments to parse. If None, an empty list is used.
+
+        Returns
+        -------
+        dict
+            A dictionary containing the parsed argument names and their corresponding values.
+            Returns an empty dictionary if no arguments are expected or provided.
+
+        Raises
+        ------
+        SystemExit
+            Raised by argparse if argument parsing fails or if help is requested.
+        """
+
+        # Initialize parsed_args to None
+        parsed_args = None
+
+        # If the command expects arguments, parse them using its ArgumentParser
+        if command.args is not None and isinstance(command.args, argparse.ArgumentParser):
+            if args is None:
+                args = []
+            try:
+                # Parse the provided arguments using the command's ArgumentParser
+                parsed_args = command.args.parse_args(args)
+            except SystemExit:
+                # Allow argparse to handle help/error messages and exit
+                raise
+
+        # Convert the parsed arguments to a dictionary and return
+        if isinstance(parsed_args, argparse.Namespace):
+            return vars(parsed_args)
+        elif isinstance(parsed_args, dict):
+            return parsed_args
+        else:
+            # Return an empty dictionary if no arguments were parsed
+            return {}
+
     def info(self) -> List[dict]:
         """
         Retrieves a list of all registered commands with their metadata.
@@ -426,8 +486,8 @@ class Reactor(IReactor):
         for command in self.__commands.values():
 
             # Extract command metadata
-            signature:str = command.get("signature")
-            description:str = command.get("description", "")
+            signature:str = command.signature
+            description:str = command.description
 
             # Skip internal commands (those with double underscores)
             if signature.startswith('__') and signature.endswith('__'):
@@ -446,103 +506,179 @@ class Reactor(IReactor):
         self,
         signature: str,
         args: Optional[List[str]] = None
-    ):
+    ) -> Optional[Any]:
         """
-        Executes a command by its signature with optional command-line arguments.
+        Executes a registered command synchronously by its signature, optionally passing command-line arguments.
 
-        This method retrieves a registered command by its signature, validates any provided
-        arguments against the command's argument parser, and executes the command's handle
-        method with the parsed arguments and application context.
+        This method retrieves a command from the internal registry using its unique signature,
+        validates and parses any provided arguments using the command's argument parser,
+        and then executes the command's `handle` method synchronously. It manages execution timing,
+        logging, and error handling, and returns any output produced by the command.
 
         Parameters
         ----------
         signature : str
             The unique signature identifier of the command to execute.
         args : Optional[List[str]], default None
-            Command-line arguments to pass to the command. If None, no arguments are provided.
+            List of command-line arguments to pass to the command. If None, no arguments are provided.
 
         Returns
         -------
-        None
-            This method does not return any value. The command's handle method is called
-            directly for execution.
+        Optional[Any]
+            The output produced by the command's `handle` method if execution is successful.
+            Returns None if the command does not produce a result or if an error occurs.
 
         Raises
         ------
-        ValueError
+        CLIOrionisValueError
             If the command with the specified signature is not found in the registry.
         SystemExit
-            If argument parsing fails due to invalid arguments provided.
+            If argument parsing fails due to invalid arguments provided (raised by argparse).
+        Exception
+            Propagates any exception raised during command execution after logging and error output.
+
+        Notes
+        -----
+        - Logs execution start, completion, and errors with timestamps if enabled.
+        - Handles argument parsing and injects parsed arguments into the command instance.
+        - All exceptions are logged and displayed in the console.
         """
 
-        # Retrieve the command from the registry
-        command: dict = self.__commands.get(signature)
+        # Retrieve the command from the registry by its signature
+        command: Command = self.__commands.get(signature)
         if command is None:
-            raise ValueError(f"Command '{signature}' not found.")
+            raise CLIOrionisValueError(f"Command '{signature}' not found.")
 
-        # Start execution timer
-        start_time = time.perf_counter()
+        # Start execution timer for performance measurement
+        self.__performance_counter.start()
 
-        # Get command details
-        command_class = command.get("class")
-        arg_parser: Optional[argparse.ArgumentParser] = command.get("args")
-        timestamps: bool = command.get("timestamps")
+        # Log the command execution start with RUNNING state if timestamps are enabled
+        if command.timestamps:
+            self.__executer.running(program=signature)
 
-        # Initialize parsed arguments
-        parsed_args = None
+        try:
+            # Instantiate the command class using the application container
+            command_instance: IBaseCommand = self.__app.make(command.obj)
 
-        # If the command has arguments and args were provided, validate them
-        if arg_parser is not None and isinstance(arg_parser, argparse.ArgumentParser):
-            if args is None:
-                args = []
-            try:
-                # Parse the provided arguments using the command's ArgumentParser
-                parsed_args = arg_parser.parse_args(args)
-            except SystemExit:
-                # Re-raise SystemExit to allow argparse to handle help/error messages
-                raise
+            # Inject parsed arguments into the command instance
+            command_instance._args = self.__parseArgs(command, args)
 
-        # Log the command execution start with RUNNING state
-        if timestamps:
+            # Execute the command's handle method and capture its output
+            output = self.__app.call(command_instance, 'handle')
+
+            # Calculate elapsed time and log completion with DONE state if command.timestamps are enabled
+            elapsed_time = round(self.__performance_counter.stop(), 2)
+            if command.timestamps:
+                self.__executer.done(program=signature, time=f"{elapsed_time}s")
+
+            # Log successful execution in the logger service
+            self.__logger.info(f"Command '{signature}' executed successfully in ({elapsed_time}) seconds.")
+
+            # Return the output produced by the command, if any
+            return output
+
+        except Exception as e:
+            # Display the error message in the console (without timestamp)
+            self.__console.error(f"An error occurred while executing command '{signature}': {e}", timestamp=False)
+
+            # Log the error in the logger service
+            self.__logger.error(f"Command '{signature}' execution failed: {e}")
+
+            # Calculate elapsed time and log failure with ERROR state if command.timestamps are enabled
+            elapsed_time = round(self.__performance_counter.stop(), 2)
+            if command.timestamps:
+                self.__executer.fail(program=signature, time=f"{elapsed_time}s")
+
+            # Propagate the exception after logging
+            raise
+
+    async def callAsync(
+        self,
+        signature: str,
+        args: Optional[List[str]] = None
+    ) -> Optional[Any]:
+        """
+        Executes a registered command asynchronously by its signature, optionally passing command-line arguments.
+
+        This method locates a command in the internal registry using its unique signature,
+        validates and parses any provided arguments using the command's argument parser,
+        and then executes the command's `handle` method asynchronously. It manages execution timing,
+        logging, and error handling, and returns any output produced by the command.
+
+        Parameters
+        ----------
+        signature : str
+            The unique signature identifier of the command to execute.
+        args : Optional[List[str]], default None
+            List of command-line arguments to pass to the command. If None, no arguments are provided.
+
+        Returns
+        -------
+        Optional[Any]
+            The output produced by the command's `handle` method if execution is successful.
+            Returns None if the command does not produce a result or if an error occurs.
+
+        Raises
+        ------
+        CLIOrionisValueError
+            If the command with the specified signature is not found in the registry.
+        SystemExit
+            If argument parsing fails due to invalid arguments provided (raised by argparse).
+        Exception
+            Propagates any exception raised during command execution after logging and error output.
+
+        Notes
+        -----
+        - Logs execution start, completion, and errors with timestamps if enabled.
+        - Handles argument parsing and injects parsed arguments into the command instance.
+        - All exceptions are logged and displayed in the console.
+        """
+
+        # Retrieve the command from the registry by its signature
+        command: Command = self.__commands.get(signature)
+        if command is None:
+            raise CLIOrionisValueError(f"Command '{signature}' not found.")
+
+        # Start execution timer for performance measurement
+        self.__performance_counter.start()
+
+        # Log the command execution start with RUNNING state if timestamps are enabled
+        if command.timestamps:
             self.__executer.running(program=signature)
 
         try:
+            # Instantiate the command class using the application container
+            command_instance: IBaseCommand = self.__app.make(command.obj)
 
-            # Create an instance of the command class and execute it
-            command_instance: IBaseCommand = self.__app.make(command_class)
+            # Inject parsed arguments into the command instance
+            command_instance._args = self.__parseArgs(command, args)
 
-            # If arguments were parsed, set them on the command instance
-            if isinstance(parsed_args, argparse.Namespace):
-                command_instance._args = vars(parsed_args)
-            elif isinstance(parsed_args, dict):
-                command_instance._args = parsed_args
-            else:
-                command_instance._args = {}
+            # Execute the command's handle method asynchronously and capture its output
+            output = await self.__app.callAsync(command_instance, 'handle')
 
-            # Call the handle method of the command instance
-            output = self.__app.call(command_instance, 'handle')
-
-            # Log the command execution completion with DONE state
-            elapsed_time = round(time.perf_counter() - start_time, 2)
-            if timestamps:
+            # Calculate elapsed time and log completion with DONE state if command.timestamps are enabled
+            elapsed_time = round(self.__performance_counter.stop(), 2)
+            if command.timestamps:
                 self.__executer.done(program=signature, time=f"{elapsed_time}s")
 
-            # Log the command execution success
+            # Log successful execution in the logger service
             self.__logger.info(f"Command '{signature}' executed successfully in ({elapsed_time}) seconds.")
 
-            # If the command has a return value or output, return it
-            if output is not None:
-                return output
+            # Return the output produced by the command, if any
+            return output
 
         except Exception as e:
 
-            # Display the error message in the console
+            # Display the error message in the console (without timestamp)
             self.__console.error(f"An error occurred while executing command '{signature}': {e}", timestamp=False)
 
             # Log the error in the logger service
             self.__logger.error(f"Command '{signature}' execution failed: {e}")
 
-            # Log the command execution failure with ERROR state
-            elapsed_time = round(time.perf_counter() - start_time, 2)
-            if timestamps:
-                self.__executer.fail(program=signature, time=f"{elapsed_time}s")
+            # Calculate elapsed time and log failure with ERROR state if command.timestamps are enabled
+            elapsed_time = round(self.__performance_counter.stop(), 2)
+            if command.timestamps:
+                self.__executer.fail(program=signature, time=f"{elapsed_time}s")
+
+            # Propagate the exception after logging
+            raise

orionis/console/enums/command.py

@@ -0,0 +1,43 @@
+import argparse
+from dataclasses import dataclass
+from typing import Type, Optional
+from orionis.support.entities.base import BaseEntity
+
+@dataclass(kw_only=True)
+class Command(BaseEntity):
+    """
+    Represents a console command and its associated metadata.
+
+    Parameters
+    ----------
+    obj : Type
+        The type or class associated with the command.
+    timestamps : bool
+        Whether timestamps are enabled for this command.
+    signature : str
+        The signature string representing the command usage.
+    description : str
+        A brief description of what the command does.
+    args : Optional[argparse.ArgumentParser], optional
+        Optional argument parser for command-line arguments.
+
+    Returns
+    -------
+    Command
+        An instance of the Command class containing metadata and configuration for a console command.
+    """
+
+    # The type or class associated with the command
+    obj: Type
+
+    # Indicates if timestamps are enabled for this command
+    timestamps: bool
+
+    # The command usage signature
+    signature: str
+
+    # Description of the command's purpose
+    description: str
+
+    # Optional argument parser for command-line arguments
+    args: Optional[argparse.ArgumentParser] = None

orionis/console/enums/task.py

@@ -0,0 +1,42 @@
+from dataclasses import dataclass
+from typing import List, Optional
+from orionis.support.entities.base import BaseEntity
+
+@dataclass(kw_only=True)
+class Task(BaseEntity):
+    """
+    Represents a task entity containing metadata for execution and description.
+
+    Parameters
+    ----------
+    signature : str
+        The unique identifier or signature of the task.
+    args : Optional[List[str]], optional
+        List of arguments required by the task, by default None.
+    purpose : str, optional
+        Brief description of the task's purpose, by default None.
+    trigger : str, optional
+        Event or condition that triggers the task, by default None.
+    details : str, optional
+        Additional details or information about the task, by default None.
+
+    Returns
+    -------
+    Task
+        An instance of the Task class with the specified metadata.
+    """
+
+    # Unique identifier for the task
+    signature: str
+
+    # List of arguments required by the task (optional)
+    args: Optional[List[str]] = None
+
+    # Brief description of the task's purpose (optional)
+    purpose: str = None
+
+    # Event or condition that triggers the task (optional)
+    trigger: str = None
+
+    # Additional details or information about the task (optional)
+    details: str = None

orionis/console/tasks/schedule.py

@@ -9,7 +9,9 @@ from apscheduler.triggers.date import DateTrigger
 from apscheduler.triggers.interval import IntervalTrigger
 from orionis.app import Orionis
 from orionis.console.contracts.reactor import IReactor
+from orionis.console.enums.task import Task
 from orionis.console.exceptions import CLIOrionisRuntimeError
+from orionis.console.exceptions.cli_orionis_value_error import CLIOrionisValueError
 from orionis.services.log.contracts.log_service import ILogger
 
 class Scheduler():
@@ -316,14 +318,13 @@ class Scheduler():
                 )
 
             # Register the job details internally.
-            self.__jobs[self.__command] = {
-                'signature': self.__command,
-                'args': self.__args,
-                'purpose': self.__purpose,
-                'trigger': 'once_at',
-                'start_at': date.strftime('%Y-%m-%d %H:%M:%S'),
-                'end_at': date.strftime('%Y-%m-%d %H:%M:%S')
-            }
+            self.__jobs[self.__command] = Task(
+                signature=self.__command,
+                args=self.__args,
+                purpose=self.__purpose,
+                trigger='once_at',
+                details=f"Date: {date.strftime('%Y-%m-%d %H:%M:%S')}, Timezone: {str(date.tzinfo) if date.tzinfo else 'UTC'}"
+            )
 
             # Add the job to the scheduler.
             self.__scheduler.add_job(
@@ -359,6 +360,74 @@ class Scheduler():
             # Wrap and raise any other exceptions as CLIOrionisRuntimeError.
             raise CLIOrionisRuntimeError(f"Error scheduling the job: {str(e)}")
 
+    def everySeconds(
+        self,
+        seconds: int
+    ) -> 'Scheduler':
+        """
+        Schedule a command to run at regular intervals in seconds.
+
+        This method sets the interval for the currently registered command to execute
+        every specified number of seconds. The job is registered internally and added
+        to the scheduler instance.
+
+        Parameters
+        ----------
+        seconds : int
+            The interval in seconds at which the command should be executed. Must be a positive integer.
+
+        Returns
+        -------
+        Scheduler
+            Returns the current instance of the Scheduler to allow method chaining.
+
+        Raises
+        ------
+        ValueError
+            If the provided seconds is not a positive integer.
+        """
+
+        try:
+
+            # Validate that the seconds parameter is a positive integer.
+            if not isinstance(seconds, int) or seconds <= 0:
+                raise CLIOrionisValueError("The interval must be a positive integer.")
+
+            # Store the interval in the jobs dictionary.
+            self.__jobs[self.__command] = Task(
+                signature=self.__command,
+                args=self.__args,
+                purpose=self.__purpose,
+                trigger='every_seconds',
+                details=f"Interval: {seconds} seconds"
+            )
+
+            # Add the job to the scheduler with an interval trigger.
+            self.__scheduler.add_job(
+                func=lambda command=self.__command, args=list(self.__args): self.__reactor.call(
+                    command,
+                    args
+                ),
+                trigger=IntervalTrigger(
+                    seconds=seconds
+                ),
+                id=self.__command,
+                name=self.__command,
+                replace_existing=True
+            )
+
+            # Return self to support method chaining.
+            return self
+
+        except Exception as e:
+
+            # Reraise known CLIOrionisValueError exceptions.
+            if isinstance(e, CLIOrionisValueError):
+                raise e
+
+            # Wrap and raise any other exceptions as CLIOrionisRuntimeError.
+            raise CLIOrionisRuntimeError(f"Error scheduling the job: {str(e)}")
+
     async def start(self) -> None:
         """
         Start the AsyncIO scheduler instance and keep it running.

orionis/container/contracts/container.py

@@ -419,4 +419,33 @@ class IContainer(ABC):
         Any
             The result of the method call.
         """
-        pass
+        pass
+
+    @abstractmethod
+    async def callAsync(
+        self,
+        instance: Any,
+        method_name: str,
+        *args,
+        **kwargs
+    ) -> Any:
+        """
+        Async version of call for when you're in an async context and need to await the result.
+
+        Parameters
+        ----------
+        instance : Any
+            The instance on which to call the method.
+        method_name : str
+            The name of the method to call.
+        *args : tuple
+            Positional arguments to pass to the method.
+        **kwargs : dict
+            Keyword arguments to pass to the method.
+
+        Returns
+        -------
+        Any
+            The result of the method call, properly awaited if async.
+        """
+        pass

orionis/foundation/application.py

@@ -180,6 +180,7 @@ class Application(Container, IApplication):
         from orionis.foundation.providers.inspirational_provider import InspirationalProvider
         from orionis.foundation.providers.executor_provider import ConsoleExecuteProvider
         from orionis.foundation.providers.reactor_provider import ReactorProvider
+        from orionis.foundation.providers.performance_counter_provider import PerformanceCounterProvider
 
         # Core framework providers
         core_providers = [
@@ -191,7 +192,8 @@ class Application(Container, IApplication):
             TestingProvider,
             InspirationalProvider,
             ConsoleExecuteProvider,
-            ReactorProvider
+            ReactorProvider,
+            PerformanceCounterProvider
         ]
 
         # Register each core provider

orionis/foundation/providers/performance_counter_provider.py

@@ -0,0 +1,64 @@
+from orionis.container.providers.service_provider import ServiceProvider
+from orionis.support.performance.contracts.counter import IPerformanceCounter
+from orionis.support.performance.counter import PerformanceCounter
+
+class PerformanceCounterProvider(ServiceProvider):
+
+    def register(self) -> None:
+        """
+        Registers the performance counter service as a transient dependency in the application container.
+
+        This method binds the `IPerformanceCounter` interface contract to the `PerformanceCounter`
+        concrete implementation within the application's dependency injection container. The binding
+        is configured with a transient lifetime, ensuring that each resolution of the service yields
+        a new instance of `PerformanceCounter`. This approach is suitable for scenarios requiring
+        independent timing or measurement operations across different parts of the application.
+
+        Additionally, an alias `"x-orionis.support.performance.counter"` is assigned to this binding,
+        allowing for alternative resolution or referencing of the service.
+
+        Parameters
+        ----------
+        None
+
+        Returns
+        -------
+        None
+            This method performs service registration as a side effect and does not return any value.
+
+        Notes
+        -----
+        - The transient lifetime ensures isolation between different consumers of the service.
+        - The alias facilitates flexible service resolution by name.
+        """
+
+        # Register the IPerformanceCounter interface to the PerformanceCounter implementation
+        # with a transient lifetime and assign an alias for alternative resolution.
+        self.app.transient(IPerformanceCounter, PerformanceCounter, alias="x-orionis.support.performance.counter")
+
+    def boot(self) -> None:
+        """
+        Performs initialization and configuration tasks for the performance counter provider during the application's bootstrapping phase.
+
+        This method is automatically invoked when the provider is loaded by the application. It is intended for setting up or registering
+        any performance counters or related resources required by the application. By default, this implementation does not perform any
+        actions, but it can be extended in subclasses to include custom initialization logic as needed.
+
+        Parameters
+        ----------
+        None
+
+        Returns
+        -------
+        None
+            This method does not return any value. It executes initialization logic as a side effect.
+
+        Notes
+        -----
+        - Override this method in subclasses to implement custom bootstrapping behavior for performance counters.
+        - This method is part of the provider lifecycle and is called after service registration.
+        """
+
+        # No initialization logic is required by default.
+        # Override this method in subclasses to perform custom setup.
+        pass

orionis/metadata/framework.py

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

orionis/support/performance/contracts/counter.py

@@ -0,0 +1,40 @@
+from abc import ABC, abstractmethod
+
+class IPerformanceCounter(ABC):
+    """
+    A class for measuring the elapsed time between two points in code execution.
+
+    This class provides methods to start and stop a high-resolution performance counter,
+    allowing users to measure the duration of specific code segments with precision.
+    """
+
+    @abstractmethod
+    def start(self) -> float:
+        """
+        Start the performance counter.
+
+        Records the current high-resolution time as the start time using
+        `time.perf_counter()`. This marks the beginning of the interval to be measured.
+
+        Returns
+        -------
+        float
+            The timestamp (in fractional seconds) at which the counter was started.
+        """
+        pass
+
+    @abstractmethod
+    def stop(self) -> float:
+        """
+        Stop the performance counter and calculate the elapsed time.
+
+        Records the current high-resolution time as the end time and computes
+        the elapsed time since `start()` was called. The elapsed time is the
+        difference between the end and start timestamps.
+
+        Returns
+        -------
+        float
+            The elapsed time in seconds (as a float) between when `start()` and `stop()` were called.
+        """
+        pass

orionis/support/performance/counter.py

@@ -0,0 +1,87 @@
+import time
+from orionis.support.performance.contracts.counter import IPerformanceCounter
+
+class PerformanceCounter(IPerformanceCounter):
+    """
+    A class for measuring the elapsed time between two points in code execution.
+
+    This class provides methods to start and stop a high-resolution performance counter,
+    allowing users to measure the duration of specific code segments with precision.
+
+    Attributes
+    ----------
+    __start_time : float or None
+        The timestamp when the counter was started.
+    __end_time : float or None
+        The timestamp when the counter was stopped.
+
+    Methods
+    -------
+    start()
+        Starts the performance counter.
+    stop()
+        Stops the performance counter and returns the elapsed time.
+
+    Notes
+    -----
+    The counter uses `time.perf_counter()` for high-resolution timing.
+    """
+
+    def __init__(self):
+        """
+        Initialize a new PerformanceCounter instance.
+
+        This constructor sets the internal start and end time attributes to None,
+        preparing the counter for use. The counter can then be started and stopped
+        to measure elapsed time between two points in code execution.
+
+        Attributes
+        ----------
+        __start_time : float or None
+            The timestamp when the counter is started, or None if not started.
+        __end_time : float or None
+            The timestamp when the counter is stopped, or None if not stopped.
+        """
+
+        # Time when the counter is started; initialized to None
+        self.__start_time = None
+
+        # Time when the counter is stopped; initialized to None
+        self.__end_time = None
+
+    def start(self) -> float:
+        """
+        Start the performance counter.
+
+        Records the current high-resolution time as the start time using
+        `time.perf_counter()`. This marks the beginning of the interval to be measured.
+
+        Returns
+        -------
+        float
+            The timestamp (in fractional seconds) at which the counter was started.
+        """
+
+        # Record the current time as the start time
+        self.__start_time = time.perf_counter()
+        return self.__start_time
+
+    def stop(self) -> float:
+        """
+        Stop the performance counter and calculate the elapsed time.
+
+        Records the current high-resolution time as the end time and computes
+        the elapsed time since `start()` was called. The elapsed time is the
+        difference between the end and start timestamps.
+
+        Returns
+        -------
+        float
+            The elapsed time in seconds (as a float) between when `start()` and `stop()` were called.
+        """
+
+        # Record the current time as the end time
+        self.__end_time = time.perf_counter()
+
+        # Calculate and return the elapsed time
+        return self.__end_time - self.__start_time

{orionis-0.475.0.dist-info → orionis-0.476.0.dist-info}/METADATA

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

{orionis-0.475.0.dist-info → orionis-0.476.0.dist-info}/RECORD

@@ -19,10 +19,10 @@ orionis/console/commands/version.py,sha256=SUuNDJ40f2uq69OQUmPQXJKaa9Bm_iVRDPmBd
 orionis/console/commands/workflow.py,sha256=NYOmjTSvm2o6AE4h9LSTZMFSYPQreNmEJtronyOxaYk,2451
 orionis/console/contracts/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 orionis/console/contracts/kernel.py,sha256=mh4LlhEYHh3FuGZZQ0GBhD6ZLa5YQvaNj2r01IIHI5Y,826
-orionis/console/contracts/reactor.py,sha256=GGhWSNYBE6E_W3HNEi4kjiDwqohsa-nnwJfoC1nJPM8,1998
+orionis/console/contracts/reactor.py,sha256=Xeq7Zrw6WE5MV_XOQfiQEchAFbb6-0TjLpjWOxYW--g,4554
 orionis/console/contracts/schedule.py,sha256=A7yYPjPmRizDHOR9k4qvY3NuRPrWBmNuQs6ENGXWtBs,70
 orionis/console/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-orionis/console/core/reactor.py,sha256=A0koFZaizrK9R1jlFbx9zdf9UZ4tBxSRJY04hcGzbsQ,23571
+orionis/console/core/reactor.py,sha256=Hd7T-jNG_tzhpJXRztjDSKCtm7-3LOh5lcQ__cIchMk,30172
 orionis/console/dumper/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 orionis/console/dumper/dump.py,sha256=CATERiQ6XuIrKQsDaWcVxzTtlAJI9qLJX44fQxEX8ws,22443
 orionis/console/dumper/contracts/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -31,6 +31,9 @@ orionis/console/dynamic/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG
 orionis/console/dynamic/progress_bar.py,sha256=iK1kAf9vJIgk6BbdlGvlJkGc1m7Ck4euNqQpg5aarW8,2880
 orionis/console/dynamic/contracts/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 orionis/console/dynamic/contracts/progress_bar.py,sha256=NYebL2h-vg2t2H6IhJjuC37gglRkpT-MW71wbJtpLNg,1784
+orionis/console/enums/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+orionis/console/enums/command.py,sha256=lCfVp2vnDojJN2gjdVxE_XU3mRjZZgOIxPfBVQYo9w4,1278
+orionis/console/enums/task.py,sha256=1oRR_VKfzsojCxxywYAMhpPvZQ8kSEEdXeXvCOfAXmg,1322
 orionis/console/exceptions/__init__.py,sha256=0qlHNuHMVZO87M-rP8lThUUyljRM1jSFNikaxSCjSbw,366
 orionis/console/exceptions/cli_exception.py,sha256=HsZ_vSeNiJWQ0gznVFNcIdhM0Bj_vkSRVBJs0wMjEKY,1141
 orionis/console/exceptions/cli_orionis_value_error.py,sha256=RQP0HRwxDG8hxFOT1kUoZ1Ab1CZ1KLoSIl5yqlmgG4M,1147
@@ -45,14 +48,14 @@ orionis/console/output/contracts/executor.py,sha256=7l3kwnvv6GlH9EYk0v94YE1olex_
 orionis/console/output/enums/__init__.py,sha256=LAaAxg-DpArCjf_jqZ0_9s3p8899gntDYkSU_ppTdC8,66
 orionis/console/output/enums/styles.py,sha256=6a4oQCOBOKMh2ARdeq5GlIskJ3wjiylYmh66tUKKmpQ,4053
 orionis/console/tasks/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-orionis/console/tasks/schedule.py,sha256=w3S4uZUg6i0EMze4P1B761pl57da2ZdWJFj_SEasarI,18939
+orionis/console/tasks/schedule.py,sha256=DFso4ia8G3me2H1tOX366dXhucIKd-LRH8c-kfJ8fhA,21395
 orionis/container/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 orionis/container/container.py,sha256=p7kJ-hwnDattTWCArt0ypol4bW3M334hIZ2FAQhID-w,87570
 orionis/container/context/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 orionis/container/context/manager.py,sha256=I08K_jKXSKmrq18Pv33qYyMKIlAovVOwIgmfiVm-J7c,2971
 orionis/container/context/scope.py,sha256=p_oCzR7dDz-5ZAd16ab4vfLc3gBf34CaN0f4iR9D0bQ,1155
 orionis/container/contracts/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-orionis/container/contracts/container.py,sha256=JUj5LuJBzSWCsv4tRNreUBXPGCMyK79ITx-RM_rKxTA,13442
+orionis/container/contracts/container.py,sha256=l-wVi6KMLL4I55JSHnNqykiaZSZO9ea6BDSzCKsysak,14217
 orionis/container/contracts/service_provider.py,sha256=TJtwFoPYvw3hvBSfIEO3-httq8iszaRQh1IjCKfDyVM,1016
 orionis/container/entities/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 orionis/container/entities/binding.py,sha256=sY0ioHbRcjp9TSQjfrFHxkO3vRn_VOrbHK62_QEGe1U,3717
@@ -78,7 +81,7 @@ orionis/container/validators/is_subclass.py,sha256=4sBaGLoRs8nUhuWjlP0VJqyTwVHYq
 orionis/container/validators/is_valid_alias.py,sha256=4uAYcq8xov7jZbXnpKpjNkxcZtlTNnL5RRctVPMwJes,1424
 orionis/container/validators/lifetime.py,sha256=IQ43fDNrxYHMlZH2zlYDJnlkLO_eS4U7Fs3UJgQBidI,1844
 orionis/foundation/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-orionis/foundation/application.py,sha256=yZ1C92A2bTtWK4RUd9RSACLVQVBPjd6zElTt6_kjV6k,77026
+orionis/foundation/application.py,sha256=fKKT4K_DBPEKTMZaeRfBpK_DsaWvEt_dVhA-yu1Wyfo,77173
 orionis/foundation/config/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 orionis/foundation/config/startup.py,sha256=vbzduprRCNyYeR2nnMaqc1uKXw6PTzAY2jVfXNQKN8I,9691
 orionis/foundation/config/app/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -185,12 +188,13 @@ orionis/foundation/providers/dumper_provider.py,sha256=nKHjLDClCo-KnPloh6EYVySjg
 orionis/foundation/providers/executor_provider.py,sha256=kwkH8YWEXoEoP51akJXQJ0U25rhlOLxnfE0s9fALr0I,3478
 orionis/foundation/providers/inspirational_provider.py,sha256=uq2o0uLd5p6PR99uH4cJAcc6NnU6nIOwe0ZIdzZcF4Q,3726
 orionis/foundation/providers/logger_provider.py,sha256=rs8UpaD_vSp3qNli0u9A4eRum3q3F0KEM0V6yhcl2GU,3417
+orionis/foundation/providers/performance_counter_provider.py,sha256=7y10Vaqx7GemGh2wCaww8XmdvFQXLXm9_E4GjpdNXcA,3010
 orionis/foundation/providers/progress_bar_provider.py,sha256=X4Ke7mPr0MgVp6WDNaQ3bI3Z_LOS8qE-wid0MQErKms,3367
 orionis/foundation/providers/reactor_provider.py,sha256=P0KQcp4AFKTrD6BStGfCTqhGUlpKgsrZTZZKSqyGJQg,3662
 orionis/foundation/providers/testing_provider.py,sha256=SrJRpdvcblx9WvX7x9Y3zc7OQfiTf7la0HAJrm2ESlE,3725
 orionis/foundation/providers/workers_provider.py,sha256=oa_2NIDH6UxZrtuGkkoo_zEoNIMGgJ46vg5CCgAm7wI,3926
 orionis/metadata/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-orionis/metadata/framework.py,sha256=qz9zbmqbECbLlCEBY3fkC_rY-M5Uq_tCpC6o2gCl-Xk,4109
+orionis/metadata/framework.py,sha256=gRPC1m0TsT2mlxRIwLsH98soldLLTqKMGuFn_WPQlw4,4109
 orionis/metadata/package.py,sha256=k7Yriyp5aUcR-iR8SK2ec_lf0_Cyc-C7JczgXa-I67w,16039
 orionis/services/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 orionis/services/asynchrony/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -300,6 +304,10 @@ orionis/support/formatter/exceptions/contracts/parser.py,sha256=onLMtggihUGPhCav
 orionis/support/patterns/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 orionis/support/patterns/singleton/__init__.py,sha256=BIyMYL5yXpzv_F-jsSEtoKYseGlM8jdJT8hwGuXZZl8,62
 orionis/support/patterns/singleton/meta.py,sha256=TmrE-QlkglBChD4bmMgQRGT3nli6Kf6UvDl1tiEjQ_o,3801
+orionis/support/performance/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+orionis/support/performance/counter.py,sha256=eTr1VoFy1Jiqc4lmyhrYGTe2ge-Vpl1zuzYt_3nMTP8,2947
+orionis/support/performance/contracts/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+orionis/support/performance/contracts/counter.py,sha256=uDBFk4YswAI4O72t2lc2H8Ck86WU4tp8p4gPXg-r3mw,1317
 orionis/support/standard/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 orionis/support/standard/std.py,sha256=zwXOellgGy9LTmeAK-rCIr7CgKYg5iQijMjdwmMblFA,3800
 orionis/support/standard/contracts/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -356,7 +364,7 @@ orionis/test/validators/web_report.py,sha256=n9BfzOZz6aEiNTypXcwuWbFRG0OdHNSmCNu
 orionis/test/validators/workers.py,sha256=rWcdRexINNEmGaO7mnc1MKUxkHKxrTsVuHgbnIfJYgc,1206
 orionis/test/view/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 orionis/test/view/render.py,sha256=f-zNhtKSg9R5Njqujbg2l2amAs2-mRVESneLIkWOZjU,4082
-orionis-0.475.0.dist-info/licenses/LICENCE,sha256=JhC-z_9mbpUrCfPjcl3DhDA8trNDMzb57cvRSam1avc,1463
+orionis-0.476.0.dist-info/licenses/LICENCE,sha256=JhC-z_9mbpUrCfPjcl3DhDA8trNDMzb57cvRSam1avc,1463
 tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 tests/container/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 tests/container/context/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -503,8 +511,8 @@ tests/testing/validators/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZ
 tests/testing/validators/test_testing_validators.py,sha256=WPo5GxTP6xE-Dw3X1vZoqOMpb6HhokjNSbgDsDRDvy4,16588
 tests/testing/view/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 tests/testing/view/test_render.py,sha256=tnnMBwS0iKUIbogLvu-7Rii50G6Koddp3XT4wgdFEYM,1050
-orionis-0.475.0.dist-info/METADATA,sha256=HbxMijbYojBubd7QWnfKhzuXEW7GKsIy_mm1STUHVqc,4801
-orionis-0.475.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-orionis-0.475.0.dist-info/top_level.txt,sha256=2bdoHgyGZhOtLAXS6Om8OCTmL24dUMC_L1quMe_ETbk,14
-orionis-0.475.0.dist-info/zip-safe,sha256=frcCV1k9oG9oKj3dpUqdJg1PxRT2RSN_XKdLCPjaYaY,2
-orionis-0.475.0.dist-info/RECORD,,
+orionis-0.476.0.dist-info/METADATA,sha256=JiWk4nLrJ8sXSpioU4N90qBnNS8z5MjfihB57lQVLfs,4801
+orionis-0.476.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+orionis-0.476.0.dist-info/top_level.txt,sha256=2bdoHgyGZhOtLAXS6Om8OCTmL24dUMC_L1quMe_ETbk,14
+orionis-0.476.0.dist-info/zip-safe,sha256=frcCV1k9oG9oKj3dpUqdJg1PxRT2RSN_XKdLCPjaYaY,2
+orionis-0.476.0.dist-info/RECORD,,