Merge branch 'master' into python3.15t

Author: cclauss

CONTRIBUTING.md

@@ -196,7 +196,7 @@ Comments which are not on the same line as code should appear ___before___ the c
       return a + b
   ```
 
-  [Install ty](https://docs.astral.sh/ty/installation/) and then pslease use the command `ty check` to test all files or `ty check path/to/file.py` to test a specific file.
+  [Install ty](https://docs.astral.sh/ty/installation/) and then please use the command `ty check` to test all files or `ty check path/to/file.py` to test a specific file.
 
 - [__List comprehensions and generators__](https://docs.python.org/3/tutorial/datastructures.html#list-comprehensions) are preferred over the use of `lambda`, `map`, `filter`, `reduce` but the important thing is to demonstrate the power of Python in code that is easy to read and maintain.
 

DIRECTORY.md

@@ -1,7 +1,7 @@
 """
-Graph Coloring also called "m coloring problem"
-consists of coloring a given graph with at most m colors
-such that no adjacent vertices are assigned the same color
+Graph Coloring (also called the "m coloring problem") is the problem of
+assigning at most 'm' colors to the vertices of a graph such that
+no two adjacent vertices share the same color.
 
 Wikipedia: https://en.wikipedia.org/wiki/Graph_coloring
 """
@@ -11,22 +11,46 @@ def valid_coloring(
     neighbours: list[int], colored_vertices: list[int], color: int
 ) -> bool:
     """
+    Check if a given vertex can be assigned the specified color
+    without violating the graph coloring constraints (i.e., no two adjacent vertices
+    have the same color).
+
+    Procedure:
     For each neighbour check if the coloring constraint is satisfied
     If any of the neighbours fail the constraint return False
     If all neighbours validate the constraint return True
 
-    >>> neighbours = [0,1,0,1,0]
+    Parameters:
+    neighbours: The list representing which vertices
+                are adjacent to the current vertex.
+                1 indicates an edge between the current vertex
+                and the neighbour.
+    colored_vertices: List of current color assignments for all vertices
+                      (-1 means uncolored).
+    color: The color we are trying to assign to the current vertex.
+
+    Returns:
+    True if the vertex can be safely colored with the given color,
+    otherwise False.
+
+    Examples:
+    >>> neighbours = [0, 1, 0, 1, 0]
     >>> colored_vertices = [0, 2, 1, 2, 0]
-
     >>> color = 1
     >>> valid_coloring(neighbours, colored_vertices, color)
     True
 
     >>> color = 2
     >>> valid_coloring(neighbours, colored_vertices, color)
     False
+
+    >>> neighbors = [1, 0, 1, 0]
+    >>> colored_vertices = [-1, -1, -1, -1]
+    >>> color = 0
+    >>> valid_coloring(neighbors, colored_vertices, color)
+    True
     """
-    # Does any neighbour not satisfy the constraints
+    # Check if any adjacent vertex has already been colored with the same color
     return not any(
         neighbour == 1 and colored_vertices[i] == color
         for i, neighbour in enumerate(neighbours)
@@ -37,7 +61,7 @@ def util_color(
     graph: list[list[int]], max_colors: int, colored_vertices: list[int], index: int
 ) -> bool:
     """
-    Pseudo-Code
+    Recursive function to try and color the graph using backtracking.
 
     Base Case:
     1. Check if coloring is complete
@@ -51,6 +75,20 @@ def util_color(
             2.4. if current coloring leads to a solution return
             2.5. Uncolor given vertex
 
+    Parameters:
+    graph: Adjacency matrix representing the graph.
+           graph[i][j] is 1 if there is an edge
+           between vertex i and j.
+    max_colors: Maximum number of colors allowed (m in the m-coloring problem).
+    colored_vertices: Current color assignments for each vertex.
+                      -1 indicates that the vertex has not been colored
+                      yet.
+    index: The current vertex index being processed.
+
+    Returns:
+    True if the graph can be colored using at most max_colors, otherwise False.
+
+    Examples:
     >>> graph = [[0, 1, 0, 0, 0],
     ...          [1, 0, 1, 0, 1],
     ...          [0, 1, 0, 1, 0],
@@ -67,43 +105,68 @@ def util_color(
     >>> util_color(graph, max_colors, colored_vertices, index)
     False
     """
-
-    # Base Case
+    # Base Case: If all vertices have been assigned a color, we have a valid solution
     if index == len(graph):
         return True
 
-    # Recursive Step
-    for i in range(max_colors):
-        if valid_coloring(graph[index], colored_vertices, i):
-            # Color current vertex
-            colored_vertices[index] = i
-            # Validate coloring
+    # Try each color for the current vertex
+    for color in range(max_colors):
+        # Check if it's valid to color the current vertex with 'color'
+        if valid_coloring(graph[index], colored_vertices, color):
+            colored_vertices[index] = color  # Assign color
+            # Recur to color the rest of the vertices
             if util_color(graph, max_colors, colored_vertices, index + 1):
                 return True
-            # Backtrack
+            # Backtrack if no solution found with the current assignment
             colored_vertices[index] = -1
-    return False
+
+    return False  # Return False if no valid coloring is possible
 
 
 def color(graph: list[list[int]], max_colors: int) -> list[int]:
     """
-    Wrapper function to call subroutine called util_color
-    which will either return True or False.
-    If True is returned colored_vertices list is filled with correct colorings
-
+    Attempt to color the graph with at most max_colors colors such that no two adjacent
+    vertices have the same color.
+    If it is possible, returns the list of color assignments;
+    otherwise, returns an empty list.
+
+    Parameters:
+    graph: Adjacency matrix representing the graph.
+    max_colors: Maximum number of colors allowed.
+
+    Returns:
+    List of color assignments if the graph can be colored using max_colors.
+    Each index in the list represents the color assigned
+    to the corresponding vertex.
+    If coloring is not possible, returns an empty list.
+
+    Examples:
     >>> graph = [[0, 1, 0, 0, 0],
     ...          [1, 0, 1, 0, 1],
     ...          [0, 1, 0, 1, 0],
     ...          [0, 1, 1, 0, 0],
     ...          [0, 1, 0, 0, 0]]
-
     >>> max_colors = 3
     >>> color(graph, max_colors)
     [0, 1, 0, 2, 0]
 
     >>> max_colors = 2
     >>> color(graph, max_colors)
     []
+
+    >>> graph = [[0, 1], [1, 0]]  # Simple 2-node graph
+    >>> max_colors = 2
+    >>> color(graph, max_colors)
+    [0, 1]
+
+    >>> graph = [[0, 1, 1], [1, 0, 1], [1, 1, 0]]  # Complete graph of 3 vertices
+    >>> max_colors = 2
+    >>> color(graph, max_colors)
+    []
+
+    >>> max_colors = 3
+    >>> color(graph, max_colors)
+    [0, 1, 2]
     >>> color([], 2)  # empty graph
     []
     >>> color([[0]], 1)  # single node, 1 color
@@ -113,9 +176,11 @@ def color(graph: list[list[int]], max_colors: int) -> list[int]:
     >>> color([[0, 1], [1, 0]], 2)  # 2 nodes, 2 colors (possible)
     [0, 1]
     """
+    # Initialize all vertices as uncolored (-1)
     colored_vertices = [-1] * len(graph)
 
+    # Use the utility function to try and color the graph starting from vertex 0
     if util_color(graph, max_colors, colored_vertices, 0):
-        return colored_vertices
+        return colored_vertices  # The successful color assignment
 
-    return []
+    return []  # No valid coloring is possible

backtracking/coloring.py

@@ -6,29 +6,28 @@ def is_valid(
 ) -> bool:
     """
     Check if a word can be placed at the given position.
+    A cell is valid if it is empty or already contains the correct letter
+    (enabling crossing/intersection between words).
 
-    >>> puzzle = [
-    ...     ['', '', '', ''],
-    ...     ['', '', '', ''],
-    ...     ['', '', '', ''],
-    ...     ['', '', '', '']
-    ... ]
+    >>> puzzle = [['', '', '', ''], ['', '', '', ''],
+    ...           ['', '', '', ''], ['', '', '', '']]
     >>> is_valid(puzzle, 'word', 0, 0, True)
     True
-    >>> puzzle = [
-    ...     ['', '', '', ''],
-    ...     ['', '', '', ''],
-    ...     ['', '', '', ''],
-    ...     ['', '', '', '']
-    ... ]
     >>> is_valid(puzzle, 'word', 0, 0, False)
     True
+    >>> puzzle2 = [['w', '', ''], ['o', '', ''], ['r', '', ''], ['d', '', '']]
+    >>> is_valid(puzzle2, 'word', 0, 0, True)
+    True
+    >>> is_valid(puzzle2, 'cat', 0, 0, True)
+    False
     """
-    for i in range(len(word)):
-        if vertical:
-            if row + i >= len(puzzle) or puzzle[row + i][col] != "":
-                return False
-        elif col + i >= len(puzzle[0]) or puzzle[row][col + i] != "":
+    rows, cols = len(puzzle), len(puzzle[0])
+    for i, ch in enumerate(word):
+        r, c = (row + i, col) if vertical else (row, col + i)
+        if r >= rows or c >= cols:
+            return False
+        cell = puzzle[r][c]
+        if cell not in ("", ch):
             return False
     return True
 
@@ -37,95 +36,87 @@ def place_word(
     puzzle: list[list[str]], word: str, row: int, col: int, vertical: bool
 ) -> None:
     """
-    Place a word at the given position.
-
-    >>> puzzle = [
-    ...     ['', '', '', ''],
-    ...     ['', '', '', ''],
-    ...     ['', '', '', ''],
-    ...     ['', '', '', '']
-    ... ]
+    Place a word at the given position in the puzzle.
+
+    >>> puzzle = [['', '', '', ''], ['', '', '', ''],
+    ...           ['', '', '', ''], ['', '', '', '']]
     >>> place_word(puzzle, 'word', 0, 0, True)
     >>> puzzle
     [['w', '', '', ''], ['o', '', '', ''], ['r', '', '', ''], ['d', '', '', '']]
     """
-    for i, char in enumerate(word):
+    for i, ch in enumerate(word):
         if vertical:
-            puzzle[row + i][col] = char
+            puzzle[row + i][col] = ch
         else:
-            puzzle[row][col + i] = char
+            puzzle[row][col + i] = ch
 
 
 def remove_word(
-    puzzle: list[list[str]], word: str, row: int, col: int, vertical: bool
+    puzzle: list[list[str]],
+    word: str,
+    row: int,
+    col: int,
+    vertical: bool,
+    snapshot: list[list[str]],
 ) -> None:
     """
-    Remove a word from the given position.
-
-    >>> puzzle = [
-    ...     ['w', '', '', ''],
-    ...     ['o', '', '', ''],
-    ...     ['r', '', '', ''],
-    ...     ['d', '', '', '']
-    ... ]
-    >>> remove_word(puzzle, 'word', 0, 0, True)
+    Remove a word from the puzzle, restoring only cells that were empty
+    before placement. Cells shared with crossing words are preserved.
+
+    >>> puzzle = [['w', 'o', 'r', 'd'], ['', '', '', ''],
+    ...           ['', '', '', ''], ['', '', '', '']]
+    >>> snap = [['', 'o', 'r', 'd'], ['', '', '', ''],
+    ...         ['', '', '', ''], ['', '', '', '']]
+    >>> remove_word(puzzle, 'word', 0, 0, False, snap)
     >>> puzzle
-    [['', '', '', ''], ['', '', '', ''], ['', '', '', ''], ['', '', '', '']]
+    [['', 'o', 'r', 'd'], ['', '', '', ''], ['', '', '', ''], ['', '', '', '']]
     """
     for i in range(len(word)):
-        if vertical:
-            puzzle[row + i][col] = ""
-        else:
-            puzzle[row][col + i] = ""
+        r, c = (row + i, col) if vertical else (row, col + i)
+        if snapshot[r][c] == "":
+            puzzle[r][c] = ""
 
 
 def solve_crossword(puzzle: list[list[str]], words: list[str]) -> bool:
     """
     Solve the crossword puzzle using backtracking.
+    Words are tried longest-first to prune the search space early.
+    Intersections between words (shared letters) are supported.
 
-    >>> puzzle = [
-    ...     ['', '', '', ''],
-    ...     ['', '', '', ''],
-    ...     ['', '', '', ''],
-    ...     ['', '', '', '']
-    ... ]
-
-    >>> words = ['word', 'four', 'more', 'last']
-    >>> solve_crossword(puzzle, words)
+    >>> puzzle = [['', '', '', ''], ['', '', '', ''],
+    ...           ['', '', '', ''], ['', '', '', '']]
+    >>> solve_crossword(puzzle, ['word', 'four', 'more', 'last'])
     True
-    >>> puzzle = [
-    ...     ['', '', '', ''],
-    ...     ['', '', '', ''],
-    ...     ['', '', '', ''],
-    ...     ['', '', '', '']
-    ... ]
-    >>> words = ['word', 'four', 'more', 'paragraphs']
-    >>> solve_crossword(puzzle, words)
+    >>> puzzle2 = [['', '', '', ''], ['', '', '', ''],
+    ...            ['', '', '', ''], ['', '', '', '']]
+    >>> solve_crossword(puzzle2, ['word', 'four', 'more', 'paragraphs'])
     False
     """
+    if not words:
+        return True
+
+    remaining = sorted(words, key=len, reverse=True)
+    word, rest = remaining[0], remaining[1:]
+
     for row in range(len(puzzle)):
         for col in range(len(puzzle[0])):
-            if puzzle[row][col] == "":
-                for word in words:
-                    for vertical in [True, False]:
-                        if is_valid(puzzle, word, row, col, vertical):
-                            place_word(puzzle, word, row, col, vertical)
-                            words.remove(word)
-                            if solve_crossword(puzzle, words):
-                                return True
-                            words.append(word)
-                            remove_word(puzzle, word, row, col, vertical)
-                return False
-    return True
+            for vertical in (True, False):
+                if is_valid(puzzle, word, row, col, vertical):
+                    snapshot = [r[:] for r in puzzle]
+                    place_word(puzzle, word, row, col, vertical)
+                    if solve_crossword(puzzle, rest):
+                        return True
+                    remove_word(puzzle, word, row, col, vertical, snapshot)
+
+    return False
 
 
 if __name__ == "__main__":
     PUZZLE = [[""] * 3 for _ in range(3)]
     WORDS = ["cat", "dog", "car"]
-
     if solve_crossword(PUZZLE, WORDS):
         print("Solution found:")
         for row in PUZZLE:
-            print(" ".join(row))
+            print(" ".join(cell or "." for cell in row))
     else:
-        print("No solution found:")
+        print("No solution found.")