Added docstrings

Author: mbrickerd

aoc/models/base.py

@@ -6,6 +6,23 @@
 
 
 class SolutionBase:
+    """
+    Base class for implementing Advent of Code puzzle solutions with benchmarking capabilities.
+
+    This class provides a framework for solving daily AoC challenges, supporting both test and
+    puzzle inputs, with optional performance benchmarking. Each puzzle solution should inherit
+    from this class and implement `part1()` and `part2()` methods.
+
+    Attributes:
+        day (int): The Advent of Code day number (-1 by default)
+        part_num (int): The puzzle part number (1 or 2)
+        is_raw (bool): Flag indicating whether to use raw input format
+        skip_test (bool): Flag indicating whether to use actual puzzle input instead of test input
+        _benchmark (bool): Flag for enabling solution timing measurements
+        benchmark_times (list): List storing benchmark timestamps
+        data: Puzzle input data loaded from either test or actual input files
+    """
+
     def __init__(
         self,
         day: int = -1,
@@ -14,6 +31,16 @@ def __init__(
         skip_test: bool = True,
         benchmark: bool = False,
     ) -> None:
+        """
+        Initialize a solution instance for an Advent of Code puzzle.
+
+        Args:
+            day (int, optional): The day number of the puzzle (1-25). Defaults to -1.
+            part_num (int, optional): Which part of the day's puzzle (1 or 2). Defaults to 1.
+            is_raw (bool, optional): Whether to load input as raw text. Defaults to `False`.
+            skip_test (bool, optional): Whether to use puzzle input instead of test input. Defaults to `True`.
+            benchmark (bool, optional): Whether to measure solution execution time. Defaults to `False`.
+        """
         self.day = day
         self.part_num = part_num
         self.is_raw = is_raw
@@ -27,11 +54,29 @@ def __init__(
         )
 
     def check_is_raw(self) -> None:
+        """
+        Verify if raw input mode is enabled for puzzles that require it.
+
+        Some Advent of Code puzzles require preserving whitespace or special characters
+        in the input. This method ensures raw mode is enabled for such puzzles.
+
+        Exits the program with a warning message if raw input mode is not enabled.
+        """
         if self.is_raw is False:
             logger.info("Please use --raw flag in this puzzle")
             exit()
 
     def benchmark(self, _print: bool = False) -> None:
+        """
+        Record or display solution execution time benchmarks.
+
+        When called with `_print=False`, records a timestamp. When called with `_print=True`,
+        calculates and displays the elapsed time since the last timestamp in appropriate
+        units (`s`, `ms`, `µs`, or `ns`).
+
+        Args:
+            _print (bool, optional): Whether to print the elapsed time. Defaults to `False`.
+        """
         if (
             _print
             and len(self.benchmark_times) > 0
@@ -51,6 +96,21 @@ def benchmark(self, _print: bool = False) -> None:
             self.benchmark_times.append(timeit.default_timer())
 
     def solve(self, part_num: int) -> int:
+        """
+        Execute the solution for a specified puzzle part.
+
+        Calls either `part1()` or `part2()` method based on the `part_num` parameter,
+        with optional execution time measurement.
+
+        Args:
+            part_num (int): Which part of the puzzle to solve (1 or 2)
+
+        Returns:
+            int: The solution result for the specified puzzle part
+
+        Note:
+            Inheriting classes must implement `part1()` and `part2()` methods.
+        """
         func = getattr(self, f"part{part_num}")
         self.benchmark()
 

aoc/models/file.py

@@ -14,8 +14,23 @@
 
 
 class File:
+    """
+    Utility class for managing Advent of Code file operations and puzzle input retrieval.
+
+    This class provides static methods for handling file paths, session management,
+    downloading puzzle/test inputs, and setting up solution files. It manages the
+    directory structure and timing for puzzle input availability.
+    """
+
     @staticmethod
     def get_path() -> str:
+        """
+        Get the absolute path to the project directory.
+
+        Returns:
+            str: Absolute path to either the directory containing the script or
+                the script's directory if it is itself a directory.
+        """
         return (
             path
             if os.path.isdir(path := os.path.realpath(sys.argv[0]))
@@ -24,6 +39,15 @@ def get_path() -> str:
 
     @staticmethod
     def get_session() -> str:
+        """
+        Retrieve the Advent of Code session token from a local file.
+
+        Returns:
+            str: The session token stripped of whitespace.
+
+        Note:
+            Expects a file named `aoc_session` in the project root directory.
+        """
         session = ""
         path = File.get_path()
         session_path = os.path.realpath(f"{path}/aoc_session")
@@ -35,6 +59,15 @@ def get_session() -> str:
 
     @staticmethod
     def get_headers() -> Dict[str, str]:
+        """
+        Load HTTP headers configuration from a JSON file.
+
+        Returns:
+            Dict[str, str]: Dictionary of HTTP headers for AoC API requests.
+
+        Note:
+            Expects a file named `aoc_headers.json` in the project root directory.
+        """
         headers = {}
         path = File.get_path()
         headers_config_path = os.path.realpath(f"{path}/aoc_headers.json")
@@ -46,6 +79,19 @@ def get_headers() -> Dict[str, str]:
 
     @staticmethod
     def download_puzzle_input(day: int) -> str:
+        """
+        Download the puzzle input for a specific day from Advent of Code.
+
+        Args:
+            day (int): The day number (1-25) of the puzzle.
+
+        Returns:
+            str: The puzzle input content.
+
+        Note:
+            Requires valid session token and headers configuration.
+            Year is determined from the project directory name.
+        """
         session = File.get_session()
         year = File.get_path().split(os.sep)[-1].split("-")[-1]
 
@@ -65,6 +111,20 @@ def download_puzzle_input(day: int) -> str:
 
     @staticmethod
     def download_test_input(day: int, part_num: int) -> str | None:
+        """
+        Download test input from the puzzle description for a specific day and part.
+
+        Args:
+            day (int): The day number (1-25) of the puzzle.
+            part_num (int): The puzzle part number (1 or 2).
+
+        Returns:
+            str | None: The test input content if found, `None` if download fails.
+
+        Note:
+            Extracts test input from code blocks in the puzzle description.
+            Part number determines which code block to use.
+        """
         session = File.get_session()
         year = File.get_path().split(os.sep)[-1].split("-")[-1]
 
@@ -91,6 +151,20 @@ def download_test_input(day: int, part_num: int) -> str | None:
 
     @staticmethod
     def add_day(day: int) -> None:
+        """
+        Set up the file structure for a new puzzle day.
+
+        Creates solution file from template and downloads puzzle input when available.
+        Waits for puzzle unlock time (5:00 UTC) if necessary.
+
+        Args:
+            day (int): The day number (1-25) to set up.
+
+        Note:
+            Creates following structure:
+            - `solutions/dayXX.py` (from template)
+            - `data/dayXX/puzzle_input.txt`
+        """
         path = File.get_path()
         solution = os.path.realpath(f"{path}/solutions/day{day:02}.py")
         solution_path = Path(solution)
@@ -141,6 +215,19 @@ def add_day(day: int) -> None:
 
     @staticmethod
     def add_test_input(day: int, part_num: int) -> None:
+        """
+        Set up and download test input for a specific puzzle part.
+
+        Creates test input file and downloads content when available.
+        Waits for puzzle unlock time (5:00 UTC) if necessary.
+
+        Args:
+            day (int): The day number (1-25) of the puzzle.
+            part_num (int): The puzzle part number (1 or 2).
+
+        Note:
+            Creates file at: `data/dayXX/test_XX_input.txt`
+        """
         path = File.get_path()
         folder = os.path.realpath(f"{path}/data/day{day:02}")
         folder_path = Path(folder)
@@ -179,6 +266,19 @@ def add_test_input(day: int, part_num: int) -> None:
 
     @staticmethod
     def add_test_file(day: int) -> None:
+        """
+        Create a test file for a specific puzzle day from template.
+
+        Args:
+            day (int): The day number (1-25) to create test file for.
+
+        Note:
+            Creates test file at: `tests/test_XX.py` using template from `templates/tests/sample.txt`
+            Replaces placeholders in template with actual day number.
+
+        Raises:
+            FileNotFoundError: If the template file is not found.
+        """
         path = File.get_path()
         test = os.path.realpath(f"{path}/tests/test_{day:02}.py")
 
@@ -197,7 +297,6 @@ def add_test_file(day: int) -> None:
             if content:
                 logger.info("Content loaded successfully")
 
-            # Replace placeholders with actual values
             content = content.format(day=day)
             with open(test, "w+") as f:
                 f.write(content)

aoc/models/reader.py

@@ -4,10 +4,28 @@
 
 
 class Reader:
+    """
+    Utility class for reading Advent of Code puzzle and test input files.
+
+    This class handles file reading operations with support for both raw and stripped
+    input formats. It maintains consistent file path handling relative to the project root.
+
+    Attributes:
+        PROJECT_ROOT (str): Absolute path to the project root directory, determined from
+            the `aoc` package location.
+    """
+
     PROJECT_ROOT = os.path.dirname(os.path.abspath(__file__).rsplit("aoc", 1)[0])
 
     @staticmethod
     def get_path() -> str:
+        """
+        Get the absolute path to the script's location.
+
+        Returns:
+            str: Absolute path to either the directory containing the script or
+                the script's directory if it is itself a directory.
+        """
         return (
             path
             if os.path.isdir(path := os.path.realpath(sys.argv[0]))
@@ -16,6 +34,20 @@ def get_path() -> str:
 
     @staticmethod
     def get_puzzle_input(day: int, is_raw: bool) -> List[str]:
+        """
+        Read in the puzzle input file for a specific day.
+
+        Args:
+            day (int): The day number (1-25) of the puzzle.
+            is_raw (bool): If True, preserves newlines. If False, strips all whitespace.
+
+        Returns:
+            List[str]: List of input lines, processed according to `is_raw` flag.
+
+        Note:
+            Expects input file at: `data/dayXX/puzzle_input.txt`
+            where `XX` is the zero-padded day number.
+        """
         file_path = os.path.join(
             Reader.PROJECT_ROOT, f"data/day{day:02d}/puzzle_input.txt"
         )
@@ -27,6 +59,21 @@ def get_puzzle_input(day: int, is_raw: bool) -> List[str]:
 
     @staticmethod
     def get_test_input(day: int, is_raw: bool, part_num: int) -> List[str]:
+        """
+        Read the test input file for a specific day and puzzle part.
+
+        Args:
+            day (int): The day number (1-25) of the puzzle.
+            is_raw (bool): If `True`, preserves newlines. If `False`, strips all whitespace.
+            part_num (int): The puzzle part number (1 or 2).
+
+        Returns:
+            List[str]: List of test input lines, processed according to `is_raw` flag.
+
+        Note:
+            Expects input file at: `data/dayXX/test_YY_input.txt`
+            where `XX` is the zero-padded day number and `YY` is the zero-padded part number.
+        """
         file_path = os.path.join(
             Reader.PROJECT_ROOT, f"data/day{day:02d}/test_{part_num:02d}_input.txt"
         )