orionis 0.436.0__tar.gz → 0.437.0__tar.gz

{orionis-0.436.0/orionis.egg-info → orionis-0.437.0}/PKG-INFO

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

orionis-0.437.0/orionis/console/contracts/kernel.py

@@ -0,0 +1,28 @@
+from abc import ABC, abstractmethod
+
+class IKernelCLI(ABC):
+    """
+    Abstract base class for the Kernel Command Line Interface (CLI).
+
+    This interface defines the contract for handling command line arguments
+    within the kernel's CLI component.
+    """
+
+    @abstractmethod
+    def handle(self, args: list) -> None:
+        """
+        Process the provided command line arguments.
+
+        Parameters
+        ----------
+        args : list
+            List of command line arguments, typically obtained from sys.argv.
+
+        Raises
+        ------
+        NotImplementedError
+            If the method is not implemented by a subclass.
+        """
+
+        # This method must be implemented by subclasses.
+        raise NotImplementedError("This method should be overridden by subclasses.")

orionis-0.437.0/orionis/console/dumper/contracts/dump.py

@@ -0,0 +1,34 @@
+from abc import ABC, abstractmethod
+from typing import Any
+
+class IDebug(ABC):
+    """
+    Abstract base class for debugging utilities that provide enhanced output and inspection of Python objects.
+
+    This class defines the interface for dumping and inspecting data in various formats, 
+    supporting features such as recursion handling and customizable indentation.
+    """
+
+    @abstractmethod
+    def dd(self, *args: Any) -> None:
+        """
+        Dump the provided arguments to the output and terminate the program.
+
+        Parameters
+        ----------
+        *args : Any
+            Variable length argument list to be dumped and displayed.
+        """
+        pass
+
+    @abstractmethod
+    def dump(self, *args: Any) -> None:
+        """
+        Dump the provided arguments for debugging or logging purposes.
+
+        Parameters
+        ----------
+        *args : Any
+            Variable length argument list to be dumped and displayed.
+        """
+        pass

{orionis-0.436.0 → orionis-0.437.0}/orionis/console/dynamic/progress_bar.py

@@ -3,17 +3,14 @@ from orionis.console.dynamic.contracts.progress_bar import IProgressBar
 
 class ProgressBar(IProgressBar):
     """
-    A console-based progress bar implementation.
-
-    This class provides a simple text-based progress bar that updates
-    in place without clearing the console.
+    Console-based progress bar for tracking and displaying progress.
 
     Parameters
     ----------
     total : int, optional
-        The total amount of progress (default is 100).
+        The maximum value representing 100% progress. Default is 100.
     width : int, optional
-        The width of the progress bar in characters (default is 50).
+        The width of the progress bar in characters. Default is 50.
 
     Attributes
     ----------
@@ -23,27 +20,18 @@ class ProgressBar(IProgressBar):
         The width of the progress bar in characters.
     progress : int
         The current progress value.
-
-    Methods
-    -------
-    start()
-        Initializes the progress bar to the starting state.
-    advance(increment=1)
-        Advances the progress bar by a given increment.
-    finish()
-        Completes the progress bar and moves to a new line.
     """
 
     def __init__(self, total=100, width=50) -> None:
         """
-        Constructs all the necessary attributes for the progress bar object.
+        Initialize a new ProgressBar instance.
 
         Parameters
         ----------
         total : int, optional
-            The total amount of progress (default is 100).
+            The maximum value representing 100% progress. Default is 100.
         width : int, optional
-            The width of the progress bar in characters (default is 50).
+            The width of the progress bar in characters. Default is 50.
         """
         self.total = total
         self.bar_width = width
@@ -51,10 +39,10 @@ class ProgressBar(IProgressBar):
 
     def __updateBar(self) -> None:
         """
-        Updates the visual representation of the progress bar.
+        Update the visual representation of the progress bar in the console.
 
-        This method calculates the percentage of progress and updates the
-        console output accordingly.
+        Calculates the percentage of completion and redraws the progress bar
+        in place, overwriting the previous output.
         """
         percent = self.progress / self.total
         filled_length = int(self.bar_width * percent)
@@ -66,21 +54,25 @@ class ProgressBar(IProgressBar):
 
     def start(self) -> None:
         """
-        Initializes the progress bar to the starting state.
+        Reset and display the progress bar at the starting state.
 
-        This method resets the progress to zero and displays the initial bar.
+        Sets the progress to zero and renders the initial progress bar.
         """
         self.progress = 0
         self.__updateBar()
 
     def advance(self, increment=1) -> None:
         """
-        Advances the progress bar by a specific increment.
+        Advance the progress bar by a specified increment.
 
         Parameters
         ----------
         increment : int, optional
-            The amount by which the progress should be increased (default is 1).
+            The value by which to increase the progress. Default is 1.
+
+        Notes
+        -----
+        Progress will not exceed the total value.
         """
         self.progress += increment
         if self.progress > self.total:
@@ -89,12 +81,12 @@ class ProgressBar(IProgressBar):
 
     def finish(self) -> None:
         """
-        Completes the progress bar.
+        Complete the progress bar and move to a new line.
 
-        This method sets the progress to its maximum value, updates the bar,
-        and moves the cursor to a new line for cleaner output.
+        Sets progress to the maximum value, updates the bar, and moves the
+        cursor to a new line for cleaner output.
         """
         self.progress = self.total
         self.__updateBar()
         sys.stdout.write("\n")
-        sys.stdout.flush()
+        sys.stdout.flush()

{orionis-0.436.0 → orionis-0.437.0}/orionis/console/output/console.py

@@ -245,12 +245,20 @@ class Console(IConsole):
     def clear(self) -> None:
         """
         Clears the console screen.
+
+        Notes
+        -----
+        Uses the appropriate system command to clear the terminal screen based on the operating system.
         """
         os.system('cls' if os.name == 'nt' else 'clear')
 
     def clearLine(self) -> None:
         """
         Clears the current line in the console.
+
+        Notes
+        -----
+        Moves the cursor to the beginning of the line and overwrites it with a space, then returns the cursor to the start.
         """
         sys.stdout.write("\r \r")
         sys.stdout.flush()
@@ -258,6 +266,10 @@ class Console(IConsole):
     def line(self) -> None:
         """
         Prints a horizontal line in the console.
+
+        Notes
+        -----
+        Outputs a newline character without advancing to a new line, effectively creating a visual separator.
         """
         print("\n", end="")
 

orionis-0.437.0/orionis/container/context/manager.py

@@ -0,0 +1,104 @@
+from orionis.container.context.scope import ScopedContext
+
+class ScopeManager:
+    """
+    Manages scoped lifetimes for instances within a container context.
+
+    This class acts as a context manager to handle the storage, retrieval,
+    and cleanup of instances associated with a specific scope. It provides
+    dictionary-like access to instances and ensures proper scope activation
+    and cleanup when used in a context.
+    """
+
+    def __init__(self):
+        """
+        Initialize the ScopeManager.
+
+        Initializes an empty dictionary to store scoped instances.
+        """
+        self._instances = {}
+
+    def __getitem__(self, key):
+        """
+        Retrieve an instance associated with the given key.
+
+        Parameters
+        ----------
+        key : hashable
+            The key identifying the instance.
+
+        Returns
+        -------
+        object or None
+            The instance associated with the key, or None if not found.
+        """
+        return self._instances.get(key)
+
+    def __setitem__(self, key, value):
+        """
+        Store an instance under the specified key.
+
+        Parameters
+        ----------
+        key : hashable
+            The key to associate with the instance.
+        value : object
+            The instance to store.
+        """
+        self._instances[key] = value
+
+    def __contains__(self, key):
+        """
+        Check if an instance exists for the given key.
+
+        Parameters
+        ----------
+        key : hashable
+            The key to check for existence.
+
+        Returns
+        -------
+        bool
+            True if the key exists in the scope, False otherwise.
+        """
+        return key in self._instances
+
+    def clear(self):
+        """
+        Remove all instances from the current scope.
+
+        Clears the internal dictionary of all stored instances.
+        """
+        self._instances.clear()
+
+    def __enter__(self):
+        """
+        Activate this scope as the current context.
+
+        Sets this ScopeManager as the active scope in ScopedContext.
+
+        Returns
+        -------
+        ScopeManager
+            The current ScopeManager instance.
+        """
+        ScopedContext.setCurrentScope(self)
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """
+        Deactivate the current scope and perform cleanup.
+
+        Clears all stored instances and resets the active scope in ScopedContext.
+
+        Parameters
+        ----------
+        exc_type : type or None
+            The exception type if an exception was raised, otherwise None.
+        exc_val : Exception or None
+            The exception instance if an exception was raised, otherwise None.
+        exc_tb : traceback or None
+            The traceback if an exception was raised, otherwise None.
+        """
+        self.clear()
+        ScopedContext.clear()

orionis-0.437.0/orionis/container/context/scope.py

@@ -0,0 +1,44 @@
+import contextvars
+
+class ScopedContext:
+    """
+    Manages scoped instances using Python's context variables, allowing for context-local storage of active scopes.
+    """
+
+    _active_scope = contextvars.ContextVar(
+        "orionis_scope",
+        default=None
+    )
+
+    @classmethod
+    def getCurrentScope(cls):
+        """
+        Retrieve the currently active scope for the current context.
+
+        Returns
+        -------
+        object or None
+            The currently active scope object, or None if no scope is set.
+        """
+        return cls._active_scope.get()
+
+    @classmethod
+    def setCurrentScope(cls, scope):
+        """
+        Set the active scope for the current context.
+
+        Parameters
+        ----------
+        scope : object
+            The scope object to be set as the active scope for the current context.
+        """
+        cls._active_scope.set(scope)
+
+    @classmethod
+    def clear(cls):
+        """
+        Clear the active scope for the current context.
+
+        Resets the active scope to None.
+        """
+        cls._active_scope.set(None)

orionis-0.437.0/orionis/container/contracts/service_provider.py

@@ -0,0 +1,34 @@
+from abc import ABC, abstractmethod
+
+class IServiceProvider(ABC):
+
+    @abstractmethod
+    async def register(self) -> None:
+        """
+        Register services into the application container.
+
+        Notes
+        -----
+        This asynchronous method must be implemented by subclasses.
+        It is responsible for binding services, configurations, or other
+        components to the application container.
+
+        Raises
+        ------
+        NotImplementedError
+            If the method is not implemented by a subclass.
+        """
+        pass
+
+    @abstractmethod
+    async def boot(self) -> None:
+        """
+        Perform post-registration bootstrapping or initialization.
+
+        Notes
+        -----
+        This asynchronous method is called after all services have been registered.
+        Subclasses should override this method to initialize services, set up
+        event listeners, or perform other operations required at boot time.
+        """
+        pass

{orionis-0.436.0 → orionis-0.437.0}/orionis/container/providers/service_provider.py

@@ -3,26 +3,20 @@ from orionis.foundation.contracts.application import IApplication
 
 class ServiceProvider(IServiceProvider):
     """
-    Base service provider class for the Orionis framework.
+    Base class for service providers in the Orionis framework.
 
-    This class serves as a base for all service providers in the application.
-    Service providers are responsible for registering components and services
-    into the application container, and initializing them when needed.
+    Service providers are responsible for registering and bootstrapping
+    services and components into the application container.
 
     Parameters
     ----------
     app : IApplication
         The application container instance to which services will be registered.
-
-    Notes
-    -----
-    All concrete service providers should inherit from this class and implement
-    the `register` method at minimum.
     """
 
     def __init__(self, app: IApplication) -> None:
         """
-        Initialize the service provider with the application container.
+        Initialize the ServiceProvider with the application container.
 
         Parameters
         ----------
@@ -33,11 +27,10 @@ class ServiceProvider(IServiceProvider):
 
     async def register(self) -> None:
         """
-        Register services into the application container.
+        Register services and components into the application container.
 
-        This method must be implemented by all concrete service providers.
-        It should bind services, configurations, or other components
-        to the application container.
+        This method must be implemented by subclasses to bind services,
+        configurations, or other components to the application container.
 
         Raises
         ------
@@ -48,10 +41,10 @@ class ServiceProvider(IServiceProvider):
 
     async def boot(self) -> None:
         """
-        Perform any post-registration bootstrapping or initialization.
+        Perform post-registration initialization or bootstrapping.
 
         This method is called after all services have been registered.
         Override this method to initialize services, set up event listeners,
         or perform other boot-time operations.
         """
-        pass
+        pass

{orionis-0.436.0 → orionis-0.437.0}/orionis/container/resolver/resolver.py

@@ -11,45 +11,52 @@ from orionis.services.introspection.dependencies.entities.known_dependencies imp
 from orionis.services.introspection.dependencies.entities.method_dependencies import MethodDependency
 
 class Resolver(IResolver):
-    """
-    Resolver class for handling dependency resolution in the container.
-    """
 
     def __init__(
         self,
-        container:IContainer
+        container: IContainer
     ):
         """
-        Initialize the resolver.
-
-        This method initializes the resolver with a reference to the container.
-
         Parameters
         ----------
         container : IContainer
-            The container instance that this resolver will use to resolve dependencies.
+            The container instance used by the resolver to resolve dependencies.
+
+        Notes
+        -----
+        Initializes the Resolver with a reference to the dependency injection container.
+        This allows the resolver to access registered bindings and resolve dependencies
+        as required throughout the container's lifecycle.
         """
         self.container = container
 
     def resolve(
         self,
-        binding:Binding,
+        binding: Binding,
         *args,
         **kwargs
     ):
         """
-        Resolves an instance from a binding.
-        This method resolves an instance based on the binding's lifetime and type.
-        It delegates to specific resolution methods based on the lifetime (transient, singleton, or scoped).
-        Args:
-            binding (Binding): The binding to resolve.
-            *args: Additional positional arguments to pass to the constructor.
-            **kwargs: Additional keyword arguments to pass to the constructor.
-        Returns:
-            Any: The resolved instance.
-        Raises:
-            OrionisContainerException: If the binding is not an instance of Binding
-                or if scoped lifetime resolution is attempted (not yet implemented).
+        Resolves an instance from a binding according to its lifetime.
+
+        Parameters
+        ----------
+        binding : Binding
+            The binding to resolve.
+        *args : tuple
+            Additional positional arguments to pass to the constructor.
+        **kwargs : dict
+            Additional keyword arguments to pass to the constructor.
+
+        Returns
+        -------
+        Any
+            The resolved instance.
+
+        Raises
+        ------
+        OrionisContainerException
+            If the binding is not an instance of Binding or if the lifetime is not supported.
         """
 
         # Ensure the binding is an instance of Binding