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

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

@@ -0,0 +1,62 @@
+from dataclasses import asdict, dataclass, field, fields
+from orionis.luminate.foundation.config.database.entities.connections import Connections
+from orionis.luminate.services.environment.env import Env
+from orionis.luminate.foundation.config.exceptions.integrity import OrionisIntegrityException
+
+@dataclass(unsafe_hash=True, kw_only=True)
+class Database:
+    """
+    Data class to represent the general database configuration.
+
+    Attributes
+    ----------
+    default : str
+        The name of the default database connection to use.
+    connections : Connections
+        The different database connections available to the application.
+    """
+    default: str = field(
+        default_factory=lambda: Env.get("DB_CONNECTION", "sqlite"),
+        metadata={
+            "description": "Default database connection name",
+            "default": "sqlite"
+        }
+    )
+
+    connections: Connections = field(
+        default_factory=Connections,
+        metadata={
+            "description": "Database connections",
+            "default": "Connections()"
+        }
+    )
+
+    def __post_init__(self):
+        """
+        Post-initialization method for validating and normalizing the 'default' and 'connections' attributes.
+        Validates that the 'default' attribute is either a valid string corresponding to a member of DatabaseConnections
+        or an instance of DatabaseConnections. If 'default' is a valid string, it is converted to its corresponding value.
+        If 'default' is not valid, raises an OrionisIntegrityException.
+        Also ensures that the 'connections' attribute is an instance of Connections and is not empty.
+        Raises an OrionisIntegrityException if the validation fails.
+        """
+
+        # Validate default attribute
+        options = [field.name for field in fields(Connections)]
+        if isinstance(self.default, str):
+            if self.default not in options:
+                raise OrionisIntegrityException(f"The 'default' attribute must be one of {str(options)}.")
+        else:
+            raise OrionisIntegrityException(f"The 'default' attribute cannot be empty. Options are: {str(options)}")
+
+        # Validate connections attribute
+        if not self.connections or not isinstance(self.connections, Connections):
+            raise OrionisIntegrityException("The 'connections' attribute must be of type Connections.")
+
+    def toDict(self) -> dict:
+        """
+        Convert the object to a dictionary representation.
+        Returns:
+            dict: A dictionary representation of the Dataclass object.
+        """
+        return asdict(self)

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

