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

tests/services/asynchrony/test_services_asynchrony_coroutine.py

@@ -1,4 +1,5 @@
 
+import asyncio
 from orionis.services.asynchrony.coroutines import Coroutine
 from orionis.services.asynchrony.exceptions import OrionisCoroutineException
 from orionis.test.cases.asynchronous import AsyncTestCase
@@ -7,34 +8,78 @@ class TestServicesAsynchronyCoroutine(AsyncTestCase):
 
     async def testExecuteWithActiveEventLoop(self):
         """
-        Test the execution of a coroutine within an active event loop.
-        This test simulates a scenario where the coroutine is executed in an environment with an active event loop,
-        such as a Jupyter notebook or a Starlette application.
+        Tests coroutine execution within an active event loop.
+
+        This method verifies that a coroutine can be executed successfully when an event loop is already running,
+        such as in asynchronous environments (e.g., Jupyter notebooks or ASGI applications). It ensures that the
+        Coroutine wrapper correctly awaits and returns the result of the coroutine.
+
+        Returns
+        -------
+        None
+            This is a test method and does not return a value. It asserts that the coroutine result matches the expected output.
         """
+
+        # Simple coroutine that returns a string
         async def sample_coroutine():
+            asyncio.sleep(0.1)
             return "Hello, World!"
 
+        # Await the result of running the coroutine using the Coroutine wrapper
         result = await Coroutine(sample_coroutine()).run()
+
+        # Assert that the result matches the expected output
         self.assertEqual(result, "Hello, World!")
 
     def testExecuteWithoutActiveEventLoop(self):
         """
-        Test the execution of a coroutine without an active event loop.
-        This test simulates a scenario where the coroutine is executed in a synchronous context without an active event loop.
+        Tests coroutine execution without an active event loop.
+
+        This method simulates the scenario where a coroutine is executed in a synchronous context,
+        such as a standard Python script, where no event loop is running. It verifies that the
+        Coroutine wrapper can correctly create and manage an event loop internally, execute the
+        coroutine, and return the expected result.
+
+        Returns
+        -------
+        None
+            This test method does not return a value. It asserts that the coroutine result matches the expected output.
         """
+
+        # Define a simple coroutine that returns a string
         async def sample_coroutine():
+            asyncio.sleep(0.1)
             return "Hello, World!"
 
+        # Run the coroutine using the Coroutine wrapper, which should handle event loop creation
         result = Coroutine(sample_coroutine()).run()
+
+        # Assert that the result matches the expected output
         self.assertEqual(result, "Hello, World!")
 
     def testExecuteWithNonCoroutine(self):
         """
-        Test the execution of a non-coroutine object.
-        This test checks that a TypeError is raised when a non-coroutine object is passed to the execute method.
+        Tests execution of a non-coroutine object.
+
+        This method verifies that passing a non-coroutine object to the Coroutine wrapper
+        raises an OrionisCoroutineException. It ensures that the Coroutine class enforces
+        the requirement for coroutine objects and does not accept regular functions or other types.
+
+        Parameters
+        ----------
+        self : TestServicesAsynchronyCoroutine
+            The test case instance.
+
+        Returns
+        -------
+        None
+            This test method does not return a value. It asserts that the appropriate exception is raised.
         """
+
+        # Define a regular function (not a coroutine)
         def sample_no_coroutine():
             return "Hello, World!"
 
+        # Assert that passing a non-coroutine raises OrionisCoroutineException
         with self.assertRaises(OrionisCoroutineException):
             Coroutine(sample_no_coroutine())

tests/services/system/test_services_system_imports.py

@@ -1,101 +1,204 @@
-from orionis.services.system.imports import Imports
-from orionis.test.cases.asynchronous import AsyncTestCase
 import sys
 import types
+from orionis.services.system.imports import Imports
+from orionis.test.cases.asynchronous import AsyncTestCase
 
 class TestServicesSystemImports(AsyncTestCase):
 
-    def testImportModule(self) -> None:
+    async def testImportModule(self) -> None:
         """
-        Test that Imports can be instantiated and collected.
+        Tests that an Imports instance can be created and that the collect() method
+        successfully populates its imports list.
+
+        This test verifies the basic instantiation of the Imports class and ensures
+        that the collect() method executes without errors.
 
         Returns
         -------
         None
+            This method does not return any value.
         """
