Added the docstrings.

Author: SohamTilekar

vidiopy/video/ImageSequenceClip.py

@@ -1,14 +1,34 @@
 import os
 import math
 from pathlib import Path
-from typing import Callable, Self, Any
+from typing import Callable
 from PIL import Image
 import numpy as np
 from ..decorators import *
 from .VideoClip import VideoClip
 
 
 class ImageSequenceClip(VideoClip):
+    """
+    A class used to represent a sequence of images as a video clip.
+
+    This class extends the VideoClip class and provides additional functionality for handling sequences of images. It allows for the creation of a video clip from a sequence of images, with the ability to specify the frames per second (fps) and duration of the clip. The sequence of images can be provided as a tuple of PIL Images, paths to images, numpy arrays, or a path to a directory. The class also provides methods for importing the image sequence, generating a numpy array or PIL Image representation of a specific frame in the clip, and applying a function to each frame of the clip.
+
+    Attributes:
+        clip (tuple[Image.Image, ...]): The sequence of images as a tuple of PIL Images.
+        fps (int | float | None): The frames per second of the clip.
+        _dur (int | float | None): The duration of the clip in seconds.
+        audio (optional): The audio of the clip.
+
+    Methods:
+        __init__(sequence, fps=None, duration=None, audio=None): Initializes an instance of the ImageSequenceClip class.
+        __eq__(other): Checks if this instance is equal to another instance.
+        _import_image_sequence(sequence): Imports an image sequence from a tuple of PIL Images, paths to images, numpy arrays, or a path to a directory.
+        make_frame_array(t): Generates a numpy array representation of a specific frame in the clip.
+        make_frame_pil(t): Generates a PIL Image representation of a specific frame in the clip.
+        fl_frame_transform(func, *args, **kwargs): Applies a function to each frame of the clip.
+        fl_clip_transform(func, *args, **kwargs): Applies a function to each frame of the clip along with its timestamp.
+    """
     def __init__(
         self,
         sequence: (
@@ -22,6 +42,28 @@ def __init__(
         duration: int | float | None = None,
         audio=None,
     ):
+        """
+        Initializes an instance of the ImageSequenceClip class.
+
+        This method imports an image sequence from the specified sequence, sets the fps and duration of the image sequence clip, and sets the audio of the image sequence clip if specified.
+
+        Args:
+            sequence (str | Path | tuple[Image.Image, ...] | tuple[np.ndarray, ...] | tuple[str | Path, ...]): The sequence to import. It can be a tuple of PIL Images, paths to images, numpy arrays, or a path to a directory.
+            fps (int | float | None, optional): The frames per second of the image sequence clip. If not specified, it is calculated from the duration and the number of images in the sequence.
+            duration (int | float | None, optional): The duration of the image sequence clip in seconds. If not specified, it is calculated from the fps and the number of images in the sequence.
+            audio (optional): The audio of the image sequence clip. If not specified, the image sequence clip will have no audio.
+
+        Raises:
+            ValueError: If neither fps nor duration is specified.
+            ValueError: If not all images in the sequence have the same size.
+
+        Example:
+            >>> image_sequence_clip = ImageSequenceClip(("image1.jpg", "image2.jpg"), fps=24)
+
+        Note:
+            This method uses the _import_image_sequence method to import the image sequence and the set_audio method to set the audio of the image sequence clip.
+        """
+        # method body goes here
         super().__init__()
 
         self.clip: tuple[Image.Image, ...] = self._import_image_sequence(sequence)
@@ -64,6 +106,27 @@ def _import_image_sequence(
             str | Path | tuple[str | Path] | tuple[Image.Image] | tuple[np.ndarray]
         ),
     ) -> tuple[Image.Image, ...]:
+        """
+        Imports an image sequence from a tuple of PIL Images, paths to images, numpy arrays, or a path to a directory.
+
+        This method checks the type of the sequence argument and imports the image sequence accordingly. If the sequence is a tuple of PIL Images, it returns the sequence as is. If the sequence is a tuple of numpy arrays, it converts each numpy array to a PIL Image. If the sequence is a tuple of paths to images, it opens each image and returns a tuple of PIL Images. If the sequence is a path to a directory, it opens all images in the directory and returns a tuple of PIL Images.
+
+        Args:
+            sequence (str | Path | tuple[str | Path] | tuple[Image.Image] | tuple[np.ndarray]): The sequence to import. It can be a tuple of PIL Images, paths to images, numpy arrays, or a path to a directory.
+
+        Returns:
+            tuple[Image.Image, ...]: The imported image sequence as a tuple of PIL Images.
+
+        Raises:
+            TypeError: If the sequence is not a tuple of PIL Images, paths to images, numpy arrays, or a path to a directory.
+
+        Example:
+            >>> image_sequence_clip = ImageSequenceClip()
+            >>> image_sequence = image_sequence_clip._import_image_sequence(("image1.jpg", "image2.jpg"))
+
+        Note:
+            This method uses the PIL Image class to open images and convert numpy arrays to images.
+        """
         if isinstance(sequence, tuple):
             if isinstance(sequence[0], Image.Image):
                 return sequence
@@ -92,14 +155,56 @@ def _import_image_sequence(
         )
 
     @requires_duration_or_end
-    def make_frame_array(self, t) -> np.ndarray:
+    def make_frame_array(self, t: int | float) -> np.ndarray:
+        """
+        Generates a numpy array representation of a specific frame in the image sequence clip.
+
+        This method calculates the index of the frame for a specific time, retrieves the frame from the image sequence clip, and converts it to a numpy array.
+
+        Args:
+            t (int | float): The time of the frame to convert.
+
+        Returns:
+            np.ndarray: The numpy array representation of the frame.
+
+        Raises:
+            None
+
+        Example:
+            >>> image_sequence_clip = ImageSequenceClip()
+            >>> frame_array = image_sequence_clip.make_frame_array(10)
+
+        Note:
+            This method uses the duration or end of the image sequence clip to calculate the time per frame.
+        """
         time_per_frame = (self.duration if self.duration else self.end) / len(self.clip)
         frame_index = math.floor(t / time_per_frame)
         frame_index = min(len(self.clip) - 1, max(0, frame_index))
         return np.array(self.clip[frame_index])
 
     @requires_duration_or_end
-    def make_frame_pil(self, t) -> Image.Image:
+    def make_frame_pil(self, t: int | float) -> Image.Image:
+        """
+        Generates a PIL Image representation of a specific frame in the image sequence clip.
+
+        This method calculates the index of the frame for a specific time, retrieves the frame from the image sequence clip, and returns it as a PIL Image.
+
+        Args:
+            t (int | float): The time of the frame to convert.
+
+        Returns:
+            Image.Image: The PIL Image representation of the frame.
+
+        Raises:
+            ValueError: If neither the duration nor the end of the image sequence clip is set.
+
+        Example:
+            >>> image_sequence_clip = ImageSequenceClip()
+            >>> frame_image = image_sequence_clip.make_frame_pil(10)
+
+        Note:
+            This method uses either the duration or the end of the image sequence clip to calculate the time per frame.
+        """
         if self.duration is None and self.end is None:
             raise ValueError("either duration or end must be set")
         time_per_frame = (self.duration if self.duration else self.end) / len(self.clip)
@@ -109,7 +214,30 @@ def make_frame_pil(self, t) -> Image.Image:
 
     def fl_frame_transform(
         self, func: Callable[..., Image.Image], *args, **kwargs
-    ) -> Self:
+    ) -> "ImageSequenceClip":
+        """
+        Applies a function to each frame of the image sequence clip.
+
+        This method iterates over each frame in the image sequence clip, applies a function to it, and replaces the original frame with the result. The function is expected to take a PIL Image as its first argument and return a PIL Image.
+
+        Args:
+            func (Callable[..., Image.Image]): The function to apply to each frame. It should take a PIL Image as its first argument and return a PIL Image.
+            *args: Additional positional arguments to pass to the function.
+            **kwargs: Additional keyword arguments to pass to the function.
+
+        Returns:
+            ImageSequenceClip: The current instance of the ImageSequenceClip class.
+
+        Raises:
+            None
+
+        Example:
+            >>> image_sequence_clip = ImageSequenceClip()
+            >>> image_sequence_clip.fl_frame_transform(lambda frame: frame.rotate(90))
+
+        Note:
+            This method modifies the current instance of the ImageSequenceClip class in-place.
+        """
         clip: list[Image.Image] = []
         for frame in self.clip:
             frame = func(frame, *args, **kwargs)
