orionis 0.436.0__py3-none-any.whl → 0.437.0__py3-none-any.whl

orionis/foundation/contracts/config.py

@@ -2,22 +2,30 @@ from abc import ABC, abstractmethod
 
 class IConfig(ABC):
     """
-    An abstract base class that defines an interface for classes that must have
-    a `config` attribute.
+    Abstract base class for configuration holders.
 
-    The subclass is required to implement the `config` attribute, which should be
-    a dataclass instance representing the configuration data.
+    This interface enforces the presence of a `config` attribute in subclasses,
+    which must return a dataclass instance containing configuration data.
 
     Attributes
     ----------
     config : object
-        A dataclass instance representing the configuration.
+        Dataclass instance representing the configuration data.
     """
 
     @property
     @abstractmethod
     def config(self):
         """
-        Should return a dataclass instance representing the configuration.
+        Get the configuration dataclass instance.
+
+        Returns
+        -------
+        object
+            Dataclass instance containing the configuration data.
+
+        Notes
+        -----
+        Subclasses must implement this property to provide access to their configuration.
         """
         pass

orionis/foundation/providers/console_provider.py

@@ -4,36 +4,37 @@ from orionis.container.providers.service_provider import ServiceProvider
 
 class ConsoleProvider(ServiceProvider):
     """
-    ConsoleProvider
-    ===============
-
-    Registers the console output service in the application container.
-    Provides access to various console output features, including information, warnings, errors, debug messages, tables, confirmations, and password prompts.
-
-    Methods
-    -------
-    register()
-        Registers the console service in the application container.
-    boot()
-        Performs post-registration initialization if needed.
+    Provides and registers the console output service within the application container.
+
+    This provider binds the console output interface to its concrete implementation,
+    enabling access to various console output features such as information, warnings,
+    errors, debug messages, tables, confirmations, and password prompts.
     """
 
     def register(self) -> None:
         """
-        Registers the console service in the application container.
+        Register the console output service in the application container.
+
+        Binds the IConsole interface to the Console implementation as a transient service,
+        with the alias "core.orionis.console".
 
         Returns
         -------
         None
         """
+
         self.app.transient(IConsole, Console, alias="core.orionis.console")
 
     def boot(self) -> None:
         """
-        Performs post-registration initialization if needed.
+        Perform post-registration initialization for the console provider.
+
+        This method is a placeholder for any additional setup required after
+        registration. Currently, it does not perform any actions.
 
         Returns
         -------
         None
         """
-        pass
+
+        pass

orionis/foundation/providers/dumper_provider.py

@@ -4,36 +4,48 @@ from orionis.container.providers.service_provider import ServiceProvider
 
 class DumperProvider(ServiceProvider):
     """
-    DumperProvider
-    ==============
+    Service provider for registering the debug message service.
 
-    Registers the debug message service in the application container.
-    Provides access to debug message printing, error reporting, and other console diagnostics.
+    This provider registers the debug service in the application container,
+    enabling debug message printing, error reporting, and console diagnostics.
+
+    Attributes
+    ----------
+    app : Application
+        The application container instance where services are registered.
 
     Methods
     -------
     register()
-        Registers the debug service in the application container.
+        Register the debug service in the application container.
     boot()
-        Performs post-registration initialization if needed.
+        Perform post-registration initialization if required.
     """
 
     def register(self) -> None:
         """
-        Registers the debug service in the application container.
+        Register the debug service in the application container.
+
+        Registers the `IDebug` interface with the `Debug` implementation
+        as a transient service, using the alias "core.orionis.dumper".
 
         Returns
         -------
         None
         """
+
         self.app.transient(IDebug, Debug, alias="core.orionis.dumper")
 
     def boot(self) -> None:
         """
-        Performs post-registration initialization if needed.
+        Perform post-registration initialization if required.
+
+        This method is a placeholder for any initialization logic that
+        should occur after the service has been registered.
 
         Returns
         -------
         None
         """
