orionis 0.404.0__py3-none-any.whl → 0.406.0__py3-none-any.whl

orionis/foundation/providers/console_provider.py

@@ -3,15 +3,37 @@ from orionis.console.output.contracts.console import IConsole
 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.
+    """
 
     def register(self) -> None:
         """
-        Register services into the application container.
+        Registers the console service in the application container.
+
+        Returns
+        -------
+        None
         """
         self.app.transient(IConsole, Console, alias="core.orionis.console")
 
     def boot(self) -> None:
         """
-        Perform any post-registration bootstrapping or initialization.
+        Performs post-registration initialization if needed.
+
+        Returns
+        -------
+        None
         """
         pass

orionis/foundation/providers/dumper_provider.py

@@ -3,15 +3,37 @@ from orionis.console.dumper.contracts.dump import IDebug
 from orionis.container.providers.service_provider import ServiceProvider
 
 class DumperProvider(ServiceProvider):
+    """
+    DumperProvider
+    ==============
+
+    Registers the debug message service in the application container.
+    Provides access to debug message printing, error reporting, and other console diagnostics.
+
+    Methods
+    -------
+    register()
+        Registers the debug service in the application container.
+    boot()
+        Performs post-registration initialization if needed.
+    """
 
     def register(self) -> None:
         """
-        Register services into the application container.
+        Registers the debug service in the application container.
+
+        Returns
+        -------
+        None
         """
         self.app.transient(IDebug, Debug, alias="core.orionis.dumper")
 
     def boot(self) -> None:
         """
-        Perform any post-registration bootstrapping or initialization.
+        Performs post-registration initialization if needed.
+
+        Returns
+        -------
+        None
         """
         pass

orionis/foundation/providers/logger_provider.py

@@ -3,15 +3,37 @@ from orionis.services.log.contracts.log_service import ILoggerService
 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.
+    """
 
     def register(self) -> None:
         """
-        Register services into the application container.
+        Registers the logging service in the application container.
+
+        Returns
+        -------
+        None
         """
         self.app.instance(ILoggerService, LoggerService(self.app.config('logging')), alias="core.orionis.logger")
 
     def boot(self) -> None:
         """
-        Perform any post-registration bootstrapping or initialization.
+        Performs post-registration initialization if needed.
+
+        Returns
+        -------
+        None
         """
         pass

orionis/foundation/providers/path_resolver_provider.py

@@ -3,15 +3,38 @@ from orionis.services.paths.contracts.resolver import IResolver
 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.
+    """
+
 
     def register(self) -> None:
         """
-        Register services into the application container.
+        Registers the path resolver service in the application container.
+
+        Returns
+        -------
+        None
         """
         self.app.transient(IResolver, Resolver, alias="core.orionis.path_resolver")
 
     def boot(self) -> None:
         """
-        Perform any post-registration bootstrapping or initialization.
+        Performs post-registration initialization if needed.
+
+        Returns
+        -------
+        None
         """
         pass

orionis/foundation/providers/progress_bar_provider.py

@@ -3,15 +3,37 @@ from orionis.console.dynamic.progress_bar import ProgressBar
 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.
+    """
 
     def register(self) -> None:
         """
-        Register services into the application container.
+        Registers the progress bar service in the application container.
+
+        Returns
+        -------
+        None
         """
         self.app.transient(IProgressBar, ProgressBar, alias="core.orionis.progress_bar")
 
     def boot(self) -> None:
         """
-        Perform any post-registration bootstrapping or initialization.
+        Performs post-registration initialization if needed.
+
+        Returns
+        -------
+        None
         """
         pass

orionis/foundation/providers/testing_provider.py

