orionis 0.253.0__py3-none-any.whl → 0.266.0__py3-none-any.whl

orionis/luminate/foundation/config/logging/enums/levels.py

@@ -0,0 +1,21 @@
+from enum import Enum
+
+class Level(Enum):
+    """
+    Enumeration of standard logging levels.
+
+    Attributes:
+        NOTSET (int): No specific logging level set. Value is 0.
+        DEBUG (int): Detailed information, typically of interest only when diagnosing problems. Value is 10.
+        INFO (int): Confirmation that things are working as expected. Value is 20.
+        WARNING (int): An indication that something unexpected happened, or indicative of some problem in the near future. Value is 30.
+        ERROR (int): Due to a more serious problem, the software has not been able to perform some function. Value is 40.
+        CRITICAL (int): A very serious error, indicating that the program itself may be unable to continue running. Value is 50.
+    """
+
+    NOTSET = 0
+    DEBUG = 10
+    INFO = 20
+    WARNING = 30
+    ERROR = 40
+    CRITICAL = 50

orionis/luminate/foundation/config/mail/entities/file.py

@@ -0,0 +1,41 @@
+from dataclasses import asdict, dataclass, field
+from orionis.luminate.foundation.config.exceptions.integrity import OrionisIntegrityException
+
+@dataclass(unsafe_hash=True, kw_only=True)
+class File:
+    """
+    Represents a file configuration entity for storing outgoing emails.
+    Attributes:
+        path (str): The file path where outgoing emails are stored.
+    Methods:
+        __post_init__():
+            Validates that the 'path' attribute is a non-empty string.
+            Raises:
+                OrionisIntegrityException: If 'path' is not a non-empty string.
+        toDict() -> dict:
+            Serializes the File instance to a dictionary.
+    """
+
+    path: str = field(
+        default="storage/mail",
+        metadata={"description": "The file path where outgoing emails are stored."}
+    )
+
+    def __post_init__(self):
+        """
+        Post-initialization method to validate the 'path' attribute.
+
+        Raises:
+            OrionisIntegrityException: If 'path' is not a non-empty string.
+        """
+        if not isinstance(self.path, str) or self.path.strip() == "":
+            raise OrionisIntegrityException("The 'path' attribute must be a non-empty string.")
+
+    def toDict(self) -> dict:
+        """
+        Converts the current instance into a dictionary representation.
+
+        Returns:
+            dict: A dictionary containing all the fields of the instance.
+        """
+        return asdict(self)

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

@@ -0,0 +1,56 @@
+from dataclasses import asdict, dataclass, field, fields
+from orionis.luminate.foundation.config.exceptions.integrity import OrionisIntegrityException
+from orionis.luminate.foundation.config.mail.entities.mailers import Mailers
+
+@dataclass(unsafe_hash=True, kw_only=True)
+class Mail:
+    """
+    Represents the mail configuration entity.
+    Attributes:
+        default (str): The default mailer transport to use.
+        mailers (Mailers): The available mail transport configurations.
+    Methods:
+        __post_init__():
+            Validates the integrity of the Mail instance after initialization.
+            Raises OrionisIntegrityException if any attribute is invalid.
+        toDict() -> dict:
+            Serializes the Mail instance to a dictionary.
+    """
+
+    default: str = field(
+        default="smtp",
+        metadata={"description": "The default mailer transport to use."}
+    )
+
+    mailers: Mailers = field(
+        default_factory=Mailers,
+        metadata={"description": "The available mail transport configurations."}
+    )
+
+    def __post_init__(self):
+        """
+        Post-initialization method to validate the 'default' and 'mailers' attributes.
+        Ensures that:
+        - The 'default' attribute is a string and matches one of the available mailer options.
+        - The 'mailers' attribute is an instance of the Mailers class.
+        Raises:
+            OrionisIntegrityException: If 'default' is not a valid string option or if 'mailers' is not a Mailers object.
+        """
+
+        options = [f.name for f in fields(Mailers)]
+        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.mailers, Mailers):
+            raise OrionisIntegrityException("The 'mailers' attribute must be a Mailers object.")
+
+    def toDict(self) -> dict:
+        """
+        Converts the current instance into a dictionary representation.
+
+        Returns:
+            dict: A dictionary containing all the fields of the instance.
+        """
+        return asdict(self)

orionis/luminate/foundation/config/mail/entities/mailers.py

