orionis 0.246.0__py3-none-any.whl → 0.247.0__py3-none-any.whl

orionis/framework.py

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

orionis/luminate/config/app/__init__.py

@@ -0,0 +1,10 @@
+from orionis.luminate.config.app.entities.app import App
+
+__all__ = [
+    "app"
+]
+__author__ = "Raúl Mauricio Uñate Castro"
+__description__ = (
+    "This dataclass defines the main configuration of the Orionis Framework application. "
+    "Its design aims to provide a flexible and adaptable structure for Python projects."
+)

orionis/luminate/config/app/entities/app.py

@@ -0,0 +1,205 @@
+from dataclasses import dataclass, field
+from orionis.luminate.config.app.enums.ciphers import Cipher
+from orionis.luminate.config.app.enums.environments import Environments
+from orionis.luminate.config.exceptions.integrity_exception import OrionisIntegrityException
+from orionis.luminate.services.environment.env import Env
+from orionis.luminate.services.workers.maximum_workers import MaximumWorkers
+
+@dataclass(unsafe_hash=True, kw_only=True)
+class App:
+    """
+    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__():
+    """
+
+    name: str = field(
+        default_factory=lambda: Env.get('APP_NAME', 'Orionis Application'),
+        metadata={
+            "description": "The name of the application. Defaults to 'Orionis Application'.",
+            "required": True,
+            "default": "Orionis Application"
+        }
+    )
+
+    env: Environments = field(
+        default_factory=lambda: Env.get('APP_ENV', Environments.DEVELOPMENT),
+        metadata={
+            "description": "The environment in which the application is running. Defaults to 'DEVELOPMENT'.",
+            "required": True,
+            "default": "Environments.DEVELOPMENT"
+        }
+    )
+
+    debug: bool = field(
+        default_factory=lambda: Env.get('APP_DEBUG', True),
+        metadata={
+            "description": "Flag indicating whether debug mode is enabled. Defaults to False.",
+            "required": True,
+            "default": True
+        }
+    )
+
+    url: str = field(
+        default_factory=lambda: Env.get('APP_URL', 'http://127.0.0.1'),
+        metadata={
+            "description": "The base URL of the application. Defaults to 'http://127.0.0.1'.",
+            "required": True,
+            "default": "http://127.0.0.1"
+        }
+    )
+
+    port: int = field(
+        default_factory=lambda: Env.get('APP_PORT', 8000),
+        metadata={
+            "description": "The port on which the application will run. Defaults to 8000.",
+            "required": True,
+            "default": 8000
+        }
+    )
+
+    workers: int = field(
+        default_factory=lambda: Env.get('APP_WORKERS', MaximumWorkers().calculate()),
+        metadata={
+            "description": "The number of worker processes to handle requests. Defaults to the maximum available workers.",
+            "required": True,
+            "default": "MaximumWorkers.calculate()"
+        }
+    )
+
+    reload: bool = field(
+        default_factory=lambda: Env.get('APP_RELOAD', True),
+        metadata={
+            "description": "Flag indicating whether the application should reload on code changes. Defaults to True.",
+            "required": True,
+            "default": True
+        }
+    )
+
+    timezone: str = field(
+        default_factory=lambda: Env.get('APP_TIMEZONE', 'UTC'),
+        metadata={
+            "description": "The timezone of the application. Defaults to 'UTC'.",
+            "required": True,
+            "default": "UTC"
+        }
+    )
+
+    locale: str = field(
+        default_factory=lambda: Env.get('APP_LOCALE', 'en'),
+        metadata={
+            "description": "The locale for the application. Defaults to 'en'.",
+            "required": True,
+            "default": "en"
+        }
+    )
+
+    fallback_locale: str = field(
+        default_factory=lambda: Env.get('APP_FALLBACK_LOCALE', 'en'),
+        metadata={
+            "description": "The fallback locale for the application. Defaults to 'en'.",
+            "required": True,
+            "default": "en"
+        }
+    )
+
+    cipher: str = field(
+        default_factory=lambda: Env.get('APP_CIPHER', Cipher.AES_256_CBC),
+        metadata={
+            "description": "The cipher used for encryption. Defaults to 'AES_256_CBC'.",
+            "required": True,
+            "default": "Cipher.AES_256_CBC"
+        }
+    )
+
+    key: str = field(
+        default_factory=lambda: Env.get('APP_KEY'),
+        metadata={
+            "description": "The encryption key for the application. Defaults to None.",
+            "required": False,
+            "default": None
+        }
+    )
+
+    maintenance: str = field(
+        default_factory=lambda: Env.get('APP_MAINTENANCE', '/maintenance'),
+        metadata={
+            "description": "The maintenance configuration for the application. Defaults to '/maintenance'.",
+            "required": True,
+            "default": "/maintenance"
+        }
+    )
+
+    def __post_init__(self):
+        """
+        Validates and normalizes the attributes after dataclass initialization.
+
+        Ensures that all fields have the correct types and values, raising TypeError
+        if any field is invalid. This helps catch configuration errors early.
+        """
+        if not isinstance(self.name, str) or not self.name.strip():
+            raise OrionisIntegrityException("The 'name' attribute must be a non-empty string of type str.")
+
+        if not isinstance(self.env, Environments):
+            if isinstance(self.env, str):
+                value = str(self.env).strip().upper()
+                if value in Environments._member_names_:
+                    self.env = getattr(Environments, value)
+                else:
+                    raise OrionisIntegrityException(f"Invalid environment value: {self.env}. Must be one of {Environments._member_names_}.")
+            else:
+                raise OrionisIntegrityException("The 'env' attribute must be of type Environments.")
+
+        if not isinstance(self.debug, bool):
+            raise OrionisIntegrityException("The 'debug' attribute must be a boolean.")
+
+        if not isinstance(self.url, str) or not self.url.strip():
+            raise OrionisIntegrityException("The 'url' attribute must be a non-empty string.")
+
+        if not isinstance(self.port, int):
+            raise OrionisIntegrityException("The 'port' attribute must be an integer.")
+
+        if not isinstance(self.workers, int):
+            raise OrionisIntegrityException("The 'workers' attribute must be an integer.")
+
+        if not isinstance(self.reload, bool):
+            raise OrionisIntegrityException("The 'reload' attribute must be a boolean.")
+
+        if not isinstance(self.timezone, str) or not self.timezone.strip():
+            raise OrionisIntegrityException("The 'timezone' attribute must be a non-empty string.")
+
+        if not isinstance(self.locale, str) or not self.locale.strip():
+            raise OrionisIntegrityException("The 'locale' attribute must be a non-empty string.")
+
+        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.")
+
+        if not isinstance(self.cipher, Cipher):
+            if isinstance(self.cipher, str):
+                value = str(self.cipher).strip().upper()
+                if value in Cipher._member_names_:
+                    self.cipher = getattr(Cipher, value)
+                else:
+                    raise OrionisIntegrityException(f"Invalid cipher value: {self.cipher}. Must be one of {Cipher._member_names_}.")
+            else:
+                raise OrionisIntegrityException("The 'cipher' attribute must be of type Cipher.")
+
+        if self.key is not None and not isinstance(self.key, str):
+            raise OrionisIntegrityException("The 'key' attribute must be a string or None.")
+
+        if not isinstance(self.maintenance, str):
+            raise OrionisIntegrityException("The 'maintenance' attribute must be a string (A Route).")

