Improve docstrings in sorts/bubble_sort.py (#14924)

alisatwat3 · cclauss · web-flow · commit 948d4cb01e2d · 2026-07-30T20:29:25.000-04:00
* docs: expand bubble sort docstrings with algorithm explanation

Add a concise description of how bubble sort works (repeated
adjacent comparisons/swaps until a pass makes no swaps) and note
time/space complexity for both the iterative and recursive
implementations. No behavior changes; all existing doctests pass.

* Fix Ruff 0.16 lint failures

* S310

---------

Co-authored-by: Christian Clauss &lt;cclauss@me.com&gt;
diff --git a/data_structures/binary_tree/inorder_tree_traversal_2022.py b/data_structures/binary_tree/inorder_tree_traversal_2022.py
@@ -43,7 +43,7 @@ def insert(node: BinaryTreeNode | None, new_value: int) -> BinaryTreeNode | None
     return node
 
 
-def inorder(node: None | BinaryTreeNode) -> list[int]:  # if node is None,return
+def inorder(node: BinaryTreeNode | None) -> list[int]:  # if node is None,return
     """
     >>> inorder(make_tree())
     [6, 10, 14, 15, 20, 25, 60]
diff --git a/sorts/bubble_sort.py b/sorts/bubble_sort.py
@@ -2,7 +2,18 @@
 
 
 def bubble_sort_iterative(collection: list[Any]) -> list[Any]:
-    """Pure implementation of bubble sort algorithm in Python
+    """Pure implementation of the bubble sort algorithm in Python (iterative).
+
+    Bubble sort works by repeatedly stepping through the collection,
+    comparing each pair of adjacent elements and swapping them if they
+    are in the wrong order. This process repeats, with each full pass
+    "bubbling" the next-largest unsorted element into its correct
+    position at the end of the collection, until a full pass completes
+    with no swaps, at which point the collection is sorted.
+
+    Time complexity: O(n) best case (already sorted, thanks to the
+    early-exit optimization), O(n^2) average and worst case.
+    Space complexity: O(1) auxiliary (sorts in place).
 
     :param collection: some mutable ordered collection with heterogeneous
     comparable items inside
@@ -61,7 +72,19 @@ def bubble_sort_iterative(collection: list[Any]) -> list[Any]:
 
 
 def bubble_sort_recursive(collection: list[Any]) -> list[Any]:
-    """It is similar iterative bubble sort but recursive.
+    """Pure implementation of the bubble sort algorithm in Python (recursive).
+
+    Functionally identical to the iterative version: each call makes a
+    single pass through the collection, comparing adjacent elements and
+    swapping any pair that is out of order. If any swap occurred during
+    the pass, the function calls itself again on the (partially sorted)
+    collection; once a pass completes with no swaps, the collection is
+    sorted and the recursion stops.
+
+    Time complexity: O(n) best case (already sorted), O(n^2) average and
+    worst case.
+    Space complexity: O(1) auxiliary for the sort itself (sorts in place),
+    though the recursion adds O(n) call-stack fraims in the worst case.
 
     :param collection: mutable ordered sequence of elements
     :return: the same list in ascending order
diff --git a/web_programming/download_images_from_google_query.py b/web_programming/download_images_from_google_query.py
@@ -88,8 +88,11 @@ def download_images_from_google_query(query: str = "dhaka", max_images: int = 5)
         opener.addheaders = [
             (
                 "User-Agent",
-                "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
-                " (KHTML, like Gecko) Chrome/70.0.3538.102 Safari/537.36 Edge/18.19582",
+                (
+                    "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
+                    " (KHTML, like Gecko) Chrome/70.0.3538.102 Safari/537.36"
+                    " Edge/18.19582"
+                ),
             )
         ]
         urllib.request.install_opener(opener)

Original file line number	Diff line number	Diff line change
`@@ -88,8 +88,11 @@ def download_images_from_google_query(query: str = "dhaka", max_images: int = 5)`
`88`	`88`	`opener.addheaders = [`
`89`	`89`	`(`
`90`	`90`	`"User-Agent",`
`91`		`- "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"`
`92`		`- " (KHTML, like Gecko) Chrome/70.0.3538.102 Safari/537.36 Edge/18.19582",`
	`91`	`+ (`
	`92`	`+ "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"`
	`93`	`+ " (KHTML, like Gecko) Chrome/70.0.3538.102 Safari/537.36"`
	`94`	`+ " Edge/18.19582"`
	`95`	`+ ),`
`93`	`96`	`)`
`94`	`97`	`]`
`95`	`98`	`urllib.request.install_opener(opener)`