orionis 0.252.0__py3-none-any.whl → 0.265.0__py3-none-any.whl

orionis/luminate/foundation/config/logging/entities/chunked.py

@@ -0,0 +1,128 @@
+from dataclasses import asdict, dataclass, field
+from orionis.luminate.foundation.config.exceptions.integrity import OrionisIntegrityException
+from orionis.luminate.foundation.config.logging.enums.levels import Level
+import re
+
+@dataclass(unsafe_hash=True, kw_only=True)
+class Chunked:
+    """
+    Configuration for chunked log file rotation.
+
+    This class defines the configuration for managing log files by splitting them into chunks
+    based on file size and limiting the number of retained log files. This prevents log files
+    from growing indefinitely and helps manage disk usage.
+
+    Attributes
+    ----------
+    path : str
+        Filesystem path where chunked log files are stored.
+    level : int | str | Level
+        Logging level for the log file. Accepts an integer, string, or Level enum.
+    mb_size : int
+        Maximum size (in megabytes) of a single log file before a new chunk is created.
+    files : int
+        Maximum number of log files to retain. Older files are deleted when this limit is exceeded.
+    """
+
+    path: str = field(
+        default='storage/log/application.log',
+        metadata={
+            "description": "Filesystem path where chunked log files are stored.",
+            "default": "storage/log/application.log",
+        },
+    )
+
+    level: int | str | Level = field(
+        default=Level.INFO,
+        metadata={
+            "description": "Logging level for the log file. Accepts int, str, or Level enum.",
+            "default": Level.INFO,
+        },
+    )
+
+    mb_size: int = field(
+        default=10,
+        metadata={
+            "description": "Maximum size (in MB) of a log file before chunking.",
+            "default": 10,
+        },
+    )
+
+    files: int = field(
+        default=5,
+        metadata={
+            "description": "Maximum number of log files to retain.",
+            "default": 5,
+        },
+    )
+
+    def __post_init__(self):
+        # Validate 'path'
+        if not isinstance(self.path, str) or not self.path.strip():
+            raise OrionisIntegrityException(
+                f"Chunked log configuration error: 'path' must be a non-empty string, got {repr(self.path)}."
+            )
+
+        # Validate 'level'
+        valid_level_types = (int, str, Level)
+        if not isinstance(self.level, valid_level_types):
+            raise OrionisIntegrityException(
+                f"File cache configuration error: 'level' must be int, str, or Level enum, got {type(self.level).__name__}."
+            )
+
+        if isinstance(self.level, str):
+            _value = self.level.strip().upper()
+            if not _value:
+                raise OrionisIntegrityException(
+                    "File cache configuration error: 'level' string cannot be empty."
+                )
+            if _value not in Level.__members__:
+                raise OrionisIntegrityException(
+                    f"File cache configuration error: 'level' must be one of {list(Level.__members__.keys())}, got '{self.level}'."
+                )
+            self.level = Level[_value].value
+        elif isinstance(self.level, int):
+            valid_values = [level.value for level in Level]
+            if self.level not in valid_values:
+                raise OrionisIntegrityException(
+                    f"File cache configuration error: 'level' must be one of {valid_values}, got '{self.level}'."
+                )
+        elif isinstance(self.level, Level):
+            self.level = self.level.value
+
+        # Validate 'mb_size'
+        if isinstance(self.mb_size, str):
+            match = re.match(r'^(\d+)\s*(MB|KB|B)?$', self.mb_size.strip(), re.IGNORECASE)
+            if not match:
+                raise OrionisIntegrityException(
+                    f"Chunked log configuration error: 'mb_size' string must be like '10MB', '500KB', or integer, got '{self.mb_size}'."
+                )
+            size, unit = match.groups()
+            size = int(size)
+            if unit is None or unit.upper() == 'MB':
+                self.mb_size = size
+            elif unit.upper() == 'KB':
+                self.mb_size = max(1, size // 1024)
+            elif unit.upper() == 'B':
+                self.mb_size = max(1, size // (1024 * 1024))
+        if not isinstance(self.mb_size, int) or self.mb_size < 1:
+            raise OrionisIntegrityException(
+                f"Chunked log configuration error: 'mb_size' must be a positive integer (MB), got {self.mb_size}."
+            )
+
+        # Validate 'files'
+        if not isinstance(self.files, int) or self.files < 1:
+            raise OrionisIntegrityException(
+                f"Chunked log configuration error: 'files' must be a positive integer, got {self.files}."
+            )
+
+    def toDict(self) -> dict:
+        """
+        Returns a dictionary representation of the Chunked configuration.
+
+        Returns
+        -------
+        dict
+            Dictionary containing all configuration fields and their values.
+        """
+        return asdict(self)

orionis/luminate/foundation/config/logging/entities/daily.py

@@ -0,0 +1,113 @@
+from dataclasses import asdict, dataclass, field
+from datetime import time
+from orionis.luminate.foundation.config.exceptions.integrity import OrionisIntegrityException
+from orionis.luminate.foundation.config.logging.enums.levels import Level
+
+@dataclass(unsafe_hash=True, kw_only=True)
+class Daily:
+    """
+    Represents the configuration for daily log file rotation.
+
+    Attributes:
+        path (str): The file path where the log is stored.
+        level (int | str | Level): The logging level (e.g., 'info', 'error', 'debug').
+        retention_days (int): The number of days to retain log files before deletion.
+        at (time): The time of day when the log rotation should occur.
+    """
+
+    path: str = field(
+        default='storage/log/application.log',
+        metadata={
+            "description": "The file path where the log is stored.",
+            "default": "storage/log/application.log",
+        },
+    )
+
+    level: int | str | Level = field(
+        default=Level.INFO,
+        metadata={
+            "description": "The logging level (e.g., 'info', 'error', 'debug').",
+            "default": Level.INFO,
+        },
+    )
+
+    retention_days: int = field(
+        default=7,
+        metadata={
+            "description": "The number of days to retain log files before deletion.",
+            "default": 7,
+        },
+    )
+
+    at: time = field(
+        default=time(0, 0),
+        metadata={
+            "description": "The time of day when the log rotation should occur.",
+            "default": time(0, 0),
+        },
+    )
+
+    def __post_init__(self):
+        """
+        Validates and normalizes the attributes after dataclass initialization.
+
+        Raises:
+            OrionisIntegrityException: If any attribute is invalid.
+        """
+        # Validate 'path'
+        if not isinstance(self.path, str) or not self.path.strip():
+            raise OrionisIntegrityException(
+                f"File cache configuration error: 'path' must be a non-empty string, got {repr(self.path)}."
+            )
+
+        # Validate 'level'
+        valid_level_types = (int, str, Level)
+        if not isinstance(self.level, valid_level_types):
+            raise OrionisIntegrityException(
+                f"File cache configuration error: 'level' must be int, str, or Level enum, got {type(self.level).__name__}."
+            )
+
+        # Normalize 'level' to int
+        if isinstance(self.level, str):
+            _value = self.level.strip().upper()
+            if not _value:
+                raise OrionisIntegrityException(
+                    "File cache configuration error: 'level' string cannot be empty."
+                )
+            if _value not in Level.__members__:
+                raise OrionisIntegrityException(
+                    f"File cache configuration error: 'level' must be one of {list(Level.__members__.keys())}, got '{self.level}'."
+                )
+            self.level = Level[_value].value
+        elif isinstance(self.level, int):
+            valid_values = [level.value for level in Level]
+            if self.level not in valid_values:
+                raise OrionisIntegrityException(
+                    f"File cache configuration error: 'level' must be one of {valid_values}, got '{self.level}'."
+                )
+        elif isinstance(self.level, Level):
+            self.level = self.level.value
+
+        # Validate 'retention_days'
+        if not isinstance(self.retention_days, int) or self.retention_days < 1 or self.retention_days > 90:
+            raise OrionisIntegrityException(
+                f"File cache configuration error: 'retention_days' must be a positive integer between 1 and 90, got {repr(self.retention_days)}."
+            )
+
+        # Validate 'at'
+        if not isinstance(self.at, time):
+            raise OrionisIntegrityException(
+                f"File cache configuration error: 'at' must be a datetime.time instance, got {type(self.at).__name__}."
+            )
+
+        # Convert 'at' to "HH:MM:SS" string format
+        self.at = self.at.strftime("%H:%M:%S")
+
+    def toDict(self) -> dict:
+        """
+        Converts the Daily object to a dictionary representation.
+
+        Returns:
+            dict: A dictionary containing the dataclass fields and their values.
+        """
+        return asdict(self)

orionis/luminate/foundation/config/logging/entities/hourly.py

@@ -0,0 +1,100 @@
+from dataclasses import asdict, dataclass, field
+from orionis.luminate.foundation.config.exceptions.integrity import OrionisIntegrityException
+from orionis.luminate.foundation.config.logging.enums.levels import Level
+
+@dataclass(unsafe_hash=True, kw_only=True)
+class Hourly:
+    """
+    Represents the configuration for hourly log file management.
+
+    Attributes:
+        path (str): The file path where the log is stored.
+        level (int | str | Level): The logging level (e.g., 'info', 'error', 'debug').
+        retention_hours (int): The number of hours to retain log files before deletion.
+    """
+
+    path: str = field(
+        default='storage/log/application.log',
+        metadata={
+            "description": "The file path where the log is stored.",
+            "default": "storage/log/application.log",
+        },
+    )
+
+    level: int | str | Level = field(
+        default=Level.INFO,
+        metadata={
+            "description": "The logging level (e.g., 'info', 'error', 'debug').",
+            "default": Level.INFO,
+        },
+    )
+
+    retention_hours: int = field(
+        default=24,
+        metadata={
+            "description": "The number of hours to retain log files before deletion.",
+            "default": 24,
+        },
+    )
+
+    def __post_init__(self):
+        """
+        Validates the attributes after dataclass initialization.
+
+        Raises:
+            OrionisIntegrityException: If any attribute is invalid.
+                - 'path' must be a non-empty string.
+                - 'level' must be an int, str, or Level enum, and a valid value.
+                - 'retention_hours' must be an integer between 1 and 168.
+        """
+        # Validate 'path'
+        if not isinstance(self.path, str) or not self.path.strip():
+            raise OrionisIntegrityException(
+                f"File cache configuration error: 'path' must be a non-empty string, got {repr(self.path)}."
+            )
+
+        # Validate 'level'
+        valid_level_types = (int, str, Level)
+        if not isinstance(self.level, valid_level_types):
+            raise OrionisIntegrityException(
+                f"File cache configuration error: 'level' must be int, str, or Level enum, got {type(self.level).__name__}."
+            )
+
+        if isinstance(self.level, str):
+            _value = self.level.strip().upper()
+            if not _value:
+                raise OrionisIntegrityException(
+                    "File cache configuration error: 'level' string cannot be empty."
+                )
+            if _value not in Level.__members__:
+                raise OrionisIntegrityException(
+                    f"File cache configuration error: 'level' must be one of {list(Level.__members__.keys())}, got '{self.level}'."
+                )
+            self.level = Level[_value].value
+        elif isinstance(self.level, int):
+            valid_values = [level.value for level in Level]
+            if self.level not in valid_values:
+                raise OrionisIntegrityException(
+                    f"File cache configuration error: 'level' must be one of {valid_values}, got '{self.level}'."
+                )
+        elif isinstance(self.level, Level):
+            self.level = self.level.value
+
+        # Validate 'retention_hours'
+        if not isinstance(self.retention_hours, int) or self.retention_hours < 0:
+            raise OrionisIntegrityException(
+                f"File cache configuration error: 'retention_hours' must be a non-negative integer, got {self.retention_hours}."
+            )
+        if self.retention_hours < 1 or self.retention_hours > 168:
+            raise OrionisIntegrityException(
+                f"File cache configuration error: 'retention_hours' must be between 1 and 168, got {self.retention_hours}."
+            )
+
+    def toDict(self) -> dict:
+        """
+        Converts the Hourly object to a dictionary representation.
+
+        Returns:
+            dict: A dictionary containing all the dataclass fields and their values.
+        """
+        return asdict(self)

orionis/luminate/foundation/config/logging/entities/logging.py

@@ -0,0 +1,51 @@
+from dataclasses import dataclass, field, asdict, fields
+from orionis.luminate.foundation.config.logging.entities.channels import Channels
+from orionis.luminate.foundation.config.exceptions.integrity import OrionisIntegrityException
+
+@dataclass(unsafe_hash=True, kw_only=True)
+class Logging:
+    """
+    Represents the logging system configuration.
+
+    Attributes
+    ----------
+    default : str
+        The default logging channel to use.
+    channels : Channels
+        A collection of available logging channels.
+    """
+    default: str = field(
+        default="stack",
+        metadata={
+            "description": "The default logging channel to use.",
+            "default": "stack",
+        }
+    )
+    channels: Channels = field(
+        default_factory=Channels,
+        metadata={
+            "description": "A collection of available logging channels.",
+            "default": "Channels()",
+        }
+    )
+
+    def __post_init__(self):
+        """
+        Validates the types of the attributes after initialization.
+        """
+        options = [field.name for field in fields(Channels)]
+        if not isinstance(self.default, str) or self.default not in options:
+            raise OrionisIntegrityException(
+                f"The 'default' property must be a string and match one of the available options ({options})."
+            )
+
+        if not isinstance(self.channels, Channels):
+            raise OrionisIntegrityException(
+                "The 'channels' property must be an instance of Channels."
+            )
+
+    def toDict(self) -> dict:
+        """
+        Converts the current instance into a dictionary representation.
+        """
+        return asdict(self)

orionis/luminate/foundation/config/logging/entities/monthly.py

@@ -0,0 +1,100 @@
+from dataclasses import asdict, dataclass, field
+from orionis.luminate.foundation.config.exceptions.integrity import OrionisIntegrityException
+from orionis.luminate.foundation.config.logging.enums.levels import Level
+
+@dataclass(unsafe_hash=True, kw_only=True)
+class Monthly:
+    """
+    Configuration entity for monthly log file management.
+
+    Attributes:
+        path (str): The file path where the log is stored.
+        level (int | str | Level): The logging level (e.g., 'info', 'error', 'debug').
+        retention_months (int): The number of months to retain log files before deletion.
+    """
+
+    path: str = field(
+        default='storage/log/application.log',
+        metadata={
+            "description": "The file path where the log is stored.",
+            "default": "storage/log/application.log",
+        },
+    )
+
+    level: int | str | Level = field(
+        default=Level.INFO,
+        metadata={
+            "description": "The logging level (e.g., 'info', 'error', 'debug').",
+            "default": Level.INFO,
+        },
+    )
+
+    retention_months: int = field(
+        default=4,
+        metadata={
+            "description": "The number of months to retain log files before deletion.",
+            "default": 4,
+        },
+    )
+
+    def __post_init__(self):
+        """
+        Validates the 'path', 'level', and 'retention_months' attributes after dataclass initialization.
+
+        Raises:
+            OrionisIntegrityException: If any attribute is invalid.
+                - 'path' must be a non-empty string.
+                - 'level' must be an int, str, or Level enum, and a valid logging level.
+                - 'retention_months' must be an integer between 1 and 12 (inclusive).
+        """
+        # Validate 'path'
+        if not isinstance(self.path, str) or not self.path.strip():
+            raise OrionisIntegrityException(
+                f"File cache configuration error: 'path' must be a non-empty string, got {repr(self.path)}."
+            )
+
+        # Validate 'level'
+        valid_level_types = (int, str, Level)
+        if not isinstance(self.level, valid_level_types):
+            raise OrionisIntegrityException(
+                f"File cache configuration error: 'level' must be int, str, or Level enum, got {type(self.level).__name__}."
+            )
+
+        if isinstance(self.level, str):
+            _value = self.level.strip().upper()
+            if not _value:
+                raise OrionisIntegrityException(
+                    "File cache configuration error: 'level' string cannot be empty."
+                )
+            if _value not in Level.__members__:
+                raise OrionisIntegrityException(
+                    f"File cache configuration error: 'level' must be one of {list(Level.__members__.keys())}, got '{self.level}'."
+                )
+            self.level = Level[_value].value
+        elif isinstance(self.level, int):
+            valid_values = [level.value for level in Level]
+            if self.level not in valid_values:
+                raise OrionisIntegrityException(
+                    f"File cache configuration error: 'level' must be one of {valid_values}, got '{self.level}'."
+                )
+        elif isinstance(self.level, Level):
+            self.level = self.level.value
+
+        # Validate 'retention_months'
+        if not isinstance(self.retention_months, int) or self.retention_months < 0:
+            raise OrionisIntegrityException(
+                f"File cache configuration error: 'retention_months' must be a non-negative integer, got {self.retention_months}."
+            )
+        if self.retention_months < 1 or self.retention_months > 12:
+            raise OrionisIntegrityException(
+                f"File cache configuration error: 'retention_months' must be between 1 and 12, got {self.retention_months}."
+            )
+
+    def toDict(self) -> dict:
+        """
+        Converts the Monthly object to a dictionary representation.
+
+        Returns:
+            dict: A dictionary containing all dataclass fields and their values.
+        """
+        return asdict(self)

orionis/luminate/foundation/config/logging/entities/stack.py

@@ -0,0 +1,74 @@
+from dataclasses import asdict, dataclass, field
+from orionis.luminate.foundation.config.exceptions.integrity import OrionisIntegrityException
+from orionis.luminate.foundation.config.logging.enums.levels import Level
+
+@dataclass(unsafe_hash=True, kw_only=True)
+class Stack:
+    """
+    Represents the configuration for a logging stack, including the log file path and logging level.
+    """
+
+    path: str = field(
+        default='storage/log/application.log',
+        metadata={
+            "description": "The file path where the log is stored.",
+            "default": "storage/log/application.log",
+        },
+    )
+
+    level: int | str | Level = field(
+        default=Level.INFO,
+        metadata={
+            "description": "The logging level (e.g., 'info', 'error', 'debug').",
+            "default": Level.INFO,
+        },
+    )
+
+    def __post_init__(self):
+        """
+        Validates the 'path' and 'level' attributes after dataclass initialization.
+
+        Raises:
+            OrionisIntegrityException: If 'path' is not a non-empty string, or if 'level' is not a valid type or value.
+        """
+        # Validate 'path'
+        if not isinstance(self.path, str) or not self.path.strip():
+            raise OrionisIntegrityException(
+                f"File cache configuration error: 'path' must be a non-empty string, got {repr(self.path)}."
+            )
+
+        # Validate 'level'
+        valid_level_types = (int, str, Level)
+        if not isinstance(self.level, valid_level_types):
+            raise OrionisIntegrityException(
+                f"File cache configuration error: 'level' must be int, str, or Level enum, got {type(self.level).__name__}."
+            )
+
+        if isinstance(self.level, str):
+            _value = self.level.strip().upper()
+            if not _value:
+                raise OrionisIntegrityException(
+                    "File cache configuration error: 'level' string cannot be empty."
+                )
+            if _value not in Level.__members__:
+                raise OrionisIntegrityException(
+                    f"File cache configuration error: 'level' must be one of {list(Level.__members__.keys())}, got '{self.level}'."
+                )
+            self.level = Level[_value].value
+        elif isinstance(self.level, int):
+            valid_values = [level.value for level in Level]
+            if self.level not in valid_values:
+                raise OrionisIntegrityException(
+                    f"File cache configuration error: 'level' must be one of {valid_values}, got '{self.level}'."
+                )
+        elif isinstance(self.level, Level):
+            self.level = self.level.value
+
+    def toDict(self) -> dict:
+        """
+        Converts the Stack instance to a dictionary representation.
+
+        Returns:
+            dict: A dictionary containing all fields of the Stack instance.
+        """
+        return asdict(self)

orionis/luminate/foundation/config/logging/entities/weekly.py

@@ -0,0 +1,102 @@
+from dataclasses import asdict, dataclass, field
+from orionis.luminate.foundation.config.exceptions.integrity import OrionisIntegrityException
+from orionis.luminate.foundation.config.logging.enums.levels import Level
+
+@dataclass(unsafe_hash=True, kw_only=True)
+class Weekly:
+    """
+    Configuration entity for weekly log file management.
+
+    Attributes:
+        path (str): The file path where the log is stored.
+        level (int | str | Level): The logging level (e.g., 'info', 'error', 'debug').
+        retention_weeks (int): The number of weeks to retain log files before deletion.
+    """
+
+    path: str = field(
+        default='storage/log/application.log',
+        metadata={
+            "description": "The file path where the log is stored.",
+            "default": "storage/log/application.log",
+        },
+    )
+
+    level: int | str | Level = field(
+        default=Level.INFO,
+        metadata={
+            "description": "The logging level (e.g., 'info', 'error', 'debug').",
+            "default": Level.INFO,
+        },
+    )
+
+    retention_weeks: int = field(
+        default=4,
+        metadata={
+            "description": "The number of weeks to retain log files before deletion.",
+            "default": 4,
+        },
+    )
+
+    def __post_init__(self):
+        """
+        Post-initialization validation for Weekly configuration.
+
+        Validates:
+            - 'path' is a non-empty string.
+            - 'level' is a valid int, str, or Level enum member.
+            - 'retention_weeks' is an integer between 1 and 12 (inclusive).
+
+        Raises:
+            OrionisIntegrityException: If any attribute is invalid.
+        """
+        # Validate 'path'
+        if not isinstance(self.path, str) or not self.path.strip():
+            raise OrionisIntegrityException(
+                f"File cache configuration error: 'path' must be a non-empty string, got {repr(self.path)}."
+            )
+
+        # Validate 'level'
+        valid_level_types = (int, str, Level)
+        if not isinstance(self.level, valid_level_types):
+            raise OrionisIntegrityException(
+                f"File cache configuration error: 'level' must be int, str, or Level enum, got {type(self.level).__name__}."
+            )
+
+        if isinstance(self.level, str):
+            _value = self.level.strip().upper()
+            if not _value:
+                raise OrionisIntegrityException(
+                    "File cache configuration error: 'level' string cannot be empty."
+                )
+            if _value not in Level.__members__:
+                raise OrionisIntegrityException(
+                    f"File cache configuration error: 'level' must be one of {list(Level.__members__.keys())}, got '{self.level}'."
+                )
+            self.level = Level[_value].value
+        elif isinstance(self.level, int):
+            valid_values = [level.value for level in Level]
+            if self.level not in valid_values:
+                raise OrionisIntegrityException(
+                    f"File cache configuration error: 'level' must be one of {valid_values}, got '{self.level}'."
+                )
+        elif isinstance(self.level, Level):
+            self.level = self.level.value
+
+        # Validate 'retention_weeks'
+        if not isinstance(self.retention_weeks, int) or self.retention_weeks < 0:
+            raise OrionisIntegrityException(
+                f"File cache configuration error: 'retention_weeks' must be a non-negative integer, got {self.retention_weeks}."
+            )
+        if self.retention_weeks < 1 or self.retention_weeks > 12:
+            raise OrionisIntegrityException(
+                f"File cache configuration error: 'retention_weeks' must be between 1 and 12, got {self.retention_weeks}."
+            )
+
+    def toDict(self) -> dict:
+        """
+        Converts the Weekly configuration object to a dictionary.
+
+        Returns:
+            dict: Dictionary representation of the Weekly configuration.
+        """
+        return asdict(self)