+
+        # Create an instance of Imports
         imports = Imports()
+
+        # Populate the imports list
         imports.collect()
+
+        # Assert that the instance is of type Imports
         self.assertIsInstance(imports, Imports)
 
-    def testCollectPopulatesImports(self):
+    async def testCollectPopulatesImports(self):
         """
-        Test that collect() populates the imports list with modules.
+        Tests that the `collect()` method of the Imports class populates the imports list with modules.
+
+        This test creates a dummy module, adds it to `sys.modules`, and verifies that after calling
+        `collect()`, the dummy module appears in the `imports` list of the Imports instance.
+
+        Parameters
+        ----------
+        self : TestServicesSystemImports
+            The test case instance.
 
         Returns
         -------
         None
+            This method does not return any value.
         """
+
+        # Create a dummy module and set its __file__ attribute
         dummy_mod = types.ModuleType("dummy_mod")
         dummy_mod.__file__ = __file__
+
+        # Add a dummy function to the module and set its __module__ attribute
         def dummy_func(): pass
         dummy_mod.dummy_func = dummy_func
         dummy_func.__module__ = "dummy_mod"
+
+        # Register the dummy module in sys.modules
         sys.modules["dummy_mod"] = dummy_mod
 
+        # Create Imports instance and collect imports
         imports = Imports()
         imports.collect()
+
+        # Check if the dummy module was collected
         found = any(imp["name"] == "dummy_mod" for imp in imports.imports)
         self.assertTrue(found)
 
-        # Cleanup
+        # Cleanup: remove the dummy module from sys.modules
         del sys.modules["dummy_mod"]
 
-    def testCollectExcludesStdlibAndSpecialModules(self):
+    async def testCollectExcludesStdlibAndSpecialModules(self):
         """
-        Test that collect() excludes standard library and special modules.
+        Tests that the `collect()` method of the Imports class excludes standard library modules and special modules.
+
+        This test verifies that after calling `collect()`, the resulting imports list does not contain entries for
+        standard library modules such as `__main__` or modules whose names start with `_distutils`. This ensures
+        that the Imports class correctly filters out modules that should not be included in the imports list.
+
+        Parameters
+        ----------
+        self : TestServicesSystemImports
+            The test case instance.
 
         Returns
         -------
         None
+            This method does not return any value.
         """
+
+        # Create Imports instance and collect imports
         imports = Imports()
         imports.collect()
+
+        # Extract the names of collected modules
         names = [imp["name"] for imp in imports.imports]
+
+        # Assert that '__main__' is not in the collected imports
         self.assertNotIn("__main__", names)
+
+        # Assert that modules starting with '_distutils' are not in the collected imports
         self.assertFalse(any(n.startswith("_distutils") for n in names))
 
-    def testClearEmptiesImports(self):
+    async def testClearEmptiesImports(self):
         """
-        Test that clear() empties the imports list.
+        Tests that the `clear()` method of the Imports class empties the imports list.
+
+        This test manually populates the `imports` attribute of an Imports instance,
+        calls the `clear()` method, and verifies that the imports list is empty afterward.
+
+        Parameters
+        ----------
+        self : TestServicesSystemImports
+            The test case instance.
 
         Returns
         -------
         None
+            This method does not return any value.
         """
+        # Create Imports instance and manually populate the imports list
         imports = Imports()
         imports.imports = [{"name": "test", "file": "test.py", "symbols": ["a"]}]
+
+        # Call clear() to empty the imports list
         imports.clear()
+
+        # Assert that the imports list is now empty
         self.assertEqual(imports.imports, [])
 
-    def testCollectHandlesModulesWithoutFile(self):
+    async def testCollectHandlesModulesWithoutFile(self):
         """
-        Test that collect() handles modules without a __file__ attribute.
+        Tests that the `collect()` method of the Imports class correctly handles modules that do not have a `__file__` attribute.
+
+        This test creates a dummy module without a `__file__` attribute, registers it in `sys.modules`, and verifies that after calling
+        `collect()`, the module does not appear in the `imports` list of the Imports instance. This ensures that the Imports class
+        properly skips modules lacking a `__file__` attribute, which are typically built-in or dynamically created modules.
+
+        Parameters
+        ----------
+        self : TestServicesSystemImports
+            The test case instance.
 
         Returns
         -------
         None
+            This method does not return any value.
         """
