orionis 0.435.0__py3-none-any.whl → 0.437.0__py3-none-any.whl

orionis/console/contracts/kernel.py

@@ -2,14 +2,27 @@ from abc import ABC, abstractmethod
 
 class IKernelCLI(ABC):
     """
-    Interface for the Kernel CLI.
+    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:
         """
-        Handle the command line arguments.
+        Process the provided command line arguments.
+
+        Parameters
+        ----------
+        args : list
+            List of command line arguments, typically obtained from sys.argv.
 
-        :param args: List of command line arguments (e.g., 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/console/dumper/contracts/dump.py

@@ -3,33 +3,32 @@ from typing import Any
 
 class IDebug(ABC):
     """
-    Debugging utility class for enhanced output and inspection of Python objects.
+    Abstract base class for debugging utilities that provide enhanced output and inspection of Python objects.
 
-    This class provides methods for dumping and inspecting data in various formats,
-    including plain text, JSON, and tabular representations. It also supports
-    rendering nested structures with recursion handling and customizable indentation.
+    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:
         """
-        Dumps the provided arguments to the output and exits the program.
+        Dump the provided arguments to the output and terminate the program.
 
         Parameters
         ----------
         *args : Any
-            Variable length argument list to be processed and output.
+            Variable length argument list to be dumped and displayed.
         """
         pass
 
     @abstractmethod
     def dump(self, *args: Any) -> None:
         """
-        Dumps the provided arguments for debugging or logging purposes.
+        Dump the provided arguments for debugging or logging purposes.
 
         Parameters
         ----------
         *args : Any
-            Variable length argument list to be processed and output.
+            Variable length argument list to be dumped and displayed.
         """
-        pass
+        pass

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/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/container/context/manager.py

@@ -2,33 +2,41 @@ from orionis.container.context.scope import ScopedContext
 
 class ScopeManager:
     """
-    A context manager to manage scoped lifetimes in the container.
+    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 a new ScopeManager with an empty instances dictionary.
+        Initialize the ScopeManager.
+
+        Initializes an empty dictionary to store scoped instances.
         """
         self._instances = {}
 
     def __getitem__(self, key):
         """
-        Get an instance by key.
+        Retrieve an instance associated with the given key.
 
         Parameters
         ----------
         key : hashable
-            The key of the instance to retrieve.
+            The key identifying the instance.
 
         Returns
         -------
         object or None
-            The instance associated with the key or None if not found.
+            The instance associated with the key, or None if not found.
         """
         return self._instances.get(key)
 
     def __setitem__(self, key, value):
         """
-        Store an instance by key.
+        Store an instance under the specified key.
 
         Parameters
         ----------
@@ -41,12 +49,12 @@ class ScopeManager:
 
     def __contains__(self, key):
         """
-        Check if a key exists in this scope.
+        Check if an instance exists for the given key.
 
         Parameters
         ----------
         key : hashable
-            The key to check.
+            The key to check for existence.
 
         Returns
         -------
@@ -57,38 +65,40 @@ class ScopeManager:
 
     def clear(self):
         """
-        Clear all instances from this scope.
+        Remove all instances from the current scope.
+
+        Clears the internal dictionary of all stored instances.
         """
         self._instances.clear()
 
     def __enter__(self):
         """
-        Enter the scope context.
+        Activate this scope as the current context.
 
-        Sets this scope as the current active scope.
+        Sets this ScopeManager as the active scope in ScopedContext.
 
         Returns
         -------
         ScopeManager
-            This scope manager instance.
+            The current ScopeManager instance.
         """
         ScopedContext.setCurrentScope(self)
         return self
 
     def __exit__(self, exc_type, exc_val, exc_tb):
         """
-        Exit the scope context.
+        Deactivate the current scope and perform cleanup.
 
-        Clears this scope and the active scope reference.
+        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, None otherwise.
+            The exception type if an exception was raised, otherwise None.
         exc_val : Exception or None
-            The exception instance if an exception was raised, None otherwise.
+            The exception instance if an exception was raised, otherwise None.
         exc_tb : traceback or None
-            The exception traceback if an exception was raised, None otherwise.
+            The traceback if an exception was raised, otherwise None.
         """
         self.clear()
         ScopedContext.clear()

orionis/container/context/scope.py

@@ -2,8 +2,9 @@ import contextvars
 
 class ScopedContext:
     """
-    Holds scoped instances for the current context.
+    Manages scoped instances using Python's context variables, allowing for context-local storage of active scopes.
     """
+
     _active_scope = contextvars.ContextVar(
         "orionis_scope",
         default=None
@@ -12,32 +13,32 @@ class ScopedContext:
     @classmethod
     def getCurrentScope(cls):
         """
-        Get the currently active scope.
+        Retrieve the currently active scope for the current context.
 
         Returns
         -------
         object or None
-            The current active scope or None if no scope is active.
+            The currently active scope object, or None if no scope is set.
         """
         return cls._active_scope.get()
 
     @classmethod
     def setCurrentScope(cls, scope):
         """
-        Set the current active scope.
+        Set the active scope for the current context.
 
         Parameters
         ----------
         scope : object
-            The scope object to set as active.
+            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 current active scope.
+        Clear the active scope for the current context.
 
-        Sets the active scope to None.
+        Resets the active scope to None.
         """
         cls._active_scope.set(None)

orionis/container/contracts/service_provider.py

@@ -7,24 +7,28 @@ class IServiceProvider(ABC):
         """
         Register services 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.
+        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 overridden in a subclass.
+            If the method is not implemented by a subclass.
         """
         pass
 
     @abstractmethod
     async def boot(self) -> None:
         """
-        Perform any post-registration bootstrapping or initialization.
+        Perform post-registration bootstrapping or initialization.
 
-        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.
+        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/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/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