orionis 0.443.0__py3-none-any.whl → 0.445.0__py3-none-any.whl

orionis/console/args/argument.py

@@ -0,0 +1,343 @@
+import argparse
+from dataclasses import dataclass, field
+from typing import Any, Optional, List, Type, Union, Dict
+from orionis.console.args.enums.actions import ArgumentAction
+from orionis.console.exceptions.cli_orionis_value_error import CLIOrionisValueError
+
+@dataclass(kw_only=True, frozen=True, slots=True)
+class CLIArgument:
+    """
+    Represents a command-line argument for argparse.
+
+    This class encapsulates all the properties and validation logic needed to create
+    a command-line argument that can be added to an argparse ArgumentParser. It provides
+    automatic validation, type checking, and smart defaults for common argument patterns.
+
+    Attributes
+    ----------
+    flags : List[str]
+        List of flags for the argument (e.g., ['--export', '-e']). Must contain at least one flag.
+    type : Type
+        Data type of the argument. Can be any Python type or custom type.
+    help : str
+        Description of the argument. If not provided, will be auto-generated from the primary flag.
+    default : Any, optional
+        Default value for the argument.
+    choices : List[Any], optional
+        List of valid values for the argument. All choices must match the specified type.
+    required : bool, default False
+        Whether the argument is required. Only applies to optional arguments.
+    metavar : str, optional
+        Metavar for displaying in help messages. Auto-generated from primary flag if not provided.
+    dest : str, optional
+        Destination name for the argument in the namespace. Auto-generated from primary flag if not provided.
+    action : Union[str, ArgumentAction], default ArgumentAction.STORE
+        Action to perform with the argument when it's encountered.
+    nargs : Union[int, str], optional
+        Number of arguments expected (e.g., 1, 2, '+', '*').
+    const : Any, optional
+        Constant value for store_const or append_const actions.
+
+    Raises
+    ------
+    CLIOrionisValueError
+        If any validation fails during initialization.
+    """
+
+    # Required fields
+    flags: List[str] = None
+    type: Type = None
+    help: str = None
+
+    default: Any = field(
+        default_factory = None,
+        metadata = {
+            "description": "Default value for the argument.",
+            "default": None
+        }
+    )
+
+    choices: Optional[List[Any]] = field(
+        default_factory = None,
+        metadata = {
+            "description": "List of valid choices for the argument.",
+            "default": None
+        }
+    )
+
+    required: bool = field(
+        default_factory = False,
+        metadata = {
+            "description": "Indicates if the argument is required.",
+            "default": False
+        }
+    )
+
+    metavar: Optional[str] = field(
+        default_factory = None,
+        metadata = {
+            "description": "Metavar for displaying in help messages.",
+            "default": None
+        }
+    )
+
+    dest: Optional[str] = field(
+        default_factory = None,
+        metadata = {
+            "description": "Destination name for the argument in the namespace.",
+            "default": None
+        }
+    )
+
+    action: Union[str, ArgumentAction] = field(
+        default_factory = ArgumentAction.STORE,
+        metadata = {
+            "description": "Action to perform with the argument.",
+            "default": ArgumentAction.STORE.value
+        }
+    )
+
+    nargs: Optional[Union[int, str]] = field(
+        default_factory = None,
+        metadata = {
+            "description": "Number of arguments expected (e.g., 1, 2, '+', '*').",
+            "default": None
+        }
+    )
+
+    const: Any = field(
+        default_factory = None,
+        metadata = {
+            "description": "Constant value for store_const or append_const actions.",
+            "default": None
+        }
+    )
+
+    def __post_init__(self):
+        """
+        Validate and normalize all argument attributes after initialization.
+
+        This method performs comprehensive validation of all argument attributes
+        and applies smart defaults where appropriate. It ensures the argument
+        configuration is valid for use with argparse.
+
+        Raises
+        ------
+        CLIOrionisValueError
+            If any validation fails or invalid values are provided.
+        """
+
+        # Validate flags - must be provided and non-empty
+        if not self.flags:
+            raise CLIOrionisValueError(
+                "Flags list cannot be empty. Please provide at least one flag (e.g., ['--export', '-e'])"
+            )
+
+        # Convert single string flag to list for consistency
+        if isinstance(self.flags, str):
+            object.__setattr__(self, 'flags', [self.flags])
+
+        # Ensure flags is a list
+        if not isinstance(self.flags, list):
+            raise CLIOrionisValueError("Flags must be a string or a list of strings")
+
+        # Validate each flag format and ensure they're strings
+        for flag in self.flags:
+            if not isinstance(flag, str):
+                raise CLIOrionisValueError("All flags must be strings")
+
+        # Check for duplicate flags
+        if len(set(self.flags)) != len(self.flags):
+            raise CLIOrionisValueError("Duplicate flags are not allowed in the flags list")
+
+        # Determine primary flag (longest one, or first if only one)
+        primary_flag = max(self.flags, key=len) if len(self.flags) > 1 else self.flags[0]
+
+        # Validate type is actually a type
+        if not isinstance(self.type, type):
+            raise CLIOrionisValueError("Type must be a valid Python type or custom type class")
+
+        # Auto-generate help if not provided
+        if self.help is None:
+            object.__setattr__(self, 'help', f"Argument for {primary_flag}")
+
+        # Ensure help is a string
+        if not isinstance(self.help, str):
+            raise CLIOrionisValueError("Help text must be a string")
+
+        # Validate choices if provided
+        if self.choices is not None:
+            # Ensure choices is a list
+            if not isinstance(self.choices, list):
+                raise CLIOrionisValueError("Choices must be provided as a list")
+
+            # Ensure all choices match the specified type
+            if self.type and not all(isinstance(choice, self.type) for choice in self.choices):
+                raise CLIOrionisValueError(
+                    f"All choices must be of type {self.type.__name__}"
+                )
+
+        # Validate required is boolean
+        if not isinstance(self.required, bool):
+            raise CLIOrionisValueError("Required field must be a boolean value (True or False)")
+
+        # Auto-generate metavar if not provided
+        if self.metavar is None:
+            metavar = primary_flag.lstrip('-').upper().replace('-', '_')
+            object.__setattr__(self, 'metavar', metavar)
+
+        # Ensure metavar is a string
+        if not isinstance(self.metavar, str):
+            raise CLIOrionisValueError("Metavar must be a string")
+
+        # Auto-generate dest if not provided
+        if self.dest is None:
+            dest = primary_flag.lstrip('-').replace('-', '_')
+            object.__setattr__(self, 'dest', dest)
+
+        # Ensure dest is a string
+        if not isinstance(self.dest, str):
+            raise CLIOrionisValueError("Destination (dest) must be a string")
+
+        # Ensure dest is a valid Python identifier
+        if not self.dest.isidentifier():
+            raise CLIOrionisValueError(f"Destination '{self.dest}' is not a valid Python identifier")
+
+        # Normalize action value
+        if self.action is None:
+            object.__setattr__(self, 'action', ArgumentAction.STORE.value)
+        elif isinstance(self.action, str):
+            try:
+                action_enum = ArgumentAction(self.action)
+                object.__setattr__(self, 'action', action_enum.value)
+            except ValueError:
+                raise CLIOrionisValueError(f"Invalid action '{self.action}'. Please use a valid ArgumentAction value")
+        elif isinstance(self.action, ArgumentAction):
+            object.__setattr__(self, 'action', self.action.value)
+        else:
+            raise CLIOrionisValueError("Action must be a string or an ArgumentAction enum value")
+
+        # Special handling for boolean types
+        if self.type is bool:
+
+            # Auto-configure action based on default value
+            action = ArgumentAction.STORE_TRUE.value if not self.default else ArgumentAction.STORE_FALSE.value
+            object.__setattr__(self, 'action', action)
+
+            # argparse ignores type with store_true/false actions
+            object.__setattr__(self, 'type', None)
+
+        # Special handling for list types
+        if self.type is list and self.nargs is None:
+
+            # Auto-configure for accepting multiple values
+            object.__setattr__(self, 'nargs', '+')
+            object.__setattr__(self, 'type', str)
+
+    def addToParser(self, parser: argparse.ArgumentParser) -> None:
+        """
+        Add this argument to an argparse ArgumentParser instance.
+
+        This method integrates the CLIArgument configuration with an argparse
+        ArgumentParser by building the appropriate keyword arguments and adding
+        the argument with all its flags and options. The method handles all
+        necessary conversions and validations to ensure compatibility with
+        argparse's expected format.
+
+        Parameters
+        ----------
+        parser : argparse.ArgumentParser
+            The ArgumentParser instance to which this argument will be added.
+            The parser must be a valid argparse.ArgumentParser object.
+
+        Returns
+        -------
+        None
+            This method does not return any value. It modifies the provided
+            parser by adding the argument configuration to it.
+
+        Raises
+        ------
+        CLIOrionisValueError
+            If there's an error adding the argument to the parser, such as
+            conflicting argument names, invalid configurations, or argparse
+            internal errors during argument registration.
+        """
+
+        # Build the keyword arguments dictionary for argparse compatibility
+        # This filters out None values and handles special argument types
+        kwargs = self._buildParserKwargs()
+
+        # Attempt to add the argument to the parser with all flags and options
+        try:
+            # Use unpacking to pass all flags as positional arguments
+            # and all configuration options as keyword arguments
+            parser.add_argument(*self.flags, **kwargs)
+
+        # Catch any exception that occurs during argument addition
+        # and wrap it in our custom exception for consistent error handling
+        except Exception as e:
+            raise CLIOrionisValueError(f"Error adding argument {self.flags}: {e}")
+
+    def _buildParserKwargs(self) -> Dict[str, Any]:
+        """
+        Build the keyword arguments dictionary for argparse compatibility.
+
+        This private method constructs a dictionary of keyword arguments that will be
+        passed to argparse's add_argument method. It handles the conversion from
+        CLIArgument attributes to argparse-compatible parameters, filtering out None
+        values and applying special handling for different argument types (optional
+        vs positional arguments).
+
+        The method ensures that the resulting kwargs dictionary contains only valid
+        argparse parameters with appropriate values, preventing errors during argument
+        registration with the ArgumentParser.
+
+        Returns
+        -------
+        Dict[str, Any]
+            A dictionary containing keyword arguments ready to be unpacked and passed
+            to argparse.ArgumentParser.add_argument(). The dictionary includes only
+            non-None values and excludes parameters that are invalid for the specific
+            argument type (e.g., 'required' parameter for positional arguments).
+
+        Notes
+        -----
+        This method distinguishes between optional arguments (those starting with '-')
+        and positional arguments, applying different validation rules for each type.
+        Positional arguments cannot use the 'required' parameter, so it's automatically
+        removed from the kwargs if present.
+        """
+
+        # Determine argument type by checking if any flag starts with a dash
+        # Optional arguments have flags like '--export' or '-e'
+        # Positional arguments have flags without dashes like 'filename'
+        is_optional = any(flag.startswith('-') for flag in self.flags)
+        is_positional = not is_optional
+
+        # Build the base kwargs dictionary with all possible argparse parameters
+        # Each key corresponds to a parameter accepted by argparse.add_argument()
+        kwargs = {
+            "help": self.help,                          # Help text displayed in usage messages
+            "default": self.default,                    # Default value when argument not provided
+            "required": self.required and is_optional,  # Whether argument is mandatory
+            "metavar": self.metavar,                    # Name displayed in help messages
+            "dest": self.dest,                          # Attribute name in the parsed namespace
+            "choices": self.choices,                    # List of valid values for the argument
+            "action": self.action,                      # Action to take when argument is encountered
+            "nargs": self.nargs,                        # Number of command-line arguments expected
+            "type": self.type,                          # Type to convert the argument to
+            "const": self.const                         # Constant value for certain actions
+        }
+
+        # Filter out None values to prevent passing invalid parameters to argparse
+        # argparse will raise errors if None values are explicitly passed for certain parameters
+        kwargs = {k: v for k, v in kwargs.items() if v is not None}
+
+        # Remove 'required' parameter for positional arguments since it's not supported
+        # Positional arguments are inherently required by argparse's design
+        if is_positional and 'required' in kwargs:
+            del kwargs['required']
+
+        # Return the cleaned and validated kwargs dictionary
+        return kwargs