+        # Create a dummy module without a __file__ attribute
         mod = types.ModuleType("mod_without_file")
         sys.modules["mod_without_file"] = mod
+
+        # Create Imports instance and collect imports
         imports = Imports()
         imports.collect()
+
+        # Extract the names of collected modules
         names = [imp["name"] for imp in imports.imports]
+
+        # Assert that the dummy module is not in the collected imports
         self.assertNotIn("mod_without_file", names)
+
+        # Cleanup: remove the dummy module from sys.modules
         del sys.modules["mod_without_file"]
 
-    def testCollectSkipsBinaryExtensions(self):
+    async def testCollectSkipsBinaryExtensions(self):
         """
-        Test that collect() skips binary extension modules.
+        Tests that the `collect()` method of the Imports class skips binary extension modules.
+
+        This test creates a dummy module with a `.pyd` file extension (representing a binary extension),
+        registers it in `sys.modules`, and verifies that after calling `collect()`, the module does not
+        appear in the `imports` list of the Imports instance. This ensures that the Imports class
+        properly excludes binary extension modules from its collected imports.
+
+        Parameters
+        ----------
+        self : TestServicesSystemImports
+            The test case instance.
 
         Returns
         -------
         None
+            This method does not return any value.
         """
+
+        # Create a dummy module with a .pyd file extension to simulate a binary extension
         mod = types.ModuleType("bin_mod")
         mod.__file__ = "bin_mod.pyd"
+
+        # Register the dummy binary module in sys.modules
         sys.modules["bin_mod"] = mod
+
+        # Create Imports instance and collect imports
         imports = Imports()
         imports.collect()
+
+        # Extract the names of collected modules
         names = [imp["name"] for imp in imports.imports]
+
+        # Assert that the binary module is not in the collected imports
         self.assertNotIn("bin_mod", names)
-        del sys.modules["bin_mod"]
+
+        # Cleanup: remove the dummy binary module from sys.modules
+        del sys.modules["bin_mod"]

tests/services/system/test_services_system_workers.py

@@ -3,88 +3,129 @@ from orionis.services.system.workers import Workers
 from orionis.test.cases.asynchronous import AsyncTestCase
 
 class TestServicesSystemWorkers(AsyncTestCase):
-    """
-    Unit tests for the Workers class.
-
-    This test suite verifies the correct calculation of the number of workers
-    based on available CPU and RAM resources.
-
-    Methods
-    -------
-    testCalculateCpuLimited()
-        Test when the number of workers is limited by CPU count.
-    testCalculateRamLimited()
-        Test when the number of workers is limited by available RAM.
-    testCalculateExactFit()
-        Test when CPU and RAM allow for the same number of workers.
-    testCalculateLowRam()
-        Test when low RAM restricts the number of workers to less than CPU count.
-    """
 
     @patch('multiprocessing.cpu_count', return_value=8)
     @patch('psutil.virtual_memory')
     def testCalculateCpuLimited(self, mockVm, mockCpuCount):
         """
-        Test when the number of workers is limited by CPU count.
+        Tests worker calculation when CPU count is the limiting factor.
 
-        Simulates 8 CPUs and 16 GB RAM, with ram_per_worker=1.
-        RAM allows 16 workers, but CPU only allows 8.
+        Simulates a system with 8 CPUs and 16 GB RAM, where each worker requires 1 GB of RAM.
+        Although the available RAM could support up to 16 workers, the CPU count restricts the number
+        of workers to 8.
+
+        Parameters
+        ----------
+        mockVm : unittest.mock.Mock
+            Mock object for `psutil.virtual_memory`.
+        mockCpuCount : unittest.mock.Mock
+            Mock object for `multiprocessing.cpu_count`.
 
         Returns
         -------
         None
+            Asserts that the calculated number of workers is limited by CPU count.
         """
+
+        # Set the mocked total RAM to 16 GB
         mockVm.return_value.total = 16 * 1024 ** 3
+
+        # Create Workers instance with 1 GB RAM required per worker
         workers = Workers(ram_per_worker=1)
