orionis 0.538.0__py3-none-any.whl → 0.540.0__py3-none-any.whl

orionis/console/fluent/command.py

@@ -0,0 +1,216 @@
+from typing import Any, Callable
+from orionis.console.args.argument import CLIArgument
+from orionis.console.entities.command import Command as CommandEntity
+from orionis.services.introspection.concretes.reflection import ReflectionConcrete
+
+class Command:
+
+    def __init__(
+        self,
+        signature: str,
+        concrete: Callable[..., Any],
+        method: str = 'handle'
+    ) -> None:
+        """
+        Initialize a new Command instance.
+
+        This constructor creates a Command object that encapsulates a command signature,
+        the concrete class that implements the command logic, and the method to be called
+        when executing the command. It validates that the provided concrete is a valid
+        class with the specified callable method.
+
+        Parameters
+        ----------
+        signature : str
+            The command signature string that defines how the command should be invoked
+            from the command line interface.
+        concrete : Callable[..., Any]
+            The concrete class that contains the implementation logic for the command.
+            Must be a valid class (not an instance) that will be instantiated when
+            the command is executed.
+        method : str, default='handle'
+            The name of the method within the concrete class that will be called
+            when executing the command. The method must exist and be callable.
+
+        Returns
+        -------
+        None
+            This is a constructor method and does not return a value.
+
+        Raises
+        ------
+        TypeError
+            If the provided concrete is not a class, or if the method parameter
+            is not a string value.
+        AttributeError
+            If the specified method does not exist in the concrete class or
+            is not callable.
+        """
+
+        # Validate that the concrete parameter is actually a class
+        if not ReflectionConcrete.isConcreteClass(concrete):
+            raise TypeError("The provided concrete must be a class.")
+
+        # Validate that the method parameter is a string
+        if not isinstance(method, str):
+            raise TypeError("The method name must be a string.")
+
+        # Validate that the specified method exists in the concrete class and is callable
+        if not hasattr(concrete, method) or not callable(getattr(concrete, method)):
+            raise AttributeError(f"The method '{method}' does not exist or is not callable in the provided concrete class.")
+
+        # Store the command signature for later use during command parsing
+        self.__signature = signature
+
+        # Store the concrete class reference for instantiation during execution
+        self.__concrete = concrete
+
+        # Store the method name to be called on the concrete instance
+        self.__method = method
+
+        # Initialize timestamp display as enabled by default
+        self.__timestamp = True
+
+        # Set default description for commands that don't provide one
+        self.__description = "No description provided."
+
+        # Initialize empty arguments list to be populated later
+        self.__arguments = []
+
+    def timestamp(self, enabled: bool = True) -> 'Command':
+        """
+        Configure whether timestamps should be included in command output.
+
+        This method allows enabling or disabling timestamp display for the command.
+        When enabled, timestamps will be shown alongside command execution results.
+
+        Parameters
+        ----------
+        enabled : bool, default=True
+            Flag to enable or disable timestamp display. True enables timestamps,
+            False disables them.
+
+        Returns
+        -------
+        Command
+            Returns the current Command instance to allow method chaining.
+
+        Raises
+        ------
+        TypeError
+            If the enabled parameter is not a boolean value.
+        """
+
+        # Validate that the enabled parameter is a boolean
+        if not isinstance(enabled, bool):
+            raise TypeError("The timestamp flag must be a boolean value.")
+
+        # Set the internal timestamp flag
+        self.__timestamp = enabled
+
+        # Return self to enable method chaining
+        return self
+
+    def description(self, desc: str) -> 'Command':
+        """
+        Set the description for the command.
+
+        This method allows setting a descriptive text that explains what the command
+        does. The description is used for help text and documentation purposes when
+        displaying command information to users.
+
+        Parameters
+        ----------
+        desc : str
+            The description text for the command. Must be a non-empty string that
+            describes the command's purpose and functionality.
+
+        Returns
+        -------
+        Command
+            Returns the current Command instance to allow method chaining.
+
+        Raises
+        ------
+        TypeError
+            If the desc parameter is not a string value.
+        """
+
+        # Validate that the description parameter is a string
+        if not isinstance(desc, str):
+            raise TypeError("The description must be a string.")
+
+        # Set the internal description attribute
+        self.__description = desc
+
+        # Return self to enable method chaining
+        return self
+
+    def arguments(self, args: list) -> 'Command':
+        """
+        Set the list of CLI arguments for the command.
+
+        This method configures the command-line arguments that the command will accept.
+        Each argument must be a properly configured CLIArgument instance that defines
+        the argument's name, type, validation rules, and other properties. The arguments
+        are used during command parsing to validate and process user input.
+
+        Parameters
+        ----------
+        args : list
+            A list of CLIArgument instances that define the command's accepted arguments.
+            Each element in the list must be a valid CLIArgument object with proper
+            configuration for argument parsing and validation.
+
+        Returns
+        -------
+        Command
+            Returns the current Command instance to allow method chaining and enable
+            fluent interface pattern for command configuration.
+
+        Raises
+        ------
+        TypeError
+            If the args parameter is not a list, or if any element in the list
+            is not an instance of CLIArgument.
+        """
+
+        # Validate that the arguments parameter is a list
+        if not isinstance(args, list):
+            raise TypeError("Arguments must be provided as a list.")
+
+        # Validate that each argument in the list is a CLIArgument instance
+        for arg in args:
+            if not isinstance(arg, CLIArgument):
+                raise TypeError("All arguments must be instances of CLIArgument.")
+
+        # Set the internal arguments list with the validated arguments
+        self.__arguments = args
+
+        # Return self to enable method chaining
+        return self
+
+    def get(self) -> tuple[str, CommandEntity]:
+        """
+        Retrieve the configured Command entity.
+
+        This method constructs and returns a Command entity object that encapsulates
+        all the configuration details of the command, including its signature, concrete
+        class, method, description, arguments, and timestamp setting. The returned
+        Command entity can be used for command execution and management.
+
+        Returns
+        -------
+        CommandEntity
+            A Command entity object containing all the command's configuration details.
+        """
+
+        # Create and return a Command entity with all the configured properties
+        return self.__signature, CommandEntity(
+            obj=self.__concrete,
+            method=self.__method,
+            timestamps=self.__timestamp,
+            signature=self.__signature,
+            description=self.__description,
+            args=self.__arguments
+        )

