`create_batches` and `fill` docs added

docs/utils/iterables.md

@@ -0,0 +1,18 @@
+---
+comments: true
+status: new
+---
+
+# Iterables Utils
+
+<div class="md-typeset">
+  <h2>create_batches</h2>
+</div>
+
+:::supervision.utils.iterables.create_batches
+
+<div class="md-typeset">
+  <h2>fill</h2>
+</div>
+
+:::supervision.utils.iterables.fill

mkdocs.yml

@@ -65,6 +65,7 @@ nav:
     - Utils:
         - Video: utils/video.md
         - Image: utils/image.md
+        - Iterables: utils/iterables.md
         - Notebook: utils/notebook.md
         - File: utils/file.md
     - Assets: assets.md

supervision/utils/iterables.py

@@ -1,25 +1,33 @@
 from typing import Generator, Iterable, List, TypeVar
 
-SequenceElement = TypeVar("SequenceElement")
+V = TypeVar("V")
 
 
 def create_batches(
-    sequence: Iterable[SequenceElement], batch_size: int
-) -> Generator[List[SequenceElement], None, None]:
+        sequence: Iterable[V], batch_size: int
+) -> Generator[List[V], None, None]:
     """
-    Provides a generator that yields chunks of input sequence
-    of size specified by `batch_size` parameter. Last
-    chunk may be smaller batch.
+    Provides a generator that yields chunks of the input sequence
+    of the size specified by the `batch_size` parameter. The last
+    chunk may be a smaller batch.
 
     Args:
-        sequence (Iterable[SequenceElement]): Sequence to be
-            split into batches.
-        batch_size (int): Expected size of a batch
+        sequence (Iterable[V]): The sequence to be split into batches.
+        batch_size (int): The expected size of a batch.
 
     Returns:
-        Generator[List[SequenceElement], None, None]: Generator
-            to yield chinks of `sequence` of size `batch_size`,
-            up to the length of input `sequence`.
+        Generator[List[V], None, None]: A generator that yields chunks
+            of `sequence` of size `batch_size`, up to the length of
+            the input `sequence`.
+
+    Examples:
+        ```python
+        list(create_batches([1, 2, 3, 4, 5], 2))
+        # [[1, 2], [3, 4], [5]]
+
+        list(create_batches("abcde", 3))
+        # [['a', 'b', 'c'], ['d', 'e']]
+        ```
     """
     batch_size = max(batch_size, 1)
     current_batch = []
@@ -28,31 +36,35 @@ def create_batches(
             yield current_batch
             current_batch = []
         current_batch.append(element)
-    if len(current_batch) > 0:
+    if current_batch:
         yield current_batch
 
 
-def fill(
-    sequence: List[SequenceElement],
-    desired_size: int,
-    content: SequenceElement,
-) -> List[SequenceElement]:
+def fill(sequence: List[V], desired_size: int, content: V) -> List[V]:
     """
-    Fill the sequence with padding elements until sequence reaches
-    desired size.
+    Fill the sequence with padding elements until the sequence reaches
+    the desired size.
 
     Args:
-        sequence (List[SequenceElement]): Input sequence.
-        desired_size (int): Expected size of output list - difference
-            between this value and actual `sequence` length (if positive)
-            dictates how many elements will be added as padding.
-        content (SequenceElement): Element to be placed at the end of
-            input `sequence` as padding.
+        sequence (List[V]): The input sequence.
+        desired_size (int): The expected size of the output list. The
+            difference between this value and the actual length of `sequence`
+            (if positive) dictates how many elements will be added as padding.
+        content (V): The element to be placed at the end of the input
+            `sequence` as padding.
 
     Returns:
-        List[SequenceElement]: Padded version of input `sequence` (if needed)
+        List[V]: A padded version of the input `sequence` (if needed).
+
+    Examples:
+        ```python
+        fill([1, 2], 4, 0)
+        # [1, 2, 0, 0]
+
+        fill(['a', 'b'], 3, 'c')
+        # ['a', 'b', 'c']
+        ```
     """
     missing_size = max(0, desired_size - len(sequence))
-    required_padding = [content] * missing_size
-    sequence.extend(required_padding)
+    sequence.extend([content] * missing_size)
     return sequence