orionis/luminate/config/app/enums/ciphers.py

@@ -0,0 +1,34 @@
+from enum import Enum
+
+class Cipher(Enum):
+    """
+    Enumeration of supported AES cipher modes.
+
+    This enum defines various Advanced Encryption Standard (AES) cipher modes and key sizes
+    commonly used for encryption and decryption operations.
+
+    Members:
+        AES_128_CBC: AES with 128-bit key in Cipher Block Chaining (CBC) mode.
+        AES_192_CBC: AES with 192-bit key in CBC mode.
+        AES_256_CBC: AES with 256-bit key in CBC mode.
+        AES_128_GCM: AES with 128-bit key in Galois/Counter Mode (GCM).
+        AES_256_GCM: AES with 256-bit key in GCM.
+        AES_CTR: AES in Counter (CTR) mode.
+        AES_CFB: AES in Cipher Feedback (CFB) mode.
+        AES_CFB8: AES in CFB mode with 8-bit feedback.
+        AES_CFB128: AES in CFB mode with 128-bit feedback.
+        AES_OFB: AES in Output Feedback (OFB) mode.
+        AES_ECB: AES in Electronic Codebook (ECB) mode.
+    """
+
+    AES_128_CBC = "AES-128-CBC"
+    AES_192_CBC = "AES-192-CBC"
+    AES_256_CBC = "AES-256-CBC"
+    AES_128_GCM = "AES-128-GCM"
+    AES_256_GCM = "AES-256-GCM"
+    AES_CTR = "AES-CTR"
+    AES_CFB = "AES-CFB"
+    AES_CFB8 = "AES-CFB8"
+    AES_CFB128 = "AES-CFB128"
+    AES_OFB = "AES-OFB"
+    AES_ECB = "AES-ECB"