orionis/console/{tasks → fluent}/event.py

@@ -6,7 +6,7 @@ from apscheduler.triggers.date import DateTrigger
 from apscheduler.triggers.interval import IntervalTrigger
 from orionis.console.contracts.event import IEvent
 from orionis.console.contracts.schedule_event_listener import IScheduleEventListener
-from orionis.console.enums.event import Event as EventEntity
+from orionis.console.entities.event import Event as EventEntity
 from orionis.console.exceptions import CLIOrionisValueError
 
 class Event(IEvent):

orionis/console/kernel.py

@@ -1,8 +1,7 @@
 from typing import List
 from orionis.console.contracts.kernel import IKernelCLI
 from orionis.console.contracts.reactor import IReactor
-from orionis.console.entities.request import CLIRequest
-from orionis.console.request.cli_request import Request
+from orionis.console.request.cli_request import CLIRequest
 from orionis.failure.contracts.catch import ICatch
 from orionis.foundation.contracts.application import IApplication
 from orionis.console.exceptions import CLIOrionisValueError
@@ -38,6 +37,9 @@ class KernelCLI(IKernelCLI):
                 f"Failed to initialize TestKernel: expected IApplication, got {type(app).__module__}.{type(app).__name__}."
             )
 
+        # Store the application container as a private attribute for internal use
+        self.__app: IApplication = app
+
         # Retrieve and initialize the reactor instance from the application container.
         # The reactor is responsible for dispatching CLI commands.
         self.__reactor: IReactor = app.make('x-orionis.console.core.reactor')