+
+        # Assert that the number of workers is limited to 8 by CPU count
         self.assertEqual(workers.calculate(), 8)
 
     @patch('multiprocessing.cpu_count', return_value=32)
     @patch('psutil.virtual_memory')
     def testCalculateRamLimited(self, mockVm, mockCpuCount):
         """
-        Test when the number of workers is limited by available RAM.
+        Tests worker calculation when RAM is the limiting factor.
 
-        Simulates 32 CPUs and 4 GB RAM, with ram_per_worker=1.
-        RAM allows only 4 workers.
+        Simulates a system with 32 CPUs and 4 GB RAM, where each worker requires 1 GB of RAM.
+        Although the CPU count could support up to 32 workers, the available RAM restricts the number
+        of workers to 4.
+
+        Parameters
+        ----------
+        mockVm : unittest.mock.Mock
+            Mock object for `psutil.virtual_memory`.
+        mockCpuCount : unittest.mock.Mock
+            Mock object for `multiprocessing.cpu_count`.
 
         Returns
         -------
         None
+            Asserts that the calculated number of workers is limited by available RAM.
         """
+
+        # Set the mocked total RAM to 4 GB
         mockVm.return_value.total = 4 * 1024 ** 3
+
+        # Create Workers instance with 1 GB RAM required per worker
         workers = Workers(ram_per_worker=1)
+
+        # Assert that the number of workers is limited to 4 by available RAM
         self.assertEqual(workers.calculate(), 4)
 
     @patch('multiprocessing.cpu_count', return_value=4)
     @patch('psutil.virtual_memory')
     def testCalculateExactFit(self, mockVm, mockCpuCount):
         """
-        Test when CPU and RAM allow for the same number of workers.
+        Tests worker calculation when both CPU count and available RAM allow for the same number of workers.
 
-        Simulates 4 CPUs and 2 GB RAM, with ram_per_worker=0.5.
-        RAM allows 4 workers.
+        Simulates a system with 4 CPUs and 2 GB RAM, where each worker requires 0.5 GB of RAM.
+        Both CPU and RAM resources permit exactly 4 workers, so the calculation should return 4.
+
+        Parameters
+        ----------
+        mockVm : unittest.mock.Mock
+            Mock object for `psutil.virtual_memory`.
+        mockCpuCount : unittest.mock.Mock
+            Mock object for `multiprocessing.cpu_count`.
 
         Returns
         -------
         None
+            Asserts that the calculated number of workers is 4, matching both CPU and RAM constraints.
         """
+        # Set the mocked total RAM to 2 GB
         mockVm.return_value.total = 2 * 1024 ** 3
+
+        # Create Workers instance with 0.5 GB RAM required per worker
         workers = Workers(ram_per_worker=0.5)
+
+        # Assert that the number of workers is limited to 4 by both CPU and RAM
         self.assertEqual(workers.calculate(), 4)
 
     @patch('multiprocessing.cpu_count', return_value=2)
     @patch('psutil.virtual_memory')
     def testCalculateLowRam(self, mockVm, mockCpuCount):
         """
-        Test when low RAM restricts the number of workers to less than CPU count.
+        Tests worker calculation when available RAM is lower than CPU count, restricting the number of workers.
+
+        Simulates a system with 2 CPUs and 0.7 GB RAM, where each worker requires 0.5 GB of RAM.
+        Although the CPU count could support up to 2 workers, the available RAM restricts the number
+        of workers to 1.
 
-        Simulates 2 CPUs and 0.7 GB RAM, with ram_per_worker=0.5.
-        RAM allows only 1 worker.
+        Parameters
+        ----------
+        mockVm : unittest.mock.Mock
+            Mock object for `psutil.virtual_memory`.
+        mockCpuCount : unittest.mock.Mock
+            Mock object for `multiprocessing.cpu_count`.
 
         Returns
         -------
         None
+            Asserts that the calculated number of workers is limited to 1 by available RAM.
         """
+
+        # Set the mocked total RAM to 0.7 GB
         mockVm.return_value.total = 0.7 * 1024 ** 3
+
+        # Create Workers instance with 0.5 GB RAM required per worker
         workers = Workers(ram_per_worker=0.5)
-        self.assertEqual(workers.calculate(), 1)
+
+        # Assert that the number of workers is limited to 1 by available RAM
+        self.assertEqual(workers.calculate(), 1)