How juestr/aoc-2024 works
Project Type and Purpose
• This is a collection of standalone Python scripts answering the daily puzzles for Advent of Code 2024.
• The purpose is to solve individual puzzles, each residing in its own file (e.g., aoc01.py through aoc25.py), using common utilities provided in aoc_util.py.
• The project also includes data files for inputs and expected results, along with utility scripts (e.g., download_input.sh) and configuration files (requirements.txt, xmas_tree.txt).
File Structure
• Top-level Python scripts: aoc01.py through aoc25.py (with one alternate version aoc04_first.py) represent the individual puzzle solutions.
• aoc_util.py provides shared functionality (command line parsing, common implementations, boilerplate) for running these standalone scripts.
• The "data" directory holds input files (e.g., aoc01_input.txt) and corresponding result files (aoc01_input.txt.results) for each day’s puzzle.
• Additional resources include configuration/metadata files (.gitignore, LICENSE, README.md), supporting scripts (download_input.sh), and extras like report.txt and xmas_tree.txt (a specific artifact from day 14).
• The project is fairly flat with all puzzles and related utilities in the root directory, indicating a modular design where each day’s logic is isolated in its own file.
README for Additional Insights
• README confirms that each day’s puzzle script can be run independently via the command line (and accepts options via --help).
• The README mentions that the puzzles were written in Python 3.13 and formatted with ruff.
• External dependencies are declared in requirements.txt.
• The mention of “xmas tree” implies there might be some interesting graphical or structured output for day 14.
a. Main Components:
• Command Line Runner & Utility Module: aoc_util.py acts as the entry point for instrumentation, argument parsing, and running each standalone puzzle.
• Puzzle Modules: Separate Python scripts (aoc01.py … aoc25.py) where each file implements the logic for that day’s puzzle.
• Data Storage: The “data” directory containing all input files and their corresponding results which the puzzle modules read.
• External Dependencies: Python 3.13 runtime environment, external packages (from requirements.txt), and possibly the Advent of Code website (for input downloads via download_input.sh).
• Auxiliary Scripts and Artifacts: download_input.sh for automating input download; report.txt and xmas_tree.txt as supplementary outputs/artifacts.
b. Relationships and Interactions:
• The Command Line Runner (via aoc_util.py) dynamically selects and triggers one of the individual puzzle scripts based on user input.
• Each Puzzle Module:
• Reads its corresponding input files from the “data” directory.
• Writes/uses result files (e.g., “aocXX_input.txt.results”) to validate/compare outputs.
• The download_input.sh script potentially interfaces with the Advent of Code website to fetch the latest puzzles’ input files.
• The system uses external dependencies and libraries as defined in requirements.txt.
c. Architectural Patterns and Design Principles:
• Separation of concerns: Each puzzle’s logic is encapsulated in its own module, while shared functionalities are abstracted into aoc_util.py.
• Modular design: The file structure supports independent development and testing of each day’s puzzle.
• Extensibility: New days/puzzles can be added as additional Python scripts without major refactoring.
• Simplicity and clarity: The flat structure and standardized naming facilitate straightforward mapping from the problem domain (Advent of Code puzzles) into code components.
d. Relevant Technologies:
• Python 3.13, ruff (for code formatting), and possibly common Python libraries listed in requirements.txt.
• The command-line interface, typical file I/O operations, and Unix shell scripting (download_input.sh).