orionis 0.407.0__py3-none-any.whl → 0.409.0__py3-none-any.whl

orionis/container/container.py

@@ -6,15 +6,17 @@ from orionis.container.entities.binding import Binding
 from orionis.container.enums.lifetimes import Lifetime
 from orionis.container.exceptions import OrionisContainerException
 from orionis.container.resolver.resolver import Resolver
-from orionis.container.validators.implements import ImplementsAbstractMethods
-from orionis.container.validators.is_abstract_class import IsAbstractClass
-from orionis.container.validators.is_callable import IsCallable
-from orionis.container.validators.is_concrete_class import IsConcreteClass
-from orionis.container.validators.is_instance import IsInstance
-from orionis.container.validators.is_not_subclass import IsNotSubclass
-from orionis.container.validators.is_subclass import IsSubclass
-from orionis.container.validators.is_valid_alias import IsValidAlias
-from orionis.container.validators.lifetime import LifetimeValidator
+from orionis.container.validators import (
+    ImplementsAbstractMethods,
+    IsAbstractClass,
+    IsCallable,
+    IsConcreteClass,
+    IsInstance,
+    IsNotSubclass,
+    IsSubclass,
+    IsValidAlias,
+    LifetimeValidator
+)
 from orionis.services.introspection.abstract.reflection import ReflectionAbstract
 from orionis.services.introspection.callables.reflection import ReflectionCallable
 

orionis/container/enums/lifetimes.py

@@ -23,7 +23,9 @@ class Lifetime(Enum):
 
     # A new instance is provided every time the dependency is requested.
     TRANSIENT = auto()
+
     # A single shared instance is provided for the entire application lifetime.
     SINGLETON = auto()
+
     # An instance is provided per scope (e.g., per request or session).
     SCOPED = auto()

orionis/container/validators/__init__.py

@@ -0,0 +1,21 @@
+from .implements import ImplementsAbstractMethods
+from .is_abstract_class import IsAbstractClass
+from .is_concrete_class import IsConcreteClass
+from .is_instance import IsInstance
+from .is_callable import IsCallable
+from .is_subclass import IsSubclass
+from .is_not_subclass import IsNotSubclass
+from .is_valid_alias import IsValidAlias
+from .lifetime import LifetimeValidator
+
+__all__ = [
+    "ImplementsAbstractMethods",
+    "IsAbstractClass",
+    "IsConcreteClass",
+    "IsInstance",
+    "IsCallable",
+    "IsSubclass",
+    "IsNotSubclass",
+    "IsValidAlias",
+    "LifetimeValidator",
+]

orionis/metadata/framework.py

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

orionis/services/log/contracts/log_service.py

@@ -4,20 +4,72 @@ class ILoggerService(ABC):
 
     @abstractmethod
     def info(self, message: str) -> None:
-        """Log an informational message."""
+        """
+        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:
-        """Log an error message."""
+        """
+        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:
-        """Log a warning message."""
+        """
+        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:
-        """Log a debug message."""
+        """
+        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/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/services/log/handlers/size_rotating.py

@@ -5,17 +5,25 @@ class PrefixedSizeRotatingFileHandler(RotatingFileHandler):
 
     def rotation_filename(self, default_name) -> str:
         """
-        Generate a rotated log filename by prefixing the original filename with a timestamp.
+        Generates a rotated log filename by prefixing the original filename with a timestamp.
 
         Parameters
         ----------
         default_name : str
-            The original file path to be rotated.
+            The original file path that is subject to rotation.
 
         Returns
         -------
         str
-            The new file path with the base name prefixed by a timestamp in the format 'YYYYMMDD_HHMMSS'.
+            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/services/log/handlers/timed_rotating.py

@@ -5,17 +5,25 @@ class PrefixedTimedRotatingFileHandler(TimedRotatingFileHandler):
 
     def rotation_filename(self, default_name) -> str:
         """