@@ -118,7 +246,32 @@ def fl_frame_transform(
         return self
 
     @requires_fps
-    def fl_clip_transform(self, func, *args, **kwargs):
+    def fl_clip_transform(
+        self, func: Callable[..., Image.Image], *args, **kwargs
+    ) -> "ImageSequenceClip":
+        """
+        Applies a function to each frame of the image sequence clip along with its timestamp.
+
+        This method iterates over each frame in the image sequence clip, applies a function to it and its timestamp, and replaces the original frame with the result. The function is expected to take a PIL Image and a float as its first two arguments and return a PIL Image.
+
+        Args:
+            func (Callable[..., Image.Image]): The function to apply to each frame. It should take a PIL Image and a float as its first two arguments and return a PIL Image.
+            *args: Additional positional arguments to pass to the function.
+            **kwargs: Additional keyword arguments to pass to the function.
+
+        Returns:
+            ImageSequenceClip: The current instance of the ImageSequenceClip class.
+
+        Raises:
+            ValueError: If the fps of the image sequence clip is not set.
+
+        Example:
+            >>> image_sequence_clip = ImageSequenceClip()
+            >>> image_sequence_clip.fl_clip_transform(lambda frame, t: frame.rotate(90 * t))
+
+        Note:
+            This method modifies the current instance of the ImageSequenceClip class in-place.
+        """
         td = 1 / self.fps
         frame_time = 0.0
         clip = []