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

orionis/services/system/contracts/workers.py

@@ -1,35 +1,52 @@
 from abc import ABC, abstractmethod
 
 class IWorkers(ABC):
-    """
-    Interface for calculating the optimal number of workers a machine can handle based on CPU and memory resources.
-
-    Notes
-    -----
-    Implementations should provide logic to determine the recommended number of worker processes
-    according to the available CPU and memory resources of the current machine.
-    """
 
     @abstractmethod
     def setRamPerWorker(self, ram_per_worker: float) -> None:
         """
-        Set the amount of RAM allocated per worker.
+        Set the amount of RAM to allocate for each worker process.
 
         Parameters
         ----------
         ram_per_worker : float
-            Amount of RAM (in GB) allocated per worker.
+            The amount of RAM, in gigabytes (GB), to allocate for each worker process.
+
+        Returns
+        -------
+        None
+            This method does not return any value.
+
+        Notes
+        -----
+        This method should be implemented by subclasses to configure the memory usage
+        per worker, which may affect the total number of workers that can be spawned
+        based on system resources.
         """
+
+        # Implementation should assign the specified RAM per worker.
         pass
 
     @abstractmethod
     def calculate(self) -> int:
         """
-        Compute the maximum number of workers supported by the current machine.
+        Compute the recommended maximum number of worker processes for the current machine.
+
+        This method should consider both CPU and memory constraints to determine the optimal
+        number of worker processes that can be safely spawned without overloading system resources.
 
         Returns
         -------
         int
-            Recommended number of worker processes based on CPU and memory limits.
+            The maximum number of worker processes that can be supported by the current machine,
+            based on available CPU cores and memory limits.
+
+        Notes
+        -----
+        Subclasses should implement this method to analyze system resources and return an integer
+        representing the recommended number of workers. The calculation should ensure that each
+        worker receives sufficient resources as configured (e.g., RAM per worker).
         """
+
+        # Implementation should analyze system resources and return the recommended worker count.
         pass

orionis/services/system/imports.py

@@ -2,58 +2,68 @@ from typing import List, Dict, Any
 from orionis.services.system.contracts.imports import IImports
 
 class Imports(IImports):
-    """
-    Utility class to collect and display information about currently loaded Python modules.
-
-    This class provides methods to gather details about user-defined Python modules
-    currently loaded in `sys.modules`, excluding standard library and virtual environment modules.
-    It can display the collected information in a formatted table using the Rich library.
-    """
 
     def __init__(self):
         """
-        Initialize the Imports object.
+        Initialize the Imports instance.
+
+        This constructor sets up the Imports object by initializing an empty list
+        to store information about user-defined Python modules. The list will
+        contain dictionaries, each representing a module with its name, file path,
+        and defined symbols.
 
-        Initializes an empty list to store module information.
+        Returns
+        -------
+        None
+            This method does not return any value.
         """
+
+        # List to hold information about imported modules
         self.imports: List[Dict[str, Any]] = []
 
     def collect(self) -> 'Imports':
         """
         Collect information about user-defined Python modules currently loaded.
 
-        For each qualifying module, gathers:
-            - The module's name.
-            - The relative file path to the module from the current working directory.
-            - A list of symbols (functions, classes, or submodules) defined in the module.
+        Iterates through all modules in `sys.modules` and gathers details for each qualifying module:
+            - Module name.
+            - Relative file path from the current working directory.
+            - List of symbols (functions, classes, or submodules) defined in the module.
 
-        Excludes:
-            - Modules from the standard library.
-            - Modules from the active virtual environment (if any).
-            - Binary extension modules (.pyd, .dll, .so).
-            - Special modules like "__main__", "__mp_main__", and modules starting with "_distutils".
+        Excludes modules that:
+            - Are part of the standard library.
+            - Reside in the active virtual environment (if any).
+            - Are binary extension modules (e.g., `.pyd`, `.dll`, `.so`).
+            - Are special modules such as `"__main__"`, `"__mp_main__"`, or those starting with `"_distutils"`.
 
-        The collected information is stored in `self.imports` as a list of dictionaries.
+        The collected information is stored in `self.imports` as a list of dictionaries, each containing the module's name, file path, and symbols.
 
         Returns
         -------
         Imports
-            The current instance with updated imports information.
+            The current instance of `Imports` with the `imports` attribute updated to include information about the collected modules.
         """
 
         import sys
         import os
         import types
 
+        # Clear any previously collected imports
         self.imports.clear()
+
+        # Get standard library paths to exclude standard modules
         stdlib_paths = [os.path.dirname(os.__file__)]
+
+        # Get virtual environment path if active
         venv_path = os.environ.get("VIRTUAL_ENV")
         if venv_path:
             venv_path = os.path.abspath(venv_path)
 
+        # Iterate over all loaded modules
         for name, module in list(sys.modules.items()):
-            file:str = getattr(module, '__file__', None)
+            file: str = getattr(module, '__file__', None)
 
+            # Filter out unwanted modules based on path, type, and name
             if (
                 file
                 and not any(file.startswith(stdlib_path) for stdlib_path in stdlib_paths)
@@ -62,18 +72,25 @@ class Imports(IImports):
                 and name not in ("__main__", "__mp_main__")
                 and not name.startswith("_distutils")
             ):
+
+                # Get relative file path from current working directory
                 rel_file = os.path.relpath(file, os.getcwd())
                 symbols = []
 
+                # Collect symbols defined in the module (functions, classes, submodules)
                 try:
                     for attr in dir(module):
                         value = getattr(module, attr)
                         if isinstance(value, (types.FunctionType, type, types.ModuleType)):
+
+                            # Ensure symbol is defined in this module
                             if getattr(value, '__module__', None) == name:
                                 symbols.append(attr)
                 except Exception:
+                    # Ignore errors during symbol collection
                     pass
 
+                # Only add modules that are not __init__.py and have symbols
                 if not rel_file.endswith('__init__.py') and symbols:
                     self.imports.append({
                         "name": name,
@@ -81,32 +98,45 @@ class Imports(IImports):
                         "symbols": symbols,
                     })
 
+        # Return the current instance with updated imports
         return self
 
     def display(self) -> None:
         """
         Display a formatted table of collected import statements using the Rich library.
 
-        If the imports have not been collected yet, it calls `self.collect()` to gather them.
-        The table includes columns for the import name, file, and imported symbols, and is
-        rendered inside a styled panel in the console.
+        This method presents a visual summary of all collected user-defined Python modules.
+        If the imports have not been collected yet, it automatically calls `self.collect()` to gather them.
+        The output is rendered as a table inside a styled panel in the console, showing each module's name,
+        relative file path, and its defined symbols.
+
+        Parameters
+        ----------
+        None
 
         Returns
         -------
         None
+            This method does not return any value. It outputs the formatted table to the console.
         """
 
+        # Collect imports if not already done
         if not self.imports:
             self.collect()
 
+        # Import Rich components for console output
         from rich.console import Console
         from rich.table import Table
         from rich.box import MINIMAL
         from rich.panel import Panel
 
+        # Create a console instance for output
         console = Console()
+
+        # Set table width to 75% of console width
         width = int(console.size.width * 0.75)
 
+        # Create a table with minimal box style and custom formatting
         table = Table(
             box=MINIMAL,
             show_header=True,
@@ -117,14 +147,17 @@ class Imports(IImports):
             collapse_padding=True,
         )
 
+        # Add columns for module name, file path, and symbols
         table.add_column("Name", style="cyan", no_wrap=True)
         table.add_column("File", style="white")
         table.add_column("Symbols", style="magenta")
 
+        # Populate the table with sorted import data
         for imp in sorted(self.imports, key=lambda x: x["name"].lower()):
             symbols_str = ", ".join(imp["symbols"])
             table.add_row(imp["name"], imp["file"], symbols_str)
 