orionis/luminate/config/app/enums/environments.py

@@ -0,0 +1,15 @@
+from enum import Enum
+
+class Environments(Enum):
+    """
+    Enumeration of possible application environments.
+
+    Attributes:
+        DEVELOPMENT: Represents the development environment.
+        TESTING: Represents the testing environment.
+        PRODUCTION: Represents the production environment.
+    """
+
+    DEVELOPMENT = 'development'
+    TESTING = 'testing'
+    PRODUCTION = 'production'

orionis/luminate/config/auth/__init__.py

@@ -0,0 +1,7 @@
+from orionis.luminate.config.auth.entities.auth import Auth
+
+__all__ = [
+    "Auth",
+]
+__author__ = "Raul Mauricio Uñate Castro"
+__description__ = "This module exports a dataclass that contains the required properties to configure an Orionis application"

orionis/luminate/config/auth/entities/auth.py

@@ -0,0 +1,11 @@
+from dataclasses import dataclass
+
+@dataclass(unsafe_hash=True, kw_only=True)
+class Auth:
+    """
+    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

orionis/luminate/config/cache/__init__.py

@@ -0,0 +1,9 @@
+from orionis.luminate.config.cache.entities.cache import Cache
+
+__all__ = [
+    "Cache",
+]
+__author__ = "Raúl Mauricio Uñate Castro"
+__description__ = (
+    "This dataclass defines the structure of the cache configuration. "
+)

orionis/luminate/config/cache/entities/cache.py

@@ -0,0 +1,58 @@
+from dataclasses import dataclass, field
+from orionis.luminate.config.cache.entities.file import File
+from orionis.luminate.config.cache.entities.stores import Stores
+from orionis.luminate.config.cache.enums.drivers import Drivers
+from orionis.luminate.config.exceptions.integrity_exception import OrionisIntegrityException
+from orionis.luminate.services.environment import Env
+
+@dataclass
+class Cache:
+    """
+    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.
+            - Converts 'default' from string to Drivers enum if necessary.
+            - Validates that 'stores' is an instance of Stores.
+    """
+
+    default: Drivers | str = field(
+        default=Env.get("CACHE_STORE", Drivers.MEMORY),
+        metadata={
+            "description": "The default cache storage type (e.g., 'memory' or 'file').",
+            "type": Drivers,
+        },
+    )
+
+    stores: Stores = field(
+        default_factory=lambda: Stores(
+            file=File(
+                path=Env.get("CACHE_PATH", "storage/framework/cache/data")
+            )
+        )
+    )
+
+    def __post_init__(self):
+        """
+        Post-initialization processing to ensure the cache configuration is set correctly.
+        """
+        # Ensure the default cache store is valid
+        if not isinstance(self.default, (Drivers, str)):
+            raise OrionisIntegrityException("The default cache store must be an instance of Drivers or a string.")
+
+        # Convert string to Drivers enum if applicable
+        if isinstance(self.default, str):
+            value = self.default.upper().strip()
+            if value not in Drivers._member_names_:
+                raise OrionisIntegrityException(f"Invalid cache driver: {self.default}. Must be one of {Drivers._member_names_}.")
+            else:
+                self.default = getattr(Drivers, value)
+
+        # Ensure the stores attribute is an instance of Stores
+        if not isinstance(self.stores, Stores):
+            raise OrionisIntegrityException("The stores must be an instance of Stores.")

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

@@ -0,0 +1,29 @@
+from dataclasses import dataclass, field
+from orionis.luminate.services.paths import Resolver
+
+@dataclass
+class File:
+    """
+    Represents a file storage path.
+
+    Attributes
+    ----------
+    path : str
+        The file path used for caching.
+    """
+    path: str = field(
+        default_factory=lambda:Resolver().relativePath('storage/framework/cache/data').toString(),
+        metadata={
+            "description": "The file path used for caching.",
+            "type": str,
+        },
+    )
+
+    def __post_init__(self):
+        """
+        Post-initialization processing to ensure the path is set correctly.
+        """
+        if not self.path:
+            raise ValueError("The file path cannot be empty.")
+        if not isinstance(self.path, str):
+            raise TypeError("The file path must be a string.")

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

@@ -0,0 +1,35 @@
+from dataclasses import dataclass, field
+from typing import Any
+from orionis.luminate.config.cache.entities.file import File
+from orionis.luminate.services.paths.resolver import Resolver
+
+@dataclass
+class Stores:
+    """
+    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=lambda: File(
+            path=Resolver().relativePath('storage/framework/cache/data').toString()
+        ),
+        metadata={
+            "description": "An instance of `File` representing file-based cache storage.",
+            "type": File,
+        },
+    )
+
+    def __post_init__(self):
+        """
+        Post-initialization processing to ensure the stores are set correctly.
+        """
+        if not isinstance(self.file, File):
+            raise TypeError("The file store must be an instance of File.")