+
         pass

orionis/foundation/providers/logger_provider.py

@@ -4,36 +4,41 @@ from orionis.services.log.log_service import LoggerService
 
 class LoggerProvider(ServiceProvider):
     """
-    LoggerProvider
-    ==============
-
-    Registers the logging service in the application container.
-    Provides a `LoggerService` instance for application-wide logging.
-
-    Methods
-    -------
-    register()
-        Registers the logging service in the application container.
-    boot()
-        Performs post-registration initialization if needed.
+    Provides and registers the logging service within the application container.
+
+    This provider binds an implementation of `ILoggerService` to the application,
+    making a `LoggerService` instance available for application-wide logging.
+
+    Attributes
+    ----------
+    app : Application
+        The application container instance where services are registered.
     """
 
     def register(self) -> None:
         """
-        Registers the logging service in the application container.
+        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.
 
         Returns
         -------
         None
         """
+
         self.app.instance(ILoggerService, LoggerService(self.app.config('logging')), alias="core.orionis.logger")
 
     def boot(self) -> None:
         """
-        Performs post-registration initialization if needed.
+        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.
 
         Returns
         -------
         None
         """
+
         pass

orionis/foundation/providers/path_resolver_provider.py

@@ -4,37 +4,40 @@ from orionis.services.paths.resolver import Resolver
 
 class PathResolverProvider(ServiceProvider):
     """
-    PathResolverProvider
-    ===================
-
     Registers the path resolution service in the application container.
-    Provides compatibility with the file system for resolving paths.
-
-    Methods
-    -------
-    register()
-        Registers the path resolver service in the application container.
-    boot()
-        Performs post-registration initialization if needed.
-    """
 
+    This provider binds the `IResolver` interface to the `Resolver` implementation,
+    allowing the application to resolve file system paths through dependency injection.
+
+    Attributes
+    ----------
+    app : Application
+        The application container instance inherited from ServiceProvider.
+    """
 
     def register(self) -> None:
         """
-        Registers the path resolver service in the application container.
+        Register the path resolver service in the application container.
+
+        Binds the `IResolver` interface to the `Resolver` implementation as a transient
+        service, with the alias "core.orionis.path_resolver".
 
         Returns
         -------
         None
         """
+
         self.app.transient(IResolver, Resolver, alias="core.orionis.path_resolver")
 
     def boot(self) -> None:
         """
-        Performs post-registration initialization if needed.
+        Perform post-registration initialization if needed.
+
+        This method is a placeholder for any actions required after service registration.
 
         Returns
         -------
         None
         """
+
         pass

orionis/foundation/providers/progress_bar_provider.py

@@ -4,36 +4,37 @@ from orionis.container.providers.service_provider import ServiceProvider
 
 class ProgressBarProvider(ServiceProvider):
     """
-    ProgressBarProvider
-    ===================
-
-    Registers the dynamic progress bar service in the application container.
-    Provides a console progress bar for visual feedback during operations.
-
-    Methods
-    -------
-    register()
-        Registers the progress bar service in the application container.
-    boot()
-        Performs post-registration initialization if needed.
+    Service provider for registering the dynamic progress bar.
+
+    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.
     """
 
     def register(self) -> None:
         """
-        Registers the progress bar service in the application container.
+        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".
 
         Returns
         -------
         None
         """
+
         self.app.transient(IProgressBar, ProgressBar, alias="core.orionis.progress_bar")
 
     def boot(self) -> None:
         """
-        Performs post-registration initialization if needed.
+        Perform post-registration initialization.
+
+        This method is called after all providers have been registered. No additional
+        initialization is required for the progress bar service.
 
         Returns
         -------
         None
         """
+
         pass

orionis/foundation/providers/testing_provider.py

@@ -4,36 +4,42 @@ from orionis.test.core.unit_test import UnitTest
 
 class TestingProvider(ServiceProvider):
     """
