Merge branch 'master' into feat/pancake-sort-comparable

Author: cclauss

data_structures/linked_list/partition_linked_list.py

@@ -103,9 +103,9 @@ def add(self, item: Any, position: int = 0) -> None:
 
     def partition_liked_list(self, value: int) -> None:
         """
-        Partition Linked List based on node elements in-order.
-        All nodes with elements less than value should occur in the left,
-        while those greater than to value, in the right.
+        Partition the linked list based on node elements in order.
+        All nodes with elements less than value should occur on the left,
+        while those greater than or equal to value should occur on the right.
 
         >>> linked_list = LinkedList()
         >>> linked_list.add(1)
@@ -156,7 +156,7 @@ def partition_liked_list(self, value: int) -> None:
         1
         """
         if self.head is None:
-            return None
+            return
 
         less_nodes, greater_nodes = Node(0), Node(0)
         current, current_less, current_greater = self.head, less_nodes, greater_nodes

maths/softmax.py

@@ -14,43 +14,105 @@
 from numpy.exceptions import AxisError
 
 
-def softmax(vector: np.ndarray, axis: int = -1) -> np.ndarray:
+def softmax(vector: np.ndarray, axis: int | None = -1) -> np.ndarray:
     """
-    Implements the softmax function.
+    Compute the softmax of ``vector`` along ``axis`` in a numerically-stable way.
 
     Parameters:
-        vector (np.ndarray | list | tuple): A numpy array of shape (1, n)
-            consisting of real values or a similar list/tuple.
-        axis (int, optional): Axis along which to compute softmax.
-            Default is -1.
+        vector (np.ndarray | list | tuple): Input data (vector, matrix or
+            higher-rank tensor). It is converted to a float ``np.ndarray``,
+            so lists, tuples and integers are accepted too.
+        axis (int | None, optional): Axis along which softmax is computed so
+            that the probabilities sum to 1 along that axis. If ``None``, the
+            softmax is computed over the flattened array (a single
+            distribution). Default is ``-1`` (the last axis).
 
     Returns:
-        np.ndarray: The input numpy array after applying softmax.
+        np.ndarray: An array with the same shape as ``vector`` whose values
+        along ``axis`` (or over the whole array when ``axis is None``) form a
+        probability distribution that sums to 1.
+
+    Raises:
+        ValueError: If ``vector`` is empty or cannot be converted to a numeric
+            float array (for example a string or a dict).
+        numpy.exceptions.AxisError: If ``axis`` is out of bounds for the input.
+
+    Note:
+        If the input contains ``NaN`` or ``inf`` the result will contain
+        ``NaN`` along the affected axis; softmax is only meaningful for finite
+        real inputs.
 
     The softmax vector adds up to one. We need to ceil to mitigate precision.
 
     >>> float(np.ceil(np.sum(softmax([1, 2, 3, 4]))))
     1.0
 
-    >>> vec = np.array([5, 5])
-    >>> softmax(vec)
+    Identical logits map to a uniform distribution:
+
+    >>> softmax(np.array([5, 5]))
     array([0.5, 0.5])
 
+    A single element always maps to 1:
+
     >>> softmax([0])
     array([1.])
+
+    It is numerically stable for large logits (no overflow):
+
+    >>> softmax([1000.0, 1001.0, 1002.0])
+    array([0.09003057, 0.24472847, 0.66524096])
+
+    For a 2-D array the ``axis`` selects where probabilities sum to 1:
+
+    >>> mat = np.array([[1.0, 2.0, 3.0], [1.0, 2.0, 3.0]])
+    >>> np.round(softmax(mat, axis=-1), 3)
+    array([[0.09 , 0.245, 0.665],
+           [0.09 , 0.245, 0.665]])
+    >>> np.round(softmax(mat, axis=0), 3)
+    array([[0.5, 0.5, 0.5],
+           [0.5, 0.5, 0.5]])
+
+    With ``axis=None`` the whole array becomes one distribution that sums to 1:
+
+    >>> float(np.round(np.sum(softmax(mat, axis=None)), 6))
+    1.0
+
+    Empty, non-numeric and out-of-bounds inputs raise clear errors:
+
+    >>> softmax([])
+    Traceback (most recent call last):
+        ...
+    ValueError: softmax input must be non-empty
+    >>> softmax("not a number")
+    Traceback (most recent call last):
+        ...
+    ValueError: softmax input must be numeric, got str
+    >>> softmax([1, 2, 3], axis=3)
+    Traceback (most recent call last):
+        ...
+    numpy.exceptions.AxisError: axis 3 is out of bounds for array of dimension 1
     """
-    # Convert input to numpy array of floats
-    vector = np.asarray(vector, dtype=float)
+    # Convert input to a float numpy array, turning numpy's terse conversion
+    # errors into a clear message about the unsupported input type.
+    try:
+        vector = np.asarray(vector, dtype=float)
+    except (ValueError, TypeError) as exc:
+        error_message = f"softmax input must be numeric, got {type(vector).__name__}"
+        raise ValueError(error_message) from exc
 
     # Handle empty input
     if vector.size == 0:
         raise ValueError("softmax input must be non-empty")
 
