orionis 0.448.0__py3-none-any.whl → 0.449.0__py3-none-any.whl

orionis/foundation/providers/logger_provider.py

@@ -4,15 +4,28 @@ from orionis.services.log.log_service import LoggerService
 
 class LoggerProvider(ServiceProvider):
     """
-    Provides and registers the logging service within the application container.
+    Service provider for logging functionality within the Orionis framework.
 
-    This provider binds an implementation of `ILoggerService` to the application,
-    making a `LoggerService` instance available for application-wide logging.
+    The LoggerProvider is responsible for registering and configuring the logging
+    service implementation in the application's dependency injection container.
+    It binds the concrete LoggerService to the ILoggerService interface, enabling
+    application-wide access to structured logging capabilities.
+
+    This provider handles the initialization of the logging service with the
+    application's configuration and ensures proper registration under both the
+    interface contract and an internal framework alias for service resolution.
 
     Attributes
     ----------
     app : Application
-        The application container instance where services are registered.
+        The application container instance used for service registration and
+        configuration retrieval. Inherited from the base ServiceProvider class.
+
+    Notes
+    -----
+    This provider follows the two-phase initialization pattern:
+    - register(): Performs service binding and container registration
+    - boot(): Handles post-registration initialization and setup
     """
 
     def register(self) -> None:
@@ -20,25 +33,51 @@ class LoggerProvider(ServiceProvider):
         Register the logging service in the application container.
 
         This method binds the `LoggerService` implementation to the `ILoggerService`
-        contract in the application container, using the application's logging configuration.
+        contract within the application's dependency injection container. The service
+        is initialized with the application's logging configuration and registered
+        with a specific alias for internal framework identification.
+
+        The registration enables application-wide access to logging functionality
+        through the container's service resolution mechanism.
 
         Returns
         -------
         None
+            This method does not return any value. It performs service registration
+            as a side effect on the application container.
         """
 
-        self.app.instance(ILoggerService, LoggerService(self.app.config('logging')), alias="core.orionis.logger")
+        # Retrieve logging configuration from application config
+        logging_config = self.app.config('logging')
+
+        # Create LoggerService instance with the retrieved configuration
+        logger_service = LoggerService(logging_config)
+
+        # Register the service instance in the container with interface binding and alias
+        self.app.instance(
+            ILoggerService,                             # Interface contract
+            logger_service,                             # Concrete implementation instance
+            alias="x-orionis.services.log.log_service"  # Internal framework alias
+        )
 
     def boot(self) -> None:
         """
         Perform post-registration initialization for the logging service.
 
-        This method is a placeholder for any additional setup required after
-        the logging service has been registered.
+        This method is called after all service providers have been registered
+        and allows for any additional configuration, setup, or initialization
+        logic that depends on other services being available in the container.
+
+        Currently, this method serves as a placeholder and performs no operations,
+        but it can be extended to include logging service initialization tasks
+        such as setting up log handlers, configuring formatters, or establishing
+        connections to external logging systems.
 
         Returns
         -------
         None
+            This method does not return any value. It performs initialization
+            operations as side effects during the application boot process.
         """
 
         pass

orionis/foundation/providers/progress_bar_provider.py

@@ -4,37 +4,82 @@ from orionis.container.providers.service_provider import ServiceProvider
 
 class ProgressBarProvider(ServiceProvider):
     """
-    Service provider for registering the dynamic progress bar.
+    Service provider for dynamic progress bar functionality.
 
-    This provider registers the `IProgressBar` interface with the `ProgressBar`
-    implementation in the application container, allowing for dependency injection
-    and usage of a console-based progress bar for visual feedback during operations.
+    This provider is responsible for registering the dynamic progress bar service
+    within the application's dependency injection container. It binds the IProgressBar
+    interface to its concrete ProgressBar implementation, enabling the creation of
+    visual progress indicators for long-running operations in console applications.
+
+    The provider follows the transient lifetime pattern, ensuring that each request
+    for a progress bar service creates a new, independent instance. This approach
+    prevents state conflicts when multiple progress bars are used simultaneously
+    across different parts of the application.
+
+    Parameters
+    ----------
+    None
+        This class does not accept initialization parameters beyond those
+        inherited from the base ServiceProvider class.
+
+    Returns
+    -------
+    None
+        Service providers do not return values as they are used for
+        registration and configuration purposes only.
+
+    Notes
+    -----
+    The progress bar service is registered with the alias 'x-orionis.console.dynamic.progress_bar'
+    to enable specific identification and retrieval from the container when needed.
+    This provider requires the orionis container framework to be properly initialized
+    before registration can occur.
     """
 
     def register(self) -> None:
         """
         Register the progress bar service in the application container.
 