@@ -0,0 +1,54 @@
+from dataclasses import asdict, dataclass, field
+from orionis.luminate.foundation.config.exceptions.integrity import OrionisIntegrityException
+from orionis.luminate.foundation.config.mail.entities.file import File
+from orionis.luminate.foundation.config.mail.entities.smtp import Smtp
+
+@dataclass(unsafe_hash=True, kw_only=True)
+class Mailers:
+    """
+    Represents the mail transport configurations for the application.
+    Attributes:
+        smtp (Smtp): The SMTP configuration used for sending emails.
+        file (File): The file-based mail transport configuration.
+    Methods:
+        __post_init__():
+            Validates that the 'smtp' and 'file' attributes are instances of their respective classes.
+            Raises:
+                OrionisIntegrityException: If 'smtp' is not a Smtp object or 'file' is not a File object.
+        toDict() -> dict:
+            Serializes the Mailers instance to a dictionary.
+    """
+
+    smtp: Smtp = field(
+        default_factory=Smtp,
+        metadata={"description": "The SMTP configuration used for sending emails."}
+    )
+
+    file: File = field(
+        default_factory=File,
+        metadata={"description": "The file-based mail transport configuration."}
+    )
+
+    def __post_init__(self):
+        """
+        Post-initialization method to validate attribute types.
+
+        Ensures that the 'smtp' attribute is an instance of the Smtp class and the 'file' attribute is an instance of the File class.
+        Raises:
+            OrionisIntegrityException: If 'smtp' is not a Smtp object or 'file' is not a File object.
+        """
+
+        if not isinstance(self.smtp, Smtp):
+            raise OrionisIntegrityException("The 'smtp' attribute must be a Smtp object.")
+
+        if not isinstance(self.file, File):
+            raise OrionisIntegrityException("The 'file' attribute must be a File object.")
+
+    def toDict(self) -> dict:
+        """
+        Converts the current instance into a dictionary representation.
+
+        Returns:
+            dict: A dictionary containing all the fields of the instance.
+        """
+        return asdict(self)

orionis/luminate/foundation/config/mail/entities/smtp.py

@@ -0,0 +1,104 @@
+from dataclasses import asdict, dataclass, field
+from typing import Optional
+from orionis.luminate.foundation.config.exceptions.integrity import OrionisIntegrityException
+
+@dataclass(unsafe_hash=True, kw_only=True)
+class Smtp:
+    """
+    Represents the configuration for an SMTP (Simple Mail Transfer Protocol) server.
+    Attributes:
+        url (str): The full URL for the SMTP service.
+        host (str): The hostname of the SMTP server.
+        port (int): The port number used for SMTP communication.
+        encryption (str): The encryption type used for secure communication (e.g., "None", "SSL", "TLS").
+        username (str): The username for authentication with the SMTP server.
+        password (str): The password for authentication with the SMTP server.
+        timeout (Optional[int]): The connection timeout duration in seconds.
+    Methods:
+        __post_init__():
+            Validates the integrity of the SMTP configuration attributes after initialization.
+            Raises:
+                OrionisIntegrityException: If any attribute does not meet the required constraints.
+        toDict() -> dict:
+            Converts the SMTP configuration to a dictionary representation.
+            Returns:
+                dict: A dictionary containing all SMTP configuration attributes.
+    """
+
+    url: str = field(
+        default="smtp.mailtrap.io",
+        metadata={"description": "The full URL for the SMTP service."}
+    )
+
+    host: str = field(
+        default="smtp.mailtrap.io",
+        metadata={"description": "The hostname of the SMTP server."}
+    )
+
+    port: int = field(
+        default=587,
+        metadata={"description": "The port number used for SMTP communication."}
+    )
+
+    encryption: str = field(
+        default="TLS",
+        metadata={"description": "The encryption type used for secure communication."}
+    )
+
+    username: str = field(
+        default="",
+        metadata={"description": "The username for authentication with the SMTP server."}
+    )
+
+    password: str = field(
+        default="",
+        metadata={"description": "The password for authentication with the SMTP server."}
+    )
+
+    timeout: Optional[int] = field(
+        default=None,
+        metadata={"description": "The connection timeout duration in seconds."}
+    )
+
+    def __post_init__(self):
+        """
+        Validates the initialization of the mail configuration entity.
+
+        Ensures that all required attributes are of the correct type and meet specific constraints:
+        - 'url' and 'host' must be non-empty strings.
+        - 'port' must be a positive integer.
+        - 'encryption', 'username', and 'password' must be strings.
+        - 'timeout', if provided, must be a non-negative integer or None.
+
+        Raises:
+            OrionisIntegrityException: If any attribute fails its validation check.
+        """
+        if not isinstance(self.url, str):
+            raise OrionisIntegrityException("The 'url' attribute must be a string.")
+
+        if not isinstance(self.host, str):
+            raise OrionisIntegrityException("The 'host' attribute must be a string.")
+
+        if not isinstance(self.port, int) or self.port < 0:
+            raise OrionisIntegrityException("The 'port' attribute must be a non-negative integer.")
+
+        if not isinstance(self.encryption, str):
+            raise OrionisIntegrityException("The 'encryption' attribute must be a string.")
+
+        if not isinstance(self.username, str):
+            raise OrionisIntegrityException("The 'username' attribute must be a string.")
+
+        if not isinstance(self.password, str):
+            raise OrionisIntegrityException("The 'password' attribute must be a string.")
+
+        if self.timeout is not None and (not isinstance(self.timeout, int) or self.timeout < 0):
+            raise OrionisIntegrityException("The 'timeout' attribute must be a non-negative integer or None.")
+
+    def toDict(self) -> dict:
+        """
+        Converts the current instance into a dictionary representation.
+
+        Returns:
+            dict: A dictionary containing all the fields of the instance.
+        """
+        return asdict(self)