-    # Validate axis
-    ndim = vector.ndim
-    if axis >= ndim or axis < -ndim:
-        error_message = f"axis {axis} is out of bounds for array of dimension {ndim}"
-        raise AxisError(error_message)
+    # Validate axis (None means "treat the whole array as one distribution")
+    if axis is not None:
+        ndim = vector.ndim
+        if axis >= ndim or axis < -ndim:
+            error_message = (
+                f"axis {axis} is out of bounds for array of dimension {ndim}"
+            )
+            raise AxisError(error_message)
+
     # Subtract max for numerical stability
     vector_max = np.max(vector, axis=axis, keepdims=True)
     exponent_vector = np.exp(vector - vector_max)
@@ -73,3 +135,5 @@ def softmax(vector: np.ndarray, axis: int = -1) -> np.ndarray:
     print("Softmax along last axis:\n", softmax(mat))
     # Matrix along axis 0
     print("Softmax along axis 0:\n", softmax(mat, axis=0))
+    # Whole-matrix distribution
+    print("Softmax over the whole matrix:\n", softmax(mat, axis=None))

scripts/pr_file_map.py

@@ -0,0 +1,115 @@
+#!/usr/bin/env python3
+"""
+pr_file_map.py
+
+Lists all open pull requests in the current directory's git repo (via `gh`)
+and, for each file touched by any open PR, which PR number(s) touch it.
+
+Output is GitHub-flavored Markdown: a sorted list of files that currently
+exist in the working directory, each with its modifying PR numbers, followed
+by a separate section for files referenced by open PRs but that do not exist
+in the working directory (e.g. deleted, renamed, or on a branch not checked
+out locally).
+
+Requirements: gh (GitHub CLI), authenticated (`gh auth login`)
+
+Usage:
+    ./pr_file_map.py
+    ./pr_file_map.py > report.md
+"""
+
+import json
+import os
+import shutil
+import subprocess
+import sys
+from collections import defaultdict
+
+
+def run_gh(args: list[str]) -> str:
+    try:
+        result = subprocess.run(  # noqa: S603
+            ["gh", *args],  # noqa: S607
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+    except FileNotFoundError:
+        sys.exit("Error: 'gh' (GitHub CLI) is not installed or not in PATH.")
+    except subprocess.CalledProcessError as e:
+        sys.exit(f"Error running 'gh {' '.join(args)}':\n{e.stderr.strip()}")
+    return result.stdout
+
+
+def check_gh_auth() -> None:
+    try:
+        subprocess.run(
+            ["gh", "auth", "status"],  # noqa: S607
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+    except subprocess.CalledProcessError:
+        sys.exit("Error: gh is not authenticated. Run 'gh auth login' first.")
+
+
+def get_open_prs() -> list[dict]:
+    raw = run_gh(
+        ["pr", "list", "--state", "open", "--limit", "1000", "--json", "number,title"]
+    )
+    return json.loads(raw)
+
+
+def get_pr_files(pr_number: int) -> list[str]:
+    raw = run_gh(["pr", "view", str(pr_number), "--json", "files"])
+    data = json.loads(raw)
+    return [f["path"] for f in data.get("files", [])]
+
+
+def main() -> None:
+    if shutil.which("gh") is None:
+        sys.exit("Error: 'gh' (GitHub CLI) is not installed or not in PATH.")
+
+    check_gh_auth()
+
+    prs = get_open_prs()
+    if not prs:
+        print("No open pull requests found.")
+        return
+
+    file_to_prs: dict[str, list[int]] = defaultdict(list)
+
+    for pr in prs:
+        pr_number = pr["number"]
+        for path in get_pr_files(pr_number):
+            file_to_prs[path].append(pr_number)
+
+    existing: dict[str, list[int]] = {}
+    missing: dict[str, list[int]] = {}
+
+    for path, pr_numbers in file_to_prs.items():
+        target = existing if os.path.exists(path) else missing
+        target[path] = sorted(set(pr_numbers))
+
+    # --- Render GitHub-flavored Markdown ---
+    print("# Open Pull Request File Map\n")
+
+    print("## Existing files\n")
+    if existing:
+        for path in sorted(existing):
+            pr_list = " ".join(f"#{n}" for n in existing[path])
+            print(f"- `{path}`: {pr_list}")
+    else:
+        print("_None._")
+
+    print("\n## Files not present in the working directory\n")
+    if missing:
+        for path in sorted(missing):
+            pr_list = " ".join(f"#{n}" for n in missing[path])
+            print(f"- `{path}`: {pr_list}")
+    else:
+        print("_None._")
+
+
+if __name__ == "__main__":
+    main()

sorts/bucket_sort.py

@@ -77,6 +77,10 @@ def bucket_sort(
     >>> data = [9, 2, 7, 1, 5]
     >>> bucket_sort(data) == sorted(data)
     True
+    >>> bucket_sort(data, 3.5)
+    Traceback (most recent call last):
+    ...
+    TypeError: bucket_count must be an integer
     """
 
     if not isinstance(bucket_count, int):