orionis 0.405.0__py3-none-any.whl → 0.407.0__py3-none-any.whl

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/support/entities/base.py

@@ -0,0 +1,104 @@
+from dataclasses import asdict, fields, is_dataclass, MISSING
+from enum import Enum
+
+class BaseEntity:
+
+    def toDict(self) -> dict:
+        """
+        Converts the current instance into a dictionary representation.
+
+        Returns
+        -------
+        dict
+            Dictionary representation of the current instance.
+        """
+        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.
+        """
+        # Dictionary to hold field information
+        __fields = []
+
+        # Iterate over the fields of the dataclass and extract relevant information
+        for field in fields(self):
+
+            # Get the field name
+            __name = field.name
+
+            # Get the field type with better handling for complex types
+            __type = getattr(field.type, '__name__', None)
+
+            # If the type is None, handle it
+            if __type is None:
+
+                # Handle Union types or other complex types
+                type_lst = []
+                type_str = str(field.type).split('|')
+                for itype in type_str:
+                    type_lst.append(itype.strip())
+                __type = type_lst
+
+            # Ensure __type is a list for consistency
+            __type = type_lst if isinstance(__type, list) else [__type]
+
+            # Extract metadata, default value, and type
+            metadata = dict(field.metadata) if field.metadata else {}
+
+            # If metadata contains a default value, normalize it
+            if 'default' in metadata:
+                metadata_default = metadata['default']
+                if callable(metadata_default):
+                    metadata_default = metadata_default()
+                if is_dataclass(metadata_default):
+                    metadata_default = asdict(metadata_default)
+                elif isinstance(metadata_default, Enum):
+                    metadata_default = metadata_default.value
+                metadata['default'] = metadata_default
+
+            # Add the field information to the list
+            __metadata = metadata
+
+            # Extract the default value, if specified
+            __default = None
+
+            # Field has a direct default value
+            if field.default is not MISSING:
+                __default = field.default() if callable(field.default) else field.default
+                if is_dataclass(__default):
+                    __default = asdict(__default)
+                elif isinstance(__default, Enum):
+                    __default = __default.value
+
+            # Field has a default factory (like list, dict, etc.)
+            elif field.default_factory is not MISSING:
+                __default = field.default_factory() if callable(field.default_factory) else field.default_factory
+                if is_dataclass(__default):
+                    __default = asdict(__default)
+                elif isinstance(__default, Enum):
+                    __default = __default.value
+
+            # No default found, check metadata for custom default
+            else:
+                __default = __metadata.get('default', None)
+
+            # Append the field information to the list
+            __fields.append({
+                "name": __name,
+                "types": __type,
+                "default": __default,
+                "metadata": __metadata
+            })
+
+        # Return the list of field information
+        return __fields

orionis/support/facades/testing.py

@@ -0,0 +1,15 @@
+from orionis.container.facades.facade import Facade
+
+class Test(Facade):
+
+    @classmethod
+    def getFacadeAccessor(cls) -> str:
+        """
+        Get the service container binding key for the dumper component.
+
+        Returns
+        -------
+        str
+            The service container binding key.
+        """
+        return "core.orionis.testing"

orionis/support/facades/workers.py

@@ -1,6 +1,6 @@
 from orionis.container.facades.facade import Facade
 
-class ProgressBar(Facade):
+class Workers(Facade):
 
     @classmethod
     def getFacadeAccessor(cls):

orionis/test/cases/asynchronous.py

@@ -30,17 +30,6 @@ class AsyncTestCase(unittest.IsolatedAsyncioTestCase, TestDumper):
         Hook method for subclass-specific async setup logic.
     onAsyncTeardown()
         Hook method for subclass-specific async teardown logic.
-
-    Examples
-    --------
-    >>> class MyAsyncTest(AsyncTestCase):
-    ...     async def onAsyncSetup(self):
-    ...         self.client = AsyncHttpClient()
-    ...         await self.client.connect()
-    ...
-    ...     async def testAsyncOperation(self):
-    ...         result = await self.client.get('/api/data')
-    ...         self.assertEqual(result.status, 200)
     """
 
     async def asyncSetUp(self):

orionis/test/cases/synchronous.py

@@ -27,15 +27,6 @@ class SyncTestCase(unittest.TestCase, TestDumper):
         Hook method for subclass-specific setup logic.
     onTeardown()
         Hook method for subclass-specific teardown logic.
