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

tests/container/test_singleton.py

@@ -5,55 +5,64 @@ from orionis.container.container import Container
 from orionis.test.cases.asynchronous import AsyncTestCase
 
 class TestSingleton(AsyncTestCase):
-    """Test suite for singleton pattern implementation."""
 
     async def testSingletonBasicFunctionality(self) -> None:
         """
-        Test basic singleton functionality.
+        Tests the fundamental behavior of the singleton pattern for `Container` and `Orionis` classes.
 
-        This test verifies that:
-        1. Multiple Container instances are the same object
-        2. Multiple Orionis instances are the same object
-        3. Container and Orionis are different singletons
+        This method verifies the following:
+        - Multiple instances of `Container` refer to the same object.
+        - Multiple instances of `Orionis` refer to the same object.
+        - The singleton instances of `Container` and `Orionis` are distinct from each other.
+
+        Returns
+        -------
+        None
+            This method does not return any value. Assertions are used to validate singleton behavior.
         """
-        # Create multiple instances
+        # Create multiple instances of Container and Orionis
         container1 = Container()
         container2 = Container()
         orionis1 = Orionis()
         orionis2 = Orionis()
 
-        # Test that Container instances are the same
+        # Assert that all Container instances are the same object
         self.assertIs(container1, container2)
         self.assertEqual(id(container1), id(container2))
 
-        # Test that Orionis instances are the same
+        # Assert that all Orionis instances are the same object
         self.assertIs(orionis1, orionis2)
         self.assertEqual(id(orionis1), id(orionis2))
 
-        # Test that Container and Orionis are different singletons
+        # Assert that Container and Orionis are different singleton instances
         self.assertIsNot(container1, orionis1)
 
     async def testSingletonThreadingSafety(self) -> None:
         """
-        Test singleton in multi-threaded environment.
+        Validates the thread safety of the singleton pattern for `Container` and `Orionis` classes.
+
+        This method ensures that, even when multiple threads attempt to instantiate
+        `Container` and `Orionis` simultaneously, only one instance of each class is created.
 
-        This test verifies that singleton pattern works correctly
-        when instances are created from multiple threads simultaneously.
+        Returns
+        -------
+        None
+            This method does not return any value. Assertions are used to validate thread-safe singleton behavior.
         """
         container_instances = []
         orionis_instances = []
 
         def create_container():
-            """Create container instance in thread."""
-            time.sleep(0.01)  # Small delay to increase chance of race condition
+            """Create and append a Container instance in a thread."""
+            time.sleep(0.01)  # Increase chance of race condition
             container_instances.append(Container())
 
         def create_orionis():
-            """Create orionis instance in thread."""
-            time.sleep(0.01)  # Small delay to increase chance of race condition
+            """Create and append an Orionis instance in a thread."""
+            time.sleep(0.01)  # Increase chance of race condition
             orionis_instances.append(Orionis())
 
-        # Create multiple threads
+        # Create threads for concurrent instantiation
         threads = []
         for i in range(10):
             t1 = threading.Thread(target=create_container)
@@ -68,10 +77,11 @@ class TestSingleton(AsyncTestCase):
         for t in threads:
             t.join()
 
-        # Check that all instances are the same
+        # Collect instance IDs for verification
         container_ids = [id(c) for c in container_instances]
         orionis_ids = [id(o) for o in orionis_instances]
 
+        # Assert that only one unique instance exists for each class
         self.assertEqual(len(set(container_ids)), 1)
         self.assertEqual(len(set(orionis_ids)), 1)
         self.assertEqual(len(container_instances), 10)
@@ -79,20 +89,29 @@ class TestSingleton(AsyncTestCase):
 
     async def testInheritanceSeparation(self) -> None:
         """
-        Test that Container and Orionis maintain separate singleton instances.
+        Ensures that singleton instances are maintained separately for `Container` and `Orionis` classes.
 
-        This test verifies that different singleton classes maintain
-        their own separate instances while both implementing singleton pattern.
+        This method checks that:
+        - Each class maintains its own singleton instance.
+        - Data added to one singleton does not affect the other.
+        - Both classes correctly implement the singleton pattern independently.
+
+        Returns
+        -------
+        None
+            This method does not return any value. Assertions are used to validate singleton separation.
         """
         container = Container()
         orionis = Orionis()
 
-        # Add some data to each to verify they're separate
+        # Add a callable to the Container singleton
         container.callable("test_container", lambda: "container_value")
 