orionis/console/args/enums/actions.py

@@ -0,0 +1,43 @@
+from enum import Enum
+
+class ArgumentAction(Enum):
+    """
+    Enumeration for valid argparse action types.
+
+    This enum provides a comprehensive list of all standard action types
+    that can be used with Python's argparse module when defining command
+    line arguments. Each enum member corresponds to a specific behavior
+    for how argument values should be processed and stored.
+
+    Returns
+    -------
+    str
+        The string value representing the argparse action type.
+    """
+
+    # Store the argument value directly
+    STORE = "store"
+
+    # Store a constant value when the argument is specified
+    STORE_CONST = "store_const"
+
+    # Store True when the argument is specified
+    STORE_TRUE = "store_true"
+
+    # Store False when the argument is specified
+    STORE_FALSE = "store_false"
+
+    # Append each argument value to a list
+    APPEND = "append"
+
+    # Append a constant value to a list when the argument is specified
+    APPEND_CONST = "append_const"
+
+    # Count the number of times the argument is specified
+    COUNT = "count"
+
+    # Display help message and exit
+    HELP = "help"
+
+    # Display version information and exit
+    VERSION = "version"

orionis/console/commands/version.py

@@ -15,17 +15,32 @@ class VersionCommand(BaseCommand):
 
     def handle(self) -> None:
         """
-        Execute the version command.
+        Executes the version command to display the current Orionis framework version.
 
-        This method retrieves and prints the version of the Orionis framework.
+        This method retrieves the version number from the framework metadata and prints it
+        in a formatted, bold, and successful style to the console. If an unexpected error occurs
+        during execution, it raises a CLIOrionisRuntimeError with the original exception message.
+
+        Parameters
+        ----------
+        None
+
+        Returns
+        -------
+        None
+            This method does not return any value. It outputs the version information to the console.
 
         Raises
         ------
-        ValueError
-            If an unexpected error occurs during execution, a ValueError is raised
+        CLIOrionisRuntimeError
+            If an unexpected error occurs during execution, a CLIOrionisRuntimeError is raised
             with the original exception message.
         """