-
-    Examples
-    --------
-    >>> class MyTest(SyncTestCase):
-    ...     def onSetup(self):
-    ...         self.data = [1, 2, 3]
-    ...
-    ...     def testExample(self):
-    ...         self.assertEqual(len(self.data), 3)
     """
 
     def setUp(self):

orionis/test/contracts/dumper.py

@@ -17,15 +17,22 @@ class ITestDumper(ABC):
     @abstractmethod
     def dd(self, *args) -> None:
         """
-        Dumps debugging information using the Debug class.
+        Outputs debugging information using the Debug class.
 
-        This method captures the caller's file and line number,
-        and uses the Debug class to output debugging information.
+        This method captures the caller's file and line number, then
+        utilizes the Debug class to display or log the provided arguments
+        for debugging purposes.
 
         Parameters
         ----------
         *args : tuple
-            Variable length argument list to be dumped.
+            Variable length argument list containing the data to be dumped.
+
+        Returns
+        -------
+        None
+            This method does not return any value. Its purpose is to output
+            or log the debugging information.
         """
         pass
 

orionis/test/contracts/kernel.py

@@ -1,7 +1,5 @@
 from abc import ABC, abstractmethod
-from typing import Any
-from orionis.foundation.config.testing.entities.testing import Testing as Configuration
-from orionis.test.core.unit_test import UnitTest
+from orionis.test.contracts.unit_test import IUnitTest
 
 class ITestKernel(ABC):
     """
@@ -19,116 +17,13 @@ class ITestKernel(ABC):
     """
 
     @abstractmethod
-    def handle(
-        self,
-        config: Configuration = None,
-        **kwargs: Any
-    ) -> UnitTest:
+    def handle(self) -> IUnitTest:
         """
-        Execute the complete test discovery and execution pipeline.
-
-        This is the main entry point for running tests. Implementations must:
-        1. Validate the provided configuration
-        2. Discover test files based on configuration
-        3. Configure and execute the test suite
-        4. Return the test results
-
-        Parameters
-        ----------
-        config : Configuration, optional
-            A pre-configured Testing configuration instance. If None,
-            implementations should create one from kwargs.
-        **kwargs : Any
-            Keyword arguments to create a Configuration instance if config is None.
-            Common parameters include:
-            - base_path : str, base directory for test discovery
-            - folder_path : str or list, specific folders to search
-            - pattern : str, file pattern for test discovery
-            - verbosity : int, output verbosity level
-            - execution_mode : str, test execution mode
-            - max_workers : int, maximum number of worker threads
-            - fail_fast : bool, stop on first failure
-
-        Returns
-        -------
-        UnitTest
-            The configured and executed test suite instance containing all results.
-
-        Raises
-        ------
-        OrionisTestConfigException
-            If the configuration validation fails.
-        """
-        pass
-
-    @abstractmethod
-    def handleCLI(
-        self,
-        sys_argv: list[str]
-    ) -> UnitTest:
-        """
-        Process command line arguments for test execution.
-
-        This method configures and runs tests based on command line arguments. It parses
-        the provided sys_argv list into a TestArguments object, extracts configuration
-        values, executes the tests, and handles output generation.
-
-        Parameters
-        ----------
-        sys_argv : list[str]
-            Command line arguments list including script name. The script name
-            (first element) will be automatically removed before parsing.
+        Configure and execute the unit tests based on the current configuration.
 
         Returns
         -------
-        UnitTest
-            The test suite instance containing all test results.
-
-        Raises
-        ------
-        OrionisTestConfigException
-            If the provided sys_argv is not a valid list or if argument parsing fails.
-
-        Notes
-        -----
-        The method supports various test execution options including parallel/sequential
-        execution mode, fail fast behavior, result output configuration, and web reporting.
+        IUnitTest
+            The configured and executed unit test instance.
         """
         pass
-
-    @abstractmethod
-    def exit(
-        self,
-        code: int = 0
-    ) -> None:
-        """
-        Terminate the test execution process and free associated resources.
-
-        This method performs a clean shutdown of the test kernel by explicitly
-        triggering garbage collection to release memory resources and then
-        terminating the process with the provided exit code. It ensures that any
-        remaining file handles, threads, or other resources are properly released.
-
-        Parameters
-        ----------
-        code : int
-            The exit code to return to the operating system. Should be 0 for
-            successful execution or a non-zero value to indicate an error.
-
-        Returns
-        -------
-        None
-            This method does not return as it terminates the process.
-
-        Raises
-        ------
-        ValueError
-            If the provided code is not a valid integer or outside the allowed range.
-
-        Notes
-        -----
-        Using os._exit() bypasses normal Python cleanup mechanisms and
-        immediately terminates the process. This can be necessary when
-        normal sys.exit() would be caught by exception handlers.
-        """
-        pass

orionis/test/contracts/logs.py

@@ -3,79 +3,56 @@ from typing import Dict, List, Optional, Tuple
 
 class ITestLogs(ABC):
     """
