orionis 0.613.0__py3-none-any.whl → 0.615.0__py3-none-any.whl

orionis/container/providers/service_provider.py

@@ -16,35 +16,57 @@ class ServiceProvider(IServiceProvider):
 
     def __init__(self, app: IApplication) -> None:
         """
-        Initialize the ServiceProvider with the application container.
+        Initialize a new ServiceProvider instance with the given application container.
 
         Parameters
         ----------
         app : IApplication
-            The application container instance.
+            The application container instance to which this service provider will be attached.
+
+        Returns
+        -------
+        None
+            This constructor does not return a value.
         """
+
+        # Store the application container instance for use in service registration and bootstrapping
         self.app = app
 
     async def register(self) -> None:
         """
         Register services and components into the application container.
 
-        This method must be implemented by subclasses to bind services,
-        configurations, or other components to the application container.
+        This asynchronous method should be implemented by subclasses to bind services,
+        configurations, or other components to the application container. It is called
+        during the application's service registration phase.
+
+        Returns
+        -------
+        None
+            This method does not return a value.
 
         Raises
         ------
         NotImplementedError
             If the method is not overridden in a subclass.
         """
-        raise NotImplementedError("This method should be overridden in the subclass")
+
+        # Optionally overridden by subclasses to register services
+        pass
 
     async def boot(self) -> None:
         """
-        Perform post-registration initialization or bootstrapping.
+        Perform post-registration initialization or bootstrapping tasks.
+
+        This asynchronous method is called after all services have been registered.
+        Subclasses may override this method to initialize services, set up event listeners,
+        or perform other operations required at application boot time.
 
-        This method is called after all services have been registered.
-        Override this method to initialize services, set up event listeners,
-        or perform other boot-time operations.
+        Returns
+        -------
+        None
+            This method does not return a value.
         """
+
+        # Optionally overridden by subclasses to perform boot-time operations
         pass

orionis/foundation/application.py

@@ -23,30 +23,46 @@ from orionis.foundation.config.startup import Configuration
 from orionis.foundation.config.testing.entities.testing import Testing
 from orionis.foundation.contracts.application import IApplication
 from orionis.foundation.exceptions import OrionisTypeError, OrionisRuntimeError, OrionisValueError
-from orionis.services.asynchrony.coroutines import Coroutine
 from orionis.services.log.contracts.log_service import ILogger
 from orionis.support.wrapper.dataclass import DataClass
 
 class Application(Container, IApplication):
     """
-    Main application container that manages the complete application lifecycle.
-
-    This class extends the Container to provide comprehensive application-level
-    functionality including service provider registration and bootstrapping, kernel
-    management, configuration handling, and application initialization. It implements
-    a fluent interface pattern to enable method chaining for configuration setup.
-
-    The Application class serves as the central orchestrator for the Orionis framework,
-    managing the loading and booting of service providers, framework kernels, and
-    various configuration subsystems such as authentication, caching, database,
-    logging, and more.
+    Application: Main container that manages the complete lifecycle of the Orionis application.
+
+    This class extends `Container` and acts as the central core of the Orionis framework,
+    orchestrating initialization, configuration, registration, and bootstrapping of all
+    application components and services. It follows a fluent interface pattern, enabling
+    method chaining for clear and concise configuration.
+
+    Key Responsibilities:
+    ---------------------
+    - Registers and boots both native and user-defined service providers, ensuring all
+        dependencies and services are available throughout the application lifecycle.
+    - Loads and manages essential framework kernels (CLI, testing, etc.), guaranteeing
+        that core components are properly initialized and accessible.
+    - Centralizes configuration management for all critical subsystems: authentication,
+        cache, database, logging, mail, queue, routing, storage, session, testing, and more.
+    - Provides methods for customizing and extending the application architecture,
+        supporting dynamic configurator loading and seamless integration of additional services.
+    - Implements mechanisms for custom exception handling and schedulers, enhancing
+        robustness and flexibility across the application lifecycle.
+    - Exposes utilities for accessing configuration and path settings using dot notation.
+
+    Typical Workflow:
+    -----------------
+    1. Instantiate the Application class.
+    2. Register providers and configurators via `withProviders` and `withConfigurators`.
+    3. Optionally customize exception handlers and schedulers.
+    4. Call `create()` to initialize and boot the application, loading kernels and providers.
+    5. Access services, configuration, and paths through the Application instance.
 
     Attributes
     ----------
     isBooted : bool
-        Read-only property indicating whether the application providers have been booted.
+            Read-only property indicating whether the application providers have been booted.
     startAt : int
-        Read-only property containing the timestamp when the application was started.
+            Read-only property containing the timestamp (epoch) when the application was started.
     """
 
     @property