@@ -0,0 +1,270 @@
+from dataclasses import asdict, dataclass, field
+from typing import Optional
+from orionis.luminate.foundation.config.database.enums.mysql_charsets import MySQLCharset
+from orionis.luminate.foundation.config.database.enums.mysql_collations import MySQLCollation
+from orionis.luminate.foundation.config.database.enums.mysql_engine import MySQLEngine
+from orionis.luminate.foundation.config.exceptions.integrity import OrionisIntegrityException
+from orionis.luminate.services.environment.env import Env
+
+@dataclass(unsafe_hash=True, kw_only=True)
+class MySQL:
+    """
+    Data class to represent the MySQL database configuration.
+
+    Attributes
+    ----------
+    driver : str
+        The database driver being used, e.g., 'mysql'.
+    host : str
+        The host address for the MySQL server.
+    port : str
+        The port for connecting to the MySQL server.
+    database : str
+        The name of the MySQL database.
+    username : str
+        The username for connecting to the MySQL database.
+    password : str
+        The password for the MySQL database.
+    unix_socket : str
+        The path to the Unix socket for MySQL connections (optional).
+    charset : str
+        The charset used for the connection.
+    collation : str
+        The collation for the database.
+    prefix : str
+        Prefix for table names.
+    prefix_indexes : bool
+        Whether to prefix index names.
+    strict : bool
+        Whether to enforce strict SQL mode.
+    engine : Optional[str]
+        The storage engine for the MySQL database (optional).
+    """
+
+    driver: str = field(
+        default="mysql",
+        metadata={
+            "description": "The database driver being used.",
+            "default": "mysql",
+        }
+    )
+
+    host: str = field(
+        default_factory=lambda: Env.get("DB_HOST", "127.0.0.1"),
+        metadata={
+            "description": "The host address for the MySQL server.",
+            "default": "127.0.0.1",
+        }
+    )
+
+    port: int = field(
+        default_factory=lambda: Env.get("DB_PORT", 3306),
+        metadata={
+            "description": "The port for connecting to the MySQL server.",
+            "default": 3306,
+        }
+    )
+
+    database: str = field(
+        default_factory=lambda: Env.get("DB_DATABASE", "orionis"),
+        metadata={
+            "description": "The name of the MySQL database.",
+            "default": "orionis",
+        }
+    )
+
+    username: str = field(
+        default_factory=lambda: Env.get("DB_USERNAME", "root"),
+        metadata={
+            "description": "The username for connecting to the MySQL database.",
+            "default": "root",
+        }
+    )
+
+    password: str = field(
+        default_factory=lambda: Env.get("DB_PASSWORD", ""),
+        metadata={
+            "description": "The password for the MySQL database.",
+            "default": "secret",
+        }
+    )
+
+    unix_socket: str = field(
+        default_factory=lambda: Env.get("DB_SOCKET", ""),
+        metadata={
+            "description": "The path to the Unix socket for MySQL connections (optional).",
+            "default": "",
+        }
+    )
+
+    charset: str | MySQLCharset = field(
+        default=MySQLCharset.UTF8MB4,
+        metadata={
+            "description": "The charset used for the connection.",
+            "default": "utf8mb4",
+        }
+    )
+
+    collation: str | MySQLCollation = field(
+        default=MySQLCollation.UTF8MB4_UNICODE_CI,
+        metadata={
+            "description": "The collation for the database.",
+            "default": "utf8mb4_unicode_ci",
+        }
+    )
+
+    prefix: str = field(
+        default="",
+        metadata={
+            "description": "Prefix for table names.",
+            "default": "",
+        }
+    )
+
+    prefix_indexes: bool = field(
+        default=True,
+        metadata={
+            "description": "Whether to prefix index names.",
+            "default": True,
+        }
+    )
+
+    strict: bool = field(
+        default=True,
+        metadata={
+            "description": "Whether to enforce strict SQL mode.",
+            "default": True,
+        }
+    )
+
+    engine: Optional[str | MySQLEngine] = field(
+        default=MySQLEngine.INNODB,
+        metadata={
+            "description": "The storage engine for the MySQL database (optional).",
+            "default": MySQLEngine.INNODB,
+            "type": str,
+        }
+    )
+
+    def __post_init__(self):
+        """
+        Post-initialization validation for MySQL database entity configuration.
+        This method performs comprehensive validation on the instance attributes to ensure
+        that all required fields are present and correctly typed. It raises an
+        OrionisIntegrityException with a descriptive message if any validation fails.
+        Validations performed:
+        - Host: Must be a non-empty string.
+        - Port: Must be an integer between 1 and 65535.
+        - Database name: Must be a non-empty string.
+        - Username: Must be a non-empty string.
+        - Password: Must be a string (can be empty).
+        - Unix socket: If provided, must be a string.
+        - Charset: Must be a non-empty string.
+        - Collation: Must be a non-empty string.
+        - Prefix: If provided, must be a string.
+        - Prefix indexes: Must be a boolean.
+        - Strict: Must be a boolean.
+        - Engine: If provided, must be a string.
+        Raises:
+            OrionisIntegrityException: If any attribute fails validation.
+        """
+
+        # Validate driver
+        if self.driver != 'mysql':
+            raise OrionisIntegrityException("Invalid driver: expected 'mysql'. Please ensure the 'driver' attribute is set to 'mysql'.")
+
+        # Validate host
+        if not self.host or not isinstance(self.host, str):
+            raise OrionisIntegrityException("Database host must be a non-empty string.")
+
+        # Validate port type
+        if not isinstance(self.port, (int)):
+            raise OrionisIntegrityException("Database port must be an integer.")
+
+        # Validate port range
+        if self.port > 65535 or self.port < 1:
+            raise OrionisIntegrityException("Database port must be between 1 and 65535.")
+
+        # Validate database name
+        if not self.database or not isinstance(self.database, str):
+            raise OrionisIntegrityException("Database name must be a non-empty string.")
+
+        # Validate username
+        if not self.username or not isinstance(self.username, str):
+            raise OrionisIntegrityException("Database username must be a non-empty string.")
+
+        # Validate password
+        if self.password is None or not isinstance(self.password, str):
+            raise OrionisIntegrityException("Database password must be a string (can be empty for some setups).")
+
+        # Validate unix_socket
+        if self.unix_socket is not None and not isinstance(self.unix_socket, str):
+            raise OrionisIntegrityException("Unix socket path must be a string.")
+
+        # Validate charset
+        if not self.charset or not isinstance(self.charset, (str, MySQLCharset)):
+            raise OrionisIntegrityException("Charset must be a non-empty string or MySQLCharset enum.")
+
+        # Convert charset to MySQLCharset enum if it's a string
+        if isinstance(self.charset, str):
+            _value = str(self.charset).upper().strip()
+            options_charsets = MySQLCharset._member_names_
+            if _value not in options_charsets:
+                raise OrionisIntegrityException(f"Charset must be a valid MySQLCharset ({str(options_charsets)}) or string.")
+            else:
+                self.charset = MySQLCharset[_value].value
+        else:
+            self.charset = self.charset.value
+
+        # Validate collation
+        if not self.collation or not isinstance(self.collation, (str, MySQLCollation)):
+            raise OrionisIntegrityException("Collation must be a non-empty string or MySQLCollation enum.")
+
+        # Convert collation to MySQLCollation enum if it's a string
+        if isinstance(self.collation, str):
+            _value = str(self.collation).upper().strip()
+            options_collations = MySQLCollation._member_names_
+            if _value not in options_collations:
+                raise OrionisIntegrityException(f"Collation must be a valid MySQLCollation ({str(options_collations)}) or string.")
+            else:
+                self.collation = MySQLCollation[_value].value
+        else:
+            self.collation = self.collation.value
+
+        # Validate prefix
+        if self.prefix is not None and not isinstance(self.prefix, str):
+            raise OrionisIntegrityException("Prefix must be a string.")
+
+        # Validate prefix_indexes
+        if not isinstance(self.prefix_indexes, bool):
+            raise OrionisIntegrityException("prefix_indexes must be a boolean value.")
+
+        # Validate strict
+        if not isinstance(self.strict, bool):
+            raise OrionisIntegrityException("strict must be a boolean value.")
+
+        # Validate engine
+        if self.engine is not None:
+
+            # Check if engine is a string or MySQLEngine enum
+            if not isinstance(self.engine, (str, MySQLEngine)):
+                raise OrionisIntegrityException(f"Engine must be a string or MySQLEngine enum.")
+
+            # Convert engine to MySQLEngine enum if it's a string
+            options_engines = MySQLEngine._member_names_
+            if isinstance(self.engine, str):
+                _value = str(self.engine).upper().strip()
+                if _value not in options_engines:
+                    raise OrionisIntegrityException(f"Engine must be a valid MySQLEngine ({str(options_engines)}) or string.")
+                else:
+                    self.engine = MySQLEngine[_value].value
+            elif isinstance(self.engine, MySQLEngine):
+                self.engine = self.engine.value
+
+    def toDict(self) -> dict:
+        """
+        Convert the object to a dictionary representation.
+        Returns:
+            dict: A dictionary representation of the Dataclass object.
+        """
+        return asdict(self)

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

