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

orionis/console/base/command.py

@@ -1,85 +1,92 @@
-import argparse
+from typing import Any, Dict
 from orionis.console.dynamic.progress_bar import ProgressBar
 from orionis.console.output.console import Console
+from orionis.console.base.contracts.command import IBaseCommand
 
-class BaseCommand(Console, ProgressBar):
+class BaseCommand(Console, ProgressBar, IBaseCommand):
     """
-    Base abstract class for implementing console commands in the Orionis framework.
+    Abstract base class for console commands in Orionis.
 
-    This class provides a foundation for creating command-line interface commands by
-    combining console output capabilities and progress bar functionality. It serves
-    as an abstract base that enforces the implementation of command-specific logic
-    while providing common argument handling functionality.
-
-    The class inherits from both Console and ProgressBar, providing access to:
-    - Console output methods for displaying messages, errors, and formatted text
-    - Progress bar functionality for long-running operations
-    - Argument parsing and management capabilities
+    Inherits from Console and ProgressBar, allowing commands to:
+    - Display messages, errors, and formatted text in the console.
+    - Manage progress bars for long-running tasks.
+    - Access and manipulate parsed arguments from the command line.
 
     Attributes
     ----------
     args : dict
-        Dictionary containing the parsed command-line arguments passed to the command.
-        This is populated by calling the `setArgs` method with either an
-        `argparse.Namespace` object or a dictionary.
+        Dictionary containing the parsed arguments for the command. Set via the setArgs method.
 
     Methods
     -------
     handle()
-        Abstract method that must be implemented by subclasses to define the
-        command's execution logic.
-    setArgs(args)
-        Sets the command arguments from either an argparse.Namespace or dict.
+        Must be implemented by each subclass to define the main logic of the command.
+    argument(key)
+        Retrieves the value of a specific argument by key.
+    arguments()
+        Returns all parsed arguments as a dictionary.
     """
 
-    args = {}
+    args: Dict[str, Any] = {}
 
     def handle(self):
         """
-        Execute the command's main logic.
+        Main entry point for command execution.
 
-        This abstract method defines the entry point for command execution and must
-        be overridden in all subclasses. It contains the core functionality that
-        the command should perform when invoked.
+        This method must be overridden in each subclass to define the specific logic of the command.
+        Access parsed arguments via self.args and use console and progress bar methods as needed.
 
-        The method has access to:
-        - `self.args`: Dictionary of parsed command-line arguments
-        - Console output methods inherited from Console class
-        - Progress bar methods inherited from ProgressBar class
+        Example:
+            def handle(self):
+                self.write("Processing...")
+                value = self.argument("key")
+                # custom logic
 
         Raises
         ------
         NotImplementedError
-            Always raised when called on the base class, as this method must be
-            implemented by concrete subclasses to define command-specific behavior.
+            Always raised in the base class. Subclasses must implement this method.
         """
-        raise NotImplementedError("The 'handle' method must be implemented in the child class.")
+        raise NotImplementedError("The 'handle' method must be implemented in the subclass.")
 
-    def setArgs(self, args) -> None:
+    def argument(self, key: str):
         """
-        Set command arguments from parsed command-line input.
-
-        This method accepts command arguments in multiple formats and normalizes
-        them into a dictionary format stored in `self.args`. It provides
-        flexibility in how arguments are passed to the command while ensuring
-        consistent internal representation.
+        Retrieves the value of a specific argument by its key.
 
         Parameters
         ----------
-        args : argparse.Namespace or dict
-            The command arguments to be set. Can be either:
-            - argparse.Namespace: Result of argparse.ArgumentParser.parse_args()
-            - dict: Dictionary containing argument name-value pairs
+        key : str
+            Name of the argument to retrieve.
+
+        Returns
+        -------
+        any or None
+            Value associated with the key, or None if it does not exist or arguments are not set.
 
         Raises
         ------
         ValueError
-            If `args` is neither an argparse.Namespace nor a dict, indicating
-            an unsupported argument type was passed.
+            If the key is not a string or if arguments are not a dictionary.
+
+        Example:
+            value = self.argument("user")
+        """
+        if not isinstance(key, str):
+            raise ValueError("Argument key must be a string.")
+        if not isinstance(self.args, dict):
+            raise ValueError("Arguments must be a dictionary.")
+        return self.args.get(key)
+
+    def arguments(self) -> dict:
+        """
+        Returns all parsed arguments as a dictionary.
+
+        Returns
+        -------
+        dict
+            Dictionary containing all arguments received by the command. If no arguments, returns an empty dictionary.
+
+        Example:
+            args = self.arguments()
         """