-        Registers the `IProgressBar` interface to resolve to the `ProgressBar`
-        implementation, with the alias "core.orionis.progress_bar".
+        This method binds the IProgressBar interface to the ProgressBar concrete
+        implementation using transient lifetime management. The service is registered
+        with a specific alias for identification and retrieval within the container.
+
+        The transient lifetime ensures that a new instance of ProgressBar is created
+        each time the IProgressBar interface is resolved from the container.
+
+        Parameters
+        ----------
+        None
 
         Returns
         -------
         None
+            This method does not return any value. It performs service registration
+            as a side effect on the application container.
         """
 
-        self.app.transient(IProgressBar, ProgressBar, alias="core.orionis.progress_bar")
+        self.app.transient(IProgressBar, ProgressBar, alias="x-orionis.console.dynamic.progress_bar")
 
     def boot(self) -> None:
         """
-        Perform post-registration initialization.
+        Perform post-registration initialization for the progress bar provider.
 
-        This method is called after all providers have been registered. No additional
-        initialization is required for the progress bar service.
+        This method is called after all service providers have been registered
+        in the application container. It provides an opportunity to perform
+        any additional setup or configuration that depends on other services
+        being available. For the progress bar provider, no additional
+        initialization steps are required as the service is fully configured
+        during registration.
+
+        Parameters
+        ----------
+        None
 
         Returns
         -------
         None
+            This method does not return any value. It serves as a lifecycle
+            hook for post-registration initialization.
         """
 
         pass

orionis/foundation/providers/testing_provider.py

@@ -6,76 +6,120 @@ import os
 
 class TestingProvider(ServiceProvider):
     """
-    Provides and registers the unit testing environment service in the application container.
+    Provides comprehensive unit testing environment services for the Orionis framework.
 
-    This provider integrates a native unit testing framework for Orionis,
-    enabling advanced testing features and registering the service as a singleton
-    within the application's dependency injection container.
+    This service provider integrates a native unit testing framework into the Orionis
+    application ecosystem, enabling advanced testing capabilities with configurable
+    execution modes, parallel processing, and persistent result storage. The provider
+    registers the testing service as a singleton within the application's dependency
+    injection container, making it available throughout the application lifecycle.
+
+    The TestingProvider handles the complete lifecycle of testing services, from
+    initial configuration and test discovery to storage preparation and service
+    registration. It supports various testing patterns, execution strategies, and
+    reporting mechanisms to accommodate different testing scenarios and requirements.
 
     Attributes
     ----------
     app : Application
-        The application container instance where services are registered.
+        The Orionis application container instance that manages service registration,
+        configuration access, and dependency injection throughout the framework.
+
+    Notes
+    -----
+    This provider follows the Orionis service provider pattern, implementing both
+    register() and boot() methods to ensure proper service initialization and
+    post-registration setup. The testing service is registered with the interface
+    binding IUnitTest and can be resolved using the alias "x-orionis.test.core.unit_test".
+
+    The provider requires a valid testing configuration section in the application
+    configuration, which should include settings for verbosity, execution mode,
+    worker configuration, and storage paths.
     """
 
     def register(self) -> None:
         """
         Register the unit testing service in the application container.
 
-        Registers the IUnitTest interface to the UnitTest implementation as a singleton,
-        with the alias "core.orionis.testing".
+        This method creates and configures a UnitTest instance using the application's
+        testing configuration, discovers test files based on specified patterns and paths,
+        and registers the configured testing service as a singleton in the dependency
+        injection container with the IUnitTest interface binding.
+
+        The registration process includes:
+        - Loading testing configuration from the application config
+        - Creating and configuring a UnitTest instance with various settings
+        - Discovering test files based on configuration parameters
+        - Binding the service to the container with alias "x-orionis.test.core.unit_test"
 
         Returns
         -------
         None