+
+        # Print the Orionis framework version in a bold, success style
         try:
             self.textSuccessBold(f"Orionis Framework v{VERSION}")
+
+        # Raise a custom runtime error if any exception occurs
         except Exception as e:
             raise CLIOrionisRuntimeError(f"An unexpected error occurred: {e}") from e

orionis/foundation/application.py

@@ -174,7 +174,6 @@ class Application(Container, IApplication):
         # Import core framework providers
         from orionis.foundation.providers.console_provider import ConsoleProvider
         from orionis.foundation.providers.dumper_provider import DumperProvider
-        from orionis.foundation.providers.path_resolver_provider import PathResolverProvider
         from orionis.foundation.providers.progress_bar_provider import ProgressBarProvider
         from orionis.foundation.providers.workers_provider import WorkersProvider
         from orionis.foundation.providers.testing_provider import TestingProvider
@@ -183,7 +182,6 @@ class Application(Container, IApplication):
         core_providers = [
             ConsoleProvider,
             DumperProvider,
-            PathResolverProvider,
             ProgressBarProvider,
             WorkersProvider,
             LoggerProvider,

orionis/foundation/providers/testing_provider.py

@@ -1,6 +1,8 @@
 from orionis.container.providers.service_provider import ServiceProvider
 from orionis.test.contracts.unit_test import IUnitTest
 from orionis.test.core.unit_test import UnitTest
+from orionis.foundation.config.testing.entities.testing import Testing
+import os
 
 class TestingProvider(ServiceProvider):
     """
@@ -28,7 +30,39 @@ class TestingProvider(ServiceProvider):
         None
         """
 
-        self.app.singleton(IUnitTest, UnitTest, alias="core.orionis.testing")
+        # Create a Testing configuration instance from the application config
+        config = Testing(**self.app.config('testing'))
+
+        # Create a UnitTest instance
+        unit_test = UnitTest(
+            app=self.app,
+            storage=self.app.path('storage_testing')
+        )
+
+        # Configure the UnitTest instance with settings from the Testing configuration
+        unit_test.configure(
+            verbosity=config.verbosity,
+            execution_mode=config.execution_mode,
+            max_workers=config.max_workers,
+            fail_fast=config.fail_fast,
+            print_result=config.print_result,
+            throw_exception=config.throw_exception,
+            persistent=config.persistent,
+            persistent_driver=config.persistent_driver,
+            web_report=config.web_report
+        )
+
+        # Discover tests based on the configuration
+        unit_test.discoverTests(
+            base_path=config.base_path,
+            folder_path=config.folder_path,
+            pattern=config.pattern,
+            test_name_pattern=config.test_name_pattern,
+            tags=config.tags
+        )
+
+        # Register the UnitTest instance in the application container
+        self.app.instance(IUnitTest, unit_test, alias="core.orionis.testing")
 
     def boot(self) -> None:
         """
@@ -42,4 +76,7 @@ class TestingProvider(ServiceProvider):
         None
         """
 
-        pass
+        # Ensure directory for testing storage exists
+        storage_path = self.app.path('storage_testing')
+        if not os.path.exists(storage_path):
+            os.makedirs(storage_path, exist_ok=True)

orionis/metadata/framework.py

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

orionis/test/core/unit_test.py

@@ -1,5 +1,6 @@
 import io
 import json
+from os import walk
 import re
 import time
 import traceback
@@ -9,6 +10,7 @@ from contextlib import redirect_stdout, redirect_stderr
 from datetime import datetime
 from pathlib import Path
 from typing import Any, Dict, List, Optional, Tuple
+from orionis.app import Orionis
 from orionis.container.resolver.resolver import Resolver
 from orionis.foundation.config.testing.enums.drivers import PersistentDrivers
 from orionis.foundation.config.testing.enums.mode import ExecutionMode
@@ -102,7 +104,9 @@ class UnitTest(IUnitTest):
     """
 
     def __init__(
-        self
+        self,
+        app: Optional[IApplication] = None,
+        storage: Optional[str] = None
     ) -> None:
         """
         Initialize a UnitTest instance with default configuration and internal state.
@@ -113,11 +117,11 @@ class UnitTest(IUnitTest):
         -------
         None
         """
-        # Application instance for dependency injection (set via __setApp)
-        self.__app: Optional[IApplication] = None
+        # Application instance for dependency injection
+        self.__app: Optional[IApplication] = app or Orionis()
 
-        # Storage path for test results (set via __setApp)
-        self.__storage: Optional[str] = None
+        # Storage path for test results
+        self.__storage: Optional[str] = storage or self.__app.path('storage_testing')
 
         # Configuration values (set via configure)
         self.__verbosity: Optional[int] = None
@@ -220,6 +224,100 @@ class UnitTest(IUnitTest):
         # Return the instance to allow method chaining
         return self
 
+    def discoverTests(
+        self,
+        base_path: str | Path,
+        folder_path: str | List[str],
+        pattern: str,
+        test_name_pattern: Optional[str] = None,
+        tags: Optional[List[str]] = None
+    ) -> 'UnitTest':
+        """
+        Discover test cases from specified folders using flexible path discovery.
+
+        This method provides a convenient way to discover and load test cases from multiple folders
+        based on various path specifications. It supports wildcard discovery, single folder loading,
+        and multiple folder loading. The method automatically resolves paths relative to the base
+        directory and discovers all folders containing files matching the specified pattern.
+
+        Parameters
+        ----------
+        base_path : str or Path
+            Base directory path for resolving relative folder paths. This serves as the root
+            directory from which all folder searches are conducted.
+        folder_path : str or list of str
+            Specification of folders to search for test cases. Can be:
+            - '*' : Discover all folders containing matching files within base_path
+            - str : Single folder path relative to base_path
+            - list of str : Multiple folder paths relative to base_path
+        pattern : str
+            File name pattern to match test files, supporting wildcards (* and ?).
+            Examples: 'test_*.py', '*_test.py', 'test*.py'
+        test_name_pattern : str, optional
+            Regular expression pattern to filter test method names. Only tests whose
+            names match this pattern will be included. Default is None (no filtering).
+        tags : list of str, optional
+            List of tags to filter tests. Only tests decorated with matching tags
+            will be included. Default is None (no tag filtering).
+
+        Returns
+        -------
+        UnitTest
+            The current UnitTest instance with discovered tests added to the suite,
+            enabling method chaining.
+
+        Notes
+        -----
+        - All paths are resolved as absolute paths relative to the base_path
+        - When folder_path is '*', the method searches recursively through all subdirectories
+        - The method uses the existing discoverTestsInFolder method for actual test discovery
+        - Duplicate folders are automatically eliminated using a set data structure
+        - The method does not validate the existence of specified folders; validation
+          occurs during the actual test discovery process
+        """
+        # Resolve the base path as an absolute path from the current working directory
+        base_path = (Path.cwd() / base_path).resolve()
+
+        # Use a set to store discovered folders and automatically eliminate duplicates
+        discovered_folders = set()
+
+        # Handle wildcard discovery: search all folders containing matching files
+        if folder_path == '*':
+
+            # Search recursively through the entire base path for folders with matching files
+            discovered_folders.update(self.__listMatchingFolders(base_path, base_path, pattern))
+
+        # Handle multiple folder paths: process each folder in the provided list
+        elif isinstance(folder_path, list):
+            for custom in folder_path:
+                # Resolve each custom folder path relative to the base path
+                custom_path = (base_path / custom).resolve()
+                # Add all matching folders found within this custom path
+                discovered_folders.update(self.__listMatchingFolders(base_path, custom_path, pattern))
+
+        # Handle single folder path: process the single specified folder
+        else:
+
+            # Resolve the single folder path relative to the base path
+            custom_path = (base_path / folder_path).resolve()
+            # Add all matching folders found within this single path
+            discovered_folders.update(self.__listMatchingFolders(base_path, custom_path, pattern))
+
+        # Iterate through all discovered folders and perform test discovery
+        for folder in discovered_folders:
+
+            # Use the existing discoverTestsInFolder method to actually discover and load tests
+            self.discoverTestsInFolder(
+                base_path=base_path,
+                folder_path=folder,
+                pattern=pattern,
+                test_name_pattern=test_name_pattern or None,
+                tags=tags or None
+            )
+
+        # Return the current instance to enable method chaining
+        return self
+
     def discoverTestsInFolder(
         self,
         *,
@@ -1342,6 +1440,37 @@ class UnitTest(IUnitTest):
         # Return the suite containing only the filtered tests
         return filtered_suite
 
+    def __listMatchingFolders(
+        self,
+        base_path: Path,
+        custom_path: Path,
+        pattern: str
+    ) -> List[str]:
+        """
+        List folders within a given path containing files matching a pattern.
+
+        Parameters
+        ----------
+        base_path : Path
+            The base directory path for calculating relative paths.
+        custom_path : Path
+            The directory path to search for matching files.
+        pattern : str
+            The filename pattern to match, supporting '*' and '?' wildcards.
+
+        Returns
+        -------
+        List[str]
+            List of relative folder paths containing files matching the pattern.
+        """
+        regex = re.compile('^' + pattern.replace('*', '.*').replace('?', '.') + '$')
+        matched_folders = set()
+        for root, _, files in walk(str(custom_path)):
+            if any(regex.fullmatch(file) for file in files):
+                rel_path = Path(root).relative_to(base_path).as_posix()
+                matched_folders.add(rel_path)
+        return list(matched_folders)
+
     def getTestNames(
         self
     ) -> List[str]: