Skip to content

Commit

Permalink
added package documentation:
Browse files Browse the repository at this point in the history 
-Shashank - sorting function implementation
-Nonso - runtime of sorting function & intro
-Marek - comparing sorting algos & intro
-Siddarth - checking list is sorted

-changed function comparison in util file
  • Loading branch information
@MarekB19
MarekB19 committed Jan 26, 2025
1 parent 1794439 commit 06a474a
Show file tree
Hide file tree
Showing 4 changed files with 226 additions and 15 deletions.
222 changes: 212 additions & 10 deletions docs/example.ipynb
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,28 +2,230 @@
"cells": [
{
"cell_type": "markdown",
"metadata": {},
"source": [
"# Example usage\n",
"\n",
"To use `pysorting` in a project:"
],
"metadata": {}
"\n",
"Picture this: you are on a project or building a pipeline, and come across a list or dataframe column that needs to be sorted. You want to find the most computationally efficient way to sort this array, but the data structure and algorithms class you took in university is years behind you. Don't know which sorting algorithm has the lowest time complexity for your specific use case? Pysorting has you covered! Our package contains all the main sorting function algortihms you might need right at your fingertip. Certain lists will be sorted quicker according to various algorithms, so import our package and start sorting away!\n",
"\n",
"Curious about which sorting function performs best, and looking for concrete methods to compare different algorithms?\n",
"Again, pysorting is here to help! We have a utlils function that lets you measure the speed of any sorting algorithm and give you the fastest for you specific use case. Want to skip the middle man, and looking to simply obtain the most efficient algorithm? Our package also lets you compare any two algorithms and will return the best one.\n",
"\n",
"In these tutorials we will show you how to call the different sorting functions attached to the package, as well as the utility functions included.\n"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Imports\n",
"First lets import all the functions we will need:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"import pysorting\n",
"from pysorting import (bubble_sort, quick_sort, insertion_sort, \n",
" shell_sort, sorting_time, find_fastest_sorting_function, \n",
" is_sorted)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Sorting Functions\n",
"\n",
"print(pysorting.__version__)"
"In this first part, we show an example on how to use one of our sorting functions. All functions follow the same convention, so this method is applicable to all sorting algorithms.\n",
"\n",
"In this example, we will be sorting a toy unsorted list:"
]
},
{
"cell_type": "code",
"execution_count": 1,
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"Done sorting the array in order.\n",
"[-69, -5, 1, 2, 3, 9, 34, 40]\n"
]
}
],
"outputs": [],
"metadata": {}
"source": [
"#first import the sorting function from the package\n",
"from pysorting import bubble_sort\n",
"\n",
"# Sample toy list\n",
"toy_list = [1, -5, 9, 40, 2, 3, -69, 34 ]\n",
"\n",
"#Call the function with the list and also specifying if you want the return in ascending or descending order\n",
"new_list = bubble_sort(toy_list, ascending=True)\n",
"\n",
"#Prints out the result\n",
"print(new_list)\n"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Getting the run time of a Sorting Function\n",
"\n",
"Here we show you how to get the runtime of a sorting algorithm.\n",
"\n",
"Generally, the methodology is to pass one of the sorting functions into the `sorting_time()` function. The output will be the time taken to sort the list"
]
},
{
"cell_type": "code",
"execution_count": 8,
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"Function 'quick_sort' executed in 0.000018 seconds.\n",
"Done sorting the array in order.\n",
"Function 'insertion_sort' executed in 0.000012 seconds.\n"
]
}
],
"source": [
"from pysorting import quick_sort, insertion_sort, sorting_time\n",
"\n",
"toy_list_2 = [3,2.5,1,4,-100, 5]\n",
"\n",
"\n",
"sort_time_quick = sorting_time(quick_sort, toy_list_2)\n"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"# Comparing Sorting algorithms\n",
"In our next test example, we want to compare two different sorting algorithms to see which performs best.\n",
"\n",
"The methodology is to pass both sorting functions, as well as the data we wish to use in comparing them into the `find_fastest_sorting_function()` function. The output will be a the name of the fastest algorithm, along with the time it took to sort the list."
]
},
{
"cell_type": "code",
"execution_count": 1,
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"Done sorting the array in order.\n",
"Function 'insertion_sort' executed in 0.000061 seconds.\n",
"Function 'shell_sort' executed in 0.000007 seconds.\n",
"╒════════════════╤═════════════╕\n",
"│ Function │ Time take │\n",
"╞════════════════╪═════════════╡\n",
"│ insertion_sort │ 6.10352e-05 │\n",
"├────────────────┼─────────────┤\n",
"│ shell_sort │ 6.9141e-06 │\n",
"╘════════════════╧═════════════╛\n",
"\n",
"\n",
"The fastest function for sorting the above array is shell_sort\n"
]
}
],
"source": [
"from pysorting import insertion_sort, shell_sort, find_fastest_sorting_function\n",
"\n",
"\n",
"list_compare = [1, 2, 3, 5, 6, 4, 7, 8, 9, 11, 12, 10, 13, 14, 15, 16, 18, 17, 19, 20, 21, 22, 23, 24, 25]\n",
"\n",
"\n",
"fastest_func, time_taken = find_fastest_sorting_function(list_compare, insertion_sort, shell_sort)\n",
"\n",
"\n",
"print(\"\\n\")\n",
"\n",
"print(f\"The fastest function for sorting the above array is {fastest_func.__name__}\")\n"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"# Checking that the list is properly sorted\n",
"\n",
"As our final use case, if you were to come across an overly long list to be sorted. You pass this list through a sorting algorithm, and now want some peace of mind that the returned list is in a proper order.\n",
"\n",
"The function below returns true if the list is indeed sorted in the proper order:"
]
},
{
"cell_type": "code",
"execution_count": 4,
"metadata": {},
"outputs": [
{
"data": {
"text/plain": [
"True"
]
},
"execution_count": 4,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"from pysorting import is_sorted\n",
"\n",
"sorted_list = [1,2,3,4,5,6,7,8,9]\n",
"\n",
"is_sorted(sorted_list, ascending=True)\n"
]
},
{
"cell_type": "code",
"execution_count": 5,
"metadata": {},
"outputs": [
{
"data": {
"text/plain": [
"False"
]
},
"execution_count": 5,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"unsorted_list = [1,3,2,4,5,6,7,8,9]\n",
"\n",
"is_sorted(unsorted_list,ascending=True)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"And thats it! Hopefully these functions help you in your future coding endeavours!"
]
}
],
"metadata": {
"kernelspec": {
"display_name": "Python 3",
"display_name": "pysorting",
"language": "python",
"name": "python3"
},
Expand All @@ -37,9 +239,9 @@
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.8.5"
"version": "3.9.21"
}
},
"nbformat": 4,
"nbformat_minor": 4
}
}
3 changes: 2 additions & 1 deletion pyproject.toml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,8 @@ license = "MIT"
readme = "README.md"