@@ -162,11 +178,7 @@ class Application(Container, IApplication):
 
         # Register each kernel instance
         for abstract, concrete in core_kernels.items():
-            self.instance(
-                abstract,
-                concrete(self),
-                alias=f"x-{abstract.__module__}.{abstract.__name__}"
-            )
+            self.instance(abstract, concrete(self), alias=f"x-{abstract.__module__}.{abstract.__name__}")
 
     def __loadFrameworkProviders(
         self
@@ -324,75 +336,102 @@ class Application(Container, IApplication):
         """
         Instantiate and register all service providers in the container.
 
-        This method iterates through all added provider classes, instantiates them
-        with the current application instance, and calls their register() method
-        to bind services into the dependency injection container. Supports both
-        synchronous and asynchronous registration methods.
+        This private method iterates through all service provider classes previously added to the application,
+        instantiates each provider with the current application instance, and invokes their `register()` method
+        to bind services into the dependency injection container. Both synchronous and asynchronous `register()`
+        methods are supported and handled appropriately.
+
+        After registration, the internal providers list is updated to contain the instantiated provider objects
+        instead of class references. This ensures that subsequent booting operations are performed on the actual
+        provider instances.
 
         Notes
         -----
-        This is a private method called during application bootstrapping. After
-        registration, the providers list is updated to contain instantiated provider
-        objects rather than class references. The method handles both coroutine
-        and regular register methods using asyncio when necessary.
+        - This method is called automatically during application bootstrapping.
+        - Handles both coroutine and regular `register()` methods using `asyncio` when necessary.
+        - The providers list is updated in-place to hold provider instances.
+
+        Returns
+        -------
+        None
+            This method does not return any value. It updates the internal state of the application by
+            replacing the provider class references with their instantiated objects.
         """
 
-        # Ensure providers list is empty before registration
+        # Prepare a list to hold initialized provider instances
         initialized_providers = []
 
-        # Iterate over each provider and register it
-        for provider in self.__providers:
+        # Iterate over each provider class in the providers list
+        for provider_cls in self.__providers:
 
-            # Initialize the provider
-            class_provider: IServiceProvider = provider(self)
+            # Instantiate the provider with the current application instance
+            provider_instance = provider_cls(self)
 
-            # Register the provider in the container
-            # Check if register is a coroutine function
-            if asyncio.iscoroutinefunction(class_provider.register):
-                Coroutine(class_provider.register).run()
-            else:
-                class_provider.register()
+            # Retrieve the 'register' method if it exists
+            register_method = getattr(provider_instance, 'register', None)
+
+            # If the register method exists, call it
+            if callable(register_method):
 
-            # Add the initialized provider to the list
-            initialized_providers.append(class_provider)
+                # If the register method is a coroutine, run it asynchronously
+                if asyncio.iscoroutinefunction(register_method):
+                    asyncio.run(register_method())
 
-        # Update the providers list with initialized providers
+                # Otherwise, call it synchronously
+                else:
+                    register_method()
+
+            # Add the initialized provider instance to the list
+            initialized_providers.append(provider_instance)
+
+        # Replace the providers list with the list of initialized provider instances
         self.__providers = initialized_providers
 
     def __bootProviders(
         self
     ) -> None:
         """
-        Execute the boot process for all registered service providers.
+        Boot all registered service providers after registration.
 
-        This method calls the boot() method on each instantiated service provider
-        to initialize services after all providers have been registered. This
-        two-phase process ensures all dependencies are available before any
-        provider attempts to use them. Supports both synchronous and asynchronous
-        boot methods.
+        This private method iterates through all instantiated service providers and calls their
+        `boot()` method to perform any post-registration initialization. This two-phase approach
+        ensures that all dependencies are registered before any provider attempts to use them.
+        Both synchronous and asynchronous `boot()` methods are supported.
+
+        After all providers have been booted, the internal providers list is cleared to free memory,
+        as provider instances are no longer needed after initialization.
 
         Notes
         -----
-        This is a private method called during application bootstrapping after
-        provider registration is complete. After booting, the providers list is
-        deleted to prevent memory leaks since providers are no longer needed
-        after initialization.
+        - This method is called automatically during application bootstrapping, after all providers
+          have been registered.
+        - Supports both synchronous and asynchronous `boot()` methods on providers.
+        - The providers list is cleared after booting to prevent memory leaks.
+
+        Returns
+        -------
+        None
+            This method does not return any value.
         """
 
-        # Iterate over each provider and boot it
+        # Iterate over each initialized provider and call its boot method if available
         for provider in self.__providers:
 
-            # Ensure provider is initialized before calling boot
-            if hasattr(provider, 'boot') and callable(getattr(provider, 'boot')):
-                # Check if boot is a coroutine function
-                if asyncio.iscoroutinefunction(provider.boot):
-                    Coroutine(provider.boot).run()
+            # Get the boot method if it exists
+            boot_method = getattr(provider, 'boot', None)
+
+            if callable(boot_method):
+
+                # If the boot method is a coroutine, run it asynchronously
+                if asyncio.iscoroutinefunction(boot_method):
+                    asyncio.run(boot_method())
+
+                # Otherwise, call it synchronously
                 else:
-                    provider.boot()
+                    boot_method()
 
-        # Remove the __providers attribute to prevent memory leaks
-        if hasattr(self, '_Application__providers'):
-            del self.__providers
+        # Clear the providers list to free memory after booting is complete
+        self.__providers.clear()
 
     # === Application Skeleton Configuration Methods ===
     # The Orionis framework provides methods to configure each component of the application,

orionis/foundation/exceptions/application.py

@@ -1,11 +1,58 @@
 class OrionisIntegrityException(Exception):
-    pass
+    """
+    Exception raised for integrity-related errors in the Orionis framework.
+
+    This exception is intended to signal violations of data integrity or
+    consistency constraints within the application.
+
+    Returns
+    -------
+    OrionisIntegrityException
+        An instance of the exception.
+    """
+    pass  # No additional logic; inherits from base Exception
+
 
 class OrionisRuntimeError(RuntimeError):
-    pass
+    """
+    Exception raised for runtime errors specific to the Orionis framework.
+
+    This exception should be used when an error occurs that is only detectable
+    during program execution.
+
+    Returns
+    -------
+    OrionisRuntimeError
+        An instance of the exception.
+    """
+    pass  # Inherits from Python's built-in RuntimeError
+
 
 class OrionisTypeError(TypeError):
-    pass
+    """
+    Exception raised for type errors in the Orionis framework.
+
+    This exception is used when an operation or function receives an argument
+    of an inappropriate type.
+
+    Returns
+    -------
+    OrionisTypeError
+        An instance of the exception.
+    """
+    pass  # Inherits from Python's built-in TypeError
+
 
 class OrionisValueError(ValueError):
-    pass
+    """
+    Exception raised for value errors in the Orionis framework.
+
+    This exception is used when an operation or function receives an argument
+    with the right type but an inappropriate value.
+
+    Returns
+    -------
+    OrionisValueError
+        An instance of the exception.
+    """
+    pass  # Inherits from Python's built-in ValueError

orionis/foundation/providers/catch_provider.py

@@ -3,47 +3,26 @@ from orionis.failure.catch import Catch
 from orionis.failure.contracts.catch import ICatch
 
 class CathcProvider(ServiceProvider):
-    """
-    Provides and registers the Catch service within the application container.
-
-    This service provider is responsible for binding the ICatch interface to its concrete
-    implementation, Catch, as a singleton. By doing so, it ensures that a single shared
-    instance of Catch is available for dependency injection throughout the application.
-
-    Returns
-    -------
-    None
-        This class does not return a value; it is used for service registration.
-    """
 
     def register(self) -> None:
         """
-        Register the Catch service as a singleton in the application container.
+        Registers the Catch service as a singleton in the application container.
 
-        This method binds the ICatch interface to the Catch implementation with an alias,
-        ensuring that only one instance of Catch is created and shared.
+        This method binds the `ICatch` interface to the `Catch` implementation as a singleton,
+        using a specific alias. This ensures that only one instance of `Catch` is created and
+        shared throughout the application's lifecycle. The binding allows the application to
+        resolve dependencies on `ICatch` with the registered `Catch` instance.
 
-        Returns
-        -------
+        Parameters
+        ----------
         None
-            This method does not return any value.
-        """
-
-        # Bind ICatch to Catch as a singleton with a specific alias
-        self.app.singleton(ICatch, Catch, alias=f"x-{ICatch.__module__}.{ICatch.__name__}")
-
-    def boot(self) -> None:
-        """
-        Perform any actions required after all providers have been registered.
-
-        This method is called after the register phase and can be used to perform
-        additional initialization if needed.
 
         Returns
         -------
         None
-            This method does not return any value.
+            This method does not return any value. It performs the registration as a side effect.
         """
 
-        # No additional boot logic required for this provider
-        pass
+        # Register the Catch implementation as a singleton for the ICatch interface
+        # The alias allows for explicit resolution by name if needed
+        self.app.singleton(ICatch, Catch, alias="x-orionis.failure.contracts.catch.ICatch")

orionis/foundation/providers/cli_request_provider.py

@@ -3,42 +3,27 @@ from orionis.console.request.cli_request import CLIRequest
 from orionis.container.providers.service_provider import ServiceProvider
 
 class CLRequestProvider(ServiceProvider):
-    """
-    Service provider for registering CLI request services in the Orionis framework.
-
-    This provider handles the registration and binding of CLI request interfaces
-    to their concrete implementations within the application container.
-    """
 
     def register(self) -> None:
         """
-        Register CLI request services in the application container.
+        Registers the CLI request services in the application container.
 
-        Binds the ICLIRequest interface to the CLIRequest implementation as a
-        transient service, making it available for dependency injection throughout
-        the application with the specified alias.
+        This method binds the `ICLIRequest` interface to the `CLIRequest` implementation
+        as a transient service within the application's dependency injection container.
+        By registering this binding, any component that depends on `ICLIRequest` will
+        receive a new instance of `CLIRequest` each time it is resolved. The binding is
+        also associated with a specific alias for reference within the container.
 
-        Returns
-        -------
+        Parameters
+        ----------
         None
-            This method does not return any value.
-        """
-        # Register CLIRequest as a transient service bound to ICLIRequest interface
-        # Transient services create a new instance each time they are resolved
-        self.app.transient(ICLIRequest, CLIRequest, alias=f"x-{ICLIRequest.__module__}.{ICLIRequest.__name__}")
-
-    def boot(self) -> None:
-        """
-        Perform any necessary bootstrapping after service registration.
-
-        This method is called after all services have been registered and can be
-        used to perform additional setup or configuration tasks. Currently, no
-        bootstrapping logic is required for CLI request services.
 
         Returns
         -------
         None
-            This method does not return any value.
+            This method does not return any value. It performs registration as a side effect.
         """
-        # No bootstrapping logic required for CLI request services
-        pass
+
+        # Bind the ICLIRequest interface to the CLIRequest implementation as a transient service.
+        # Each resolution of ICLIRequest will provide a new CLIRequest instance.
+        self.app.transient(ICLIRequest, CLIRequest, alias="x-orionis.console.contracts.cli_request.ICLIRequest")

orionis/foundation/providers/console_provider.py

@@ -3,63 +3,29 @@ from orionis.console.contracts.console import IConsole
 from orionis.container.providers.service_provider import ServiceProvider
 
 class ConsoleProvider(ServiceProvider):
-    """
-    Console output service provider for the Orionis framework.
-
-    This service provider is responsible for registering and configuring the console
-    output service within the application's dependency injection container. It binds
-    the IConsole interface to its concrete Console implementation, enabling the
-    application to access comprehensive console output functionality including
-    informational messages, warnings, errors, debug output, tabular data display,
-    user confirmations, and secure password input prompts.
-
-    The provider follows the standard service provider pattern, implementing both
-    registration and boot phases for proper initialization within the application
-    lifecycle.
-    """
 
     def register(self) -> None:
         """
-        Register the console output service in the application's dependency injection container.
+        Registers the console output service within the application's dependency injection container.
 
-        This method binds the IConsole interface to its concrete Console implementation,
-        making console output functionality available throughout the application. The
-        service is registered as a transient dependency, meaning a new instance will
-        be created each time it is requested from the container.
+        This method binds the `IConsole` interface to its concrete `Console` implementation,
+        enabling console output functionality to be injected wherever required in the application.
+        The service is registered as a transient dependency, ensuring that a new instance of
+        `Console` is created each time the service is resolved from the container. The registration
+        uses a predefined alias to maintain consistent service identification and facilitate
+        straightforward service resolution throughout the framework.
 
-        The registration uses a predefined alias to ensure consistent service
-        identification across the framework and facilitate easy service resolution.
-
-        Returns
-        -------
+        Parameters
+        ----------
         None
-            This method does not return any value. It performs side effects by
-            modifying the application's service container.
-        """
-
-        self.app.transient(IConsole, Console, alias=f"x-{IConsole.__module__}.{IConsole.__name__}")
-
-    def boot(self) -> None:
-        """
-        Perform post-registration initialization for the console provider.
-
-        This method is called after the registration phase is complete and all services
-        have been registered in the container. It provides an opportunity to perform
-        any additional setup, configuration, or initialization that depends on other
-        services being available in the container.
-
-        Currently, this implementation serves as a placeholder and does not perform
-        any specific initialization tasks. The console service is fully functional
-        after registration and does not require additional boot-time configuration.
-
-        This method is part of the service provider lifecycle and is automatically
-        invoked by the framework during application startup.
 
         Returns
         -------
         None
-            This method does not return any value and is called for its side effects
-            during the service provider boot phase.
+            This method does not return any value. It performs side effects by
+            modifying the application's service container to register the console service.
         """
 
-        pass
+        # Register the IConsole interface to the Console implementation as a transient service.
+        # This ensures a new Console instance is provided on each resolution.
+        self.app.transient(IConsole, Console, alias="x-orionis.console.contracts.console.IConsole")

orionis/foundation/providers/directory_provider.py

@@ -3,53 +3,27 @@ from orionis.services.file.contracts.directory import IDirectory
 from orionis.services.file.directory import Directory
 
 class DirectoryProvider(ServiceProvider):
-    """
-    Service provider for registering the directory service in the application container.
-
-    This provider binds the `IDirectory` interface to its concrete implementation (`Directory`)
-    as a singleton. This ensures that a single shared instance of the directory service is
-    available for dependency injection throughout the application.
-
-    Attributes
-    ----------
-    app : Application
-        The application container instance where services are registered.
-
-    Methods
-    -------
-    register()
-        Registers the directory service as a singleton in the application container.
-    boot()
-        Performs post-registration actions if necessary.
-    """
 
     def register(self) -> None:
         """
-        Register the directory service as a singleton in the application container.
+        Registers the directory service as a singleton within the application container.
 
-        This method binds the `IDirectory` interface to the `Directory` implementation with
-        a specific alias. Only one instance of `Directory` will be created and shared
-        throughout the application's lifecycle.
+        This method binds the `IDirectory` interface to its concrete implementation `Directory`
+        as a singleton. The binding is associated with a specific alias, ensuring that only one
+        instance of `Directory` is created and shared across the application's lifecycle. This
+        promotes efficient resource usage and consistent behavior when accessing directory-related
+        services.
 
-        Returns
-        -------
+        Parameters
+        ----------
         None
-            This method does not return any value.
-        """
-        # Bind IDirectory to Directory as a singleton with a specific alias
-        self.app.singleton(IDirectory, Directory, alias=f"x-{IDirectory.__module__}.{IDirectory.__name__}")
-
-    def boot(self) -> None:
-        """
-        Perform actions required after all providers have been registered.
-
-        This method is called after the `register` phase. It can be used for additional
-        initialization if needed. No additional boot logic is required for this provider.
 
         Returns
         -------
         None
-            This method does not return any value.
+            This method does not return any value. It performs registration as a side effect.
         """
-        # No additional boot logic required for this provider
-        pass
+
+        # Bind the IDirectory interface to the Directory implementation as a singleton.
+        # The alias ensures unique identification within the container.
+        self.app.singleton(IDirectory, Directory, alias="x-orionis.services.file.contracts.directory.IDirectory")