-    Abstract base class for test logging and report persistence.
-
-    This interface defines the contract for managing test reports in a persistent
-    storage system. Implementations should provide functionality to create, retrieve,
-    and reset test report data while maintaining proper data validation and error
-    handling.
-
-    The interface supports chronological retrieval of reports and provides methods
-    for database management operations.
-
-    Methods
-    -------
-    create(report)
-        Create and store a new test report in the persistence layer.
-    reset()
-        Reset the storage by clearing all existing test reports.
-    get(first, last)
-        Retrieve test reports with optional chronological filtering.
+    Interface for test logs persistence using a relational database.
     """
 
     @abstractmethod
     def create(self, report: Dict) -> bool:
         """
-        Create a new test report in the history database.
-
-        This method persists a test report containing execution results and
-        metadata to the underlying storage system. The report should include
-        all necessary fields for proper tracking and analysis.
+        Store a new test report in the database.
 
         Parameters
         ----------
         report : Dict
-            A dictionary containing the test report data. Must include fields
-            such as total_tests, passed, failed, errors, skipped, total_time,
-            success_rate, and timestamp.
+            Must include the following keys:
+            - json (str): JSON-serialized report.
+            - total_tests (int)
+            - passed (int)
+            - failed (int)
+            - errors (int)
+            - skipped (int)
+            - total_time (float)
+            - success_rate (float)
+            - timestamp (str)
 
         Returns
         -------
         bool
-            True if the report was successfully created and stored, False otherwise.
+            True if the report was stored successfully.
 
         Raises
         ------
         OrionisTestValueError
-            If the report structure is invalid or missing required fields.
+            If required fields are missing or invalid.
         OrionisTestPersistenceError
-            If there is an error during the storage operation.
+            If a database error occurs.
         """
         pass
 
     @abstractmethod
     def reset(self) -> bool:
         """
-        Reset the history database by dropping the existing table.
-
-        This method clears all stored test reports and resets the storage
-        system to its initial state. Use with caution as this operation
-        is irreversible and will result in permanent data loss.
+        Drop the reports table, removing all test history.
 
         Returns
         -------
         bool
-            True if the database was successfully reset, False otherwise.
+            True if the table was dropped or did not exist.
 
         Raises
         ------
         OrionisTestPersistenceError
-            If there is an error during the reset operation.
-
-        Notes
-        -----
-        This operation is destructive and cannot be undone. Ensure that
-        any important historical data is backed up before calling this method.
+            If a database error occurs.
         """
         pass
 
@@ -86,40 +63,25 @@ class ITestLogs(ABC):
         last: Optional[int] = None
     ) -> List[Tuple]:
         """
-        Retrieve test reports from the history database.
-
-        This method allows for chronological retrieval of test reports with
-        optional filtering. You can retrieve either the earliest or most recent
-        reports, but not both in a single call.
+        Retrieve test reports from the database.
 
         Parameters
         ----------
-        first : Optional[int], default=None
-            The number of earliest reports to retrieve, ordered ascending by ID.
-            Must be a positive integer if specified.
-        last : Optional[int], default=None
-            The number of latest reports to retrieve, ordered descending by ID.
-            Must be a positive integer if specified.
+        first : Optional[int]
+            Number of earliest reports (ascending by id).
+        last : Optional[int]
+            Number of latest reports (descending by id).
 
         Returns
         -------
         List[Tuple]
-            A list of tuples representing the retrieved reports. Each tuple
-            contains the report data in the order: (id, json, total_tests,
-            passed, failed, errors, skipped, total_time, success_rate, timestamp).
+            Each tuple: (id, json, total_tests, passed, failed, errors, skipped, total_time, success_rate, timestamp)
 
         Raises
         ------
         OrionisTestValueError
-            If both 'first' and 'last' are specified, or if either parameter
-            is not a positive integer when provided.
+            If both 'first' and 'last' are specified, or if either is not a positive integer.
         OrionisTestPersistenceError
-            If there is an error retrieving reports from the storage system.
-
-        Notes
-        -----
-        Only one of 'first' or 'last' parameters can be specified in a single
-        call. The returned results are ordered chronologically based on the
-        selected parameter.
+            If a database error occurs.
         """
-        pass
+        pass