@@ -0,0 +1,39 @@
+from orionis.container.providers.service_provider import ServiceProvider
+from orionis.test.contracts.unit_test import IUnitTest
+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.
+    """
+
+    def register(self) -> None:
+        """
+        Registers the unit testing service in the application container.
+
+        Returns
+        -------
+        None
+        """
+        self.app.singleton(IUnitTest, UnitTest, alias="core.orionis.testing")
+
+    def boot(self) -> None:
+        """
+        Performs post-registration initialization if needed.
+
+        Returns
+        -------
+        None
+        """
+        pass

orionis/foundation/providers/workers_provider.py

@@ -3,15 +3,37 @@ from orionis.services.system.contracts.workers import IWorkers
 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.
+    """
 
     def register(self) -> None:
         """
-        Register services into the application container.
+        Registers the worker service in the application container.
+
+        Returns
+        -------
+        None
         """
         self.app.transient(IWorkers, Workers, alias="core.orionis.workers")
 
     def boot(self) -> None:
         """
-        Perform any post-registration bootstrapping or initialization.
+        Performs post-registration initialization if needed.
+
+        Returns
+        -------
+        None
         """
         pass

orionis/metadata/framework.py

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

orionis/services/environment/helpers/functions.py

@@ -17,5 +17,4 @@ def env(key: str, default: Any = None) -> Any:
     Any
         The value of the environment variable if it exists, otherwise the default value.
     """
-    dotenv = DotEnv()
-    return dotenv.get(key, default)
+    return DotEnv().get(key, default)

orionis/services/environment/key/key_generator.py

@@ -0,0 +1,37 @@
+import os
+import base64
+
+class SecureKeyGenerator:
+    """
+    Provides static methods for generating secure random keys in base64 format.
+
+    Methods
+    -------
+    generate_key() : str
+        Generates a secure random key encoded in base64.
+    """
+
+    @staticmethod
+    def generate() -> str:
+        """
+        Generates a secure random key and encodes it in base64 format.
+
+        This method creates a cryptographically secure random key of 32 bytes,
+        encodes it using base64 encoding, and returns the result as a string
+        prefixed with 'base64:'.
+
+        Returns
+        -------
+        str
+            A string in the format 'base64:<key>', where <key> is a base64-encoded
+            representation of a securely generated 32-byte random key.
+        """
+
+        # Generate 32 bytes of cryptographically secure random data
+        key = os.urandom(32)
+
+        # Encode the random bytes using base64 and decode to a UTF-8 string
+        encoded = base64.b64encode(key).decode('utf-8')
+
+        # Return the key in the required format
+        return f"base64:{encoded}"

orionis/services/log/handlers/filename.py

@@ -0,0 +1,64 @@
+import os
+from datetime import datetime
+from pathlib import Path
+
+class FileNameLogger:
+
+    def __init__(self, path: str) -> None:
+        """
+        Initialize the FileNameLogger.
+
+        Parameters
+        ----------
+        path : str
+            The original file path for the log file.
+        """
+
+        # If the path is not a string or is empty, raise a ValueError
+        if not isinstance(path, str) or not path:
+            raise ValueError("The 'path' parameter must be a non-empty string.")
+
+        # Set the instance variable __path to the stripped path
+        self.__path = path.strip()
+
+    def generate(self) -> str:
+        """
+        Generate a new log file path with a timestamp prefix.
+
+        Returns
+        -------
+        str
+            The full path to the log file with a timestamped file name.
+
+        Notes
+        -----
+        The method ensures that the directory for the log file exists.
+        """
+
+        # Split the original path to extract the base name and extension
+        if '/' in self.__path:
+            parts = self.__path.split('/')
+        elif '\\' in self.__path:
+            parts = self.__path.split('\\')
+        else:
+            parts = self.__path.split(os.sep)
+
+        # Get the base name and extension
+        filename, ext = os.path.splitext(parts[-1])
+
+        # Create the path without the last part
+        path = os.path.join(*parts[:-1]) if len(parts) > 1 else ''
+
+        # Prefix the base name with a timestamp
+        prefix = datetime.now().strftime("%Y%m%d_%H%M%S")
+
+        # Join the path, prefix, and filename to create the full path
+        full_path = os.path.join(path, f"{prefix}_{filename}{ext}")
+
+        # Ensure the log directory exists
+        log_dir = Path(full_path).parent
+        if not log_dir.exists():
+            log_dir.mkdir(parents=True, exist_ok=True)
+
+        # Return the full path as a string
+        return full_path

orionis/services/log/handlers/size_rotating.py

@@ -1,52 +1,21 @@
-from datetime import datetime
 from logging.handlers import RotatingFileHandler
-from pathlib import Path
-import os
+from orionis.services.log.handlers.filename import FileNameLogger
 
 class PrefixedSizeRotatingFileHandler(RotatingFileHandler):
 
-    def rotation_filename(self, default_name):
+    def rotation_filename(self, default_name) -> str:
         """
