orionis 0.408.0__tar.gz → 0.410.0__tar.gz

{orionis-0.408.0/orionis.egg-info → orionis-0.410.0}/PKG-INFO

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

{orionis-0.408.0 → orionis-0.410.0}/orionis/metadata/framework.py

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

orionis-0.410.0/orionis/services/log/contracts/log_service.py

@@ -0,0 +1,75 @@
+from abc import ABC, abstractmethod
+
+class ILoggerService(ABC):
+
+    @abstractmethod
+    def info(self, message: str) -> None:
+        """
+        Logs an informational message.
+
+        Parameters
+        ----------
+        message : str
+            The message to be logged as informational.
+
+        Returns
+        -------
+        None
+            This method does not return any value.
+        """
+        # To be implemented by subclasses
+        pass
+
+    @abstractmethod
+    def error(self, message: str) -> None:
+        """
+        Logs an error message.
+
+        Parameters
+        ----------
+        message : str
+            The message to be logged as an error.
+
+        Returns
+        -------
+        None
+            This method does not return any value.
+        """
+        # To be implemented by subclasses
+        pass
+
+    @abstractmethod
+    def warning(self, message: str) -> None:
+        """
+        Logs a warning message.
+
+        Parameters
+        ----------
+        message : str
+            The message to be logged as a warning.
+
+        Returns
+        -------
+        None
+            This method does not return any value.
+        """
+        # To be implemented by subclasses
+        pass
+
+    @abstractmethod
+    def debug(self, message: str) -> None:
+        """
+        Logs a debug message.
+
+        Parameters
+        ----------
+        message : str
+            The message to be logged for debugging purposes.
+
+        Returns
+        -------
+        None
+            This method does not return any value.
+        """
+        # To be implemented by subclasses
+        pass

{orionis-0.408.0 → orionis-0.410.0}/orionis/services/log/handlers/filename.py

@@ -12,19 +12,27 @@ class FileNameLogger:
         ----------
         path : str
             The original file path for the log file.
-        """
 
-        # If the path is not a string or is empty, raise a ValueError
+        Raises
+        ------
+        ValueError
+            If the provided path is not a non-empty string.
+        """
+        # Validate that the path is a non-empty string
         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
+        # Store the stripped path as a private instance variable
         self.__path = path.strip()
 
     def generate(self) -> str:
         """
         Generate a new log file path with a timestamp prefix.
 
+        The method constructs a new file path by prefixing the original file name
+        with a timestamp in the format 'YYYYMMDD_HHMMSS'. It also ensures that the
+        directory for the log file exists, creating it if necessary.
+
         Returns
         -------
         str
@@ -32,10 +40,10 @@ class FileNameLogger:
 
         Notes
         -----
-        The method ensures that the directory for the log file exists.
+        - The timestamp is generated using the current date and time.
+        - The directory for the log file is created if it does not exist.
         """
-
-        # Split the original path to extract the base name and extension
+        # Split the original path into components based on the separator
         if '/' in self.__path:
             parts = self.__path.split('/')
         elif '\\' in self.__path:
@@ -43,22 +51,22 @@ class FileNameLogger:
         else:
             parts = self.__path.split(os.sep)
 
-        # Get the base name and extension
+        # Extract the base file name and its extension
         filename, ext = os.path.splitext(parts[-1])
 
-        # Create the path without the last part
+        # Reconstruct the directory path (excluding the file name)
         path = os.path.join(*parts[:-1]) if len(parts) > 1 else ''
 
-        # Prefix the base name with a timestamp
+        # Generate a timestamp prefix for the file name
         prefix = datetime.now().strftime("%Y%m%d_%H%M%S")
 
-        # Join the path, prefix, and filename to create the full path
+        # Build the full file path with the timestamped file name
         full_path = os.path.join(path, f"{prefix}_{filename}{ext}")
 
-        # Ensure the log directory exists
+        # Ensure the log directory exists; create it if it does not
         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 the full path to the timestamped log file
         return full_path

orionis-0.410.0/orionis/services/log/handlers/size_rotating.py

@@ -0,0 +1,29 @@
+from logging.handlers import RotatingFileHandler
+from orionis.services.log.handlers.filename import FileNameLogger
+
+class PrefixedSizeRotatingFileHandler(RotatingFileHandler):
+
+    def rotation_filename(self, default_name) -> str:
+        """
+        Generates a rotated log filename by prefixing the original filename with a timestamp.
+
+        Parameters
+        ----------
+        default_name : str
+            The original file path that is subject to rotation.
+
+        Returns
+        -------
+        str
+            The new file path as a string, where the base name is prefixed with a timestamp
+            in the format 'YYYYMMDD_HHMMSS'. This ensures uniqueness and chronological ordering
+            of rotated log files.
+
+        Notes
+        -----
+        This method utilizes the FileNameLogger class to construct the prefixed filename.
+        The timestamp prefix helps in identifying the creation time of each rotated log file.
+        """
+
+        # Generate the new filename using FileNameLogger, which adds a timestamp prefix.
+        return FileNameLogger(default_name).generate()