@@ -0,0 +1,227 @@
+from dataclasses import asdict, dataclass, field
+from typing import Optional
+from orionis.luminate.foundation.config.database.enums.oracle_encoding import OracleEncoding
+from orionis.luminate.foundation.config.database.enums.oracle_nencoding import OracleNencoding
+from orionis.luminate.foundation.config.exceptions.integrity import OrionisIntegrityException
+from orionis.luminate.services.environment.env import Env
+
+@dataclass(unsafe_hash=True, kw_only=True)
+class Oracle:
+    """
+    Data class to represent Oracle database configuration using oracledb.
+
+    Attributes
+    ----------
+    driver : str
+        The database driver being used, typically 'oracle'.
+    username : str
+        Username for the database connection.
+    password : str
+        Password for the database connection.
+    host : str
+        Hostname or IP address of the Oracle server.
+    port : int
+        Port number for the Oracle listener (default 1521).
+    service_name : Optional[str]
+        Service name for connection using the SERVICE_NAME method.
+    sid : Optional[str]
+        SID for connection using the SID method.
+    dsn : Optional[str]
+        Full DSN string, used if service_name/sid are not specified.
+    tns_name : Optional[str]
+        TNS alias name defined in tnsnames.ora.
+    encoding : str
+        Character encoding for the connection.
+    """
+
+    driver: str = field(
+        default="oracle",
+        metadata={
+            "description": "The database driver being used, typically 'oracle'.",
+            "default": "oracle"
+        }
+    )
+
+    username: str = field(
+        default_factory=lambda: Env.get("DB_USERNAME", "sys"),
+        metadata={
+            "description": "Oracle DB username.",
+            "default": "sys"
+        }
+    )
+
+    password: str = field(
+        default_factory=lambda: Env.get("DB_PASSWORD", ""),
+        metadata={
+            "description": "Oracle DB password.",
+            "default": ""
+        }
+    )
+
+    host: str = field(
+        default_factory=lambda: Env.get("DB_HOST", "localhost"),
+        metadata={
+            "description": "Oracle DB host address.",
+            "default": "localhost"
+        }
+    )
+
+    port: int = field(
+        default_factory=lambda: Env.get("DB_PORT", 1521),
+        metadata={
+            "description": "Oracle DB listener port.",
+            "default": 1521
+        }
+    )
+
+    service_name: Optional[str] = field(
+        default_factory=lambda: Env.get("DB_SERVICE_NAME", "ORCL"),
+        metadata={
+            "description": "Service name for Oracle DB.",
+            "default": "ORCL"
+        }
+    )
+
+    sid: Optional[str] = field(
+        default_factory=lambda: Env.get("DB_SID", None),
+        metadata={
+            "description": "SID for Oracle DB.",
+            "default": None
+        }
+    )
+
+    dsn: Optional[str] = field(
+        default_factory=lambda: Env.get("DB_DSN", None),
+        metadata={
+            "description": "DSN string (overrides host/port/service/sid).",
+            "default": None
+        }
+    )
+
+    tns_name: Optional[str] = field(
+        default_factory=lambda: Env.get("DB_TNS", None),
+        metadata={
+            "description": "TNS alias defined in tnsnames.ora file.",
+            "default": None
+        }
+    )
+
+    encoding: str | OracleEncoding = field(
+        default_factory=lambda: Env.get("DB_ENCODING", OracleEncoding.AL32UTF8),
+        metadata={
+            "description": "Database charset (CHAR/VARCHAR2)",
+            "default": "AL32UTF8"
+        }
+    )
+
+    nencoding: str | OracleNencoding = field(
+        default_factory=lambda: Env.get("DB_NENCODING", OracleNencoding.AL32UTF8),
+        metadata={
+            "description": "Database charset (NCHAR/NVARCHAR2)",
+            "default": "AL32UTF8"
+        }
+    )
+
+    def __post_init__(self):
+        """
+        Post-initialization validation for Oracle database connection entity.
+        This method performs strict validation on the configuration fields required to establish
+        an Oracle database connection. It ensures that all necessary parameters are present and
+        correctly formatted, raising an `OrionisIntegrityException` if any validation fails.
+        Validation rules:
+        - `driver` must be the string 'oracle'.
+        - `username` and `password` must be non-empty strings.
+        - `dsn` and `tns_name`, if provided, must be non-empty strings or None.
+        - If neither `dsn` nor `tns_name` is provided:
+            - `host` must be a non-empty string.
+            - `port` must be an integer between 1 and 65535.
+            - At least one of `service_name` or `sid` must be provided as a non-empty string.
+            - If provided, `service_name` and `sid` must be non-empty strings or None.
+        - `encoding` must be a non-empty string or an instance of `OracleEncoding`.
+        - `nencoding` must be a non-empty string.
+        Raises:
+            OrionisIntegrityException: If any configuration parameter is invalid.
+        """
+
+        # Validate driver
+        if not isinstance(self.driver, str) or self.driver.strip().lower() != "oracle":
+            raise OrionisIntegrityException("Invalid 'driver': must be the string 'oracle'.")
+
+        # Validate username
+        if not isinstance(self.username, str) or not self.username.strip():
+            raise OrionisIntegrityException("Invalid 'username': must be a non-empty string.")
+
+        # Validate password
+        if not isinstance(self.password, str):
+            raise OrionisIntegrityException("Invalid 'password': must be a string.")
+
+        # Validate dsn
+        if self.dsn is not None and (not isinstance(self.dsn, str) or not self.dsn.strip()):
+            raise OrionisIntegrityException("Invalid 'dsn': must be a non-empty string or None.")
+
+        # Validate tns_name
+        if self.tns_name is not None and (not isinstance(self.tns_name, str) or not self.tns_name.strip()):
+            raise OrionisIntegrityException("Invalid 'tns_name': must be a non-empty string or None.")
+
+        # If not using DSN or TNS, validate host/port/service_name/sid
+        if not self.dsn and not self.tns_name:
+
+            # Validate host
+            if not isinstance(self.host, str) or not self.host.strip():
+                raise OrionisIntegrityException("Invalid 'host': must be a non-empty string.")
+
+            # Validate port
+            if not isinstance(self.port, int) or self.port <= 0 or self.port > 65535:
+                raise OrionisIntegrityException("Invalid 'port': must be an integer between 1 and 65535.")
+
+            # Validate service_name and sid
+            if (self.service_name is None or not str(self.service_name).strip()) and (self.sid is None or not str(self.sid).strip()):
+                raise OrionisIntegrityException(
+                    "You must provide at least one of: 'service_name', 'sid', 'dsn', or 'tns_name'."
+                )
+
+            # Validate service_name and sid
+            if self.service_name is not None and (not isinstance(self.service_name, str) or not self.service_name.strip()):
+                raise OrionisIntegrityException("Invalid 'service_name': must be a non-empty string or None.")
+
+            # Validate sid
+            if self.sid is not None and (not isinstance(self.sid, str) or not self.sid.strip()):
+                raise OrionisIntegrityException("Invalid 'sid': must be a non-empty string or None.")
+
+        # Validate encoding
+        options_encoding = OracleEncoding._member_names_
+        if isinstance(self.encoding, str):
+            _value = self.encoding.upper().strip()
+            if _value not in options_encoding:
+                raise OrionisIntegrityException(
+                    f"The 'encoding' attribute must be a valid option {str(OracleEncoding._member_names_)}"
+                )
+            else:
+                self.encoding = OracleEncoding[_value].value
+        elif isinstance(self.encoding, OracleEncoding):
+            self.encoding = self.encoding.value
+        else:
+            raise OrionisIntegrityException("Invalid 'encoding': must be a string or OracleEncoding.")
+
+        # Validate nencoding
+        options_nencoding = OracleNencoding._member_names_
+        if isinstance(self.nencoding, str):
+            _value = self.nencoding.upper().strip()
+            if _value not in options_nencoding:
+                raise OrionisIntegrityException(
+                    f"The 'nencoding' attribute must be a valid option {str(OracleNencoding._member_names_)}"
+                )
+            else:
+                self.nencoding = OracleNencoding[_value].value
+        elif isinstance(self.nencoding, OracleNencoding):
+            self.nencoding = self.nencoding.value
+        else:
+            raise OrionisIntegrityException("Invalid 'nencoding': must be a string or OracleNencoding.")
+
+    def toDict(self) -> dict:
+        """
+        Convert the object to a dictionary representation.
+        Returns:
+            dict: A dictionary representation of the Dataclass object.
+        """
+        return asdict(self)