docstring

src/core/app_config_object.py

@@ -8,7 +8,24 @@
 
 class AppConfigurationObject:
 
-    # Container pour la configuration de l'App
+    """
+    AppConfigurationObject is a class responsible for managing the application's configuration settings,
+    which are loaded from a YAML file. It handles parameters related to resizing modes and color schemes, 
+    ensuring the correct format and values are applied.
+
+    Key functionalities:
+    - Loads and validates the application configuration from the specified YAML file.
+    - Provides access to various configuration properties such as color schemes and resize modes.
+    - Allows switching between different resize modes (adjust and stretch).
+    - Saves updated configuration back to the YAML file.
+    - Supports loading and applying new color themes from external YAML files.
+
+    Attributes:
+    - config_file_path (str): The file path of the configuration file.
+    - random_name_length (int): The length of the random name to be generated.
+    - colors (ColorHelper): The color settings for the application.
+    - resize_mode (int): The current resize mode (0 for adjust, 1 for stretch).
+    """
 
     def __init__(self, config_fp: str) -> None:
 

src/core/assertion_helper.py

@@ -5,6 +5,20 @@
 
 class AssertionHelper:
 
+    """
+    AssertionHelper is a utility class that provides static methods for verifying file paths and extensions.
+    It helps ensure that file paths are valid and that files have the expected extension, raising assertions
+    if any condition is not met.
+
+    Methods:
+    - verify_filepath(fp: str): Verifies that the provided file path is a string and exists in the filesystem.
+    - verify_file_extension(fp: str, extension: str): Ensures the file at the given path has the specified file extension,
+    and that the file path itself is valid.
+
+    Raises:
+    - AssertionError: If the file path does not exist, is not a string, or if the file extension does not match.
+    """
+
     @staticmethod
     def verify_filepath(fp: str) -> None:
         assert isinstance(fp, str), f"[E] L'objet '{fp}' n'est pas du bon type (string). type={type(fp)}"

src/core/color_object.py

@@ -2,6 +2,29 @@
 
 class ColorHelper:
 
+    """
+    ColorHelper is a class designed to manage and provide access to various color configurations for the application.
+    It is initialized with a dictionary of color settings, and each color can be accessed through its respective property.
+
+    Attributes:
+    - background1_color (str): The primary background color.
+    - background2_color (str): The secondary background color.
+    - header_color (str): The color for headers.
+    - footer_color (str): The color for footers.
+    - frame1_color (str): The color for the first frame.
+    - frame2_color (str): The color for the second frame.
+    - frame3_color (str): The color for the third frame.
+    - border_color (str): The color for borders.
+    - button1_color (str): The primary button color.
+    - button2_color (str): The secondary button color.
+    - text1_color (str): The primary text color.
+    - text2_color (str): The secondary text color.
+    - positive_color (str): The color used for positive actions or indicators.
+    - negative_color (str): The color used for negative actions or indicators.
+    - unusable_button_color (str): The color for disabled or unusable buttons.
+    - placeholder_color (str): The color for placeholder text or elements.
+    """
+
     def __init__(self, color_config: dict) -> None:
 
         self._background1_color: str = color_config['background1_color']

src/core/file_objects.py

@@ -12,7 +12,29 @@
 
 class FileObject:
 
-    # File object meant to be opened by App.
+    """
+    FileObject is a base class for representing and managing a file within the application.
+    It provides methods for validating file paths and retrieving metadata such as the file name, size, and timestamps
+    for when the file was last accessed or modified.
+
+    Methods:
+    - set_new_path(new_fp: str): Sets a new file path after verifying its validity.
+    - get_file_data(): Returns a dictionary containing metadata such as the file's path, name, size, last opened, and last modified times.
+    - close(): Placeholder method, can be extended in subclasses for resource management.
+
+    Properties:
+    - path (str): Returns the full file path.
+    - dirname (str): Returns the directory of the file.
+    - filename (str): Returns the name of the file.
+    - extension (str): Returns the file's extension (e.g., .txt, .png).
+    - filesize (int): Returns the size of the file in bytes.
+    - last_opened (str): Returns a string representing the last time the file was accessed.
+    - last_modified (str): Returns a string representing the last time the file was modified.
+
+    Raises:
+    - AssertionError: If the file path is invalid or the file does not exist.
+    """
+
     def __init__(self, fp: str) -> None:
         AssertionHelper.verify_filepath(fp=fp)
         self._fp: str = fp