@@ -64,21 +66,36 @@ class KernelCLI(IKernelCLI):
         SystemExit
             If invalid arguments are provided or no command is specified, this method may terminate the process with an error message.
         """
+        try:
 
-        request: CLIRequest = CLIRequest()
+            # Ensure the arguments are provided as a list
+            if not isinstance(args, list):
+                raise CLIOrionisValueError(
+                    f"Failed to handle command line arguments: expected list, got {type(args).__module__}.{type(args).__name__}."
+                )
 
-        try:
+            # If no arguments or only the script name is provided, show the default help command
+            if not args or len(args) <= 1:
+                return self.__reactor.call('help')
+
+            # Remove the first argument (script name) to process only the command and its parameters
+            args = args[1:]
 
-            # create a CLIRequest instance by processing the provided arguments
-            request = Request(args)
+            # If no command is provided after removing the script name, exit with an error
+            if len(args) == 0:
+                raise CLIOrionisValueError("No command provided to execute.")
+
+            # If only the command is provided, call it without additional arguments
+            if len(args) == 1:
+                return self.__reactor.call(args[0])
 
             # If command and arguments are provided, call the command with its arguments
-            return self.__reactor.call(
-                request.command,
-                request.args
-            )
+            return self.__reactor.call(args[0], args[1:])
 
         except BaseException as e:
 
+            # If an exception occurs, prepare a CLIRequest with the command (if available)
+            command = args[0] if args else "__unknown__"
+
             # Catch any exceptions that occur during command handling
-            self.__catch.exception(self, request, e)
+            self.__catch.exception(self, CLIRequest(command, {}), e)

orionis/console/output/console.py

@@ -3,7 +3,7 @@ import getpass
 import os
 import sys
 from orionis.console.output.enums import ANSIColors
-from orionis.console.output.contracts.console import IConsole
+from orionis.console.contracts.console import IConsole
 
 class Console(IConsole):
     """

orionis/console/output/executor.py

@@ -1,5 +1,5 @@
 from datetime import datetime
-from orionis.console.output.contracts.executor import IExecutor
+from orionis.console.contracts.executor import IExecutor
 from orionis.console.output.enums.styles import ANSIColors
 
 class Executor(IExecutor):

orionis/console/request/cli_request.py

@@ -1,45 +1,127 @@
-from typing import List
-from orionis.console.entities.request import CLIRequest as CLIRequestEntity
+from typing import Any
+from orionis.console.contracts.cli_request import ICLIRequest
 from orionis.console.exceptions.cli_orionis_value_error import CLIOrionisValueError
 
-class CLIRequest:
-    def __call__(self, args: List[str]) -> "CLIRequestEntity":
+class CLIRequest(ICLIRequest):
+
+    def __init__(
+        self,
+        command: str,
+        args: dict
+    ):
         """
-        Processes command-line arguments and returns a CLIRequest instance.
+        Initialize a CLI request object with command line arguments.
 
-        Parameters
-        ----------
-        args : List[str]
-            The list of command-line arguments. The first argument is expected to be the script name.
+        Args:
+            args (dict, optional): Dictionary containing command line arguments and their values.
+                                  Defaults to an empty dictionary.
+
+        Raises:
+            CLIOrionisValueError: If the provided args parameter is not a dictionary.
+
+        Note:
+            The args dictionary is stored privately and used to manage CLI request parameters
+            throughout the lifecycle of the CLI request object.
+        """
+
+        # Validate that args is a dictionary
+        if not isinstance(args, dict):
+            raise CLIOrionisValueError("Args must be a dictionary")
+
+        # Validate that command is a string
+        if not isinstance(command, str):
+            raise CLIOrionisValueError("Command must be a string")
+
+        # Store the args dictionary as a private attribute
+        self.__command = command
+        self.__args = args if args is not None else {}
+
+    def command(self) -> str:
+        """
+        Retrieve the command name associated with this CLI request.
+
+        This method provides access to the command string that was specified during
+        the initialization of the CLIRequest object. The command represents the
+        primary action or operation that should be executed based on the CLI input.
+
+        Returns
+        -------
+        str
+            The command name stored as a string. This is the exact command value
+            that was passed to the constructor during object initialization.
+
+        Notes
+        -----
+        The returned command string is immutable and represents the core action
+        identifier for this CLI request. This value is essential for determining
+        which operation should be performed by the CLI handler.
+        """
+
+        # Return the command name stored in the private attribute
+        # This provides access to the command specified during initialization
+        return self.__command
+
+    def all(self) -> dict:
+        """
+        Retrieve all command line arguments as a complete dictionary.
+
+        This method provides access to the entire collection of command line arguments
+        that were passed during the initialization of the CLIRequest object. It returns
+        a reference to the internal arguments dictionary, allowing for comprehensive
+        access to all parsed CLI parameters.
 
         Returns
         -------
-        CLIRequestEntity
-            An instance representing the parsed command and its arguments.
+        dict
+            A dictionary containing all the parsed command line arguments as key-value
+            pairs, where keys are argument names (str) and values are the corresponding
+            argument values of any type. If no arguments were provided during
+            initialization, returns an empty dictionary.
 
-        Raises
-        ------
-        CLIOrionisValueError
-            If the provided arguments are not a list or if no command is provided.
+        Notes
+        -----
+        This method returns a reference to the internal arguments dictionary rather
+        than a copy. Modifications to the returned dictionary will affect the
+        internal state of the CLIRequest object.
         """
