Merge branch 'main' into shell-sort-test

.github/workflows/ci-cd.yml

@@ -0,0 +1,95 @@
+name: ci-cd
+
+on: [push, pull_request]
+
+jobs:
+  ci:
+    # Set up operating system
+    runs-on: ubuntu-latest
+
+    # Define job steps
+    steps:
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.9"
+
+      - name: Check-out repository
+        uses: actions/checkout@v3
+
+      - name: Install poetry
+        uses: snok/install-poetry@v1
+
+      - name: Install package
+        run: poetry install
+
+      - name: Test with pytest
+        run: poetry run pytest tests/ --cov=pysorting --cov-report=xml
+
+      - name: Use Codecov to track coverage
+        uses: codecov/codecov-action@v5
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: ./coverage.xml   # coverage report
+
+      - name: Build documentation
+        run: poetry run make html --directory docs/
+
+  cd:
+    permissions:
+      id-token: write
+      contents: write
+
+    # Only run this job if the "ci" job passes
+    needs: ci
+
+    # Only run this job if new work is pushed to "main"
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+
+    # Set up operating system
+    runs-on: ubuntu-latest
+
+    # Define job steps
+    steps:
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.9"
+
+      - name: Check-out repository
+        uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+
+      - name: Use Python Semantic Release to prepare release
+        id: release
+        uses: python-semantic-release/[email protected]
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        if: steps.release.outputs.released == 'true'
+        with:
+          repository-url: https://test.pypi.org/legacy/
+          password: ${{ secrets.TEST_PYPI_API_TOKEN }}
+
+      - name: Test install from TestPyPI
+        if: steps.release.outputs.released == 'true'
+        run: |
+            pip install \
+            --index-url https://test.pypi.org/simple/ \
+            --extra-index-url https://pypi.org/simple \
+            pysorting
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        if: steps.release.outputs.released == 'true'
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}
+
+      - name: Publish package distributions to GitHub Releases
+        uses: python-semantic-release/upload-to-gh-release@main
+        if: steps.release.outputs.released == 'true'
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}

README.md

@@ -1,6 +1,55 @@
 # pysorting
 