[tool.poetry.dependencies]
python = "^3.9"
python = ">=3.9, <3.11"
tabulate = "^0.9.0"


[tool.poetry.group.dev.dependencies]
Expand Down
10 changes: 9 additions & 1 deletion src/pysorting/utils.py
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
import time
from tabulate import tabulate


class InvalidElementTypeError(Exception):
Expand Down Expand Up @@ -65,7 +66,7 @@ def sorting_time(sorting_function, data):
return elapsed_time


def find_fastest_sorting_function(sorting_functions, data):
def find_fastest_sorting_function(data, *sorting_functions):
"""
Finds the fastest sorting function based on execution time.
Expand All @@ -88,6 +89,13 @@ def find_fastest_sorting_function(sorting_functions, data):

# Find the function with the minimum elapsed time
fastest_function, fastest_time = min(results, key=lambda x: x[1])

list_dict = {
"Function": [x[0].__name__ for x in results],
"Time take": [f"{x[1]:.10f}" for x in results],
}
print(tabulate(list_dict, headers="keys", tablefmt="fancy_grid"))

return fastest_function, fastest_time


Expand Down
6 changes: 3 additions & 3 deletions tests/test_utils.py
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
from pysorting import bubble_sort
from pysorting import bubble_sort, insertion_sort, shell_sort
from pysorting import find_fastest_sorting_function, sorting_time, is_sorted


Expand All @@ -12,8 +12,8 @@ def test_sorting_time():
# Test find_fastest_sorting_function
def test_find_fastest_sorting_function():
data = [5, 3, 8, 6, 2, 7, 4, 1]
sorting_functions = [bubble_sort]
fastest_func, fastest_time = find_fastest_sorting_function(sorting_functions, data)
sorting_functions = [shell_sort, bubble_sort, insertion_sort]
fastest_func, fastest_time = find_fastest_sorting_function(data, *sorting_functions)

assert fastest_func in sorting_functions # Ensure the fastest function is valid
assert fastest_time > 0 # Ensure the time taken is positive
Expand Down

0 comments on commit 06a474a

Please sign in to comment.