-        if isinstance(args, argparse.Namespace):
-            self.args = vars(args)
-        elif isinstance(args, dict):
-            self.args = args
-        else:
-            raise ValueError("Invalid argument type. Expected 'argparse.Namespace' or 'dict'.")
+        return dict(self.args) if isinstance(self.args, dict) else {}

orionis/console/base/contracts/command.py

@@ -0,0 +1,68 @@
+
+from abc import ABC, abstractmethod
+from typing import Any, Dict
+
+class IBaseCommand(ABC):
+    """
+    Abstract base contract for console commands in Orionis.
+
+    Inherits from ABC and defines the required interface for all console commands:
+    - Stores parsed command-line arguments.
+    - Requires implementation of main execution logic and argument accessors.
+
+    Attributes
+    ----------
+    args : Dict[str, Any]
+        Dictionary containing the parsed arguments for the command. Should be set by the command parser.
+    """
+
+    args: Dict[str, Any] = {}
+
+    @abstractmethod
+    def handle(self):
+        """
+        Main entry point for command execution.
+
+        This method must be overridden in each subclass to define the specific logic of the command.
+        Access parsed arguments via self.args and use console/output methods as needed.
+
+        Raises
+        ------
+        NotImplementedError
+            Always raised in the base class. Subclasses must implement this method.
+        """
+        pass
+
+    @abstractmethod
+    def argument(self, key: str) -> Any:
+        """
+        Retrieves the value of a specific argument by its key.
+
+        Parameters
+        ----------
+        key : str
+            Name of the argument to retrieve.
+
+        Returns
+        -------
+        Any or None
+            Value associated with the key, or None if it does not exist or arguments are not set.
+
+        Raises
+        ------
+        ValueError
+            If the key is not a string or if arguments are not a dictionary.
+        """
+        pass
+
+    @abstractmethod
+    def arguments(self) -> Dict[str, Any]:
+        """
+        Returns all parsed arguments as a dictionary.
+
+        Returns
+        -------
+        dict
+            Dictionary containing all arguments received by the command. If no arguments, returns an empty dictionary.
+        """
+        pass

orionis/console/dynamic/contracts/progress_bar.py

@@ -19,7 +19,7 @@ class IProgressBar(ABC):
     """
 
     @abstractmethod
-    def start(self):
+    def start(self) -> None:
         """
         Initializes the progress bar.
 
@@ -34,7 +34,7 @@ class IProgressBar(ABC):
         pass
 
     @abstractmethod
-    def advance(self, increment: int):
+    def advance(self, increment: int) -> None:
         """
         Advances the progress bar by a given increment.
 
@@ -51,7 +51,7 @@ class IProgressBar(ABC):
         pass
 
     @abstractmethod
-    def finish(self):
+    def finish(self) -> None:
         """
         Completes the progress bar.
 

orionis/console/dynamic/progress_bar.py

@@ -34,7 +34,7 @@ class ProgressBar(IProgressBar):
         Completes the progress bar and moves to a new line.
     """
 
-    def __init__(self, total=100, width=50):
+    def __init__(self, total=100, width=50) -> None:
         """
         Constructs all the necessary attributes for the progress bar object.
 
@@ -49,7 +49,7 @@ class ProgressBar(IProgressBar):
         self.bar_width = width
         self.progress = 0
 
-    def _update_bar(self):
+    def __updateBar(self) -> None:
         """
         Updates the visual representation of the progress bar.
 
@@ -64,16 +64,16 @@ class ProgressBar(IProgressBar):
         sys.stdout.write("\r" + bar)
         sys.stdout.flush()
 
-    def start(self):
+    def start(self) -> None:
         """
         Initializes the progress bar to the starting state.
 
         This method resets the progress to zero and displays the initial bar.
         """
         self.progress = 0
-        self._update_bar()
+        self.__updateBar()
 
-    def advance(self, increment=1):
+    def advance(self, increment=1) -> None:
         """
         Advances the progress bar by a specific increment.
 
@@ -85,9 +85,9 @@ class ProgressBar(IProgressBar):
         self.progress += increment
         if self.progress > self.total:
             self.progress = self.total
-        self._update_bar()
+        self.__updateBar()
 