-a package to aid user in implementing various sorting algorithms
+## Overview
+This Python package provides an interactive and educational platform for understanding popular sorting algorithms. Designed for students and educators, it includes implementations of four key sorting algorithms. The package is simple to use and highly customizable, making it an excellent tool for learning and teaching sorting concepts.
+
+
+## Contributors
+- Chukwunonso Ebele-muolokwu
+- Marek Boulerice
+- Shashank Hosahalli Shivamurthy
+- Siddarth Subrahmanian
+
+# Features
+- `bubble_sort`:
+  -This function takes in a list of numbers provided by the user and sorts it following a bubble-sort algorithm. A simple, comparison-based sorting algorithm that repeatedly swaps adjacent elements if they are in the wrong order.
+- `insertion_sort`:
+  -This function takes in a list of numbers provided by the user and sorts it following a insertion-sort algorithm. A straightforward algorithm that builds the sorted array one element at a time.
+- `quick_sort`:
+  -This function takes in a list of numbers provided by the user and sorts it following a quick-sort algorithm. Implements the divide-and-conquer sorting algorithm that partitions the array around a pivot element.
+- `shell_sort`:
+  -This function takes in a list of numbers provided by the user and sorts it following a shell-sort algorithm. A generalization of insertion sort that allows the exchange of far-apart elements to improve performance.
+
+## Time Complexity Measurement
+
+The library allows users to measure the time complexity of a specific sorting function. This helps in optimizing code by choosing the most suitable sorting algorithm for different use cases. For example
+
+- Bubble Sort is efficient for small datasets.
+- Insertion Sort performs well for iterables that are partially sorted.
+
+This feature ensures users can make informed decisions about algorithm selection based on their dataset characteristics.
+
+## Comparing Sorting Algorithms
+
+The library provides functionality to compare the performance of two or more sorting functions. By passing in a list, the function identifies and returns the fastest sorting algorithm for the given dataset. This is particularly useful for benchmarking and optimizing your code.
+
+## Checking if a list is sorted
+
+A convenient helper function is included to verify if a list is sorted. It takes a list as input and returns a boolean value:
+
+- True if the list is sorted.
+- False otherwise.
+
+This utility is handy for debugging and ensuring the correctness of sorting implementations.
+
+---
+
+The package was created with the goal to be a tool for aspiring computer and data scientists to use in order to better understand the steps, similiraities and differences of various sorting functions. With the current functions included, a user can easily pass an array and implement a sorting function of his choosing to return the sorted array. Further developments for this package will include a function to generate a random list of desired size for sorting, one function to compute the big-o complexity of a given sorting algortithm, and a visualization of the sorting process for a chosen algorithm.
+
+
+## `pysorting` in the Python Ecosystem
+There are many presences of similar sorting functions within the python ecosystem. For one, python itself already has a built in [`.sort()` function](https://docs.python.org/3/library/stdtypes.html#list.sort). There is also a [`sorted()` built-in function](https://docs.python.org/3/library/functions.html#sorted) that builds a new sorted list from an iterable.Additionally, several packages have also been created with similar goal of implementing various sorting algortithms. One example project is shown here: [https://pypi.org/project/sort-algorithms/](https://github.com/DahlitzFlorian/SortingAlgorithms)
+Our package aims to distinguish itself from other packages through its easy access to auxiliary tools making it easy to implement various sorting algorithm, and importantly to highlight differences between them.  
 
 ## Installation
 
@@ -9,12 +58,17 @@ $ pip install pysorting
 ```
 
 ## Usage
+The following examples illustrate how the sorting functions in this package are intended to be used. Please note that the functions are currently not implemented—only their docstrings are in place for now.
 
-- TODO
+After installing the package, you can import the functions (once implemented) as follows:
+
+```python
+from pysorting import quick_sort, bubble_sort, shell_sort, insertion_sort
+```
 
 ## Contributing
 
-Interested in contributing? Check out the contributing guidelines. Please note that this project is released with a Code of Conduct. By contributing to this project, you agree to abide by its terms.
+Interested in contributing? Check out the [contributing guidelines](https://github.com/UBC-MDS/pysorting/blob/main/CONTRIBUTING.md). Please note that this project is released with a Code of Conduct. By contributing to this project, you agree to abide by its terms.
 
 ## License
 

src/pysorting/__init__.py

@@ -3,4 +3,3 @@
 from .shell_sort import shell_sort
 
 __version__ = version("pysorting")
-

src/pysorting/bubble.py

@@ -0,0 +1,37 @@
+"""This module implements the bubble sort algorithm in python.Bubble sort is a basic algorithm
+that sorts a list of data by comparing adjacent elements and swapping them if they are out of order
+@author: Nonso Ebele-Muolokwu
+"""
+
+# import numpy as np
+
+
+def bubble_sort(arr):
+    """
+    Sorts a list of numbers in ascending order using the Bubble Sort algorithm.
+
+    Parameters
+    ----------
+    arr : list
+        A list of numeric values to be sorted.
+
+    Returns
+    -------
+    list
+        A sorted list in ascending order.
+
+    Raises
+    ------
+    TypeError
+        If the input is not a list.
+    ValueError
+        If the list contains non-numeric elements.
+
+    Examples
+    --------
+    >>> bubble_sort([4, 2, 7, 1, 3])
+    [1, 2, 3, 4, 7]
+
+    >>> bubble_sort([10, -3, 0, 5, 9])
+    [-3, 0, 5, 9, 10]
+    """

src/pysorting/insertion_sort.py

@@ -0,0 +1,35 @@
+# insertion_sort.py
+# author: Marek Boulerice
+# date: 2024-01-10
+
+def insertion_sort(unsorted[float]):
+    """
+    Performs insertion sorting algorithm on given list and returns new sorted list.
+
+    This function takes in a single list as a parameter. It performs insertion sorting via the following algorithm:
+        1. Begin with the second item in the list. 
+        2. Compare the value of the item with the value of the item to its immediate left. 
+        If the value is smaller than the item to its left, switch the position of the two items
+        3. If If the value is larger than the item to its left, or if the item is in the first position of the list, stop. Otherwise repeat step 2.
+        4. Repeat steps 2 and 3 for the next unchecked item, until all items have been checked
+    After completing insertion sorting, function will return the newly sorted array
+    
+    Parameters
+    ----------
+    unsorted : list[float]
+        a list of float values to be sorted
+
+    Returns
+    -------
+    list[float]
+        The list of sorted values.
+
+    Examples
+    ------
+    insertion_sort([8, 2, 12, 5, 1])
+    [1, 2, 5, 8, 12]
+
+    insertion_sort([0.1, 0, 12, 0, 100.01])
+    [0, 0, 0.1, 12, 100.01]
+    """
+    pass

src/pysorting/quicksort.py

@@ -0,0 +1,49 @@
+"""
+Quicksort Algorithm Implementation.
+This module provides an implementation of the Quicksort algorithm, a popular 
+sorting technique.
+Author: Shashank
+Date: 10 Jan, 2025
+"""
+def quick_sort(arr, reverse=False):
+    """
+    Sorts an array using the Quicksort 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 `reverse` parameter.
+
+    Parameters:
+    ----------
+    arr : list
+        The list of elements to be sorted. This can contain any comparable types.
+    reverse : bool, optional
+        If `True`, sorts the array in descending order. If `False` (default), sorts the array in ascending order.
+
+    Returns:
+    -------
+    list
+        The sorted array in ascending order if `reverse=False`, or in descending order if `reverse=True`.
+
+    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):
+    >>> arr = [4, 2, 7, 1, 3]
+    >>> quick_sort(arr)
+    [1, 2, 3, 4, 7]
+
+    Sorting in descending order:
+    >>> arr = [4, 2, 7, 1, 3]
+    >>> quick_sort(arr, reverse=True)
+    [7, 4, 3, 2, 1]
+    """
+    pass