-    TestingProvider
-    ===============
-
-    Registers the unit testing environment service in the application container.
-    Provides a native unit testing framework for Orionis with features beyond common frameworks.
-
-    Methods
-    -------
-    register()
-        Registers the unit testing service in the application container.
-    boot()
-        Performs post-registration initialization if needed.
+    Provides and registers the unit testing environment service in the application container.
+
+    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.
+
+    Attributes
+    ----------
+    app : Application
+        The application container instance where services are registered.
     """
 
     def register(self) -> None:
         """
-        Registers the unit testing service in the application container.
+        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".
 
         Returns
         -------
         None
         """
+
         self.app.singleton(IUnitTest, UnitTest, alias="core.orionis.testing")
 
     def boot(self) -> None:
         """
-        Performs post-registration initialization if needed.
+        Perform post-registration initialization if required.
+
+        This method is intended for any setup needed after service registration.
+        Currently, no additional initialization is performed.
 
         Returns
         -------
         None
         """
+
         pass

orionis/foundation/providers/workers_provider.py

@@ -4,36 +4,41 @@ from orionis.services.system.workers import Workers
 
 class WorkersProvider(ServiceProvider):
     """
-    WorkersProvider
-    ===============
-
-    Registers the worker management service in the application container.
-    Determines the optimal number of workers to start based on system analysis.
-
-    Methods
-    -------
-    register()
-        Registers the worker service in the application container.
-    boot()
-        Performs post-registration initialization if needed.
+    Provides and registers the worker management service within the application container.
+
+    This provider determines and registers the optimal worker management implementation,
+    making it available for dependency injection throughout the application.
+
+    Attributes
+    ----------
+    app : Application
+        The application container instance where services are registered.
     """
 
     def register(self) -> None:
         """
-        Registers the worker service in the application container.
+        Register the worker service in the application container.
+
+        Registers the `Workers` implementation as a transient service for the `IWorkers`
+        contract, with the alias "core.orionis.workers".
 
         Returns
         -------
         None
         """
+
         self.app.transient(IWorkers, Workers, alias="core.orionis.workers")
 
     def boot(self) -> None:
         """
-        Performs post-registration initialization if needed.
+        Perform post-registration initialization if required.
+
+        This method is a placeholder for any initialization logic that should occur
+        after the worker service has been registered.
 
         Returns
         -------
         None
         """
+
         pass

orionis/metadata/framework.py

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

orionis/services/asynchrony/contracts/coroutines.py

@@ -23,5 +23,6 @@ class ICoroutine(ABC):
         - Schedules the coroutine for asynchronous execution and returns a Future when called inside an event loop.
         - The caller is responsible for awaiting the Future if asynchronous execution is used.
         """
+
         # This method should be implemented by subclasses to handle coroutine execution.
         pass

orionis/services/asynchrony/coroutines.py

@@ -22,6 +22,7 @@ class Coroutine(ICoroutine):
         OrionisCoroutineException
             If the provided object is not a coroutine.
         """
+
         # Validate that the provided object is a coroutine
         if not Type(func).isCoroutine():
             raise OrionisCoroutineException(
@@ -51,6 +52,7 @@ class Coroutine(ICoroutine):
         - If called within an active event loop, the coroutine is scheduled for asynchronous execution and a Future is returned.
         - The method automatically detects the execution context and chooses the appropriate execution strategy.
         """
+
         # Attempt to get the currently running event loop
         try:
             loop = asyncio.get_running_loop()

orionis/services/asynchrony/exceptions/exception.py

@@ -9,6 +9,7 @@ class OrionisCoroutineException(Exception):
         msg : str
             A descriptive error message explaining the cause of the exception.
         """
+
         # Call the base Exception constructor with the provided message
         super().__init__(msg)
 
@@ -21,5 +22,6 @@ class OrionisCoroutineException(Exception):
         str
             The error message provided during exception initialization.
         """