-        Generates a rotated log filename by prefixing the original filename with a timestamp.
-        This method takes an original file path, extracts its directory, base name, and extension,
-        and returns a new file path where the base name is prefixed with the current timestamp
-        in the format 'YYYYMMDD_HHMMSS'. If the target directory does not exist, it is created.
+        Generate a rotated log filename by prefixing the original filename with a timestamp.
+
+        Parameters
+        ----------
+        default_name : str
             The original file path to be rotated.
-            The new file path with a timestamp prefix added to the base name.
-        Notes
-        -----
-        - The timestamp is based on the current local time.
-        - The method ensures that the parent directory for the new file exists.
 
         Returns
         -------
         str
-            The new filename with a timestamp prefix in the format 'YYYYMMDD_HHMMSS'.
+            The new file path with the base name prefixed by a timestamp in the format 'YYYYMMDD_HHMMSS'.
         """
-        # Split the original path to extract the base name and extension
-        if '/' in default_name:
-            parts = default_name.split('/')
-        elif '\\' in default_name:
-            parts = default_name.split('\\')
-        else:
-            parts = default_name.split(os.sep)
-
-        # Get the base name and extension
-        filename, ext = os.path.splitext(parts[-1])
-
-        # Create the path without the last part
-        path = os.path.join(*parts[:-1]) if len(parts) > 1 else ''
-
-        # Prefix the base name with a timestamp
-        prefix = datetime.now().strftime("%Y%m%d_%H%M%S")
-
-        # Join the path, prefix, and filename to create the full path
-        full_path = os.path.join(path, f"{prefix}_{filename}{ext}")
-
-        # Ensure the log directory exists
-        log_dir = Path(full_path).parent
-        if not log_dir.exists():
-            log_dir.mkdir(parents=True, exist_ok=True)
 
-        # Return the full path as a string
-        return full_path
+        return FileNameLogger(default_name).generate()

orionis/services/log/handlers/timed_rotating.py

@@ -1,53 +1,21 @@
-from datetime import datetime
 from logging.handlers import TimedRotatingFileHandler
-from pathlib import Path
-import os
+from orionis.services.log.handlers.filename import FileNameLogger
 
 class PrefixedTimedRotatingFileHandler(TimedRotatingFileHandler):
 
-    def rotation_filename(self, default_name):
+    def rotation_filename(self, default_name) -> str:
         """
-        Generates a rotated log filename by prefixing the original filename with a timestamp.
-        This method takes an original file path, extracts its directory, base name, and extension,
-        and returns a new file path where the base name is prefixed with the current timestamp
-        in the format 'YYYYMMDD_HHMMSS'. If the target directory does not exist, it is created.
+        Generate a rotated log filename by prefixing the original filename with a timestamp.
+
+        Parameters
+        ----------
+        default_name : str
             The original file path to be rotated.
-            The new file path with a timestamp prefix added to the base name.
-        Notes
-        -----
-        - The timestamp is based on the current local time.
-        - The method ensures that the parent directory for the new file exists.
 
         Returns
         -------
         str