orionis/luminate/config/cache/enums/drivers.py

@@ -0,0 +1,12 @@
+from enum import Enum
+
+class Drivers(Enum):
+    """
+    Enumeration of supported cache drivers.
+
+    Attributes:
+        MEMORY: Represents an in-memory cache driver.
+        FILE: Represents a file-based cache driver.
+    """
+    MEMORY = "memory"
+    FILE = "file"

orionis/luminate/config/entities/testing.py

@@ -1,7 +1,17 @@
-from dataclasses import dataclass
-from typing import List
+from dataclasses import dataclass, field
+from typing import Any, List
+from orionis.luminate.config.exceptions.integrity_exception import OrionisIntegrityException
+from orionis.luminate.services.workers.maximum_workers import MaximumWorkers
 
-@dataclass(frozen=True, kw_only=True)
+def defaultExecutionMode() -> Any:
+    """
+    This function is a placeholder for the ExecutionMode enumeration.
+    In a real-world scenario, this would be replaced with the actual import statement.
+    """
+    from orionis.luminate.test.enums.test_mode import ExecutionMode
+    return ExecutionMode.SEQUENTIAL
+
+@dataclass(frozen=True, kw_only=True, slots=True)
 class Testing:
     """
     Testing is a dataclass that holds configuration options for running tests.
@@ -24,14 +34,182 @@ class Testing:
         test_name_pattern (str | None): A pattern to match specific test names. Default is None.
         tags (List[str] | None): A list of tags to filter tests. Default is None.
     """
