pysorting ========= .. py:module:: pysorting Submodules ---------- .. toctree:: :maxdepth: 1 /autoapi/pysorting/bubblesort/index /autoapi/pysorting/insertionsort/index /autoapi/pysorting/quicksort/index /autoapi/pysorting/shellsort/index /autoapi/pysorting/utils/index Attributes ---------- .. autoapisummary:: pysorting.__version__ pysorting.__version__ Exceptions ---------- .. autoapisummary:: pysorting.InvalidElementTypeError pysorting.NonUniformTypeError pysorting.InvalidAscendingTypeError Functions --------- .. autoapisummary:: pysorting.bubble_sort pysorting.quick_sort pysorting.shell_sort pysorting.insertion_sort pysorting.find_fastest_sorting_function pysorting.sorting_time pysorting.is_sorted Package Contents ---------------- .. py:data:: __version__ .. py:function:: bubble_sort(arr, ascending=True) Sorts a list of numbers in ascending or descending order using the Bubble Sort algorithm. Bubble Sort repeatedly compares adjacent elements in the list and swaps them if they are in the wrong order. This process is repeated until the list is fully sorted. The sorting order can be controlled using the `ascending` parameter. Parameters: ---------- arr : list The list of numeric values to be sorted. ascending : bool, optional If `True` (default), sorts the list in ascending order. If `False`, sorts the list in descending order. Returns: ------- list The sorted list in ascending order if `ascending=True`, or in descending order if `ascending=False`. Raises: ------ TypeError If the input is not a list. InvalidElementTypeError If the list contains non-numeric elementsor string values. NonUniformTypeError If the list contains more than one form of data type Notes: ----- - Bubble Sort is a simple sorting algorithm with a time complexity of O(n^2) for average and worst cases. - This algorithm is inefficient for large datasets but can be used for educational purposes or small lists. - Sorting in descending order is achieved by reversing the comparison logic during the sorting process. Examples: -------- Sorting in ascending order (default): >>> bubble_sort([4, 2, 7, 1, 3]) [1, 2, 3, 4, 7] Sorting in descending order: >>> bubble_sort([4, 2, 7, 1, 3], ascending=False) [7, 4, 3, 2, 1] .. py:function:: quick_sort(arr, ascending=True) Sorts a list of numbers in ascending or descending order using the Quick Sort algorithm. Quicksort is a divide-and-conquer algorithm that selects a "pivot" element and partitions the array into two sub-arrays: one with elements smaller than the pivot and one with elements greater than the pivot. It recursively sorts the sub-arrays and combines them into a sorted array. The sorting order can be controlled with the ascending parameter. Parameters: ---------- arr : list The list of numeric values to be sorted. ascending : bool, optional If `True` (default), sorts the list in ascending order. If `False`, sorts the list in descending order. Returns: ------- list The sorted array in ascending order if `reverse=False`, or in descending order if `reverse=True`. Raises: ------ TypeError If the input is not a list. InvalidElementTypeError If the list contains non-comparable elements. NonUniformTypeError If the list contains more than one form of data type. Notes: ----- - This function operates in-place, modifying the input `arr` directly. - The average time complexity is O(n log n), while the worst-case complexity is O(n^2), which occurs when the pivot selection results in highly unbalanced partitions. - Sorting in descending order is achieved by reversing the comparison logic during partitioning. Examples: -------- Sorting in ascending order (default): >>> quick_sort([4, 2, 7, 1, 3]) [1, 2, 3, 4, 7] Sorting in descending order: >>> quick_sort([4, 2, 7, 1, 3], ascending=False) [7, 4, 3, 2, 1] .. py:function:: shell_sort(arr: list[float], ascending: bool = True) -> list[float] Sorts an array using the Shell Sort algorithm. Shell Sort repeatedly compares elements separated by a specific gap and rearranges them in the correct order. The gap is reduced over iterations until it becomes 1, at which point the list is fully sorted. The sorting order can be controlled using the `ascending` parameter. :param arr: The array of numeric values to be sorted. :type arr: list[float] :param ascending: If `True` (default), sorts the array in ascending order. If `False`, sorts the array in descending order. :type ascending: bool, optional :returns: A sorted array in ascending order if `ascending=True`, or in descending order if `ascending=False`. :rtype: list[float] :raises TypeError: If the input is not a list. :raises InvalidElementTypeError: If the list contains non-numeric elements or string values. :raises NonUniformTypeError: If the list contains more than one form of data type. :raises InvalidAscendingTypeError: If the `ascending` parameter is not a boolean. .. rubric:: Notes - Shell Sort is an improvement over Bubble Sort and Insertion Sort, with a time complexity of O(n^2) in the worst case. - This algorithm is more efficient than Bubble Sort for larger datasets. .. rubric:: Examples Sorting in ascending order (default): >>> shell_sort([5, 2, 8, 3, 1]) [1, 2, 3, 5, 8] Sorting in descending order: >>> shell_sort([3.5, 1.2, 2.8, 0.5], ascending=False) [3.5, 2.8, 1.2, 0.5] .. py:function:: insertion_sort(arr, ascending=True) Sorts a list of numbers in ascending or descending order using the Insertion Sort algorithm. This function takes a single list as a parameter and performs insertion sorting using the following algorithm. It begins with the second item in the list and compares its value to the item immediately to its left. If the value is smaller, it swaps the two items. If the value is larger than the item to its left, or if the item is in the first position, the function stops. Otherwise, it continues comparing and swapping as needed. The process is repeated for each subsequent item in the list until all items have been checked. After completing the sorting process, the function returns the newly sorted array. Parameters: ---------- arr : list The list of numeric values to be sorted. ascending : bool, optional If `True` (default), sorts the list in ascending order. If `False`, sorts the list in descending order. Returns: ------- list The sorted list in ascending order if `ascending=True`, or in descending order if `ascending=False`. Raises: ------ TypeError If the input is not a list. InvalidElementTypeError If the list contains non-numeric elementsor string values. NonUniformTypeError If the list contains more than one form of data type Notes: ----- - Insertion Sort is a simple sorting algorithm with a time complexity of O(n^2) for average and worst cases. - This algorithm is inefficient for large datasets but can be used for educational purposes or small lists. - Sorting in descending order is achieved by reversing the comparison logic during the sorting process. Examples: -------- Sorting in ascending order (default): >>> insertion_sort([4, 2, 7, 1, 3]) [1, 2, 3, 4, 7] Sorting in descending order: >>> insertion_sort([4, 2, 7, 1, 3], ascending=False) [7, 4, 3, 2, 1] .. py:exception:: InvalidElementTypeError(message='All elements must be either a string or a list of strings.') Bases: :py:obj:`Exception` Custom exception raised when elements are not strings or lists of strings. .. py:attribute:: message :value: 'All elements must be either a string or a list of strings.' .. py:exception:: NonUniformTypeError(message='Elements are not of the same type.') Bases: :py:obj:`Exception` Custom exception raised when elements are not strings or lists of strings. .. py:attribute:: message :value: 'Elements are not of the same type.' .. py:exception:: InvalidAscendingTypeError(message="The parameter 'ascending' must be a boolean value.") Bases: :py:obj:`Exception` Custom exception raised when 'ascending' is not a boolean. .. py:attribute:: message :value: "The parameter 'ascending' must be a boolean value." .. py:function:: find_fastest_sorting_function(data, *sorting_functions) Finds the fastest sorting function based on execution time. Parameters: - sorting_functions: List of sorting functions to compare. - test_data: List to sort (same data will be passed to all functions). Returns: - A tuple (fastest_function, fastest_time). .. py:function:: sorting_time(sorting_function, data) Returns the time taken to sort a function. Parameters: - sorting_function: Sorting function to output the time taken to sort. - test_data: List to sort (same data will be passed to all functions). Returns: - A tuple (fastest_function, fastest_time). .. py:function:: is_sorted(lst, ascending=True) Checks if a list is sorted in ascending or descending order. Parameters: - lst (list): The list to check. - ascending (bool): If True, checks for ascending order; otherwise, descending. Returns: - bool: True if the list is sorted in the specified order, False otherwise. .. py:data:: __version__