orionis-0.410.0/orionis/services/log/handlers/timed_rotating.py

@@ -0,0 +1,29 @@
+from logging.handlers import TimedRotatingFileHandler
+from orionis.services.log.handlers.filename import FileNameLogger
+
+class PrefixedTimedRotatingFileHandler(TimedRotatingFileHandler):
+
+    def rotation_filename(self, default_name) -> str:
+        """
+        Generates a rotated log filename by prefixing the original filename with a timestamp.
+
+        Parameters
+        ----------
+        default_name : str
+            The original file path that is subject to rotation.
+
+        Returns
+        -------
+        str
+            The new file path as a string, where the base name is prefixed with a timestamp
+            in the format 'YYYYMMDD_HHMMSS'. This ensures each rotated log file is uniquely
+            identified by its creation time.
+
+        Notes
+        -----
+        This method utilizes the FileNameLogger class to construct the new filename.
+        The timestamp prefix helps in organizing and distinguishing rotated log files.
+        """
+
+        # Use FileNameLogger to generate a new filename with a timestamp prefix
+        return FileNameLogger(default_name).generate()

orionis-0.410.0/orionis/services/log/log_service.py

@@ -0,0 +1,296 @@
+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
+
+class LoggerService(ILoggerService):
+
+    def __init__(
+        self,
+        config: Logging | dict = None,
+        **kwargs
+    ):
+        """
+        Initializes the LoggerService instance with the provided logging configuration.
+
+        This constructor sets up the logger configuration using either a `Logging` object,
+        a configuration dictionary, or keyword arguments. It validates the input and
+        ensures that the configuration is properly instantiated before initializing
+        the logger. If no configuration is provided, it attempts to create one using
+        the supplied keyword arguments.
+
+        Parameters
+        ----------
+        config : Logging or dict, optional
+            The logging configuration. Can be an instance of the `Logging` class,
+            a dictionary containing configuration parameters, or None. If None,
+            configuration is initialized using `kwargs`.
+        **kwargs
+            Additional keyword arguments used to initialize the `Logging` configuration
+            if `config` is None.
+
+        Returns
+        -------
+        None
+            This method does not return any value. It sets up the logger service instance.
+
+        Raises
+        ------
+        LoggerRuntimeError
+            If the logger configuration cannot be initialized from the provided arguments,
+            such as invalid types or missing required parameters.
+        """
+
+        # Initialize private attributes for logger and configuration
+        self.__logger = None
+        self.__config = None
+
+        # If no configuration is provided, attempt to create one using kwargs
+        if config is None:
+            try:
+                self.__config = Logging(**kwargs)
+            except Exception as e:
+                # Raise a runtime error if configuration initialization fails
+                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 a Logging instance
+        elif isinstance(config, dict):
+            self.__config = Logging(**config)
+
+        # If config is already a Logging instance, use it directly
+        elif isinstance(config, Logging):
+            self.__config = config
+
+        # Initialize the logger using the validated configuration
+        self.__initLogger()
+
+    def __initLogger(self):
+        """
+        Initializes and configures the logger instance based on the provided settings.
+
+        This method sets up the logger to write logs to a file, using different handlers
+        depending on the logging channel type (e.g., stack, hourly, daily, weekly, monthly, chunked).
+        It ensures the log format includes a timestamp, log level, and message. If the specified
+        log directory does not exist, it is created automatically. The logger's level and retention
+        policies are determined by the configuration.
+
+        Parameters
+        ----------
+        None
+
+        Returns
+        -------
+        None
+            This method does not return any value. It sets up the logger instance as an attribute.
+
+        Raises
+        ------
+        LoggerRuntimeError
+            If the logger cannot be initialized due to an error in configuration or handler setup.
+        """
+        import logging
+        from datetime import datetime
+
+        try:
+            # List to hold the logging handlers
+            handlers = []
+
+            # Retrieve the default logging channel from configuration
+            channel: str = self.__config.default
+
+            # Get the configuration object for the selected channel
+            config_channels = getattr(self.__config.channels, channel)
+
+            # Generate the log file path using the FileNameLogger utility
+            path: str = FileNameLogger(getattr(config_channels, 'path')).generate()
+
+            # Determine the logging level (default to DEBUG if not specified)
+            level: Level | int = getattr(config_channels, 'level', 10)
+            level = level if isinstance(level, int) else level.value
+
+            # Select and configure the appropriate handler based on the channel type
+            if channel == "stack":
+                # Simple file handler for stack channel
+                handlers = [
+                    logging.FileHandler(
+                        filename=path,
+                        encoding="utf-8"
+                    )
+                ]
+
+            elif channel == "hourly":
+                # Rotating file handler for hourly logs
+                handlers = [
+                    PrefixedTimedRotatingFileHandler(
+                        filename=path,
+                        when="h",
+                        interval=1,
+                        backupCount=getattr(config_channels, 'retention_hours', 24),
+                        encoding="utf-8",
+                        utc=False
+                    )
+                ]
+
+            elif channel == "daily":
+                # Rotating file handler for daily logs
+                handlers = [
+                    PrefixedTimedRotatingFileHandler(
+                        filename=path,
+                        when="d",
+                        interval=1,
+                        backupCount=getattr(config_channels, 'retention_days', 7),
+                        encoding="utf-8",
+                        atTime=datetime.strptime(getattr(config_channels, 'at', "00:00"), "%H:%M").time(),
+                        utc=False
+                    )
+                ]
+
+            elif channel == "weekly":
+                # Rotating file handler for weekly logs
+                handlers = [
+                    PrefixedTimedRotatingFileHandler(
+                        filename=path,
+                        when="w0",
+                        interval=1,
+                        backupCount=getattr(config_channels, 'retention_weeks', 4),
+                        encoding="utf-8",
+                        utc=False
+                    )
+                ]
+
+            elif channel == "monthly":
+                # Rotating file handler for monthly logs
+                handlers = [
+                    PrefixedTimedRotatingFileHandler(
+                        filename=path,
+                        when="midnight",
+                        interval=30,
+                        backupCount=getattr(config_channels, 'retention_months', 4),
+                        encoding="utf-8",
+                        utc=False
+                    )
+                ]
+
+            elif channel == "chunked":
+                # Size-based rotating file handler for chunked logs
+                handlers = [
+                    PrefixedSizeRotatingFileHandler(
+                        filename=path,
+                        maxBytes=getattr(config_channels, 'mb_size', 10) * 1024 * 1024,
+                        backupCount=getattr(config_channels, 'files', 5),
+                        encoding="utf-8"
+                    )
+                ]
+
+            # Configure the logger with the selected handlers and formatting
+            logging.basicConfig(
+                level=level,
+                format="%(asctime)s [%(levelname)s] - %(message)s",
+                datefmt="%Y-%m-%d %H:%M:%S",
+                encoding="utf-8",
+                handlers=handlers
+            )
+
+            # Store the logger instance as a private attribute
+            self.__logger = logging.getLogger(__name__)
+
+        except Exception as e:
+            # Raise a runtime error if logger initialization fails
+            raise LoggerRuntimeError(f"Failed to initialize logger: {e}")
+
+    def info(self, message: str) -> None:
+        """
+        Logs an informational message to the configured logger.
+
+        This method records informational messages that highlight the progress or state
+        of the application at a coarse-grained level. The message is stripped of leading
+        and trailing whitespace before being logged.
+
+        Parameters
+        ----------
+        message : str
+            The informational message to log.
+
+        Returns
+        -------
+        None
+            This method does not return any value.
+        """
+
+        # Log the informational message after stripping whitespace
+        self.__logger.info(message.strip())
+
+    def error(self, message: str) -> None:
+        """
+        Logs an error-level message to the configured logger.
+
+        This method records error messages that indicate serious issues or failures
+        within the application. The message is stripped of leading and trailing
+        whitespace before being logged.
+
+        Parameters
+        ----------
+        message : str
+            The error message to log.
+
+        Returns
+        -------
+        None
+            This method does not return any value.
+        """
+
+        # Log the error message after stripping whitespace
+        self.__logger.error(message.strip())
+
+    def warning(self, message: str) -> None:
+        """
+        Log a warning-level message to the configured logger.
+
+        This method records warning messages that indicate potential issues or
+        unexpected situations in the application. The message is stripped of
+        leading and trailing whitespace before being logged.
+
+        Parameters
+        ----------
+        message : str
+            The warning message to log.
+
+        Returns
+        -------
+        None
+            This method does not return any value.
+        """
+
+        # Log the warning message after stripping whitespace
+        self.__logger.warning(message.strip())
+
+    def debug(self, message: str) -> None:
+        """
+        Logs a debug-level message to the configured logger.
+
+        This method records diagnostic messages that are useful for debugging
+        and development purposes. The message is stripped of leading and trailing
+        whitespace before being logged.
+
+        Parameters
+        ----------
+        message : str
+            The debug message to be logged.
+
+        Returns
+        -------
+        None
+            This method does not return any value.
+        """
+
+        # Log the debug message after stripping whitespace
+        self.__logger.debug(message.strip())