+            This method does not return any value. It performs side effects by
+            registering the testing service in the application container.
         """
 
-        # Create a Testing configuration instance from the application config
+        # Load testing configuration from application config and create Testing instance
         config = Testing(**self.app.config('testing'))
 
-        # Create a UnitTest instance
+        # Instantiate the UnitTest implementation with application reference
         unit_test = UnitTest(
             app=self.app
         )
 
-        # Configure the UnitTest instance with settings from the Testing configuration
+        # Apply configuration settings to the UnitTest instance
         unit_test.configure(
-            verbosity=config.verbosity,
-            execution_mode=config.execution_mode,
-            max_workers=config.max_workers,
-            fail_fast=config.fail_fast,
-            print_result=config.print_result,
-            throw_exception=config.throw_exception,
-            persistent=config.persistent,
-            persistent_driver=config.persistent_driver,
-            web_report=config.web_report
+            verbosity=config.verbosity,                 # Set output verbosity level
+            execution_mode=config.execution_mode,       # Configure test execution mode
+            max_workers=config.max_workers,             # Set maximum worker threads for parallel execution
+            fail_fast=config.fail_fast,                 # Enable/disable fail-fast behavior
+            print_result=config.print_result,           # Control result output printing
+            throw_exception=config.throw_exception,     # Configure exception throwing behavior
+            persistent=config.persistent,               # Enable/disable persistent test results
+            persistent_driver=config.persistent_driver, # Set persistent storage driver
+            web_report=config.web_report                # Enable/disable web-based reporting
         )
 
-        # Discover tests based on the configuration
+        # Discover and load test files based on configuration criteria
         unit_test.discoverTests(
-            base_path=config.base_path,
-            folder_path=config.folder_path,
-            pattern=config.pattern,
-            test_name_pattern=config.test_name_pattern,
-            tags=config.tags
+            base_path=config.base_path,                 # Root directory for test discovery
+            folder_path=config.folder_path,             # Specific folder path within base_path
+            pattern=config.pattern,                     # File name pattern for test files
+            test_name_pattern=config.test_name_pattern, # Pattern for test method names
+            tags=config.tags                            # Tags to filter tests during discovery
         )
 
-        # Register the UnitTest instance in the application container
-        self.app.instance(IUnitTest, unit_test, alias="core.orionis.testing")
+        # Register the configured UnitTest instance in the DI container
+        # Binds IUnitTest interface to the UnitTest implementation as a singleton
+        self.app.instance(IUnitTest, unit_test, alias="x-orionis.test.core.unit_test")
 
     def boot(self) -> None:
         """
-        Perform post-registration initialization if required.
+        Perform post-registration initialization for the testing provider.
 
-        This method is intended for any setup needed after service registration.
-        Currently, no additional initialization is performed.
+        This method is called after the service registration phase to handle any
+        additional setup required for the testing environment. It ensures that
+        the necessary storage directories for testing operations are created
+        and available before test execution begins.
+
+        The boot process includes:
+        - Creating the testing storage directory if it doesn't exist
+        - Setting appropriate permissions for the storage path
+        - Preparing the filesystem structure for test artifacts
 
         Returns
         -------
         None
+            This method does not return any value. It performs initialization
+            side effects by creating required directories in the filesystem.
         """
 
-        # Ensure directory for testing storage exists
+        # Retrieve the configured storage path for testing artifacts and temporary files
         storage_path = self.app.path('storage_testing')
+
+        # Check if the testing storage directory exists in the filesystem
         if not os.path.exists(storage_path):
+
+            # Create the directory structure recursively, including parent directories
+            # exist_ok=True prevents errors if directory is created by another process
             os.makedirs(storage_path, exist_ok=True)

orionis/foundation/providers/workers_provider.py

@@ -4,41 +4,99 @@ from orionis.services.system.workers import Workers
 
 class WorkersProvider(ServiceProvider):
     """
-    Provides and registers the worker management service within the application container.
+    Service provider for worker management functionality within the Orionis framework.
 
-    This provider determines and registers the optimal worker management implementation,
-    making it available for dependency injection throughout the application.
+    This provider is responsible for registering and configuring the worker management
+    service implementation in the application's dependency injection container. It
+    establishes the binding between the IWorkers interface contract and its concrete
+    Workers implementation, enabling consistent worker operations throughout the
+    application lifecycle.
+
+    The provider follows the standard service provider pattern, offering both
+    registration and boot phases for complete service lifecycle management.
 
     Attributes
     ----------
     app : Application
