orionis 0.404.0__py3-none-any.whl → 0.406.0__py3-none-any.whl

orionis/foundation/config/app/entities/app.py

@@ -1,141 +1,171 @@
-from dataclasses import asdict, dataclass, field, fields
+from dataclasses import dataclass, field
 from orionis.foundation.config.app.enums import Cipher, Environments
 from orionis.foundation.exceptions import OrionisIntegrityException
 from orionis.services.environment.env import Env
+from orionis.services.environment.key.key_generator import SecureKeyGenerator
 from orionis.services.system.workers import Workers
+from orionis.support.entities.base import BaseEntity
 
 @dataclass(unsafe_hash=True, kw_only=True)
-class App:
+class App(BaseEntity):
     """
-    Represents the configuration settings for the application.
-    Attributes:
-        name (str): The name of the application. Defaults to 'Orionis Application'.
-        env (Environments): The environment in which the application is running. Defaults to 'DEVELOPMENT'.
-        debug (bool): Flag indicating whether debug mode is enabled. Defaults to True.
-        url (str): The base URL of the application. Defaults to 'http://127.0.0.1'.
-        port (int): The port on which the application will run. Defaults to 8000.
-        workers (int): The number of worker processes to handle requests. Defaults to the maximum available workers.
-        reload (bool): Flag indicating whether the application should reload on code changes. Defaults to True.
-        timezone (str): The timezone of the application. Defaults to 'UTC'.
-        locale (str): The locale for the application. Defaults to 'en'.
-        fallback_locale (str): The fallback locale for the application. Defaults to 'en'.
-        cipher (Cipher): The cipher used for encryption. Defaults to 'AES_256_CBC'.
-        key (str or None): The encryption key for the application. Defaults to None.
-        maintenance (Maintenance): The maintenance configuration for the application. Defaults to '/maintenance'.
-    Methods:
-        __post_init__():
+    Application configuration settings.
+
+    Parameters
+    ----------
+    name : str, optional
+        The name of the application. Default is 'Orionis Application'.
+    env : str or Environments, optional
+        The environment in which the application is running. Default is 'DEVELOPMENT'.
+    debug : bool, optional
+        Whether debug mode is enabled. Default is True.
+    url : str, optional
+        The base URL of the application. Default is 'http://127.0.0.1'.
+    port : int, optional
+        The port on which the application will run. Default is 8000.
+    workers : int, optional
+        Number of worker processes to handle requests. Default is maximum available workers.
+    reload : bool, optional
+        Whether the application should reload on code changes. Default is True.
+    timezone : str, optional
+        The timezone of the application. Default is 'UTC'.
+    locale : str, optional
+        The locale for the application. Default is 'en'.
+    fallback_locale : str, optional
+        The fallback locale for the application. Default is 'en'.
+    cipher : str or Cipher, optional
+        The cipher used for encryption. Default is 'AES_256_CBC'.
+    key : str, optional
+        The encryption key for the application. Default is None.
+    maintenance : str, optional
+        The maintenance route for the application. Default is '/maintenance'.
+
+    Methods
+    -------
+    __post_init__()
+        Validates and normalizes the attributes after dataclass initialization.
     """
 
     name: str = field(
-        default_factory=lambda: Env.get('APP_NAME', 'Orionis Application'),
-        metadata={
+        default = Env.get('APP_NAME', 'Orionis Application'),
+        metadata = {
             "description": "The name of the application. Defaults to 'Orionis Application'.",
-            "default": "Orionis Application"
+            "default": 'Orionis Application'
         }
     )
 
     env: str | Environments = field(
-        default_factory=lambda: Env.get('APP_ENV', Environments.DEVELOPMENT),
-        metadata={
+        default = Env.get('APP_ENV', Environments.DEVELOPMENT.value),
+        metadata = {
             "description": "The environment in which the application is running. Defaults to 'DEVELOPMENT'.",
-            "default": "Environments.DEVELOPMENT"
+            "default": Environments.DEVELOPMENT.value
         }
     )
 
     debug: bool = field(
-        default_factory=lambda: Env.get('APP_DEBUG', True),
-        metadata={
+        default = Env.get('APP_DEBUG', True),
+        metadata = {
             "description": "Flag indicating whether debug mode is enabled. Defaults to False.",
             "default": True
         }
     )
 
     url: str = field(
-        default_factory=lambda: Env.get('APP_URL', 'http://127.0.0.1'),
-        metadata={
+        default = Env.get('APP_URL', 'http://127.0.0.1'),
+        metadata = {
             "description": "The base URL of the application. Defaults to 'http://127.0.0.1'.",
-            "default": "http://127.0.0.1"
+            "default": 'http://127.0.0.1'
         }
     )
 
     port: int = field(
-        default_factory=lambda: Env.get('APP_PORT', 8000),
-        metadata={
+        default = Env.get('APP_PORT', 8000),
+        metadata = {
             "description": "The port on which the application will run. Defaults to 8000.",
             "default": 8000
         }
     )
 
     workers: int = field(
-        default_factory=lambda: Env.get('APP_WORKERS', Workers().calculate()),
-        metadata={
+        default = Env.get('APP_WORKERS', Workers().calculate()),
+        metadata = {
             "description": "The number of worker processes to handle requests. Defaults to the maximum available workers.",
-            "default": "Calculated by Workers()."
+            "default": Workers().calculate()
         }
     )
 
     reload: bool = field(
-        default_factory=lambda: Env.get('APP_RELOAD', True),
-        metadata={
+        default = Env.get('APP_RELOAD', True),
+        metadata = {
             "description": "Flag indicating whether the application should reload on code changes. Defaults to True.",
             "default": True
         }
     )
 
     timezone: str = field(
-        default_factory=lambda: Env.get('APP_TIMEZONE', 'UTC'),
-        metadata={
+        default = Env.get('APP_TIMEZONE', 'UTC'),
+        metadata = {
             "description": "The timezone of the application. Defaults to 'UTC'.",
-            "default": "UTC"
+            "default": 'UTC'
         }
     )
 
     locale: str = field(
-        default_factory=lambda: Env.get('APP_LOCALE', 'en'),
-        metadata={
+        default = Env.get('APP_LOCALE', 'en'),
+        metadata = {
             "description": "The locale for the application. Defaults to 'en'.",
-            "default": "en"
+            "default": 'en'
         }
     )
 
     fallback_locale: str = field(
-        default_factory=lambda: Env.get('APP_FALLBACK_LOCALE', 'en'),
-        metadata={
+        default = Env.get('APP_FALLBACK_LOCALE', 'en'),
+        metadata = {
             "description": "The fallback locale for the application. Defaults to 'en'.",
-            "default": "en"
+            "default": 'en'
         }
     )
 
     cipher: str | Cipher = field(
-        default_factory=lambda: Env.get('APP_CIPHER', Cipher.AES_256_CBC),
-        metadata={
+        default = Env.get('APP_CIPHER', Cipher.AES_256_CBC.value),
+        metadata = {
             "description": "The cipher used for encryption. Defaults to 'AES_256_CBC'.",
-            "default": "Cipher.AES_256_CBC"
+            "default": Cipher.AES_256_CBC.value
         }
     )
 
     key: str = field(
-        default_factory=lambda: Env.get('APP_KEY'),
-        metadata={
+        default = Env.get('APP_KEY'),
+        metadata = {
             "description": "The encryption key for the application. Defaults to None.",
             "default": None
         }
     )
 
     maintenance: str = field(
-        default_factory=lambda: Env.get('APP_MAINTENANCE', '/maintenance'),
-        metadata={
+        default = Env.get('APP_MAINTENANCE', '/maintenance'),
+        metadata = {
             "description": "The maintenance configuration for the application. Defaults to '/maintenance'.",
-            "default": "/maintenance"
+            "default": '/maintenance'
         }
     )
 
     def __post_init__(self):
         """
-        Validates and normalizes the attributes after dataclass initialization.
+        Validate and normalize attributes after dataclass initialization.
+
+        This method checks that all configuration fields have the correct types and valid values.
+        If any field is invalid, an OrionisIntegrityException is raised to prevent misconfiguration.
 
-        Ensures that all fields have the correct types and values, raising TypeError
-        if any field is invalid. This helps catch configuration errors early.
+        Raises
+        ------
+        OrionisIntegrityException
+            If any attribute does not meet the required type or value constraints.
+
+        Notes
+        -----
+        This method is automatically called after the dataclass is instantiated to ensure
+        application configuration integrity and catch errors early in the lifecycle.
         """
 
         # Validate `name` attribute
@@ -153,30 +183,43 @@ class App:
         elif isinstance(self.env, Environments):
             self.env = self.env.value
 
+        # Validate `debug` attribute
         if not isinstance(self.debug, bool):
             raise OrionisIntegrityException("The 'debug' attribute must be a boolean.")
 
+        # Validate `url` attribute
         if not isinstance(self.url, str) or not self.url.strip():
             raise OrionisIntegrityException("The 'url' attribute must be a non-empty string.")
 
+        # Validate `port` attribute
         if not isinstance(self.port, int):
             raise OrionisIntegrityException("The 'port' attribute must be an integer.")
 
+        # Validate `workers` attribute
         if not isinstance(self.workers, int):
             raise OrionisIntegrityException("The 'workers' attribute must be an integer.")
 
+        real_workers = Workers().calculate()
+        if self.workers < 1 or self.workers > real_workers:
+            raise OrionisIntegrityException(f"The 'workers' attribute must be between 1 and {real_workers}.")
+
+        # Validate `reload` attribute
         if not isinstance(self.reload, bool):
             raise OrionisIntegrityException("The 'reload' attribute must be a boolean.")
 
+        # Validate `timezone` attribute
         if not isinstance(self.timezone, str) or not self.timezone.strip():
             raise OrionisIntegrityException("The 'timezone' attribute must be a non-empty string.")
 
+        # Validate `locale` attribute
         if not isinstance(self.locale, str) or not self.locale.strip():
             raise OrionisIntegrityException("The 'locale' attribute must be a non-empty string.")
 
+        # Validate `fallback_locale` attribute
         if not isinstance(self.fallback_locale, str) or not self.fallback_locale.strip():
             raise OrionisIntegrityException("The 'fallback_locale' attribute must be a non-empty string.")
 
+        # Validate `cipher` attribute
         options_cipher = Cipher._member_names_
         if not isinstance(self.cipher, (Cipher, str)):
             raise OrionisIntegrityException("The 'cipher' attribute must be a Cipher or a string.")
@@ -190,38 +233,12 @@ class App:
         elif isinstance(self.cipher, Cipher):
             self.cipher = self.cipher.value
 
-        if self.key is not None and not isinstance(self.key, str):
-            raise OrionisIntegrityException("The 'key' attribute must be a string or None.")
+        # Validate `key` attribute
+        if self.key is None:
+            self.key = SecureKeyGenerator.generate()
+        if not isinstance(self.key, str):
+            raise OrionisIntegrityException("The 'key' attribute must be a string.")
 
+        # Validate `maintenance` attribute
         if not isinstance(self.maintenance, str) or not self.name.strip() or not self.maintenance.startswith('/'):
-            raise OrionisIntegrityException("The 'maintenance' attribute must be a non-empty string representing a valid route (e.g., '/maintenance').")
-
-    def toDict(self) -> dict:
-        """
-        Convert the object to a dictionary representation.
-        Returns:
-            dict: A dictionary representation of the Dataclass object.
-        """
-        return asdict(self)
-
-    def getFields(self):
-        """
-        Retrieves a list of field information for the current dataclass instance.
-
-        Returns:
-            list: A list of dictionaries, each containing details about a field:
-                - name (str): The name of the field.
-                - type (type): The type of the field.
-                - default: The default value of the field, if specified; otherwise, the value from metadata or None.
-                - metadata (mapping): The metadata associated with the field.
-        """
-        __fields = []
-        for field in fields(self):
-            __metadata = dict(field.metadata) or {}
-            __fields.append({
-                "name": field.name,
-                "type": field.type.__name__ if hasattr(field.type, '__name__') else str(field.type),
-                "default": field.default if (field.default is not None and '_MISSING_TYPE' not in str(field.default)) else __metadata.get('default', None),
-                "metadata": __metadata
-            })
-        return __fields
+            raise OrionisIntegrityException("The 'maintenance' attribute must be a non-empty string representing a valid route (e.g., '/maintenance').")

orionis/foundation/config/auth/entities/auth.py

@@ -1,41 +1,12 @@
-from dataclasses import asdict, dataclass, fields
+from dataclasses import dataclass
+from orionis.support.entities.base import BaseEntity
 
 @dataclass(unsafe_hash=True, kw_only=True)
-class Auth:
+class Auth(BaseEntity):
     """
     Represents the authentication entity within the system.
 
     This class serves as a placeholder for authentication-related attributes and methods.
     Extend this class to implement authentication logic such as user credentials, token management, or session handling.
     """
-    pass
-
-    def toDict(self) -> dict:
-        """
-        Convert the object to a dictionary representation.
-        Returns:
-            dict: A dictionary representation of the Dataclass object.
-        """
-        return asdict(self)
-
-    def getFields(self):
-        """
-        Retrieves a list of field information for the current dataclass instance.
-
-        Returns:
-            list: A list of dictionaries, each containing details about a field:
-                - name (str): The name of the field.
-                - type (type): The type of the field.
-                - default: The default value of the field, if specified; otherwise, the value from metadata or None.
-                - metadata (mapping): The metadata associated with the field.
-        """
-        __fields = []
-        for field in fields(self):
-            __metadata = dict(field.metadata) or {}
-            __fields.append({
-                "name": field.name,
-                "type": field.type.__name__ if hasattr(field.type, '__name__') else str(field.type),
-                "default": field.default if (field.default is not None and '_MISSING_TYPE' not in str(field.default)) else __metadata.get('default', None),
-                "metadata": __metadata
-            })
-        return __fields
+    pass

orionis/foundation/config/cache/entities/cache.py

@@ -1,18 +1,21 @@
-from dataclasses import asdict, dataclass, field, fields
+from dataclasses import dataclass, field
 from orionis.foundation.config.cache.entities.stores import Stores
 from orionis.foundation.config.cache.enums import Drivers
 from orionis.foundation.exceptions import OrionisIntegrityException
 from orionis.services.environment.env import Env
+from orionis.support.entities.base import BaseEntity
 
 @dataclass(unsafe_hash=True, kw_only=True)
-class Cache:
+class Cache(BaseEntity):
     """
     Represents the cache configuration for the application.
+
     Attributes:
         default (Drivers | str): The default cache storage type. Can be a member of the Drivers enum or a string
             (e.g., 'memory', 'file'). Defaults to the value of the 'CACHE_STORE' environment variable or Drivers.MEMORY.
         stores (Stores): The configuration for available cache stores. Defaults to a Stores instance with a file store
             at the path specified by the 'CACHE_PATH' environment variable or "storage/framework/cache/data".
+
     Methods:
         __post_init__():
             - Validates that 'default' is either a Drivers enum member or a string.
@@ -21,28 +24,30 @@ class Cache:
     """
 
     default: Drivers | str = field(
-        default_factory=lambda:Env.get("CACHE_STORE", Drivers.MEMORY),
-        metadata={
+        default_factory = lambda : Env.get("CACHE_STORE", Drivers.MEMORY),
+        metadata = {
             "description": "The default cache storage type. Can be a member of the Drivers enum or a string (e.g., 'memory', 'file').",
-            "default": "Drivers.MEMORY",
+            "default": Drivers.MEMORY.value
         },
     )
 
-    stores: Stores = field(
-        default_factory=Stores,
-        metadata={
+    stores: Stores | dict = field(
+        default_factory = lambda: Stores(),
+        metadata = {
             "description": "The configuration for available cache stores. Defaults to a file store at the specified path.",
-            "default": "file=File(path='storage/framework/cache/data')",
+            "default": lambda: Stores().toDict()
         }
     )
 
     def __post_init__(self):
         """
         Post-initialization method for validating and normalizing cache configuration.
+
         Ensures that:
         - The `default` attribute is either an instance of `Drivers` or a string representing a valid driver name.
         - If `default` is a string, it is converted to the corresponding `Drivers` enum member after validation.
         - The `stores` attribute is an instance of `Stores`.
+
         Raises:
             OrionisIntegrityException: If `default` is not a valid driver or if `stores` is not an instance of `Stores`.
         """
@@ -62,35 +67,7 @@ class Cache:
             self.default = self.default.value
 
         # Validate the 'stores' attribute to ensure it is an instance of Stores
-        if not isinstance(self.stores, Stores):
-            raise OrionisIntegrityException("The stores must be an instance of Stores.")
-
-    def toDict(self) -> dict:
-        """
-        Convert the object to a dictionary representation.
-        Returns:
-            dict: A dictionary representation of the Dataclass object.
-        """
-        return asdict(self)
-
-    def getFields(self):
-        """
-        Retrieves a list of field information for the current dataclass instance.
-
-        Returns:
-            list: A list of dictionaries, each containing details about a field:
-                - name (str): The name of the field.
-                - type (type): The type of the field.
-                - default: The default value of the field, if specified; otherwise, the value from metadata or None.
-                - metadata (mapping): The metadata associated with the field.
-        """
-        __fields = []
-        for field in fields(self):
-            __metadata = dict(field.metadata) or {}
-            __fields.append({
-                "name": field.name,
-                "type": field.type.__name__ if hasattr(field.type, '__name__') else str(field.type),
-                "default": field.default if (field.default is not None and '_MISSING_TYPE' not in str(field.default)) else __metadata.get('default', None),
-                "metadata": __metadata
-            })
-        return __fields
+        if not isinstance(self.stores, (Stores, dict)):
+            raise OrionisIntegrityException("The stores configuration must be an instance of Stores or a dictionary.")
+        if isinstance(self.stores, dict):
+            self.stores = Stores(**self.stores)

orionis/foundation/config/cache/entities/file.py

@@ -1,13 +1,16 @@
-from dataclasses import asdict, dataclass, field, fields
+from dataclasses import dataclass, field
 from orionis.foundation.exceptions import OrionisIntegrityException
+from orionis.support.entities.base import BaseEntity
 
 @dataclass(unsafe_hash=True, kw_only=True)
-class File:
+class File(BaseEntity):
     """
     Represents the configuration entity for a file-based cache store.
+
     Attributes:
         path (str): The file system path where cache data will be stored. By default, this is set to
             'storage/framework/cache/data' using a relative path resolver.
+
     Methods:
         __post_init__():
             Validates the 'path' attribute after dataclass initialization. Raises an
@@ -15,8 +18,8 @@ class File:
     """
 
     path: str = field(
-        default='storage/framework/cache/data',
-        metadata={
+        default = 'storage/framework/cache/data',
+        metadata = {
             "description": "The configuration for available cache stores. Defaults to a file store at the specified path.",
             "default": "storage/framework/cache/data"
         },
@@ -35,34 +38,4 @@ class File:
         if not self.path:
             raise OrionisIntegrityException("File cache configuration error: 'path' cannot be empty. Please provide a valid file path.")
         if not isinstance(self.path, str):
-            raise OrionisIntegrityException(f"File cache configuration error: 'path' must be a string, got {type(self.path).__name__}.")
-
-    def toDict(self) -> dict:
-        """
-        Convert the object to a dictionary representation.
-        Returns:
-            dict: A dictionary representation of the Dataclass object.
-        """
-        return asdict(self)
-
-    def getFields(self):
-        """
-        Retrieves a list of field information for the current dataclass instance.
-
-        Returns:
-            list: A list of dictionaries, each containing details about a field:
-                - name (str): The name of the field.
-                - type (type): The type of the field.
-                - default: The default value of the field, if specified; otherwise, the value from metadata or None.
-                - metadata (mapping): The metadata associated with the field.
-        """
-        __fields = []
-        for field in fields(self):
-            __metadata = dict(field.metadata) or {}
-            __fields.append({
-                "name": field.name,
-                "type": field.type.__name__ if hasattr(field.type, '__name__') else str(field.type),
-                "default": field.default if (field.default is not None and '_MISSING_TYPE' not in str(field.default)) else __metadata.get('default', None),
-                "metadata": __metadata
-            })
-        return __fields
+            raise OrionisIntegrityException(f"File cache configuration error: 'path' must be a string, got {type(self.path).__name__}.")

orionis/foundation/config/cache/entities/stores.py

@@ -1,26 +1,29 @@
-from dataclasses import asdict, dataclass, field, fields
+from dataclasses import dataclass, field
 from orionis.foundation.config.cache.entities.file import File
 from orionis.foundation.exceptions import OrionisIntegrityException
+from orionis.support.entities.base import BaseEntity
 
 @dataclass(unsafe_hash=True, kw_only=True)
-class Stores:
+class Stores(BaseEntity):
     """
     Represents a collection of cache storage backends for the application.
+
     Attributes:
         file (File): An instance of `File` representing file-based cache storage.
             The default path is set to 'storage/framework/cache/data', resolved
             relative to the application's root directory.
+
     Methods:
         __post_init__():
             Ensures that the 'file' attribute is properly initialized as an instance of `File`.
             Raises a TypeError if the type check fails.
     """
 
-    file: File = field(
-        default_factory=File,
-        metadata={
+    file: File | dict = field(
+        default_factory = lambda: File(),
+        metadata = {
             "description": "An instance of `File` representing file-based cache storage.",
-            "default": "File(path='storage/framework/cache/data')",
+            "default": lambda: File().toDict()
         },
     )
 
@@ -29,40 +32,16 @@ class Stores:
         Post-initialization method to validate the 'file' attribute.
 
         Ensures that the 'file' attribute is an instance of the File class.
+
         Raises:
             OrionisIntegrityException: If 'file' is not an instance of File, with a descriptive error message.
         """
-        if not isinstance(self.file, File):
+
+        # Validate `file` atribute
+        if not isinstance(self.file, (File, dict)):
             raise OrionisIntegrityException(
-                f"The 'file' attribute must be an instance of File, but got {type(self.file).__name__}."
+                f"The 'file' attribute must be an instance of File or a dict, "
+                f"but got {type(self.file).__name__}."
             )
-
-    def toDict(self) -> dict:
-        """
-        Convert the object to a dictionary representation.
-        Returns:
-            dict: A dictionary representation of the Dataclass object.
-        """
-        return asdict(self)
-
-    def getFields(self):
-        """
-        Retrieves a list of field information for the current dataclass instance.
-
-        Returns:
-            list: A list of dictionaries, each containing details about a field:
-                - name (str): The name of the field.
-                - type (type): The type of the field.
-                - default: The default value of the field, if specified; otherwise, the value from metadata or None.
-                - metadata (mapping): The metadata associated with the field.
-        """
-        __fields = []
-        for field in fields(self):
-            __metadata = dict(field.metadata) or {}
-            __fields.append({
-                "name": field.name,
-                "type": field.type.__name__ if hasattr(field.type, '__name__') else str(field.type),
-                "default": field.default if (field.default is not None and '_MISSING_TYPE' not in str(field.default)) else __metadata.get('default', None),
-                "metadata": __metadata
-            })
-        return __fields
+        if isinstance(self.file, dict):
+            self.file = File(**self.file)