+        # Render the table inside a styled panel in the console
         console.print(Panel(
             table,
             title="[bold blue]🔎 Loaded Python Modules (Orionis Imports Trace)[/bold blue]",
@@ -134,10 +167,17 @@ class Imports(IImports):
 
     def clear(self) -> None:
         """
-        Clear the collected imports list.
+        Remove all entries from the collected imports list.
+
+        This method resets the `imports` attribute by removing all currently stored
+        module information. It is useful for discarding previously collected data
+        before performing a new collection or when a fresh state is required.
 
         Returns
         -------
         None
+            This method does not return any value. The `imports` list is emptied in place.
         """
+
+        # Remove all items from the imports list to reset its state
         self.imports.clear()

orionis/services/system/runtime/imports.py

@@ -25,6 +25,7 @@ Notes
 - Thread safety is provided via a threading.Lock.
 
 """
+
 import builtins
 from collections import defaultdict
 from threading import Lock
@@ -40,40 +41,48 @@ _import_lock = Lock()
 
 def custom_import(name, globals=None, locals=None, fromlist=(), level=0):
     """
-    Custom import function that tracks imports of 'orionis' modules.
+    Tracks and logs imports of modules whose names start with 'orionis'.
+
+    This function overrides Python's built-in import mechanism to monitor
+    how many times modules from the 'orionis' package are imported. It
+    increments an internal counter for each such import and prints a log
+    message with the module name, import count, and fromlist. Thread safety
+    is ensured using a lock.
 
     Parameters
     ----------
     name : str
         The name of the module to import.
     globals : dict, optional
-        The global namespace.
+        The global namespace in which the import is performed.
     locals : dict, optional
-        The local namespace.
+        The local namespace in which the import is performed.
     fromlist : tuple, optional
         Names to import from the module.
     level : int, optional
-        Relative import level.
+        Relative import level (0 for absolute, >0 for relative).
 
     Returns
     -------
-    module
-        The imported module.
+    module : ModuleType
+        The imported module object as returned by the original import function.
     """
-    # Check if the module name starts with 'orionis'
+    # Only track imports for modules starting with 'orionis'
     if str(name).startswith("orionis"):
         with _import_lock:
+
+            # Increment the import count for this module
             _import_count[name] += 1
             count = _import_count[name]
 
-            # Print the import details
+            # Print import details to the console
             print(
                 f"\033[1;37mModule\033[0m: \033[90m{name}\033[0m | "
                 f"\033[1;37mImported\033[0m: \033[90m{count}\033[0m | "
                 f"\033[1;37mFromList\033[0m: \033[90m{fromlist}\033[0m"
             )
 
-    # Call the original import function
+    # Delegate the actual import to the original __import__ function
     return _original_import(name, globals, locals, fromlist, level)
 
 # Override the built-in __import__ function

orionis/services/system/workers.py

@@ -4,21 +4,10 @@ import psutil
 from orionis.services.system.contracts.workers import IWorkers
 
 class Workers(IWorkers):
-    """
-    Estimate the optimal number of worker processes based on system CPU and memory resources.
-
-    This class calculates the recommended number of Uvicorn (or similar) workers by considering:
-    the number of available CPU cores, total system memory (RAM), and the estimated memory usage per worker.
-
-    Parameters
-    ----------
-    ram_per_worker : float, optional
-        Estimated amount of RAM in gigabytes (GB) that each worker will consume. Default is 0.5.
-    """
 
     def __init__(self, ram_per_worker: float = 0.5):
         """
-        Initialize the worker system with resource constraints.
+        Initialize the Workers system with resource constraints.
 
         Parameters
         ----------
@@ -33,31 +22,75 @@ class Workers(IWorkers):
             Total system RAM in gigabytes.
         _ram_per_worker : float
             RAM allocated per worker in gigabytes.
+
+        Returns
+        -------
+        None
+            This constructor does not return a value.
         """
+
+        # Get the number of CPU cores available
         self._cpu_count = multiprocessing.cpu_count()
+
+        # Get the total system RAM in gigabytes
         self._ram_total_gb = psutil.virtual_memory().total / (1024 ** 3)
+
+        # Set the RAM allocated per worker
         self._ram_per_worker = ram_per_worker
 
     def setRamPerWorker(self, ram_per_worker: float) -> None:
         """
-        Set the amount of RAM allocated per worker.
+        Update the RAM allocation per worker.
 
         Parameters
         ----------
         ram_per_worker : float
-            Amount of RAM (in GB) allocated per worker.
+            The new amount of RAM (in GB) to allocate for each worker.
+
+        Returns
+        -------
+        None
+            This method does not return a value. It updates the internal RAM allocation setting.
+
+        Notes
+        -----
+        Changing the RAM allocation per worker may affect the recommended number of workers
+        calculated by the system. This method only updates the internal configuration and does
+        not trigger any recalculation automatically.
         """
+
+        # Update the RAM allocated per worker
         self._ram_per_worker = ram_per_worker
 
     def calculate(self) -> int:
         """
-        Compute the maximum number of workers supported by the current machine.
+        Compute the recommended maximum number of worker processes for the current machine,
+        considering both CPU and memory constraints.
+
+        Parameters
+        ----------
+        None
 
         Returns
         -------
         int
-            The recommended number of worker processes based on CPU and memory constraints.
+            The maximum number of worker processes that can be safely run in parallel,
+            determined by the lesser of available CPU cores and memory capacity.
+
+        Notes
+        -----
+        The calculation is based on:
+            - The total number of CPU cores available.
+            - The total system RAM divided by the RAM allocated per worker.
+        The method ensures that neither CPU nor memory resources are overcommitted.
+
         """
+
+        # Calculate the maximum workers allowed by CPU core count
         max_workers_by_cpu = self._cpu_count
+
+        # Calculate the maximum workers allowed by available RAM
         max_workers_by_ram = math.floor(self._ram_total_gb / self._ram_per_worker)
+
+        # Return the minimum of the two to avoid overcommitting resources
         return min(max_workers_by_cpu, max_workers_by_ram)

orionis/test/output/dumper.py

@@ -65,6 +65,7 @@ class TestDumper(ITestDumper):
                     AsyncTestCase,
                     SyncTestCase,
                     unittest.TestCase,
+                    unittest.IsolatedAsyncioTestCase
                 ),
             )
 

{orionis-0.406.0.dist-info → orionis-0.408.0.dist-info}/METADATA

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