-        The application container instance where services are registered.
+        The main application container instance used for service registration
+        and dependency injection management.
+
+    Notes
+    -----
+    This provider registers the worker service with transient lifetime, ensuring
+    that each request for worker functionality receives a fresh instance. This
+    approach is optimal for worker operations that may maintain temporary state
+    or require isolation between different execution contexts.
     """
 
     def register(self) -> None:
         """
-        Register the worker service in the application container.
+        Register the worker management service in the application container.
 
-        Registers the `Workers` implementation as a transient service for the `IWorkers`
-        contract, with the alias "core.orionis.workers".
+        This method registers the concrete Workers implementation as the service
+        provider for the IWorkers interface contract. The service is configured
+        as transient, meaning a new instance will be created each time it is
+        requested from the container. The registration includes a descriptive
+        alias for easy identification and retrieval.
+
+        Parameters
+        ----------
+        None
 
         Returns
         -------
         None
+            This method does not return any value. It performs registration
+            side effects on the application container.
+
+        Notes
+        -----
+        The service is registered with transient lifetime, which means:
+        - A new instance is created for each resolution request
+        - No instance caching or singleton behavior is applied
+        - Suitable for stateless or short-lived worker operations
         """
 
-        self.app.transient(IWorkers, Workers, alias="core.orionis.workers")
+        self.app.transient(
+            IWorkers,  # The interface contract that defines worker operations
+            Workers,   # The concrete implementation class
+            alias="x-orionis.services.system.workers"  # Descriptive alias for container lookup
+        )
 
     def boot(self) -> None:
         """
-        Perform post-registration initialization if required.
+        Perform post-registration initialization for the worker management service.
 
-        This method is a placeholder for any initialization logic that should occur
-        after the worker service has been registered.
+        This method is called after all services have been registered in the container
+        and provides an opportunity to perform any additional setup, configuration,
+        or initialization logic that depends on other services being available.
+
+        The boot phase occurs after the registration phase and allows for:
+        - Cross-service dependency configuration
+        - Service warm-up operations
+        - Additional service binding or decoration
+        - Runtime configuration validation
+
+        Currently, this implementation serves as a placeholder with no specific
+        initialization requirements for the worker service. Future enhancements
+        may include worker pool initialization, background task setup, or
+        performance monitoring configuration.
+
+        Parameters
+        ----------
+        None
 
         Returns
         -------
         None
+            This method performs initialization side effects only and does not
+            return any value.
+
+        Notes
+        -----
+        This method is automatically called by the service provider framework
+        during the application boot sequence. It should not be called manually
+        in application code.
         """
 
         pass

orionis/metadata/framework.py

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

orionis/support/facades/console.py

@@ -5,11 +5,19 @@ class Console(Facade):
     @classmethod
     def getFacadeAccessor(cls) -> str:
         """
-        Get the service container binding key for the console component.
+        Get the registered service container binding key for the console component.
+
+        This method returns the specific binding key that is used to resolve the
+        console output service from the dependency injection container. The facade
+        pattern uses this key to locate and instantiate the underlying console
+        service implementation.
 
         Returns
         -------
         str
-            The binding key used to resolve the console service from the container.
+            The string identifier 'x-orionis.console.output.console' used as the
+            binding key to resolve the console service from the service container.
         """
-        return "core.orionis.console"
+
+        # Return the predefined binding key for the console output service
+        return "x-orionis.console.output.console"

orionis/support/facades/dumper.py

@@ -5,11 +5,18 @@ class Dumper(Facade):
     @classmethod
     def getFacadeAccessor(cls) -> str:
         """
-        Returns the service container binding key for the dumper component.
+        Get the registered name of the component in the service container.
+
+        This method defines the binding key used to resolve the dumper service
+        from the application's service container. The dumper facade provides
+        a static interface to the underlying dumper service implementation.
 
         Returns
         -------
         str