orionis/luminate/foundation/config/queue/entities/brokers.py

@@ -0,0 +1,55 @@
+
+from dataclasses import asdict, dataclass, field
+from orionis.luminate.foundation.config.exceptions.integrity import OrionisIntegrityException
+from orionis.luminate.foundation.config.queue.entities.database import Database
+
+@dataclass(unsafe_hash=True, kw_only=True)
+class Brokers:
+    """
+    Represents the configuration for queue brokers.
+    Attributes:
+        sync (bool): Indicates if the sync broker is enabled. Defaults to True.
+        database (Database): The configuration for the database-backed queue. Defaults to a new Database instance.
+    Methods:
+        __post_init__():
+            Validates and normalizes the properties after initialization.
+            Ensures 'sync' is a boolean and 'database' is an instance of Database.
+    """
+
+    sync: bool = field(
+        default=True,
+        metadata={
+            "description": "Indicates if the sync broker is enabled.",
+            "default": True
+        }
+    )
+
+    database: Database = field(
+        default_factory=Database,
+        metadata={
+            "description": "The configuration for the database-backed queue.",
+            "default": "Database()"
+        }
+    )
+
+    def __post_init__(self):
+        """
+        Post-initialization validation for the Brokers entity.
+        Validates and normalizes the following properties:
+        - sync: Must be a boolean.
+        - database: Must be an instance of the Database class.
+        """
+        if not isinstance(self.sync, bool):
+            raise OrionisIntegrityException("sync must be a boolean.")
+
+        if not isinstance(self.database, Database):
+            raise OrionisIntegrityException("database must be an instance of the Database class.")
+
+    def toDict(self) -> dict:
+        """
+        Converts the current instance into a dictionary representation.
+
+        Returns:
+            dict: A dictionary containing all the fields of the instance.
+        """
+        return asdict(self)

orionis/luminate/foundation/config/queue/entities/database.py