-        if not isinstance(args, list):
-            raise CLIOrionisValueError(
-                f"Failed to handle command line arguments: expected list, got {type(args).__module__}.{type(args).__name__}."
-            )
 
-        if len(args) <= 1:
-            raise CLIOrionisValueError("No command provided to execute.")
+        # Return the complete arguments dictionary containing all CLI parameters
+        return self.__args
+
+    def argument(self, name: str, default: Any = None):
+        """
+        Retrieve the value of a specific command line argument by its name.
 
-        # Remove the script name
-        args = args[1:]
+        This method provides access to individual command line arguments that were
+        passed during initialization. It safely retrieves argument values without
+        raising exceptions if the argument doesn't exist.
 
-        if not args or not args[0]:
-            raise CLIOrionisValueError("No command provided to execute.")
+        Parameters
+        ----------
+        name : str
+            The name of the command line argument to retrieve. This should match
+            the key used when the argument was originally parsed and stored.
+        default : Any, optional
+            The default value to return if the specified argument name does not
+            exist in the arguments dictionary. Defaults to None.
+
+        Returns
+        -------
+        Any or None
+            The value associated with the specified argument name if it exists
+            in the arguments dictionary. Returns None if the argument name is
+            not found or was not provided during CLI execution.
+
+        Notes
+        -----
+        This method uses the dictionary's get() method to safely access values,
+        ensuring that missing arguments return None rather than raising a KeyError.
+        """
 
-        return CLIRequestEntity(
-            command=args[0],
-            args=args[1:]
-        )
+        # Safely retrieve the argument value using dict.get() to avoid KeyError
+        # Returns None if the argument name doesn't exist in the dictionary
+        if name not in self.__args or self.__args[name] is None:
+            return default
 
-# Export the CLIRequest Singleton
-Request = CLIRequest()
+        # Return the value associated with the specified argument name
+        return self.__args.get(name, default)

orionis/console/tasks/schedule.py

@@ -25,16 +25,16 @@ from orionis.console.contracts.reactor import IReactor
 from orionis.console.contracts.schedule import ISchedule
 from orionis.console.contracts.schedule_event_listener import IScheduleEventListener
 from orionis.console.entities.event_job import EventJob
-from orionis.console.entities.request import CLIRequest
 from orionis.console.entities.scheduler_error import SchedulerError
 from orionis.console.entities.scheduler_paused import SchedulerPaused
 from orionis.console.entities.scheduler_resumed import SchedulerResumed
 from orionis.console.entities.scheduler_shutdown import SchedulerShutdown
 from orionis.console.entities.scheduler_started import SchedulerStarted
-from orionis.console.enums.event import Event as EventEntity
+from orionis.console.entities.event import Event as EventEntity
 from orionis.console.enums.listener import ListeningEvent
 from orionis.console.exceptions import CLIOrionisRuntimeError
 from orionis.console.exceptions.cli_orionis_value_error import CLIOrionisValueError
+from orionis.console.request.cli_request import CLIRequest
 from orionis.failure.contracts.catch import ICatch
 from orionis.foundation.contracts.application import IApplication
 from orionis.services.log.contracts.log_service import ILogger
@@ -282,7 +282,7 @@ class Schedule(ISchedule):
             raise CLIOrionisValueError(f"The command '{signature}' is not available or does not exist.")
 
         # Import Event here to avoid circular dependency issues
