orionis 0.443.0__tar.gz → 0.444.0__tar.gz

{orionis-0.443.0/orionis.egg-info → orionis-0.444.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: orionis
-Version: 0.443.0
+Version: 0.444.0
 Summary: Orionis Framework – Elegant, Fast, and Powerful.
 Home-page: https://github.com/orionis-framework/framework
 Author: Raul Mauricio Uñate Castro

orionis-0.444.0/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-0.444.0/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-0.444.0/orionis/console/commands/version.py

@@ -0,0 +1,46 @@
+from orionis.console.base.command import BaseCommand
+from orionis.console.exceptions import CLIOrionisRuntimeError
+from orionis.metadata.framework import VERSION
+
+class VersionCommand(BaseCommand):
+    """
+    Command class to display the current version of the Orionis framework.
+
+    This command prints the version number of the framework in use.
+    """
+
+    signature: str = "version"
+
+    description: str = "Prints the version of the framework in use."
+
+    def handle(self) -> None:
+        """
+        Executes the version command to display the current Orionis framework version.
+
+        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
+        ------
+        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-0.444.0/orionis/foundation/providers/testing_provider.py

@@ -0,0 +1,82 @@
+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):
+    """
+    Provides and registers the unit testing environment service in the application container.
+
+    This provider integrates a native unit testing framework for Orionis,
+    enabling advanced testing features and registering the service as a singleton
+    within the application's dependency injection container.
+
+    Attributes
+    ----------
+    app : Application
+        The application container instance where services are registered.
+    """
+
+    def register(self) -> None:
+        """
+        Register the unit testing service in the application container.
+
+        Registers the IUnitTest interface to the UnitTest implementation as a singleton,
+        with the alias "core.orionis.testing".
+
+        Returns
+        -------
+        None
+        """
+
+        # 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:
+        """
+        Perform post-registration initialization if required.
+
+        This method is intended for any setup needed after service registration.
+        Currently, no additional initialization is performed.
+
+        Returns
+        -------
+        None
+        """
+
+        # 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-0.443.0 → orionis-0.444.0}/orionis/metadata/framework.py

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