orionis 0.613.0__tar.gz → 0.615.0__tar.gz

{orionis-0.613.0/orionis.egg-info → orionis-0.615.0}/PKG-INFO

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

orionis-0.615.0/orionis/container/providers/service_provider.py

@@ -0,0 +1,72 @@
+from orionis.container.contracts.service_provider import IServiceProvider
+from orionis.foundation.contracts.application import IApplication
+
+class ServiceProvider(IServiceProvider):
+    """
+    Base class for service providers in the Orionis framework.
+
+    Service providers are responsible for registering and bootstrapping
+    services and components into the application container.
+
+    Parameters
+    ----------
+    app : IApplication
+        The application container instance to which services will be registered.
+    """
+
+    def __init__(self, app: IApplication) -> None:
+        """
+        Initialize a new ServiceProvider instance with the given application container.
+
+        Parameters
+        ----------
+        app : IApplication
+            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 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.
+        """
+
+        # Optionally overridden by subclasses to register services
+        pass
+
+    async def boot(self) -> None:
+        """
+        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.
+
+        Returns
+        -------
+        None
+            This method does not return a value.
+        """
+
+        # Optionally overridden by subclasses to perform boot-time operations
+        pass

{orionis-0.613.0 → orionis-0.615.0}/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-0.615.0/orionis/foundation/exceptions/application.py

@@ -0,0 +1,58 @@
+class OrionisIntegrityException(Exception):
+    """
+    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):
+    """
+    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):
+    """
+    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):
+    """
+    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-0.615.0/orionis/foundation/providers/catch_provider.py

@@ -0,0 +1,28 @@
+from orionis.container.providers.service_provider import ServiceProvider
+from orionis.failure.catch import Catch
+from orionis.failure.contracts.catch import ICatch
+
+class CathcProvider(ServiceProvider):
+
+    def register(self) -> None:
+        """
+        Registers the Catch service as a singleton in the application container.
+
+        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.
+
+        Parameters
+        ----------
+        None
+
+        Returns
+        -------
+        None
+            This method does not return any value. It performs the registration as a side effect.
+        """
+
+        # 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-0.615.0/orionis/foundation/providers/cli_request_provider.py

@@ -0,0 +1,29 @@
+from orionis.console.contracts.cli_request import ICLIRequest
+from orionis.console.request.cli_request import CLIRequest
+from orionis.container.providers.service_provider import ServiceProvider
+
+class CLRequestProvider(ServiceProvider):
+
+    def register(self) -> None:
+        """
+        Registers the CLI request services in the application container.
+
+        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.
+
+        Parameters
+        ----------
+        None
+
+        Returns
+        -------
+        None
+            This method does not return any value. It performs registration as a side effect.
+        """
+
+        # 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-0.615.0/orionis/foundation/providers/console_provider.py

@@ -0,0 +1,31 @@
+from orionis.console.output.console import Console
+from orionis.console.contracts.console import IConsole
+from orionis.container.providers.service_provider import ServiceProvider
+
+class ConsoleProvider(ServiceProvider):
+
+    def register(self) -> None:
+        """
+        Registers the console output service within the application's dependency injection 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.
+
+        Parameters
+        ----------
+        None
+
+        Returns
+        -------
+        None
+            This method does not return any value. It performs side effects by
+            modifying the application's service container to register the console service.
+        """
+
+        # 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-0.615.0/orionis/foundation/providers/directory_provider.py

@@ -0,0 +1,29 @@
+from orionis.container.providers.service_provider import ServiceProvider
+from orionis.services.file.contracts.directory import IDirectory
+from orionis.services.file.directory import Directory
+
+class DirectoryProvider(ServiceProvider):
+
+    def register(self) -> None:
+        """
+        Registers the directory service as a singleton within the application container.
+
+        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.
+
+        Parameters
+        ----------
+        None
+
+        Returns
+        -------
+        None
+            This method does not return any value. It performs registration as a side effect.
+        """
+
+        # 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")

orionis-0.615.0/orionis/foundation/providers/dumper_provider.py

@@ -0,0 +1,29 @@
+from orionis.console.dumper.debug import Debug
+from orionis.console.contracts.debug import IDebug
+from orionis.container.providers.service_provider import ServiceProvider
+
+class DumperProvider(ServiceProvider):
+
+    def register(self) -> None:
+        """
+        Registers the debug service in the application container.
+
+        This method binds the `IDebug` interface to its concrete implementation, the `Debug` class,
+        within the application's dependency injection container. The service is registered as
+        transient, ensuring that a new instance is created each time it is requested. Additionally,
+        an alias is assigned to the service for convenient retrieval throughout the application.
+
+        This registration enables the application to resolve dependencies related to debugging,
+        error reporting, and console diagnostics by referencing the interface or its alias.
+
+        Returns
+        -------
+        None
+            This method does not return any value. It performs side effects by modifying
+            the application's service registry.
+        """
+
+        # Register the Debug service as a transient binding for the IDebug interface.
+        # A new instance of Debug will be created each time it is requested.
+        # The alias allows for easy retrieval of the service elsewhere in the application.
+        self.app.transient(IDebug, Debug, alias=f"x-orionis.console.contracts.debug.IDebug")

orionis-0.615.0/orionis/foundation/providers/executor_provider.py

@@ -0,0 +1,31 @@
+from orionis.console.contracts.executor import IExecutor
+from orionis.console.output.executor import Executor
+from orionis.container.providers.service_provider import ServiceProvider
+
+class ConsoleExecuteProvider(ServiceProvider):
+
+    def register(self) -> None:
+        """
+        Registers the console executor service within the application container.
+
+        This method binds the `IExecutor` interface to its concrete `Executor` implementation
+        as a transient service. Each time the service is requested from the container, a new
+        instance of `Executor` is created, ensuring isolated execution contexts for console
+        operations. The service is registered with the alias
+        `"x-orionis.console.contracts.executor.IExecutor"` for convenient retrieval and
+        identification within the dependency injection container.
+
+        Parameters
+        ----------
+        None
+
+        Returns
+        -------
+        None
+            This method does not return any value. It performs the side effect of
+            registering the executor service binding in the application container.
+        """
+
+        # Bind the IExecutor interface to the Executor implementation as a transient service.
+        # This ensures a new Executor instance is created on each request.
+        self.app.transient(IExecutor, Executor, alias="x-orionis.console.contracts.executor.IExecutor")

orionis-0.615.0/orionis/foundation/providers/inspirational_provider.py

@@ -0,0 +1,28 @@
+from orionis.container.providers.service_provider import ServiceProvider
+from orionis.services.inspirational.contracts.inspire import IInspire
+from orionis.services.inspirational.inspire import Inspire
+
+class InspirationalProvider(ServiceProvider):
+
+    def register(self) -> None:
+        """
+        Registers the inspirational service as a transient binding in the application container.
+
+        This method binds the `IInspire` interface to its concrete implementation `Inspire`
+        as a transient service within the application's service container. Each time the
+        service is requested, a new instance of `Inspire` will be provided. The service is
+        also registered with a specific alias to facilitate convenient resolution and
+        identification throughout the application.
+
+        This registration enables dependency injection, allowing other components to
+        receive an instance of `Inspire` whenever the `IInspire` contract is requested.
+
+        Returns
+        -------
+        None
+            This method does not return any value. It performs service registration as a side effect.
+        """
+
+        # Register the IInspire contract to the Inspire implementation as a transient service.
+        # Each resolution from the container will provide a new instance.
+        self.app.transient(IInspire, Inspire, alias="x-orionis.services.inspirational.contracts.inspire.IInspire")

orionis-0.615.0/orionis/foundation/providers/logger_provider.py

@@ -0,0 +1,36 @@
+from orionis.container.providers.service_provider import ServiceProvider
+from orionis.services.log.contracts.log_service import ILogger
+from orionis.services.log.log_service import Logger
+
+class LoggerProvider(ServiceProvider):
+
+    def register(self) -> None:
+        """
+        Registers the Logger service implementation in the application container.
+
+        This method binds the `Logger` class to the `ILogger` contract within the application's
+        dependency injection container. It retrieves the logging configuration from the application,
+        creates a `Logger` instance using this configuration, and registers it with an alias for
+        internal framework identification. This setup allows the logging service to be resolved
+        and used throughout the application via 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.
+        """
+
+        # Retrieve the logging configuration from the application
+        logging_config = self.app.config('logging')
+
+        # Instantiate the Logger with the retrieved configuration
+        logger_instance = Logger(logging_config)
+
+        # Register the Logger instance in the application container,
+        # binding it to the ILogger contract and assigning an alias
+        self.app.instance(ILogger, logger_instance, alias="x-orionis.services.log.contracts.log_service.ILogger")

orionis-0.615.0/orionis/foundation/providers/performance_counter_provider.py

@@ -0,0 +1,38 @@
+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 to the `PerformanceCounter` implementation
+        within the application's dependency injection container. The binding uses a transient lifetime,
+        ensuring that each resolution of the service provides a new instance of `PerformanceCounter`.
+        This is useful for scenarios where independent timing or measurement operations are required
+        across different parts of the application.
+
+        An alias, `"x-orionis.support.performance.contracts.counter.IPerformanceCounter"`, is also
+        assigned to this binding, enabling alternative resolution or referencing of the service by name.
+
+        Parameters
+        ----------
+        None
+
+        Returns
+        -------
+        None
+            This method does not return any value. It performs service registration as a side effect.
+
+        Notes
+        -----
+        - The transient lifetime ensures that each consumer receives a separate instance of the service.
+        - The alias allows for flexible service resolution by a specific name.
+        """
+
+        # Register the IPerformanceCounter interface to the PerformanceCounter implementation
+        # with a transient lifetime. Each resolution yields a new instance.
+        # Assign an alias for alternative resolution by name.
+        self.app.transient(IPerformanceCounter, PerformanceCounter, alias="x-orionis.support.performance.contracts.counter.IPerformanceCounter")