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

tests/metadata/test_metadata_framework.py

@@ -13,13 +13,23 @@ class TestMetadataFramework(AsyncTestCase):
 
     async def testConstantsExistAndAreStr(self):
         """
-        Test that all metadata constants exist and are of type `str`.
+        Validate that all metadata constants exist and are of type `str`.
+
+        This test iterates over a predefined list of metadata constants and checks
+        that each constant is present and its type is `str`.
 
         Raises
         ------
         AssertionError
             If any constant is not a string.
+
+        Returns
+        -------
+        None
+            This method does not return any value.
         """
+
+        # Check each metadata constant for type str
         for const in [
             NAME, VERSION, AUTHOR, AUTHOR_EMAIL, DESCRIPTION,
             SKELETON, FRAMEWORK, DOCS, API, PYTHON_REQUIRES
@@ -28,27 +38,49 @@ class TestMetadataFramework(AsyncTestCase):
 
     async def testClassifiersStructure(self):
         """
-        Test that `CLASSIFIERS` is a list of tuples of strings.
+        Ensure that `CLASSIFIERS` is a list of tuples containing strings.
+
+        This test verifies the structure of the `CLASSIFIERS` constant, ensuring
+        it is a list where each element is a tuple, and each tuple contains only strings.
 
         Raises
         ------
         AssertionError
             If `CLASSIFIERS` is not a list of tuples of strings.
+
+        Returns
+        -------
+        None
+            This method does not return any value.
         """
+
+        # Confirm CLASSIFIERS is a list
         self.assertIsInstance(CLASSIFIERS, list)
+
+        # Check each item in CLASSIFIERS for tuple of strings
         for item in CLASSIFIERS:
             self.assertIsInstance(item, tuple)
             self.assertTrue(all(isinstance(part, str) for part in item))
 
     async def testGetClassifiers(self):
         """
-        Test that `get_classifiers` returns a list of classifier strings.
+        Verify that `get_classifiers` returns a list of classifier strings.
+
+        This test calls the `get_classifiers` utility function and checks that
+        the returned value is a list of strings, each representing a classifier.
 
         Raises
         ------
         AssertionError
             If the returned value is not a list of strings containing '::'.
+
+        Returns
+        -------
+        None
+            This method does not return any value.
         """
+
+        # Retrieve classifiers and validate their format
         classifiers = get_classifiers()
         self.assertIsInstance(classifiers, list)
         for c in classifiers:
@@ -57,28 +89,50 @@ class TestMetadataFramework(AsyncTestCase):
 
     async def testKeywords(self):
         """
-        Test that `KEYWORDS` is a list of strings and contains specific keywords.
+        Check that `KEYWORDS` is a list of strings and contains required keywords.
+
+        This test ensures that the `KEYWORDS` constant is a list of strings and
+        verifies the presence of specific keywords relevant to the framework.
 
         Raises
         ------
         AssertionError
             If `KEYWORDS` is not a list of strings or required keywords are missing.
+
+        Returns
+        -------
+        None
+            This method does not return any value.
         """
+
+        # Confirm KEYWORDS is a list of strings
         self.assertIsInstance(KEYWORDS, list)
         for kw in KEYWORDS:
             self.assertIsInstance(kw, str)
+
+        # Check for required keywords
         self.assertIn("orionis", KEYWORDS)
         self.assertIn("framework", KEYWORDS)
 
     async def testRequiresStructure(self):
         """
-        Test that `REQUIRES` is a list of 2-element tuples of strings.
+        Validate that `REQUIRES` is a list of 2-element tuples of strings.
+
+        This test checks the structure of the `REQUIRES` constant, ensuring it is
+        a list where each element is a tuple of length 2, and both elements are strings.
 
         Raises
         ------
         AssertionError
             If `REQUIRES` is not a list of 2-element tuples of strings.
+
+        Returns
+        -------
+        None
+            This method does not return any value.
         """
+
+        # Confirm REQUIRES is a list of 2-element tuples of strings
         self.assertIsInstance(REQUIRES, list)
         for req in REQUIRES:
             self.assertIsInstance(req, tuple)
@@ -87,13 +141,24 @@ class TestMetadataFramework(AsyncTestCase):
 
     async def testGetRequires(self):
         """
-        Test that `get_requires` returns a list of requirement strings.
+        Ensure that `get_requires` returns a list of requirement strings.
+
+        This test calls the `get_requires` utility function and checks that the
+        returned value is a list of strings, each representing a requirement and
+        containing the '>=' version specifier.
 
         Raises
         ------
         AssertionError
             If the returned value is not a list of strings containing '>='.
+
+        Returns
+        -------
+        None
+            This method does not return any value.
         """
+
+        # Retrieve requirements and validate their format
         requires = get_requires()
         self.assertIsInstance(requires, list)
         for req in requires:

tests/metadata/test_metadata_package.py

@@ -6,89 +6,134 @@ class TestPypiPackageApi(AsyncTestCase):
     @patch("orionis.metadata.package.PypiPackageApi")
     async def testGetName(self, MockPypiPackageApi):
         """
-        Test for the getName method.
+        Tests the `getName` method of the `PypiPackageApi` class.
+
+        This test verifies that the mocked `getName` method returns the expected package name.
 
         Parameters
         ----------
         MockPypiPackageApi : MagicMock
-            Mocked PypiPackageApi class.
+            Mocked `PypiPackageApi` class.
 
         Returns
         -------
         None
+            This method does not return anything. It asserts the expected behavior.
         """
+
+        # Get the mocked API instance
         api = MockPypiPackageApi.return_value
+
+        # Set the return value for getName
         api.getName.return_value = "orionis"
+
+        # Assert that getName returns the expected value
         self.assertEqual(api.getName(), "orionis")
 
     @patch("orionis.metadata.package.PypiPackageApi")
     async def testGetAuthor(self, MockPypiPackageApi):
         """
-        Test for the getAuthor method.
+        Tests the `getAuthor` method of the `PypiPackageApi` class.
+
+        This test checks that the mocked `getAuthor` method returns the correct author name.
 
         Parameters
         ----------
         MockPypiPackageApi : MagicMock
-            Mocked PypiPackageApi class.
+            Mocked `PypiPackageApi` class.
 
         Returns
         -------
         None
+            This method does not return anything. It asserts the expected behavior.
         """
+
+        # Get the mocked API instance
         api = MockPypiPackageApi.return_value
+
+        # Set the return value for getAuthor
         api.getAuthor.return_value = "Raul Mauricio Uñate Castro"
+
+        # Assert that getAuthor returns the expected value
         self.assertEqual(api.getAuthor(), "Raul Mauricio Uñate Castro")
 
     @patch("orionis.metadata.package.PypiPackageApi")
     async def testGetAuthorEmail(self, MockPypiPackageApi):
         """
-        Test for the getAuthorEmail method.
+        Tests the `getAuthorEmail` method of the `PypiPackageApi` class.
+
+        This test ensures that the mocked `getAuthorEmail` method returns the correct author email address.
 
         Parameters
         ----------
         MockPypiPackageApi : MagicMock
-            Mocked PypiPackageApi class.
+            Mocked `PypiPackageApi` class.
 
         Returns
         -------
         None
+            This method does not return anything. It asserts the expected behavior.
         """
+
+        # Get the mocked API instance
         api = MockPypiPackageApi.return_value
+
+        # Set the return value for getAuthorEmail
         api.getAuthorEmail.return_value = "raulmauriciounate@gmail.com"
+
+        # Assert that getAuthorEmail returns the expected value
         self.assertEqual(api.getAuthorEmail(), "raulmauriciounate@gmail.com")
 
     @patch("orionis.metadata.package.PypiPackageApi")
     async def testGetDescription(self, MockPypiPackageApi):
         """
-        Test for the getDescription method.
+        Tests the `getDescription` method of the `PypiPackageApi` class.
+
+        This test verifies that the mocked `getDescription` method returns the expected package description.
 
         Parameters
         ----------
         MockPypiPackageApi : MagicMock
-            Mocked PypiPackageApi class.
+            Mocked `PypiPackageApi` class.
 
         Returns
         -------
         None
+            This method does not return anything. It asserts the expected behavior.
         """
+
+        # Get the mocked API instance
         api = MockPypiPackageApi.return_value
+
+        # Set the return value for getDescription
         api.getDescription.return_value = "Orionis Framework – Elegant, Fast, and Powerful."
+
+        # Assert that getDescription returns the expected value
         self.assertEqual(api.getDescription(), "Orionis Framework – Elegant, Fast, and Powerful.")
 
     @patch("orionis.metadata.package.PypiPackageApi")
     async def testGetPythonVersion(self, MockPypiPackageApi):
         """
-        Test for the getPythonVersion method.
+        Tests the `getPythonVersion` method of the `PypiPackageApi` class.
+
+        This test checks that the mocked `getPythonVersion` method returns the correct Python version requirement.
 
         Parameters
         ----------
         MockPypiPackageApi : MagicMock
-            Mocked PypiPackageApi class.
+            Mocked `PypiPackageApi` class.
 
         Returns
         -------
         None
+            This method does not return anything. It asserts the expected behavior.
         """
+
+        # Get the mocked API instance
         api = MockPypiPackageApi.return_value
+
+        # Set the return value for getPythonVersion
         api.getPythonVersion.return_value = ">=3.12"
+
+        # Assert that getPythonVersion returns the expected value
         self.assertEqual(api.getPythonVersion(), ">=3.12")

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"]