chore: docstrings for solution and tests

Author: Mallory Brickerd

_2025/solutions/day02.py

@@ -1,11 +1,12 @@
-"""Boilerplate solution template for Advent of Code daily challenges.
+"""Day 2: Gift Shop
 
-This module provides a template class for solving Advent of Code puzzle problems.
-It includes a base structure with two method stubs (part1 and part2) that can be
-implemented for specific day's challenges.
+This module provides the solution for Advent of Code 2025 - Day 2.
 
-The template follows the SolutionBase pattern used across the Advent of Code solutions,
-allowing for consistent handling of input parsing and solution execution.
+It identifies invalid product IDs within given ranges. An ID is considered
+invalid if it is formed by a repeating sequence of digits.
+
+The module contains a Solution class that inherits from SolutionBase for
+parsing ID ranges and summing the invalid IDs found.
 """
 
 from collections.abc import Callable
@@ -15,17 +16,28 @@
 
 
 class Solution(SolutionBase):
-    """Solution template for Advent of Code daily puzzle.
+    """Find and sum invalid product IDs based on repeating digit patterns.
 
-    This class provides a standardized structure for implementing solutions to
-    daily Advent of Code challenges. It inherits from SolutionBase and includes
-    method stubs for part1 and part2 of the puzzle.
+    This solution processes a string of comma-separated ID ranges (e.g., "1-10,20-30").
+    It checks each ID in every range to see if it matches a specific pattern of
+    repeating digits.
 
-    Subclasses should override these methods with specific implementation logic
-    for parsing input and solving the puzzle requirements.
+    Part 1 defines an invalid ID as one made of a digit sequence repeated twice (e.g., 1212).
+    Part 2 expands this to any ID made of a sequence repeated at least twice (e.g., 1212, 121212).
     """
 
     def has_repeated_sequence(self, n: int, num_repeats: int | None = None) -> bool:
+        """Check if a number consists of a repeating sequence of digits.
+
+        Args:
+            n: The integer to check.
+            num_repeats: If an integer, checks for exactly that many repetitions.
+                         If None, checks for any number of repetitions (>= 2).
+
+        Returns
+        -------
+            bool: True if the number is formed by a repeating sequence, False otherwise.
+        """
         s = str(n)
         length = len(s)
 
@@ -39,6 +51,7 @@ def has_repeated_sequence(self, n: int, num_repeats: int | None = None) -> bool:
             size = length // num_repeats
             return s == s[:size] * num_repeats
 
+        # Check for any number of repetitions from 2 up to the length of the string
         for k in range(2, length + 1):
             if length % k == 0:
                 size = length // k
@@ -47,37 +60,58 @@ def has_repeated_sequence(self, n: int, num_repeats: int | None = None) -> bool:
 
         return False
 
-    def solve_part(self, data: list[str], func: Callable) -> int:
-        invalid = 0
+    def solve_part(self, data: list[str], func: Callable[[int], bool]) -> int:
+        """Generic solver to find and sum invalid IDs based on a check function.
+
+        Parses the input string of ranges, iterates through each number, and applies
+        the provided checking function to identify and sum invalid IDs.
+
+        Args:
+            data: A list containing one string of comma-separated ranges.
+            func: A callable that takes an integer and returns True if it's invalid.
+
+        Returns
+        -------
+            int: The sum of all invalid product IDs found.
+        """
+        invalid_sum = 0
         for line in data[0].split(","):
             start, end = map(int, line.split("-"))
-            for product in range(start, end + 1):
-                if func(product):
-                    invalid += product
+            for product_id in range(start, end + 1):
+                if func(product_id):
+                    invalid_sum += product_id
 
-        return invalid
+        return invalid_sum
 
     def part1(self, data: list[str]) -> int:
-        """Solve the first part of the daily puzzle.
+        """Calculate the sum of invalid IDs where a digit sequence is repeated twice.
+
+        An ID is invalid if it's formed by a sequence of digits repeated
+        exactly twice (e.g., `6464` from `64`). This method sums all such
+        IDs found in the input ranges.
 
         Args:
-            data: List of input strings to be processed
+            data: A list containing the input string of ID ranges.
 
         Returns
         -------
-            int: Solution for part 1 of the puzzle
+            int: The total sum of invalid IDs for Part 1.
         """
         check_func = partial(self.has_repeated_sequence, num_repeats=2)
         return self.solve_part(data, check_func)
 
     def part2(self, data: list[str]) -> int:
-        """Solve the second part of the daily puzzle.
+        """Calculate the sum of invalid IDs where a digit sequence is repeated at least twice.
+
+        An ID is invalid if it's formed by a sequence of digits repeated two
+        or more times (e.g., `1212` or `121212`). This method sums all such
+        IDs found in the input ranges.
 
         Args:
-            data: List of input strings to be processed
+            data: A list containing the input string of ID ranges.
 
         Returns
         -------
-            int: Solution for part 2 of the puzzle
+            int: The total sum of invalid IDs for Part 2.
         """
         return self.solve_part(data, self.has_repeated_sequence)

_2025/tests/test_02.py

@@ -1,19 +1,17 @@
-"""Test suite for Advent of Code daily challenge solution.
+"""Test suite for Day 2: Gift Shop
 
-This module contains the test cases for the solution to the Advent of Code
-daily puzzle. It uses the TestSolutionUtility to run tests for both parts
-of the challenge.
+This module contains tests for the Day 2 solution, which identifies and sums
+invalid product IDs from a list of ranges. The tests verify:
 
-The template provides a structure for defining tests for a specific day's
-solution, ensuring that the implementation meets the expected outputs for
-given test inputs.
+1. Part 1: Summing IDs where a digit sequence is repeated exactly twice.
+2. Part 2: Summing IDs where a digit sequence is repeated at least twice.
 """
 
 from aoc.models.tester import TestSolutionUtility
 
 
 def test_day02_part1() -> None:
-    """Test the solution for Part 1 of the daily puzzle.
+    """Test summing invalid IDs with a twice-repeated digit sequence.
 
     This test runs the solution for Part 1 of the puzzle against the
     provided test input and compares the result with the expected output.
@@ -28,7 +26,7 @@ def test_day02_part1() -> None:
 
 
 def test_day02_part2() -> None:
-    """Test the solution for Part 2 of the daily puzzle.
+    """Test summing invalid IDs with a digit sequence repeated at least twice.
 
     This test runs the solution for Part 2 of the puzzle against the
     provided test input and compares the result with the expected output.