-        from orionis.console.tasks.event import Event
+        from orionis.console.fluent.event import Event
 
         # Store the command and its arguments for scheduling
         self.__events[signature] = Event(
@@ -981,7 +981,7 @@ class Schedule(ISchedule):
 
         # Delegate exception handling to the application's error catching mechanism
         # This ensures consistent error handling across the entire application
-        self.__catch.exception(self, CLIRequest(command="schedule:work", args=[]), exception)
+        self.__catch.exception(self, CLIRequest(command="schedule:work", args={}), exception)
 
     def setListener(
         self,

orionis/container/container.py

@@ -18,7 +18,6 @@ from orionis.services.introspection.concretes.reflection import ReflectionConcre
 from orionis.services.introspection.dependencies.entities.argument import Argument
 from orionis.services.introspection.dependencies.entities.resolve_argument import ResolveArguments
 from orionis.services.introspection.dependencies.reflection import ReflectDependencies
-from orionis.services.introspection.instances.reflection import ReflectionInstance
 
 class Container(IContainer):
 
@@ -541,6 +540,101 @@ class Container(IContainer):
         # Return True to indicate successful registration
         return True
 
+    def scopedInstance(
+        self,
+        abstract: Callable[..., Any],
+        instance: Any,
+        *,
+        alias: str = None,
+        enforce_decoupling: bool = False
+    ) -> Optional[bool]:
+        """
+        Registers an instance of a class or interface in the container with scoped lifetime.
+
+        Parameters
+        ----------
+        abstract : Callable[..., Any]
+            The abstract class or interface to associate with the instance.
+        instance : Any
+            The concrete instance to register.
+        alias : str, optional
+            An optional alias to register the instance under. If not provided,
+            the abstract's `__name__` attribute will be used as the alias if available.
+        enforce_decoupling : bool, optional
+            Whether to enforce decoupling between abstract and concrete types.
+
+        Returns
+        -------
+        bool
+            True if the instance was successfully registered.
+
+        Raises
+        ------
+        TypeError
+            If `abstract` is not an abstract class or if `alias` is not a valid string.
+        ValueError
+            If `instance` is not a valid instance of `abstract`.
+        OrionisContainerException
+            If no active scope is found.
+
+        Notes
+        -----
+        This method registers the instance with scoped lifetime, meaning it will be
+        available only within the current active scope. If no scope is active,
+        an exception will be raised.
+        """
+
+        # Ensure that the abstract is an abstract class
+        IsAbstractClass(abstract, f"Instance {Lifetime.SCOPED}")
+
+        # Ensure that the instance is a valid instance
+        IsInstance(instance)
+
+        # Ensure that instance is NOT a subclass of abstract
+        if enforce_decoupling:
+            IsNotSubclass(abstract, instance.__class__)
+        else:
+            # Validate that instance is a subclass of abstract
+            IsSubclass(abstract, instance.__class__)
+
+        # Ensure implementation
+        ImplementsAbstractMethods(
+            abstract=abstract,
+            instance=instance
+        )
+
+        # Ensure that the alias is a valid string if provided
+        if alias:
+            IsValidAlias(alias)
+        else:
+            rf_asbtract = ReflectionAbstract(abstract)
+            alias = rf_asbtract.getModuleWithClassName()
+
+        # If the service is already registered in container bindings, drop it
+        self.drop(abstract, alias)
+
+        # Register the binding in the container for future scope resolutions
+        self.__bindings[abstract] = Binding(
+            contract=abstract,
+            instance=instance,
+            lifetime=Lifetime.SCOPED,
+            enforce_decoupling=enforce_decoupling,
+            alias=alias
+        )
+
+        # Register the alias
+        self.__aliases[alias] = self.__bindings[abstract]
+
+        # Store the instance directly in the current scope
+        scope = ScopedContext.getCurrentScope()
+        if scope:
+            scope[abstract] = instance
+            if alias != abstract:
+                scope[alias] = instance
+
+        # Return True to indicate successful registration
+        return True
+
     def instance(
         self,
         abstract: Callable[..., Any],
@@ -1760,6 +1854,11 @@ class Container(IContainer):
             If the dependency cannot be resolved through any available method.
         """
 
+        # Check if the dependency is already in the current scope (for SCOPED lifetime)
+        scoped = ScopedContext.getCurrentScope()
+        if scoped and (dependency.type in scoped or dependency.full_class_path in scoped):
+            return scoped[dependency.type] if dependency.type in scoped else scoped[dependency.full_class_path]
+
         # If the dependency has a default value, use it
         if dependency.default is not None:
             return dependency.default
@@ -1775,10 +1874,12 @@ class Container(IContainer):
             )
 
         # Try to resolve from container using type (Abstract or Interface)
+        # This will automatically handle SCOPED lifetime through resolve() -> __resolveScoped()
         if self.bound(dependency.type):
             return self.resolve(self.getBinding(dependency.type))
 
         # Try to resolve from container using full class path
+        # This will also handle SCOPED lifetime appropriately
         if self.bound(dependency.full_class_path):
             return self.resolve(self.getBinding(dependency.full_class_path))