docs: added docs and tests

cereja/utils/_utils.py

@@ -708,10 +708,31 @@ def combine_with_all(
 
 
 def value_from_memory(memory_id):
+    """
+    Retrieve the Python object stored at a specific memory address.
+
+    Args:
+    memory_id (int): The memory address of the object.
+
+    Returns:
+    object: The Python object stored at the given memory address.
+    """
     return ctypes.cast(memory_id, ctypes.py_object).value
 
 
 def combinations(iterable, size, is_sorted=False):
+    """
+    Generate all possible combinations of a certain size from an iterable.
+    The combinations are generated using the unique object IDs to ensure distinctness.
+
+    Args:
+    iterable (iterable): An iterable of Python objects.
+    size (int): The size of each combination.
+    is_sorted (bool, optional): If True, returns combinations in sorted order based on the values. Defaults to False.
+
+    Returns:
+    list of tuples: A list containing tuples of the combinations generated.
+    """
     pool = tuple(set(map(id, iterable)))
     n = len(pool)
     combinations_result = []
@@ -725,6 +746,18 @@ def combinations(iterable, size, is_sorted=False):
 
 
 def combinations_sizes(iterable, min_size, max_size, is_sorted=False):
+    """
+    Generate all possible combinations for all sizes within the specified range from an iterable.
+
+    Args:
+    iterable (iterable): An iterable of Python objects.
+    min_size (int): The minimum size of the combinations.
+    max_size (int): The maximum size of the combinations.
+    is_sorted (bool, optional): If True, each combination is sorted. Defaults to False.
+
+    Returns:
+    list of tuples: A list containing tuples of all combinations for sizes between min_size and max_size.
+    """
     res = []
     for n in range(min_size, max_size + 1):
         for i in combinations(iterable, size=n, is_sorted=is_sorted):

tests/testsutils.py

@@ -484,6 +484,39 @@ def test_get_batch_strides(self):
                     expected,
             )
 
+    def test_value_from_memory(self):
+        # Create a test object
+        test_object = "Hello, world!"
+        # Get the memory ID of the object
+        memory_id = id(test_object)
+        # Retrieve the object from memory
+        retrieved_object = utils.value_from_memory(memory_id)
+        # Check if the retrieved object is the same as the original
+        self.assertEqual(retrieved_object, test_object)
+
+    def test_combinations(self):
+        test_iterable = [1, 2, 3]
+        size = 2
+        expected_output = [(1, 2), (1, 3), (2, 3)]
+        actual_output = utils.combinations(test_iterable, size)
+        # Check if the output matches the expected combinations
+        self.assertListEqual(sorted(actual_output), sorted(expected_output))
+
+    def test_combinations_sizes(self):
+        test_iterable = [3, 2, 1, 4]
+        min_size = 2
+        max_size = 3
+        expected_output = [(1, 3), (2, 3), (3, 4), (1, 2), (1, 4), (2, 4), (1, 2, 3), (1, 3, 4), (2, 3, 4), (1, 2, 4)]
+        actual_output = utils.combinations_sizes(test_iterable, min_size, max_size, is_sorted=True)
+        # Check if the output includes all combinations for sizes in the given range
+        self.assertListEqual(actual_output, expected_output)
+
+        expected_output_unsorted = [(3, 1), (3, 2), (3, 4), (1, 2), (1, 4), (2, 4), (3, 1, 2), (3, 1, 4), (3, 2, 4),
+                                    (1, 2, 4)]
+        actual_output = utils.combinations_sizes(test_iterable, min_size, max_size, is_sorted=False)
+        # Check if the output includes all combinations for sizes in the given range
+        self.assertListEqual(actual_output, expected_output_unsorted)
+
 
 class CjTestTest(unittest.TestCase):
     def test_add_check(self):