@@ -0,0 +1,107 @@
+
+from dataclasses import asdict, dataclass, field
+from orionis.luminate.foundation.config.exceptions.integrity import OrionisIntegrityException
+from orionis.luminate.foundation.config.queue.enums.strategy import Strategy
+import re
+
+@dataclass(unsafe_hash=True, kw_only=True)
+class Database:
+    """
+    Represents the configuration entity for a database-backed queue.
+    Attributes:
+        table (str): The name of the table used for the queue. Must match the pattern `[a-z_][a-z_]*` (lowercase letters or underscores only, no numbers).
+        queue (str): The name of the queue. Must contain only ASCII characters.
+        retry_after (int): The time in seconds to wait before retrying a failed job. Must be a positive integer.
+        strategy (str | Strategy): The strategy used for the queue. Options are FIFO, LIFO, or PRIORITY. Can be provided as a string (case-insensitive) or as a `Strategy` enum member.
+    Methods:
+        __post_init__():
+            Validates and normalizes the entity's properties after initialization.
+            - Ensures `table` is a valid string matching the required pattern.
+            - Ensures `queue` is a valid ASCII string.
+            - Ensures `retry_after` is a positive integer.
+            - Ensures `strategy` is a valid string or `Strategy` enum member, and normalizes it to the corresponding enum value.
+    """
+
+    table: str = field(
+        default="jobs",
+        metadata={
+            "description": "The name of the table used for the queue.",
+            "default": "jobs",
+        }
+    )
+
+    queue: str = field(
+        default="default",
+        metadata={
+            "description": "The name of the queue.",
+            "default": "default",
+        }
+    )
+
+    retry_after: int = field(
+        default=90,
+        metadata={
+            "description": "The time in seconds to wait before retrying a failed job.",
+            "default": 90,
+        }
+    )
+
+    strategy : str | Strategy = field(
+        default=Strategy.FIFO,
+        metadata={
+            "description": "The strategy used for the queue. Options are FIFO, LIFO, or PRIORITY.",
+            "default": "Strategy.FIFO",
+        }
+    )
+
+    def __post_init__(self):
+        """
+        Post-initialization validation for the entity.
+        Validates and normalizes the following properties:
+        - `table`: Must be a string matching the pattern `[a-z_][a-z_]*` (lowercase letters or underscores only, no numbers).
+        - `queue`: Must be a string containing only ASCII characters.
+        - `retry_after`: Must be a positive integer.
+        - `strategy`: Must be either a string (matching a valid `Strategy` member name, case-insensitive) or an instance of `Strategy`. Converts the value to the corresponding `Strategy` enum value.
+        Raises:
+            OrionisIntegrityException: If any property fails validation.
+        """
+
+        if not isinstance(self.table, str):
+            raise OrionisIntegrityException("The 'table' property must be a string.")
+        if not re.fullmatch(r'[a-z_][a-z_]*', self.table):
+            raise OrionisIntegrityException(
+                "The 'table' property must be a valid table name: start with a lowercase letter or underscore, contain only lowercase letters or underscores (no numbers allowed)."
+            )
+
+        if not isinstance(self.queue, str):
+            raise OrionisIntegrityException("The 'queue' property must be a string.")
+        try:
+            self.queue.encode('ascii')
+        except UnicodeEncodeError:
+            raise OrionisIntegrityException("The 'queue' property must contain only ASCII characters (no UTF-8 or non-ASCII allowed).")
+
+        if not isinstance(self.retry_after, int) or self.retry_after <= 0:
+            raise OrionisIntegrityException("The 'retry_after' property must be a positive integer.")
+
+        if not isinstance(self.strategy, (str, Strategy)):
+            raise OrionisIntegrityException("The 'strategy' property must be a string or an instance of Strategy.")
+        if isinstance(self.strategy, str):
+            options = Strategy._member_names_
+            _value = str(self.strategy).upper().strip()
+            if _value not in options:
+                raise OrionisIntegrityException(
+                    f"The 'strategy' property must be one of the following: {', '.join(options)}."
+                )
+            else:
+                self.strategy = Strategy[_value].value
+        else:
+            self.strategy = self.strategy.value
+
+    def toDict(self) -> dict:
+        """
+        Converts the current instance into a dictionary representation.
+
+        Returns:
+            dict: A dictionary containing all the fields of the instance.
+        """
+        return asdict(self)

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

@@ -0,0 +1,47 @@
+from dataclasses import asdict, dataclass, field, fields
+from orionis.luminate.foundation.config.exceptions.integrity import OrionisIntegrityException
+from orionis.luminate.foundation.config.queue.entities.brokers import Brokers
+
+@dataclass(unsafe_hash=True, kw_only=True)
+class Queue:
+
+    default: str = field(
+        default="sync",
+        metadata={
+            "description": "The default queue connection to use.",
+            "default": "sync"
+        }
+    )
+
+    brokers: Brokers = field(
+        default_factory=Brokers,
+        metadata={
+            "description": "The default queue broker to use.",
+            "default": "Brokers()"
+        }
+    )
+
+    def __post_init__(self):
+        """
+        Post-initialization validation for the Queue entity.
+        Validates and normalizes the following properties:
+        - default: Must be a string.
+        - brokers: Must be a string or an instance of the Brokers class.
+        """
+        options = [f.name for f in fields(Brokers)]
+        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.brokers, Brokers):
+            raise OrionisIntegrityException("brokers must be an instance of the Brokers class.")
+
+    def toDict(self) -> dict:
+        """
+        Converts the current instance into a dictionary representation.
+
+        Returns:
+            dict: A dictionary containing all the fields of the instance.
+        """
+        return asdict(self)

orionis/luminate/foundation/config/queue/enums/strategy.py

@@ -0,0 +1,15 @@
+from enum import Enum
+
+class Strategy(Enum):
+    """
+    Enumeration representing the different types of queues supported by the system.
+    Attributes:
+        FIFO: (First-In, First-Out) Elements are processed in the order they arrive.
+        LIFO: (Last-In, First-Out) The most recent elements are processed first.
+        PRIORITY: Elements are processed according to their assigned priority, not necessarily in arrival order.
+    Use this enumeration to specify the queue behavior in the system configuration.
+    """
+
+    FIFO = 'fifo'
+    LIFO = 'lifo'
+    PRIORITY = 'priority'