pysorting

Submodules

Attributes

`__version__`
`__version__`

Exceptions

`InvalidElementTypeError`	Custom exception raised when elements are not strings or lists of strings.
`NonUniformTypeError`	Custom exception raised when elements are not strings or lists of strings.
`InvalidAscendingTypeError`	Custom exception raised when 'ascending' is not a boolean.

Functions

`bubble_sort`(arr[, ascending])	Sorts a list of numbers in ascending or descending order using the Bubble Sort algorithm.
`quick_sort`(arr[, ascending])	Sorts a list of numbers in ascending or descending order using the Quick Sort algorithm.
`shell_sort`(→ list[float])	Sorts an array using the Shell Sort algorithm.
`insertion_sort`(arr[, ascending])	Sorts a list of numbers in ascending or descending order using the Insertion Sort algorithm.
`find_fastest_sorting_function`(data, *sorting_functions)	Determines the fastest sorting function by measuring execution time.
`sorting_time`(sorting_function, data)	Measures the execution time of a given sorting function.
`is_sorted`(lst[, ascending])	Determines whether a list is sorted in ascending or descending order.

Package Contents

pysorting.__version__

pysorting.bubble_sort(arr, ascending=True)[source]

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:

arrlist: The list of numeric values to be sorted.
ascendingbool, 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]

pysorting.quick_sort(arr, ascending=True)[source]

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:

arrlist: The list of numeric values to be sorted.
ascendingbool, 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]

pysorting.shell_sort(arr: list[float], ascending: bool = True) → list[float][source]

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.

Parameters:

arr (list[float]) – The array of numeric values to be sorted.
ascending (bool, optional) – If True (default), sorts the array in ascending order. If False, sorts the array in descending order.

Returns:

A sorted array in ascending order if ascending=True, or in descending order if ascending=False.

Return type:

list[float]

Raises:

TypeError – If the input is not a list.
InvalidElementTypeError – If the list contains non-numeric elements or string values.
NonUniformTypeError – If the list contains more than one form of data type.
InvalidAscendingTypeError – If the ascending parameter is not a boolean.

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.

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]

pysorting.insertion_sort(arr, ascending=True)[source]

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:

arrlist: The list of numeric values to be sorted.
ascendingbool, 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]

exception pysorting.InvalidElementTypeError(message='All elements must be either a string or a list of strings.')[source]

Bases: Exception

Custom exception raised when elements are not strings or lists of strings.

message = 'All elements must be either a string or a list of strings.'

exception pysorting.NonUniformTypeError(message='Elements are not of the same type.')[source]

Bases: Exception

Custom exception raised when elements are not strings or lists of strings.

message = 'Elements are not of the same type.'

exception pysorting.InvalidAscendingTypeError(message="The parameter 'ascending' must be a boolean value.")[source]

Bases: Exception

Custom exception raised when ‘ascending’ is not a boolean.

message = "The parameter 'ascending' must be a boolean value."

pysorting.find_fastest_sorting_function(data, *sorting_functions)[source]

Determines the fastest sorting function by measuring execution time.

This function tests multiple sorting functions on the same dataset, measures their execution times, and identifies the fastest one. The execution times for all sorting functions are displayed in a formatted table.

Parameters:

datalist: The list of values to be sorted. A copy of this list is passed to each sorting function to ensure that the original data remains unmodified.
sorting_functionstuple of functions: A variable number of sorting functions to be tested. Each function should accept a list as input and return a sorted list.

Returns:

tuple: A tuple containing: - fastest_function (function): The sorting function with the shortest execution time. - fastest_time (float): The execution time (in seconds) of the fastest function.

Notes:

Each sorting function is wrapped using the timer decorator to measure execution time.
The execution times of all tested functions are displayed in a table format using tabulate.
The function automatically selects the sorting function with the minimum execution time.

Examples:

Comparing multiple sorting functions:

>>> test_data = [5, 2, 8, 1, 3]
>>> fastest_function, fastest_time = find_fastest_sorting_function(test_data, bubble_sort, quick_sort)
┏━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┓
┃ Function      ┃ Time taken (s)  ┃
┡━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━┩
├ bubble_sort   │ 0.0000253456    │
├ quick_sort    │ 0.0000024567    │
└───────────────┴────────────────┘
>>> print(f"The fastest function is {fastest_function.__name__} with a time of {fastest_time:.6f} seconds.")
The fastest function is quick_sort with a time of 0.000002 seconds.

pysorting.sorting_time(sorting_function, data)[source]

Measures the execution time of a given sorting function.

This function wraps the specified sorting function using the timer decorator to measure how long it takes to sort the provided dataset.

Parameters:

sorting_functionfunction: The sorting function whose execution time needs to be measured. It should accept a list as input and return a sorted list.
datalist: The list of values to be sorted. A copy of this list is passed to the sorting function to prevent modification of the original data.

Returns:

float: The execution time (in seconds) of the sorting function.

Notes:

The function uses the timer decorator to record execution time.
A copy of the input data is passed to the sorting function to avoid side effects.
Useful for benchmarking different sorting algorithms.

Examples:

Measuring the execution time of a sorting function:

>>> test_data = [5, 2, 8, 1, 3]
>>> sorting_time(quick_sort, test_data)
Function 'quick_sort' executed in 0.000002 seconds.
0.0000024567

pysorting.is_sorted(lst, ascending=True)[source]

Determines whether a list is sorted in ascending or descending order.

This function checks if the elements in the list are in non-decreasing (ascending) or non-increasing (descending) order, based on the ascending parameter.

Parameters:

lstlist: The list of elements to check. The function assumes the elements are comparable.
ascendingbool, optional: If True (default), checks whether the list is sorted in ascending order. If False, checks whether the list is sorted in descending order.

Returns:

bool: True if the list is sorted in the specified order, False otherwise.

Raises:

TypeError: If the list contains elements that cannot be compared.

Notes:

An empty list or a list with a single element is considered sorted.
The function performs a pairwise comparison to verify sorting order.

Examples:

Checking if a list is sorted in ascending order (default):

>>> is_sorted([1, 2, 3, 4, 5])
True

Checking if a list is sorted in descending order:

>>> is_sorted([5, 4, 3, 2, 1], ascending=False)
True

Checking an unsorted list:

>>> is_sorted([1, 3, 2, 4, 5])
False

pysorting.__version__