-        # Check that they're different instances but both are singletons
+        # Verify that Container and Orionis are distinct singletons
         self.assertEqual(type(container).__name__, "Container")
         self.assertEqual(type(orionis).__name__, "Application")
         self.assertIsNot(container, orionis)
+
+        # Check that the callable is bound only to Container
         self.assertTrue(container.bound('test_container'))
         self.assertFalse(orionis.bound('test_container'))

tests/container/test_thread_safety.py

@@ -10,16 +10,34 @@ class TestThreadSafety(AsyncTestCase):
 
     async def testStressSingleton(self) -> None:
         """
-        Test singleton under extreme concurrent conditions.
-
-        This test creates a large number of threads that simultaneously
-        attempt to create singleton instances to verify thread-safety.
+        Stress test singleton behavior under extreme concurrent conditions.
+
+        This method creates a large number of threads that simultaneously attempt to
+        instantiate singleton objects (`Container` and `Orionis`). It verifies that
+        only one unique instance of each singleton exists, regardless of concurrent
+        access, and that the singleton instances are distinct from each other.
+
+        Parameters
+        ----------
+        None
+
+        Returns
+        -------
+        None
+            This method does not return any value. Assertions are used to validate
+            singleton behavior under stress.
+
+        Notes
+        -----
+        - Random delays are introduced to increase the likelihood of race conditions.
+        - ThreadPoolExecutor is used to simulate high concurrency.
+        - The test ensures that singleton integrity is maintained even under heavy load.
         """
         container_instances = []
         orionis_instances = []
 
         def create_container_with_delay():
-            """Create container with random delay to simulate real conditions."""
+            """Create a Container instance after a random delay to simulate real-world concurrency."""
             # Random delay to increase chance of race conditions
             time.sleep(random.uniform(0.001, 0.01))
             container = Container()
@@ -27,16 +45,17 @@ class TestThreadSafety(AsyncTestCase):
             return id(container)
 
         def create_orionis_with_delay():
-            """Create orionis with random delay to simulate real conditions."""
+            """Create an Orionis instance after a random delay to simulate real-world concurrency."""
             # Random delay to increase chance of race conditions
             time.sleep(random.uniform(0.001, 0.01))
             orionis = Orionis()
             orionis_instances.append(orionis)
             return id(orionis)
 
-        # Create a large number of threads
+        # Number of concurrent threads to simulate
         num_threads = 100
 
+        # Use ThreadPoolExecutor to run tasks concurrently
         with ThreadPoolExecutor(max_workers=50) as executor:
             # Submit container creation tasks
             container_futures = [
@@ -50,11 +69,11 @@ class TestThreadSafety(AsyncTestCase):
                 for _ in range(num_threads)
             ]
 
-            # Wait for all tasks to complete
+            # Wait for all tasks to complete and collect instance IDs
             container_ids = [future.result() for future in as_completed(container_futures)]
             orionis_ids = [future.result() for future in as_completed(orionis_futures)]
 
-        # Verify all instances are the same
+        # Verify all instances are the same (singleton property)
         unique_container_ids = set(container_ids)
         unique_orionis_ids = set(orionis_ids)
 
@@ -68,150 +87,3 @@ class TestThreadSafety(AsyncTestCase):
         orionis_id = list(unique_orionis_ids)[0] if unique_orionis_ids else None
 
         self.assertNotEqual(container_id, orionis_id)