-    def finish(self):
+    def finish(self) -> None:
         """
         Completes the progress bar.
 
@@ -95,6 +95,6 @@ class ProgressBar(IProgressBar):
         and moves the cursor to a new line for cleaner output.
         """
         self.progress = self.total
-        self._update_bar()
+        self.__updateBar()
         sys.stdout.write("\n")
         sys.stdout.flush()

orionis/console/output/console.py

@@ -537,7 +537,10 @@ class Console(IConsole):
         """
         if message:
             self.success(message)
-        sys.exit(0)
+        try:
+            sys.exit(0)
+        except SystemExit:
+            os._exit(0)
 
     def exitError(self, message: str = None) -> None:
         """
@@ -550,4 +553,7 @@ class Console(IConsole):
         """
         if message:
             self.error(message)
-        sys.exit(1)
+        try:
+            sys.exit(0)
+        except SystemExit:
+            os._exit(0)

orionis/console/output/contracts/console.py

@@ -1,5 +1,5 @@
 from abc import ABC, abstractmethod
-from typing import List, Union, Optional
+from typing import List, Optional
 
 class IConsole(ABC):
     """

orionis/container/container.py

@@ -32,8 +32,8 @@ class Container(IContainer):
         """
         Creates and returns a singleton instance for each specific class.
 
-        This method implements a truly thread-safe singleton pattern with proper 
-        inheritance support, ensuring that each class in the hierarchy has its own 
+        This method implements a truly thread-safe singleton pattern with proper
+        inheritance support, ensuring that each class in the hierarchy has its own
         singleton instance. Uses double-checked locking with proper memory barriers.
 
         Returns

orionis/container/context/scope.py

@@ -4,7 +4,10 @@ class ScopedContext:
     """
     Holds scoped instances for the current context.
     """
-    _active_scope = contextvars.ContextVar("orionis_scope", default=None)
+    _active_scope = contextvars.ContextVar(
+        "orionis_scope",
+        default=None
+    )
 
     @classmethod
     def getCurrentScope(cls):

orionis/container/contracts/service_provider.py

@@ -3,7 +3,7 @@ from abc import ABC, abstractmethod
 class IServiceProvider(ABC):
 
     @abstractmethod
-    def register(self) -> None:
+    async def register(self) -> None:
         """
         Register services into the application container.
 
@@ -19,7 +19,7 @@ class IServiceProvider(ABC):
         pass
 
     @abstractmethod
-    def boot(self) -> None:
+    async def boot(self) -> None:
         """
         Perform any post-registration bootstrapping or initialization.
 

orionis/container/entities/binding.py

@@ -1,14 +1,15 @@
-from dataclasses import asdict, dataclass, field, fields
+from dataclasses import dataclass, field
 from orionis.container.enums.lifetimes import Lifetime
 from orionis.container.exceptions import OrionisContainerTypeError
+from orionis.support.entities.base import BaseEntity
 
 @dataclass(unsafe_hash=True, kw_only=True)
-class Binding:
+class Binding(BaseEntity):
 
     contract: type = field(
         default=None,
         metadata={
-            "description": "Contrato de la clase concreta a inyectar.",
+            "description": "Contract of the concrete class to inject.",
             "default": None
         }
     )
@@ -16,7 +17,7 @@ class Binding:
     concrete: type = field(
         default=None,
         metadata={
-            "description": "Clase concreta que implementa el contrato.",
+            "description": "Concrete class implementing the contract.",
             "default": None
         }
     )
@@ -24,7 +25,7 @@ class Binding:
     instance: object = field(
         default=None,
         metadata={
-            "description": "Instancia concreta de la clase, si se proporciona.",
+            "description": "Concrete instance of the class, if provided.",
             "default": None
         }
     )
@@ -32,7 +33,7 @@ class Binding:
     function: callable = field(
         default=None,
         metadata={
-            "description": "Función que se invoca para crear la instancia.",
+            "description": "Function invoked to create the instance.",
             "default": None
         }
     )
@@ -40,7 +41,7 @@ class Binding:
     lifetime: Lifetime = field(
         default=Lifetime.TRANSIENT,
         metadata={
-            "description": "Tiempo de vida de la instancia.",
+            "description": "Lifetime of the instance.",
             "default": Lifetime.TRANSIENT
         }
     )
@@ -48,7 +49,7 @@ class Binding:
     enforce_decoupling: bool = field(
         default=False,
         metadata={
-            "description": "Indica si se debe forzar el desacoplamiento entre contrato y concreta.",
+            "description": "Indicates whether to enforce decoupling between contract and concrete.",
             "default": False
         }
     )
@@ -56,69 +57,55 @@ class Binding:
     alias: str = field(
         default=None,
         metadata={
-            "description": "Alias para resolver la dependencia desde el contenedor.",
+            "description": "Alias for resolving the dependency from the container.",
             "default": None
         }
     )
 
     def __post_init__(self):
         """