{orionis-0.408.0 → orionis-0.410.0}/orionis/services/paths/contracts/resolver.py

@@ -1,5 +1,4 @@
 from abc import ABC, abstractmethod
-from typing import Optional
 
 class IResolver(ABC):
     """

{orionis-0.408.0 → orionis-0.410.0/orionis.egg-info}/PKG-INFO

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

{orionis-0.408.0 → orionis-0.410.0}/orionis.egg-info/SOURCES.txt

@@ -548,6 +548,8 @@ tests/services/inspection/reflection/test_reflection_instance.py
 tests/services/inspection/reflection/test_reflection_module.py
 tests/services/inspection/reflection/mock/__init__.py
 tests/services/inspection/reflection/mock/fake_reflect_instance.py
+tests/services/log/__init__.py
+tests/services/log/test_log.py
 tests/services/path/__init__.py
 tests/services/path/test_services_resolver.py
 tests/services/system/__init__.py

orionis-0.410.0/tests/services/log/test_log.py

@@ -0,0 +1,97 @@
+from orionis.services.log.log_service import LoggerService
+from orionis.support.facades.logger import Log
+from orionis.test.cases.asynchronous import AsyncTestCase
+
+class TestLoggerService(AsyncTestCase):
+
+    async def testHasInfoMethod(self):
+        """
+        Checks if the LoggerService class has an 'info' method.
+
+        Returns
+        -------
+        None
+            This test passes if the 'info' method exists, otherwise it fails.
+        """
+        self.assertTrue(hasattr(LoggerService, "info"))
+
+    async def testHasErrorMethod(self):
+        """
+        Checks if the LoggerService class has an 'error' method.
+
+        Returns
+        -------
+        None
+            This test passes if the 'error' method exists, otherwise it fails.
+        """
+        self.assertTrue(hasattr(LoggerService, "error"))
+
+    async def testHasWarningMethod(self):
+        """
+        Checks if the LoggerService class has a 'warning' method.
+
+        Returns
+        -------
+        None
+            This test passes if the 'warning' method exists, otherwise it fails.
+        """
+        self.assertTrue(hasattr(LoggerService, "warning"))
+
+    async def testHasDebugMethod(self):
+        """
+        Checks if the LoggerService class has a 'debug' method.
+
+        Returns
+        -------
+        None
+            This test passes if the 'debug' method exists, otherwise it fails.
+        """
+        self.assertTrue(hasattr(LoggerService, "debug"))
+
+    async def testLoggerWritesInfo(self):
+        """
+        Tests that the logger writes an info-level message.
+
+        Returns
+        -------
+        None
+            This test passes if the info message is processed without error.
+        """
+        # Log an info message
+        Log.info("Mensaje de prueba info")
+
+    async def testLoggerWritesError(self):
+        """
+        Tests that the logger writes an error-level message.
+
+        Returns
+        -------
+        None
+            This test passes if the error message is processed without error.
+        """
+        # Log an error message
+        Log.error("Mensaje de prueba error")
+
+    async def testLoggerWritesWarning(self):
+        """
+        Tests that the logger writes a warning-level message.
+
+        Returns
+        -------
+        None
+            This test passes if the warning message is processed without error.
+        """
+        # Log a warning message
+        Log.warning("Mensaje de prueba warning")
+
+    async def testLoggerWritesDebug(self):
+        """
+        Tests that the logger writes a debug-level message.
+
+        Returns
+        -------
+        None
+            This test passes if the debug message is processed without error.
+        """
+        # Log a debug message
+        Log.debug("Mensaje de prueba debug")

orionis-0.408.0/orionis/services/log/contracts/log_service.py

@@ -1,23 +0,0 @@
-from abc import ABC, abstractmethod
-
-class ILoggerService(ABC):
-
-    @abstractmethod
-    def info(self, message: str) -> None:
-        """Log an informational message."""
-        pass
-
-    @abstractmethod
-    def error(self, message: str) -> None:
-        """Log an error message."""
-        pass
-
-    @abstractmethod
-    def warning(self, message: str) -> None:
-        """Log a warning message."""
-        pass
-
-    @abstractmethod
-    def debug(self, message: str) -> None:
-        """Log a debug message."""
-        pass