-        Generate a rotated log filename by prefixing the original filename with a timestamp.
+        Generates a rotated log filename by prefixing the original filename with a timestamp.
 
         Parameters
         ----------
         default_name : str
-            The original file path to be rotated.
+            The original file path that is subject to rotation.
 
         Returns
         -------
         str
-            The new file path with the base name prefixed by a timestamp in the format 'YYYYMMDD_HHMMSS'.
+            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/services/log/log_service.py

@@ -14,33 +14,46 @@ class LoggerService(ILoggerService):
         **kwargs
     ):
         """
-        Initialize the LoggerService with the provided configuration.
+        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 of configuration parameters, or None. If None, configuration
-            is initialized using kwargs.
+            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.
+            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.
+            If the logger configuration cannot be initialized from the provided arguments,
+            such as invalid types or missing required parameters.
         """
 
-        # Attributes
+        # Initialize private attributes for logger and configuration
         self.__logger = None
         self.__config = None
 
-        # Initialize the logger configuration using **kwargs if provided
+        # 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. "
@@ -49,54 +62,64 @@ class LoggerService(ILoggerService):
                     f"Expected: {Logging.__module__}.{Logging.__name__} or dict."
                 )
 
-        # If config is a dictionary, convert it to Logging
+        # If config is a dictionary, convert it to a Logging instance
         elif isinstance(config, dict):
             self.__config = Logging(**config)
 
-        # If config is already an instance of Logging, use it directly
+        # If config is already a Logging instance, use it directly
         elif isinstance(config, Logging):
             self.__config = config
 
-        # Initialize LoggerService
+        # Initialize the logger using the validated configuration
         self.__initLogger()
 
     def __initLogger(self):
         """
-        Configures the logger with the specified settings.
+        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
 
-        This method sets up the logger to write logs to a file. If the specified
-        directory does not exist, it creates it. The log format includes the
-        timestamp and the log message.
+        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.
+            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 handlers
+            # List to hold the logging handlers
             handlers = []
 
-            # Get the channel from the configuration
+            # Retrieve the default logging channel from configuration
             channel: str = self.__config.default
 
-            # Get the configuration for the specified channel
+            # Get the configuration object for the selected channel
             config_channels = getattr(self.__config.channels, channel)
 
-            # Get the path from the channel configuration
+            # Generate the log file path using the FileNameLogger utility
             path: str = FileNameLogger(getattr(config_channels, 'path')).generate()
 
-            # Get Level from the channel configuration, defaulting to 10 (DEBUG)
+            # 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
 
-            # Create handlers based on the channel type
+            # 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,
@@ -105,89 +128,92 @@ class LoggerService(ILoggerService):
                 ]
 
             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
+                        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
+                        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
+                        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
+                        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"
+                        filename=path,
+                        maxBytes=getattr(config_channels, 'mb_size', 10) * 1024 * 1024,
+                        backupCount=getattr(config_channels, 'files', 5),
+                        encoding="utf-8"
                     )
                 ]
 
-            # Configure the logger
+            # 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
+                level=level,
+                format="%(asctime)s [%(levelname)s] - %(message)s",
+                datefmt="%Y-%m-%d %H:%M:%S",
+                encoding="utf-8",
+                handlers=handlers
             )
 
-            # Get the logger instance
+            # 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:
         """
-        Log an informational message.
+        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
         ----------
@@ -197,12 +223,19 @@ class LoggerService(ILoggerService):
         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:
         """
-        Log an error message.
+        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
         ----------
@@ -212,12 +245,19 @@ class LoggerService(ILoggerService):
         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 message.
+        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
         ----------
@@ -227,20 +267,30 @@ class LoggerService(ILoggerService):
         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:
         """
-        Log a debug message.
+        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 log.
+            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/services/paths/contracts/resolver.py

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

{orionis-0.407.0.dist-info → orionis-0.409.0.dist-info}/METADATA

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