-
-    async def testRapidAccess(self) -> None:
-        """
-        Test rapid concurrent access to existing singleton instances.
-
-        This test verifies that rapid concurrent access to already
-        created singleton instances maintains consistency.
-        """
-        # Create initial instances
-        initial_container = Container()
-        initial_orionis = Orionis()
-
-        container_ids = []
-        orionis_ids = []
-
-        def rapid_container_access():
-            """Rapidly access container singleton."""
-            for _ in range(100):
-                container = Container()
-                container_ids.append(id(container))
-
-        def rapid_orionis_access():
-            """Rapidly access orionis singleton."""
-            for _ in range(100):
-                orionis = Orionis()
-                orionis_ids.append(id(orionis))
-
-        # Create threads for rapid access
-        threads = []
-        for _ in range(20):
-            t1 = threading.Thread(target=rapid_container_access)
-            t2 = threading.Thread(target=rapid_orionis_access)
-            threads.extend([t1, t2])
-
-        # Start all threads simultaneously
-        start_time = time.time()
-        for t in threads:
-            t.start()
-
-        # Wait for all threads to complete
-        for t in threads:
-            t.join()
-
-        end_time = time.time()
-
-        # Verify consistency
-        unique_container_ids = set(container_ids)
-        unique_orionis_ids = set(orionis_ids)
-
-        self.assertEqual(len(container_ids), 20 * 100)  # 20 threads * 100 accesses each
-        self.assertEqual(len(unique_container_ids), 1)
-        self.assertEqual(len(orionis_ids), 20 * 100)
-        self.assertEqual(len(unique_orionis_ids), 1)
-
-        # Verify performance is reasonable (should complete quickly)
-        self.assertLess(end_time - start_time, 10.0)  # Should complete in less than 10 seconds
-
-    async def testMixedOperations(self) -> None:
-        """
-        Test mixed read/write operations on singletons.
-
-        This test verifies that concurrent read/write operations
-        maintain singleton consistency and data integrity.
-        """
-        errors = []
-
-        def mixed_operations():
-            """Perform mixed operations on containers."""
-            try:
-                # Get instances
-                container = Container()
-                orionis = Orionis()
-
-                # Perform some operations
-                test_key = f"test_func_{threading.current_thread().ident}"
-                container.callable(test_key, lambda: "test_value")
-
-                # Verify the same instance
-                container2 = Container()
-                orionis2 = Orionis()
-
-                if container is not container2:
-                    errors.append("Container singleton violated")
-
-                if orionis is not orionis2:
-                    errors.append("Orionis singleton violated")
-
-                # Check bindings consistency
-                if not container2.bound(test_key):
-                    errors.append("Binding not consistent across instances")
-
-            except Exception as e:
-                errors.append(f"Exception in mixed operations: {e}")
-
-        # Run mixed operations in multiple threads
-        threads = []
-        for _ in range(50):
-            t = threading.Thread(target=mixed_operations)
-            threads.append(t)
-
-        for t in threads:
-            t.start()
-
-        for t in threads:
-            t.join()
-
-        # Assert no errors occurred
-        self.assertEqual(len(errors), 0, f"Errors found: {errors[:5]}")
-
-    async def testMemoryConsistency(self) -> None:
-        """
-        Test memory consistency across threads.
-
-        This test verifies that changes made in one thread
-        are visible in other threads due to singleton behavior.
-        """
-        results = []
-
-        def thread_a():
-            """Thread A - modifies the container."""
-            container = Container()
-            container.callable("thread_a_marker", lambda: "from_thread_a")
-            results.append("A_completed")
-
-        def thread_b():
-            """Thread B - reads from the container."""
-            # Small delay to ensure thread A runs first
-            time.sleep(0.01)
-            container = Container()
-            has_marker = container.bound("thread_a_marker")
-            results.append(f"B_sees_marker: {has_marker}")
-
-        t1 = threading.Thread(target=thread_a)
-        t2 = threading.Thread(target=thread_b)
-
-        t1.start()
-        t2.start()
-
-        t1.join()
-        t2.join()
-
-        # Verify that thread B saw the changes made by thread A
-        a_completed = "A_completed" in results
-        b_saw_marker = any("B_sees_marker: True" in r for r in results)
-
-        self.assertTrue(a_completed, "Thread A should have completed")
-        self.assertTrue(b_saw_marker, "Thread B should see Thread A's changes")

tests/container/validators/test_implements.py

@@ -4,20 +4,25 @@ from orionis.container.validators.implements import ImplementsAbstractMethods
 from orionis.container.exceptions.exception import OrionisContainerException
 
 class TestImplementsAbstractMethods(AsyncTestCase):
-    """
-    Test cases for the ImplementsAbstractMethods validator in orionis.container.validators.implements.
-
-    Notes
-    -----
-    This test suite validates the functionality of the ImplementsAbstractMethods validator
-    which ensures that concrete classes correctly implement abstract methods.
-    """
 
     async def asyncSetUp(self) -> None:
         """
-        Set up test fixtures.
+        Set up test fixtures for ImplementsAbstractMethods validator tests.
+
+        This method defines several abstract and concrete classes to be used in the test cases:
+        - An abstract base class with two abstract methods.
+        - A concrete class that correctly implements all abstract methods.
+        - A concrete class that does not implement all abstract methods.
+        - A non-abstract base class for negative test cases.
+
+        The defined classes are assigned to instance attributes for use in subsequent tests.
+
+        Returns
+        -------
+        None
+            This method does not return any value.
         """
-        # Define abstract classes for testing
+        # Define an abstract base class with two abstract methods
         class AbstractBase(ABC):
             @abstractmethod
             def abstract_method(self) -> None:
@@ -27,6 +32,7 @@ class TestImplementsAbstractMethods(AsyncTestCase):
             def another_abstract_method(self) -> str:
                 pass
 
+        # Concrete class that implements all abstract methods
         class ConcreteCorrect(AbstractBase):
             def abstract_method(self) -> None:
                 pass
@@ -34,14 +40,17 @@ class TestImplementsAbstractMethods(AsyncTestCase):
             def another_abstract_method(self) -> str:
                 return "implemented"
 
+        # Concrete class that does not implement all abstract methods
         class ConcreteIncomplete(AbstractBase):
             def abstract_method(self) -> None:
                 pass
 
+        # Non-abstract base class for negative test cases
         class NonAbstractBase:
             def regular_method(self) -> None:
                 pass
 
+        # Assign classes to instance attributes for use in tests
         self.AbstractBase = AbstractBase
         self.ConcreteCorrect = ConcreteCorrect
         self.ConcreteIncomplete = ConcreteIncomplete
@@ -50,6 +59,11 @@ class TestImplementsAbstractMethods(AsyncTestCase):
     async def testValidImplementation(self) -> None:
         """
         Test that validation passes when all abstract methods are implemented.
+
+        Returns
+        -------
+        None
+            This method does not return any value.
         """
         # Test with class
         ImplementsAbstractMethods(
@@ -67,8 +81,13 @@ class TestImplementsAbstractMethods(AsyncTestCase):
     async def testIncompleteImplementation(self) -> None:
         """
         Test that validation fails when not all abstract methods are implemented.
+
+        Returns
+        -------
+        None
+            This method does not return any value.
         """
-        # Test with class
+        # Test with class missing an abstract method
         with self.assertRaises(OrionisContainerException) as context:
             ImplementsAbstractMethods(
                 abstract=self.AbstractBase,
@@ -78,7 +97,7 @@ class TestImplementsAbstractMethods(AsyncTestCase):
         self.assertIn("does not implement the following abstract methods", str(context.exception))
         self.assertIn("another_abstract_method", str(context.exception))
 
-        # Test with instance
+        # Test with instance missing an abstract method
         with self.assertRaises(TypeError):
             ImplementsAbstractMethods(
                 abstract=self.AbstractBase,
@@ -88,7 +107,13 @@ class TestImplementsAbstractMethods(AsyncTestCase):
     async def testMissingAbstractClass(self) -> None:
         """
         Test that validation fails when no abstract class is provided.
+
+        Returns
+        -------
+        None
+            This method does not return any value.
         """
+        # Should raise exception if abstract class is not provided
         with self.assertRaises(OrionisContainerException) as context:
             ImplementsAbstractMethods(
                 concrete=self.ConcreteCorrect
@@ -99,7 +124,13 @@ class TestImplementsAbstractMethods(AsyncTestCase):
     async def testMissingConcreteImplementation(self) -> None:
         """
         Test that validation fails when neither concrete class nor instance is provided.
+
+        Returns
+        -------
+        None
+            This method does not return any value.
         """
+        # Should raise exception if neither concrete nor instance is provided
         with self.assertRaises(OrionisContainerException) as context:
             ImplementsAbstractMethods(
                 abstract=self.AbstractBase
@@ -110,7 +141,13 @@ class TestImplementsAbstractMethods(AsyncTestCase):
     async def testNonAbstractClass(self) -> None:
         """
         Test that validation fails when the provided abstract class has no abstract methods.
+
+        Returns
+        -------
+        None
+            This method does not return any value.
         """
+        # Should raise exception if abstract class does not define any abstract methods
         with self.assertRaises(OrionisContainerException) as context:
             ImplementsAbstractMethods(
                 abstract=self.NonAbstractBase,
@@ -122,13 +159,22 @@ class TestImplementsAbstractMethods(AsyncTestCase):
     async def testRenamedAbstractMethods(self) -> None:
         """
         Test handling of renamed abstract methods with class name prefixes.
+
+        This test verifies that the validator correctly handles cases where abstract methods
+        are renamed with class name prefixes in the concrete implementation.
+
+        Returns
+        -------
+        None
+            This method does not return any value.
         """
-        # Define classes with renamed methods
+        # Define an abstract class with a prefixed abstract method
         class AbstractWithPrefix(ABC):
             @abstractmethod
             def _AbstractWithPrefix_method(self) -> None:
                 pass
 
+        # Concrete class with a similarly prefixed method
         class ConcreteWithPrefix:
             def _ConcreteWithPrefix_method(self) -> None:
                 pass