@@ -65,6 +87,20 @@ def close(self) -> None:
 
 class ImageObject(FileObject):
 
+    """
+    ImageObject is a subclass of FileObject, specifically designed to handle image files.
+    In addition to the basic file operations provided by FileObject, ImageObject adds functionality to retrieve image dimensions.
+
+    Methods:
+    - get_file_data(): Returns a dictionary containing the file's metadata and the dimensions of the image.
+
+    Properties:
+    - dimension (tuple): Returns the width and height of the image as a tuple (width, height). If the dimensions cannot be retrieved, it returns None.
+
+    Raises:
+    - Exception: If there is an issue when trying to open the image to retrieve its dimensions.
+    """
+
     def __init__(self, fp: str) -> None:
         super().__init__(fp)
 
@@ -86,6 +122,25 @@ def get_file_data(self) -> dict:
 
 class VideoObject(FileObject):
 
+    """
+    VideoObject is a subclass of FileObject, specifically designed to handle video files.
+    It includes functionality for loading video files, replaying videos, retrieving the current frame, and obtaining the video's dimensions and duration.
+
+    Methods:
+    - load_video_cap(): Loads the video file into a cv2.VideoCapture object for further operations.
+    - replay_video(): Resets the video to the beginning for replaying.
+    - get_current_frame(): Retrieves the current frame of the video as a PIL Image object. If the end of the video is reached, it automatically replays.
+    - close_video_cap(): Closes and releases the cv2.VideoCapture object.
+    - get_file_data(): Returns a dictionary containing the file's metadata, video dimensions, and video duration.
+
+    Properties:
+    - dimension (tuple): Returns the video's width and height as a tuple (width, height).
+    - duration (int): Returns the duration of the video in seconds.
+
+    Raises:
+    - AssertionError: If the file path is invalid or the file does not exist.
+    """
+
     def __init__(self, fp: str) -> None:
 
         super().__init__(fp)

src/core/queue.py

@@ -2,6 +2,26 @@
 
 class Queue:
 
+    """
+    Queue is a class that implements a basic queue data structure, allowing for typical queue operations such as enqueue, dequeue, and priority insertion.
+    It also provides methods to check if the queue is empty, retrieve the current size, and inspect the first element.
+
+    Methods:
+    - is_empty() -> bool: Returns True if the queue is empty, otherwise False.
+    - enqueue(obj: object) -> None: Adds an object to the end of the queue.
+    - dequeue() -> object: Removes and returns the first object from the queue. Returns None if the queue is empty.
+    - enqueue_max_priority(obj: object) -> None: Adds an object to the front of the queue (priority insertion).
+    - remove(obj: object) -> None: Removes the specified object from the queue, if it exists.
+    - top() -> object: Returns the first object in the queue without removing it.
+
+    Properties:
+    - size (int): Returns the current size of the queue.
+    - values (list): Returns the list of objects currently in the queue.
+
+    Raises:
+    - None. The methods handle queue underflow internally by checking if the queue is empty.
+    """
+
     def __init__(self, init_values: list[object]) -> None:
 
         self._values: list = init_values if init_values else []

src/core/sorting_task.py

@@ -7,6 +7,34 @@
 
 class SortingTask:
 