+
         # Return the first argument passed to the Exception, which is the error message
         return str(self.args[0])

orionis/services/environment/core/dot_env.py

@@ -61,6 +61,11 @@ class DotEnv(metaclass=Singleton):
             # Raise an error if the .env file cannot be created or accessed
             raise OSError(f"Failed to create or access the .env file at {self.__resolved_path}: {e}")
 
+        except Exception as e:
+
+            # Raise a general error for any other exceptions during initialization
+            raise Exception(f"An unexpected error occurred while initializing DotEnv: {e}")
+
     def set(
         self,
         key: str,
@@ -95,6 +100,8 @@ class DotEnv(metaclass=Singleton):
         serializes the value (optionally using a type hint), writes the variable to the `.env` file,
         and updates the variable in the current process environment.
         """
+
+        # Ensure thread-safe operation during the set process.
         with self._lock:
 
             # Validate the environment variable key name.
@@ -148,6 +155,8 @@ class DotEnv(metaclass=Singleton):
         OrionisEnvironmentValueError
             If `key` is not a string.
         """
+
+        # Ensure thread-safe operation while retrieving the environment variable.
         with self._lock:
 
             # Ensure the key is a string.

orionis/services/environment/dynamic/caster.py

@@ -55,11 +55,13 @@ class EnvironmentCaster(IEnvironmentCaster):
 
         # If the input is a string, attempt to parse type hint and value
         if isinstance(raw, str):
+
             # Remove leading whitespace from the input
             self.__value_raw = raw.lstrip()
 
             # Check if the string contains a colon, indicating a type hint
             if ':' in self.__value_raw:
+
                 # Split at the first colon to separate type hint and value
                 type_hint, value_str = raw.split(':', 1)
 
@@ -243,6 +245,7 @@ class EnvironmentCaster(IEnvironmentCaster):
             raise
 
         except Exception as e:
+
             # Catch any other unexpected errors and wrap them in an environment value error
             raise OrionisEnvironmentValueError(
                 f"Error converting value '{self.__value_raw}' to type '{type_hint}': {str(e)}"
@@ -263,6 +266,8 @@ class EnvironmentCaster(IEnvironmentCaster):
         OrionisEnvironmentValueError
             If the internal value is not a string or bytes.
         """
+
+        # Import the base64 module for encoding
         import base64
 
         # Ensure the internal value is a string or bytes before encoding
@@ -294,13 +299,18 @@ class EnvironmentCaster(IEnvironmentCaster):
         OrionisEnvironmentValueException
             If the internal value cannot be decoded from Base64.
         """
+
+        # Import the base64 module for decoding
         import base64
 
         try:
+
             # Decode the Base64 encoded value and return as string
             decoded_value = base64.b64decode(self.__value_raw).decode()
             return decoded_value
+
         except Exception as e:
+
             # Raise a custom exception if decoding fails
             raise OrionisEnvironmentValueException(f"Cannot decode Base64 value '{self.__value_raw}': {str(e)}")
 
@@ -322,6 +332,8 @@ class EnvironmentCaster(IEnvironmentCaster):
         OrionisEnvironmentValueException
             If the value cannot be processed as a valid path.
         """
+
+        # Import the Path class from pathlib for path manipulation
         from pathlib import Path
 
         # If the value is already a Path object, return its POSIX representation
@@ -349,8 +361,9 @@ class EnvironmentCaster(IEnvironmentCaster):
         OrionisEnvironmentValueError
             If the internal value is not a string or a pathlib.Path object.
         """
+
+        # Import the Path class from pathlib for path manipulation
         from pathlib import Path
-        import os
 
         # Ensure the internal value is a string or Path object
         if not isinstance(self.__value_raw, (str, Path)):
@@ -418,8 +431,10 @@ class EnvironmentCaster(IEnvironmentCaster):
         OrionisEnvironmentValueError
             If the internal value is not a string.
         """
+
         # Ensure the internal value is a string before conversion
         if not isinstance(self.__value_raw, str):
+
             # Raise an error if the value is not a string
             raise OrionisEnvironmentValueError(
                 f"Value must be a string to convert to str, got {type(self.__value_raw).__name__} instead."
@@ -445,6 +460,7 @@ class EnvironmentCaster(IEnvironmentCaster):
         OrionisEnvironmentValueException
             If the value cannot be converted to an integer due to invalid format or type.
         """
+
         # Remove leading and trailing whitespace from the raw value
         value = self.__value_raw.strip()
 
@@ -526,6 +542,7 @@ class EnvironmentCaster(IEnvironmentCaster):
         OrionisEnvironmentValueError
             If the internal value is not a float.
         """
+
         # Ensure the internal value is a float before conversion
         if not isinstance(self.__value_raw, float):
 
@@ -556,6 +573,7 @@ class EnvironmentCaster(IEnvironmentCaster):
         OrionisEnvironmentValueException
             If the value cannot be converted to a boolean because it does not match 'true' or 'false'.
         """
+
         # Remove leading and trailing whitespace, then convert to lowercase for comparison
         value = self.__value_raw.strip().lower()
 
@@ -618,6 +636,8 @@ class EnvironmentCaster(IEnvironmentCaster):
         OrionisEnvironmentValueException
             If the value cannot be converted to a list due to invalid format or type.
         """
+
+        # Import the ast module for safe evaluation of string literals
         import ast
 
         # Remove leading and trailing whitespace from the raw value to ensure clean input
@@ -666,7 +686,7 @@ class EnvironmentCaster(IEnvironmentCaster):
 
             # Raise an error if the value is not a list
             raise OrionisEnvironmentValueError(
-            f"Value must be a list to convert to list, got {type(self.__value_raw).__name__} instead."
+                f"Value must be a list to convert to list, got {type(self.__value_raw).__name__} instead."
             )
 
         # Return the formatted string with type hint and list value
@@ -692,11 +712,14 @@ class EnvironmentCaster(IEnvironmentCaster):
         OrionisEnvironmentValueException
             If the value cannot be converted to a dictionary due to invalid format or type.
         """
+
+        # Import the ast module for safe evaluation of string literals
         import ast
 
         # Remove leading and trailing whitespace from the raw value to ensure clean input
         value = self.__value_raw.strip()
 
+        # Attempt to parse the string as a dictionary
         try:
 
             # Safely evaluate the string to a Python object using ast.literal_eval
@@ -729,6 +752,7 @@ class EnvironmentCaster(IEnvironmentCaster):
         OrionisEnvironmentValueError
             If the internal value is not a dictionary.
         """
+
         # Ensure the internal value is a dictionary before conversion
         if not isinstance(self.__value_raw, dict):
 
@@ -760,6 +784,8 @@ class EnvironmentCaster(IEnvironmentCaster):
         OrionisEnvironmentValueException
             If the value cannot be converted to a tuple due to invalid format or type.
         """
+
+        # Import the ast module for safe evaluation of string literals
         import ast
 
         # Remove leading and trailing whitespace from the raw value to ensure clean input
@@ -829,6 +855,8 @@ class EnvironmentCaster(IEnvironmentCaster):
         OrionisEnvironmentValueException
             If the value cannot be converted to a set due to invalid format or type.
         """
+
+        # Import the ast module for safe evaluation of string literals
         import ast
 
         # Remove leading and trailing whitespace from the raw value to ensure clean input
@@ -866,6 +894,7 @@ class EnvironmentCaster(IEnvironmentCaster):
         OrionisEnvironmentValueError
             If the internal value is not a set.
         """
+
         # Ensure the internal value is a set before conversion
         if not isinstance(self.__value_raw, set):
             # Raise an error if the value is not a set