-            The new filename with a timestamp prefix in the format 'YYYYMMDD_HHMMSS'.
+            The new file path with the base name prefixed by a timestamp in the format 'YYYYMMDD_HHMMSS'.
         """
 
-        # Split the original path to extract the base name and extension
-        if '/' in default_name:
-            parts = default_name.split('/')
-        elif '\\' in default_name:
-            parts = default_name.split('\\')
-        else:
-            parts = default_name.split(os.sep)
-
-        # Get the base name and extension
-        filename, ext = os.path.splitext(parts[-1])
-
-        # Create the path without the last part
-        path = os.path.join(*parts[:-1]) if len(parts) > 1 else ''
-
-        # Prefix the base name with a timestamp
-        prefix = datetime.now().strftime("%Y%m%d_%H%M%S")
-
-        # Join the path, prefix, and filename to create the full path
-        full_path = os.path.join(path, f"{prefix}_{filename}{ext}")
-
-        # Ensure the log directory exists
-        log_dir = Path(full_path).parent
-        if not log_dir.exists():
-            log_dir.mkdir(parents=True, exist_ok=True)
-
-        # Return the full path as a string
-        return full_path
+        return FileNameLogger(default_name).generate()

orionis/services/log/log_service.py

@@ -2,6 +2,7 @@ from orionis.foundation.config.logging.entities.logging import Logging
 from orionis.foundation.config.logging.enums import Level
 from orionis.services.log.contracts.log_service import ILoggerService
 from orionis.services.log.exceptions import LoggerRuntimeError
+from orionis.services.log.handlers.filename import FileNameLogger
 from orionis.services.log.handlers.size_rotating import PrefixedSizeRotatingFileHandler
 from orionis.services.log.handlers.timed_rotating import PrefixedTimedRotatingFileHandler
 
@@ -40,7 +41,13 @@ class LoggerService(ILoggerService):
             try:
                 self.__config = Logging(**kwargs)
             except Exception as e:
-                raise LoggerRuntimeError(f"Failed to initialize logger configuration: {e}")
+                raise LoggerRuntimeError(
+                    f"Error initializing logger configuration: {e}. "
+                    "Please check the provided parameters. "
+                    f"Expected a Logging dataclass or a configuration dictionary. "
+                    f"Type received: {type(config).__module__}.{type(config).__name__}. "
+                    f"Expected: {Logging.__module__}.{Logging.__name__} or dict."
+                )
 
         # If config is a dictionary, convert it to Logging
         elif isinstance(config, dict):
@@ -53,56 +60,6 @@ class LoggerService(ILoggerService):
         # Initialize LoggerService
         self.__initLogger()
 
-    def __filename(self, original_path:str) -> str:
-        """
-        Generates a rotated log filename by prefixing the original filename with a timestamp.
-        This method takes an original file path, extracts its directory, base name, and extension,
-        and returns a new file path where the base name is prefixed with the current timestamp
-        in the format 'YYYYMMDD_HHMMSS'. If the target directory does not exist, it is created.
-            The original file path to be rotated.
-            The new file path with a timestamp prefix added to the base name.
-        Notes
-        -----
-        - The timestamp is based on the current local time.
-        - The method ensures that the parent directory for the new file exists.
-
-        Returns
-        -------
-        str
-            The new filename with a timestamp prefix in the format 'YYYYMMDD_HHMMSS'.
-        """
-        import os
-        from datetime import datetime
-        from pathlib import Path
-
-        # Split the original path to extract the base name and extension
-        if '/' in original_path:
-            parts = original_path.split('/')
-        elif '\\' in original_path:
-            parts = original_path.split('\\')
-        else:
-            parts = original_path.split(os.sep)
-
-        # Get the base name and extension
-        filename, ext = os.path.splitext(parts[-1])
-
-        # Create the path without the last part
-        path = os.path.join(*parts[:-1]) if len(parts) > 1 else ''
-
-        # Prefix the base name with a timestamp
-        prefix = datetime.now().strftime("%Y%m%d_%H%M%S")
-
-        # Join the path, prefix, and filename to create the full path
-        full_path = os.path.join(path, f"{prefix}_{filename}{ext}")
-
-        # Ensure the log directory exists
-        log_dir = Path(full_path).parent
-        if not log_dir.exists():
-            log_dir.mkdir(parents=True, exist_ok=True)
-
-        # Return the full path as a string
-        return full_path
-
     def __initLogger(self):
         """
         Configures the logger with the specified settings.
@@ -131,7 +88,7 @@ class LoggerService(ILoggerService):
             config_channels = getattr(self.__config.channels, channel)
 
             # Get the path from the channel configuration
-            path: str = self.__filename(getattr(config_channels, 'path'))
+            path: str = FileNameLogger(getattr(config_channels, 'path')).generate()
 
             # Get Level from the channel configuration, defaulting to 10 (DEBUG)
             level: Level | int = getattr(config_channels, 'level', 10)