-            The binding key "core.orionis.dumper" used to resolve the dumper service from the container.
+            The service container binding key "x-orionis.console.dumper.dump"
+            that identifies the dumper service instance.
         """
-        return "core.orionis.dumper"
+
+        # Return the specific binding key for the dumper service in the container
+        return "x-orionis.console.dumper.dump"

orionis/support/facades/executor.py

@@ -0,0 +1,24 @@
+from orionis.container.facades.facade import Facade
+
+class ConsoleExecutor(Facade):
+
+    @classmethod
+    def getFacadeAccessor(cls) -> str:
+        """
+        Get the registered service container binding key for the executor facade.
+
+        This method provides the specific binding key that the service container
+        uses to resolve and instantiate the executor service. The executor is
+        responsible for handling command-line operations and console output
+        management within the Orionis framework.
+
+        Returns
+        -------
+        str
+            The string identifier 'x-orionis.console.output.executor' used as
+            the binding key to locate and resolve the executor service instance
+            from the dependency injection container.
+        """
+
+        # Return the predefined binding key for the executor service
+        return "x-orionis.console.output.executor"

orionis/support/facades/inspire.py

@@ -5,16 +5,19 @@ class Inspire(Facade):
     @classmethod
     def getFacadeAccessor(cls):
         """
-        Retrieves the binding key used to resolve the 'inspire' service from the service container.
+        Get the registered name of the component.
 
-        This method provides the unique identifier string that the service container uses to locate
-        and return the implementation associated with the 'inspire' service. It is typically used
-        internally by the Facade base class to delegate calls to the appropriate service instance.
+        This method returns the service container binding key that identifies the
+        inspirational service implementation. The facade system uses this accessor
+        to resolve the underlying service instance from the IoC container when
+        facade methods are called.
 
         Returns
         -------
         str
-            The binding key "core.orionis.inspire" that identifies the 'inspire' service in the container.
+            The service container binding key 'x-orionis.services.inspirational.inspire'
+            used to resolve the inspirational service instance.
         """
 
-        return "core.orionis.inspire"
+        # Return the service container binding key for the inspirational service
+        return "x-orionis.services.inspirational.inspire"

orionis/support/facades/logger.py

@@ -5,12 +5,19 @@ class Log(Facade):
     @classmethod
     def getFacadeAccessor(cls) -> str:
         """
-        Returns the binding key for the logger service in the service container.
+        Get the registered name of the component.
+
+        This method returns the service container binding key that identifies
+        the logger service implementation. It serves as the bridge between the
+        facade and the actual service instance registered in the container.
 
         Returns
         -------
         str
-            The unique identifier used to resolve the logger service, specifically
-            "core.orionis.logger".
+            The service container binding key "x-orionis.services.log.log_service"
+            used to resolve the logger service instance from the dependency
+            injection container.
         """
-        return "core.orionis.logger"
+
+        # Return the service container binding key for the logger service
+        return "x-orionis.services.log.log_service"

orionis/support/facades/progress_bar.py

@@ -5,11 +5,17 @@ class ProgressBar(Facade):
     @classmethod
     def getFacadeAccessor(cls):
         """
-        Returns the binding key for the progress bar service.
+        Get the registered name of the component.
+
+        This method returns the binding key that identifies the progress bar service
+        within the service container. The facade uses this key to resolve the actual
+        progress bar implementation when static methods are called.
 
         Returns
         -------
         str
-            The unique identifier used to retrieve the progress bar service from the service container.
+            The service container binding key 'x-orionis.console.dynamic.progress_bar'
+            used to retrieve the progress bar service instance.
         """
-        return "core.orionis.progress_bar"
+
+        return "x-orionis.console.dynamic.progress_bar"

orionis/support/facades/testing.py

@@ -5,12 +5,18 @@ class Test(Facade):
     @classmethod
     def getFacadeAccessor(cls) -> str:
         """
-        Returns the binding key for the testing component in the service container.
+        Get the registered name of the component.
+
+        This method returns the service container binding key that identifies
+        the testing component implementation. The facade uses this key to
+        resolve the appropriate testing service from the container when
+        static methods are called on the facade.
 
         Returns
         -------
         str
-            The unique string identifier for the testing component, used by the service
-            container to resolve the appropriate implementation.
+            The service container binding key "x-orionis.test.core.unit_test"
+            used to resolve the testing component implementation.
         """
-        return "core.orionis.testing"
+
+        return "x-orionis.test.core.unit_test"