gnome_sort : type hints, docstring, doctests

Author: grochedix

sorts/gnome_sort.py

@@ -1,25 +1,55 @@
-"""Gnome Sort Algorithm."""
+"""
+Gnome Sort Algorithm (A.K.A. Stupid Sort)
 
+This algorithm iterates over a list comparing an element with the previous one.
+If order is not respected, it swaps element backward until
+order is respected with previous element.
+It resumes the initial iteration from element new position.
 
-def gnome_sort(unsorted):
-    """Pure implementation of the gnome sort algorithm in Python."""
-    if len(unsorted) <= 1:
-        return unsorted
+For doctests run following command:
+python3 -m doctest -v gnome_sort.py
+
+For manual testing run:
+python3 gnome_sort.py
+"""
+
+
+def gnome_sort(lst: list) -> list:
+    """
+    Pure implementation of the gnome sort algorithm in Python
+
+    Take some mutable ordered collection with heterogeneous
+    comparable items inside as argument,
+    return the same collection ordered by ascending.
+
+    Examples:
+    >>> gnome_sort([0, 5, 3, 2, 2])
+    [0, 2, 2, 3, 5]
+
+    >>> gnome_sort([])
+    []
+
+    >>> gnome_sort([-2, -5, -45])
+    [-45, -5, -2]
+    """
+    if len(lst) <= 1:
+        return lst
 
     i = 1
 
-    while i < len(unsorted):
-        if unsorted[i - 1] <= unsorted[i]:
+    while i < len(lst):
+        if lst[i - 1] <= lst[i]:
             i += 1
         else:
-            unsorted[i - 1], unsorted[i] = unsorted[i], unsorted[i - 1]
+            lst[i - 1], lst[i] = lst[i], lst[i - 1]
             i -= 1
             if i == 0:
                 i = 1
 
+    return lst
+
 
 if __name__ == "__main__":
     user_input = input("Enter numbers separated by a comma:\n").strip()
     unsorted = [int(item) for item in user_input.split(",")]
-    gnome_sort(unsorted)
-    print(unsorted)
+    print(gnome_sort(unsorted))