-        Performs type validation of instance attributes after initialization.
+        Validates the types of specific instance attributes after object initialization.
+
+        This method ensures that:
+        - The 'lifetime' attribute is an instance of the `Lifetime` enum.
+        - The 'enforce_decoupling' attribute is a boolean.
+        - The 'alias' attribute is either a string or None.
+
+        If any of these conditions are not met, an `OrionisContainerTypeError` is raised to prevent improper usage.
 
         Parameters
         ----------
         None
 
+        Returns
+        -------
+        None
+            This method does not return any value. It raises an exception if validation fails.
+
         Raises
         ------
         OrionisContainerTypeError
-            If 'lifetime' is not an instance of `Lifetime` (when not None).
+            If 'lifetime' is not an instance of `Lifetime`.
         OrionisContainerTypeError
             If 'enforce_decoupling' is not of type `bool`.
         OrionisContainerTypeError
             If 'alias' is not of type `str` or `None`.
         """
-        if self.lifetime is not None and not isinstance(self.lifetime, Lifetime):
+
+        # Validate that 'lifetime' is an instance of Lifetime enum if provided
+        if self.lifetime and not isinstance(self.lifetime, Lifetime):
             raise OrionisContainerTypeError(
                 f"The 'lifetime' attribute must be an instance of 'Lifetime', but received type '{type(self.lifetime).__name__}'."
             )
 
+        # Validate that 'enforce_decoupling' is a boolean
         if not isinstance(self.enforce_decoupling, bool):
             raise OrionisContainerTypeError(
                 f"The 'enforce_decoupling' attribute must be of type 'bool', but received type '{type(self.enforce_decoupling).__name__}'."
             )
 
-        if self.alias is not None and not isinstance(self.alias, str):
+        # Validate that 'alias' is either a string or None
+        if self.alias and not isinstance(self.alias, str):
             raise OrionisContainerTypeError(
                 f"The 'alias' attribute must be of type 'str' or 'None', but received type '{type(self.alias).__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
+            )

orionis/container/enums/lifetimes.py

@@ -1,8 +1,29 @@
 from enum import Enum, auto
 
 class Lifetime(Enum):
-    """Defines the lifecycle types for dependency injection."""
+    """
+    Represents the lifecycle types used for dependency injection.
 
+    This enumeration defines how and when instances of a dependency are created and shared.
+
+    Attributes
+    ----------
+    TRANSIENT : Lifetime
+        A new instance is created and provided every time the dependency is requested.
+    SINGLETON : Lifetime
+        A single shared instance is created and used throughout the entire application lifetime.
+    SCOPED : Lifetime
+        An instance is created and shared within a defined scope (such as per request or session).
+
+    Returns
+    -------
+    Lifetime
+        An enumeration member representing the selected lifecycle type.
+    """
+
+    # A new instance is provided every time the dependency is requested.
     TRANSIENT = auto()
+    # A single shared instance is provided for the entire application lifetime.
     SINGLETON = auto()
+    # An instance is provided per scope (e.g., per request or session).
     SCOPED = auto()

orionis/container/facades/facade.py

@@ -98,5 +98,4 @@ class Facade(metaclass=FacadeMeta):
             )
 
         # Resolve the service instance from the container
-        service_instance = cls._app.make(service_name, *args, **kwargs)
-        return service_instance
+        return cls._app.make(service_name, *args, **kwargs)

orionis/container/providers/service_provider.py

@@ -31,7 +31,7 @@ class ServiceProvider(IServiceProvider):
         """
         self.app = app
 
-    def register(self) -> None:
+    async def register(self) -> None:
         """
         Register services into the application container.
 
@@ -46,7 +46,7 @@ class ServiceProvider(IServiceProvider):
         """
         raise NotImplementedError("This method should be overridden in the subclass")
 
-    def boot(self) -> None:
+    async def boot(self) -> None:
         """
         Perform any post-registration bootstrapping or initialization.