+    """
+    SortingTask is a class designed to manage and organize a collection of files for sorting tasks. 
+    It utilizes a Queue to hold files that need to be sorted and a Stack to keep track of files that have already been reviewed. 
+    Additionally, it supports custom categorization for sorting.
+
+    Attributes:
+    - files (Queue): A queue that holds files pending sorting.
+    - reviewed_files (Stack): A stack that contains files that have been reviewed.
+    - custom_categories (list): A list of custom categories for sorting files.
+    - path (str | None): The path associated with the sorting task.
+    - init_file_count (int | None): The initial count of files to be sorted.
+
+    Methods:
+    - is_empty() -> bool: Returns True if there are no files to sort, otherwise False.
+    - file_enqueue(file: FileObject) -> None: Adds a file to the queue for sorting.
+    - file_dequeue() -> FileObject: Removes the next file from the queue and pushes it onto the reviewed files stack.
+    - get_current_file() -> FileObject: Returns the file currently at the front of the queue without removing it.
+    - get_most_recent_reviewed_file() -> FileObject: Returns the most recently reviewed file from the stack without removing it.
+    - restore_previous_reviewed_file() -> None: Restores the most recently reviewed file back to the front of the queue.
+    - get_custom_categories(sort_by_name: bool = True) -> list: Returns the list of custom categories, sorted by name if specified.
+    - add_custom_categories(*new_categories: dict) -> None: Adds new custom categories to the existing list.
+    - remove_custom_category(target: dict) -> None: Removes a specified custom category from the list.
+    - clear_custom_categories() -> None: Clears all custom categories from the list.
+
+    Raises:
+    - AssertionError: If a new category added is not a dictionary.
+    """
+
     def __init__(self,
             files: list[FileObject] | None = None,
             reviewed_files: list[FileObject] | None = None,

src/core/stack.py

@@ -2,6 +2,26 @@
 
 class Stack:
 
+    """
+    Stack is a class that implements a basic stack data structure, allowing for standard stack operations such as push, pop, and priority insertion.
+    It provides methods to check if the stack is empty, retrieve the current size, and inspect the top element.
+
+    Methods:
+    - is_empty() -> bool: Returns True if the stack is empty, otherwise False.
+    - push(obj: object) -> None: Adds an object to the top of the stack.
+    - pop() -> object: Removes and returns the top object from the stack. Returns None if the stack is empty.
+    - push_lowest_priority(obj: object) -> None: Adds an object to the bottom of the stack (lowest priority).
+    - remove(obj: object) -> None: Removes the specified object from the stack, if it exists.
+    - top() -> object: Returns the top object in the stack without removing it.
+
+    Properties:
+    - size (int): Returns the current size of the stack.
+    - values (list): Returns the list of objects currently in the stack.
+
+    Raises:
+    - None. The methods handle stack underflow internally by checking if the stack is empty.
+    """
+
     def __init__(self, init_values: list[object]) -> None:
 
         self._values: list = init_values if init_values else []

src/gui/subgui/custom_category_gui.py

@@ -12,6 +12,31 @@
 
 class CustomCategoryGUI:
 
+    """
+    A graphical user interface for creating custom categories in a sorting task.
+
+    Attributes:
+    - root (tk.Tk): The main application window.
+    - _sorting_task (SortingTask): The sorting task to which custom categories will be added.
+    - _app_config (AppConfigurationObject): The application configuration object.
+    - _target_directory (str): The directory selected for the custom category.
+    - has_created_category (bool): Indicates whether a category has been created.
+
+    Methods:
+    - __init__(root: tk.Tk, sorting_task: SortingTask, app_config: AppConfigurationObject): Initializes the GUI and prompts the user to select a target directory.
+    - ask_directory() -> None: Prompts the user to select a directory.
+    - init_GUI() -> None: Initializes the GUI components for creating a custom category.
+    - create_category() -> None: Creates a custom category based on user input.
+    - on_enter(event: tk.Event) -> None: Handles the Enter key event to create a category.
+    - on_escape(event: tk.Event) -> None: Handles the Escape key event to close the category window.
+
+    Properties:
+    - sorting_task: Returns the sorting task associated with the GUI.
+    - app_config: Returns the application configuration.
+    - target_directory: Returns the target directory for the custom category.
+    - set_target_directory(new_dir: str) -> None: Sets the target directory and verifies its validity.
+    """
+
     def __init__(self, root: tk.Tk, sorting_task: SortingTask, app_config: AppConfigurationObject) -> None:
 
         self.root: tk.Tk = root

src/gui/subgui/favorite_crawler_gui.py

@@ -1,22 +1,48 @@
 
-
-
-
 from src.scripts.favorite_manager import FavoriteManager
 from src.core.app_config_object import AppConfigurationObject
 from src.core.assertion_helper import AssertionHelper
 
 import tkinter as tk
 from tkinter import filedialog
-
 import os
 
 
 
-
-
 class FavoriteCrawlerGUI:
 
+    """
+    A graphical user interface for selecting source and destination directories to 
+    copy favorite files marked with a specific symbol.
+
+    Attributes:
+    - root (tk.Tk): The main application window.
+    - _app_config (AppConfigurationObject): The application configuration object.
+    - _target_directory (tk.StringVar): The source directory for favorite files.
+    - _direction_folder (tk.StringVar): The destination directory for copying files.
+    - _create_subdir (tk.BooleanVar): A flag indicating whether to create subdirectories.
+    - _favorite_mark (str): The marker used to identify favorite files.
+
+    Methods:
+    - __init__(root: tk.Tk, app_config: AppConfigurationObject, favorite_mark: str = '[★]'): Initializes the GUI and sets default values.
+    - init_GUI() -> None: Initializes and configures the GUI components for the favorite file crawler.
+    - ask_target_directory() -> None: Prompts the user to select a source directory.
+    - ask_destination_directory() -> None: Prompts the user to select a destination directory.
+    - on_quit() -> None: Closes the favorite crawler window.
+    - on_confirm() -> None: Confirms the selected directories, verifies them, and copies favorite files.
+    - on_enter(event: tk.Event) -> None: Handles the Enter key event to confirm selections.
+    - on_escape(event: tk.Event) -> None: Handles the Escape key event to close the window.
+
+    Properties:
+    - app_config: Returns the application configuration object.
+    - target_directory: Returns the selected source directory.
+    - direction_folder: Returns the selected destination directory.
+    - create_subdir: Returns whether to create subdirectories.
+    - favorite_mark: Returns the favorite file marker.
+    - set_target_directory(new_dir: str) -> None: Sets the target directory for favorite files.
+    - set_direction_directory(new_dir: str) -> None: Sets the destination directory for copied files.
+    - set_create_subdir(boolvar: bool) -> None: Sets the flag for creating subdirectories.
+    """
 
     def __init__(self, root: tk.Tk, app_config: AppConfigurationObject, favorite_mark: str = '[★]') -> None:
 

src/gui/subgui/name_changer_gui.py

@@ -10,6 +10,28 @@
 
 class NameChangerGUI:
 
+    """
+    A graphical user interface for changing the names of files in a sorting task.
+
+    Attributes:
+    - root (tk.Tk): The main application window.
+    - _sorting_task (SortingTask): The current sorting task containing files to rename.
+    - _app_config (AppConfigurationObject): The application configuration object.
+    - has_changed_name (bool): Flag indicating whether the file name has been changed.
+
+    Methods:
+    - __init__(root: tk.Tk, sorting_task: SortingTask, app_config: AppConfigurationObject): Initializes the GUI and sets up the window and components.
+    - init_GUI() -> None: Initializes and configures the GUI components for renaming files.
+    - rename_file() -> None: Renames the selected file to the new name provided by the user.
+    - rename_file_random() -> None: Renames the selected file to a random name of specified length.
+    - on_enter(event: tk.Event) -> None: Handles the Enter key event to confirm the renaming of the file.
+    - on_escape(event: tk.Event) -> None: Closes the name change window.
+
+    Properties:
+    - sorting_task: Returns the current sorting task.
+    - app_config: Returns the application configuration object.
+    """
+
     def __init__(self, root: tk.Tk, sorting_task: SortingTask, app_config: AppConfigurationObject) -> None:
 
         self.root: tk.Tk = root

src/gui/subgui/task_creation_gui.py

@@ -14,6 +14,31 @@
 
 class TaskCreationGUI:
 
+    """
+    A graphical user interface for creating a sorting task with customizable file selection options.
+
+    Attributes:
+    - root (tk.Tk): The main application window.
+    - _app_config (AppConfigurationObject): The application configuration object.
+    - _supported_extensions_fp (str): The file path to the YAML file containing supported file extensions.
+    - _supported_extensions (dict[str: list[str]]): A dictionary of supported file extensions loaded from the YAML file.
+    - _sorting_task (SortingTask): The current sorting task created by the user.
+
+    Methods:
+    - __init__(root: tk.Tk, app_config: AppConfigurationObject, supported_extensions_fp: str): Initializes the GUI and sets up the window and components.
+    - init_GUI() -> None: Initializes and configures the GUI components for creating a sorting task.
+    - select_filesource_folder() -> None: Opens a dialog to select the folder containing files to sort.
+    - confirm_task_creation() -> None: Creates a new sorting task with the specified options and closes the window.
+    - on_enter(event: tk.Event) -> None: Handles the Enter key event to confirm the task creation.
+    - on_escape(event: tk.Event) -> None: Closes the task creation window.
+
+    Properties:
+    - app_config: Returns the application configuration object.
+    - supported_extensions: Returns a dictionary of supported file extensions.
+    - supported_extensions_filepath: Returns the file path of the supported extensions YAML file.
+    - sorting_task: Returns the currently created sorting task.
+    """
+
     def __init__(self, root: tk.Tk, app_config: AppConfigurationObject, supported_extensions_fp: str) -> None:
 
         self.root: tk.Tk = root