-    verbosity: int = 2
-    execution_mode: str = 'sequential'
-    max_workers: int = 4
-    fail_fast: bool = False
-    print_result: bool = True
-    throw_exception: bool = False
-    base_path: str = 'tests'
-    folder_path: str = '*'
-    pattern: str = 'test_*.py'
-    test_name_pattern: str | None = None,
-    tags: List[str] | None = None
+    verbosity: int = field(
+        default=2,
+        metadata={
+            "description": "The verbosity level of the test output. Default is 2.",
+            "required": True,
+            "default": 2
+        }
+    )
+
+    execution_mode : Any = field(
+        default_factory=lambda: defaultExecutionMode(),
+        metadata={
+            "description": "The mode of test execution. Default is ExecutionMode.SEQUENTIAL.",
+            "required": True,
+            "default": "ExecutionMode.SEQUENTIAL"
+        }
+    )
+
+    max_workers: int = field(
+        default_factory=lambda : MaximumWorkers().calculate(),
+        metadata={
+            "description": "The maximum number of worker threads/processes to use when running tests in parallel. Default is 4.",
+            "required": True,
+            "default": "MaximumWorkers.calculate()"
+        }
+    )
+
+    fail_fast: bool = field(
+        default=False,
+        metadata={
+            "description": "Whether to stop execution after the first test failure. Default is False.",
+            "required": True,
+            "default": False
+        }
+    )
+
+    print_result: bool = field(
+        default=True,
+        metadata={
+            "description": "Whether to print the test results to the console. Default is True.",
+            "required": True,
+            "default": True
+        }
+    )
+
+    throw_exception: bool = field(
+        default=False,
+        metadata={
+            "description": "Whether to throw an exception if a test fails. Default is False.",
+            "required": True,
+            "default": False
+        }
+    )
+
+    base_path: str = field(
+        default='tests',
+        metadata={
+            "description": "The base directory where tests are located. Default is 'tests'.",
+            "required": True,
+            "default": 'tests'
+        }
+    )
+
+    folder_path: str | list = field(
+        default='*',
+        metadata={
+            "description": "The folder path pattern to search for tests. Default is '*'.",
+            "required": True,
+            "default": '*'
+        }
+    )
+
+    pattern: str = field(
+        default='test_*.py',
+        metadata={
+            "description": "The filename pattern to identify test files. Default is 'test_*.py'.",
+            "required": True,
+            "default": 'test_*.py'
+        }
+    )
+
+    test_name_pattern: str | None = field(
+        default=None,
+        metadata={
+            "description": "A pattern to match specific test names. Default is None.",
+            "required": False,
+            "default": None
+        }
+    )
+
+    tags: List[str] | None = field(
+        default_factory=lambda:[],
+        metadata={
+            "description": "A list of tags to filter tests. Default is an empty list.",
+            "required": False,
+            "default": []
+        }
+    )
+
+    def __post_init__(self):
+        """
+        Post-initialization validation for the testing configuration entity.
+        This method performs type and value checks on the instance attributes to ensure they meet the expected constraints:
+        - `verbosity` must be an integer between 0 and 2 (inclusive).
+        - `execution_mode` must not be None.
+        - `max_workers` must be a positive integer.
+        - `fail_fast`, `print_result`, and `throw_exception` must be booleans.
+        - `base_path`, `folder_path`, and `pattern` must be strings.
+        - `test_name_pattern` must be either a string or None.
+        - `tags` must be either None or a list of strings.
+        Raises:
+            OrionisIntegrityException: If any of the attributes do not meet the specified constraints.
+        """
+        if not isinstance(self.verbosity, int) or self.verbosity < 0 or self.verbosity > 2:
+            raise OrionisIntegrityException(
+                f"Invalid value for 'verbosity': {self.verbosity}. It must be an integer between 0 (silent) and 2 (detailed output)."
+            )
+
+        if self.execution_mode is None:
+            raise OrionisIntegrityException(
+                "'execution_mode' cannot be None. Please provide a valid ExecutionMode value."
+            )
+
+        if not isinstance(self.max_workers, int) or self.max_workers < 1:
+            raise OrionisIntegrityException(
+                f"Invalid value for 'max_workers': {self.max_workers}. It must be a positive integer greater than 0."
+            )
+
+        if not isinstance(self.fail_fast, bool):
+            raise OrionisIntegrityException(
+                f"Invalid type for 'fail_fast': {type(self.fail_fast).__name__}. It must be a boolean (True or False)."
+            )
+
+        if not isinstance(self.print_result, bool):
+            raise OrionisIntegrityException(
+                f"Invalid type for 'print_result': {type(self.print_result).__name__}. It must be a boolean (True or False)."
+            )
+
+        if not isinstance(self.throw_exception, bool):
+            raise OrionisIntegrityException(
+                f"Invalid type for 'throw_exception': {type(self.throw_exception).__name__}. It must be a boolean (True or False)."
+            )
+
+        if not isinstance(self.base_path, str):
+            raise OrionisIntegrityException(
+                f"Invalid type for 'base_path': {type(self.base_path).__name__}. It must be a string representing the base directory for tests."
+            )
+
+        if not (isinstance(self.folder_path, str) or isinstance(self.folder_path, list)):
+            raise OrionisIntegrityException(
+            f"Invalid type for 'folder_path': {type(self.folder_path).__name__}. It must be a string or a list of strings representing the folder path pattern."
+            )
+        if isinstance(self.folder_path, list):
+            for i, folder in enumerate(self.folder_path):
+                if not isinstance(folder, str):
+                    raise OrionisIntegrityException(
+                        f"Invalid type for folder at index {i} in 'folder_path': {type(folder).__name__}. Each folder path must be a string."
+                    )
+
+        if not isinstance(self.pattern, str):
+            raise OrionisIntegrityException(
+                f"Invalid type for 'pattern': {type(self.pattern).__name__}. It must be a string representing the filename pattern for test files."
+            )
+
+        if self.test_name_pattern is not None and not isinstance(self.test_name_pattern, str):
+            raise OrionisIntegrityException(
+                f"Invalid type for 'test_name_pattern': {type(self.test_name_pattern).__name__}. It must be a string or None."
+            )
+
+        if self.tags is not None:
+            if not isinstance(self.tags, list):
+                raise OrionisIntegrityException(
+                    f"Invalid type for 'tags': {type(self.tags).__name__}. It must be a list of strings or None."
+                )
+            for i, tag in enumerate(self.tags):
+                if not isinstance(tag, str):
+                    raise OrionisIntegrityException(
+                        f"Invalid type for tag at index {i} in 'tags': {type(tag).__name__}. Each tag must be a string."
+                    )