Darren "Dazbo" Lester (derailed-dash) · aoc.just2good.co.uk · darrenlester.net · Dev.to (dazbo) · Medium (@dazbo)
I've been using Advent of Code for years to sharpen my Python skills — exploring modern standard-library features, benchmarking alternative algorithms, and turning thorny December puzzles into clean, documented code. Every walkthrough pairs runnable Python with plain-English explanations on aoc.just2good.co.uk, alongside a 48-chapter Python Journey curriculum covering reusable patterns, dynamic programming, range algebra, modular cycles, grid geometry, graphs, shortest paths, symbolic maths and integer optimisation, PEGs, and visualisations.
My hope is that this repository and companion site help you:
- Become more fluent and idiomatic in modern Python (
>=3.13). - Get unstuck on Advent of Code puzzles without staring at cryptic one-liners.
- Compare practical approaches — standalone
uv-managed CLI scripts, reusable grid/graph abstractions (src/aoc_common/), and cloud-runnable Jupyter Notebooks.
| Year | Progress | Format | Site Entry Point |
|---|---|---|---|
| 2026 | Upcoming (12 days) |
Python Scripts + Walkthroughs (Template v3) | 2026 Walkthroughs |
| 2025 | 12 / 12 (24 ★) |
Python Scripts + Walkthroughs | 2025 Walkthroughs |
| 2024 | 25 / 25 (50 ★) |
Jupyter Notebook + Google Colab | 2024 Notebook |
| 2023 | 25 / 25 (50 ★) |
Jupyter Notebook + Google Colab | 2023 Notebook |
| 2022 | 25 / 25 (50 ★) |
Python Scripts + Walkthroughs | 2022 Walkthroughs |
| 2021 | 25 / 25 (50 ★) |
Python Scripts + Walkthroughs | 2021 Walkthroughs |
| 2020 | 25 / 25 (50 ★) |
Python Scripts + Source Code Index | 2020 Code Index |
| 2018 | 6 / 25 |
Python Scripts + Walkthroughs | 2018 Walkthroughs |
| 2017 | 12 / 25 |
Jupyter Notebook + Google Colab | 2017 Notebook |
| 2016 | 25 / 25 (50 ★) |
Python Scripts + Walkthroughs | 2016 Walkthroughs |
| 2015 | 25 / 25 (50 ★) |
Python Scripts + Walkthroughs | 2015 Walkthroughs |
This software is shared as open source under the MIT Licence. If you use parts of it in your own solutions or fork it into your repository, I'd really appreciate an acknowledgement and a link back to this repo, aoc.just2good.co.uk, or darrenlester.net.
Created by Eric Wastl every December since 2015, Advent of Code releases a two-part programming puzzle each day. Part 1 sets up the challenge; Part 2 almost always scales up the problem until brute-force approaches break and better data structures, memoisation, or algorithms matter. Every past event stays online year-round, and you can solve them in any language you choose.
Traditionally (2015–2024) AoC ran for 25 days (50 ★ to save Christmas); from 2025 onwards, the event runs for 12 days (24 ★).
To run the solutions in this repository, you'll need the following:
- Python >=3.13
uv: Manages the virtual environment, Python runtime, and lockfile dependencies (pyproject.toml/uv.lock).- Jupyter: Installed via
--extra jupyterfor running the notebook-based solutions (.ipynbfiles). - Legacy (
2015–2024) Dependencies: Historical solutions that still importdazbo-commons/coloramaare supported via--extra legacy(included inmake install).
-
Clone the repository:
git clone https://github.com/derailed-dash/Advent-of-Code.git cd Advent-of-Code -
Create a virtual environment and install dependencies:
# Install project, dev tooling, Jupyter, and legacy (2015-2024) dependencies make install # runs: uv sync --dev --extra jupyter --extra legacy
-
Run solutions on built-in sample inputs (out of the box — no AoC session cookie or decryption key needed):
- Repository CLI (
aoc):uv run aoc list # Overview of all years, day counts, and Standalone/Jupyter format uv run aoc list 2025 # Inspect day scripts and sample/real input readiness for one year uv run aoc run 2018d07 -s # Run a Template v3 day in sample-only mode (no input.txt needed) uv run aoc run 2026 1 -s # Template v3 sample-only run (once 2026 is scaffolded) uv run aoc new-year 2026 --dry-run # Preview scaffolding d01..d12 from Template v3
- Python scripts directly:
uv run python src/AoC_2025/d01/d01.py
- Jupyter Notebooks: Open directly in VS Code or launch JupyterLab locally:
uv run jupyter lab
- Run offline lint, spellcheck, typecheck, and unit tests:
make check # runs codespell, ruff, pyright, and pytest src/tests
- Repository CLI (
-
Run with your own Advent of Code inputs (optional): My personal
input.txtfiles are encrypted in Git (per AoC's sharing policy). To use your own inputs instead:cp .env.template .env # Add your adventofcode.com 'session' cookie to AOC_SESSION_COOKIE make clean-inputs # Remove locked git-crypt input files (leaves samples & unlocked files intact) uv run aoc run 2025d01 # Downloads your personal input.txt and runs the solution
(Forking this repo? See Encrypting AoC Inputs with
git-crypt.)
Maintainer Multi-Machine Setup (git-crypt)
This repository uses two git-crypt mechanisms so private puzzle inputs and local credentials stay encrypted on GitHub:
- Direct filter (
input*.txt filter=git-crypt): Puzzle inputs (src/AoC_YYYY/dNN/input/input*.txt) are tracked directly in Git and transparently decrypted in the working tree once unlocked. - Parallel
.enctwins (*.enc filter=git-crypt): Local secrets and workspace skills (.env,docs/.env,.agents/skills/*/SKILL.md) stay gitignored in plaintext and synchronise via encrypted.enctwins managed bygit-crypt-helper.sh.
On a new machine (never run git-crypt init, which mints an incompatible key):
git-crypt unlock ~/localdev/git-crypt-keygit-crypt-helper.sh sync-from-encmake sync-secrets
Whenever you update .env, docs/.env, or .agents/skills/*/SKILL.md, re-encrypt its twin with git-crypt-helper.sh sync-to-enc <file> before committing. See docs/python/encrypting.md for the full git-crypt guide.
pyproject.toml exposes [project.scripts] aoc = "aoc_common.cli:main", implemented in src/aoc_common/cli.py. Invoke it from the repository root with uv run aoc <subcommand> ... (add --no-sync after uv run for instant startup once .venv is synced via make install).
| Command | Parameters & Flags | Purpose |
|---|---|---|
| Global | --root PATH |
Override auto-detected repository root (useful in scripts or tests) |
aoc list |
[YEAR] --json |
List every AoC_YYYY year with Completed/Total progress (e.g. 25/25, 12/25, 12/12) and solution format (Standalone (.py), Jupyter (.ipynb), or Both), or inspect dNN solved status, scripts, and boolean input/sample readiness for one YEAR (terminal output adds clickable OSC 8 hyperlinks on Year and Day columns pointing to the AoC event and problem pages; never reads input file contents) |
aoc fetch |
<TARGET> [DAY] (1, 01, d01, 20251, 202501, 2025d01, or 2025 1) --desc-only | --input-only --write-sample --sample-part {1,2} --sample-index N --force --dry-run --json |
Fetch the AoC problem page in memory (no temporary desc.html), rank <pre><code> sample candidates, optionally populate input/sample_input_part_N.txt via heuristic or --sample-index (overwriting 0-byte placeholders safely), and cache input/input.txt without exposing raw input data |
aoc run |
<TARGET> [DAY] (1, 01, d01, 20251, 202501, 2025d01, or 2025 1) -p/--part {1,2,all} -s/--sample-only --no-samples -d/--debug --json --script FILENAME |
Execute a puzzle script; runs Template v3 scripts in-process via run_puzzle and legacy scripts via subprocess (when only a day is passed, picks AOC_YEAR, else current year if src/AoC_<year> exists, else latest existing AoC_YYYY; auto-resolves single scripts in historical dNN_<slug> folders or prompts with --script when multiple variants exist) |
aoc new-year |
<YEAR> --days N (1–25, default 12) --dry-run --force --json |
Scaffold src/AoC_<YEAR>/d01..d<days> from Template v3 without overwriting existing scripts (unless --force) and without creating empty input.txt files |
aoc clean-inputs |
--dry-run --json |
Delete locked git-crypt input*.txt blobs under src/ so public cloners can fetch their own AoC inputs (leaves samples and unlocked files untouched) |
Individual Template v3 day scripts (such as src/template_folder/template.py) also accept the same -p/--part, -s/--sample-only, --no-samples, -d/--debug, and --json flags directly via uv run python ... (-s and --no-samples are mutually exclusive; --json emits clean JSON on stdout and routes Rich logs to stderr).
Makefile wraps the aoc CLI, offline quality checks, git-crypt status checks, and local Jekyll previews:
| Target / Script | Underlying Command | Example / Notes |
|---|---|---|
make help |
Built-in target help | make or make help |
make install |
uv sync --dev --extra jupyter --extra legacy |
Installs core, dev, Jupyter, and legacy 2015–2024 extras |
make list |
uv run aoc list ... |
make list, make list 2025, or make list YEAR=2025 |
make fetch |
uv run aoc fetch ... |
make fetch 202501, make fetch 2018d07, make fetch TARGET=2018d07, or make fetch 1 ARGS="--write-sample --desc-only" |
make run |
uv run aoc run ... |
make run 1, make run 2018d07, make run TARGET=2018d07, or make run YEAR=2026 DAY=1 ARGS="-s -d" (pass runner flags via ARGS="..." because make intercepts bare -s/-d) |
make new-year |
uv run aoc new-year ... |
make new-year 2026 or make new-year YEAR=2026 DAYS=25 (defaults to 12 days for 2025+) |
scripts/create_year.sh |
Standalone Bash fallback (sed scaffold) |
./scripts/create_year.sh 2026 |
make lint |
codespell -s, ruff check, pyright |
Read-only offline checks on active code and docs |
make fix |
codespell -w, ruff check --fix, ruff format |
Auto-fixes active modules (src/aoc_common, src/tests, src/template_folder) |
make test |
uv run pytest src/tests |
Offline unit test suite |
make check |
make lint + make test |
Full offline verification gate |
make sync-secrets |
git-crypt-helper.sh status |
Shows parallel .enc secret sync status (or git-crypt status -e) |
make docs |
cd docs && docker compose up |
Serves local Jekyll preview at http://127.0.0.1:4000 |
make docs-build |
cd docs && docker compose build |
Rebuilds Docker image after editing docs/Dockerfile or docs/Gemfile |
make docs-stop |
cd docs && docker compose down |
Stops and removes the local Jekyll container |
make clean-inputs |
uv run aoc clean-inputs ... |
make clean-inputs or make clean-inputs ARGS="--dry-run" (removes locked git-crypt input*.txt blobs only) |
make clean |
Cache cleanup | Removes .pytest_cache, .ruff_cache, __pycache__, and docs/_site |
A typical day follows a quick sample-first loop from scaffolding through walkthrough publication:
- Scaffold the year (once per event):
make new-year YEAR=2026 # defaults to 12 days for 2025+; pass DAYS=25 for legacy years - Ensure
AOC_SESSION_COOKIEis configured: Copy.env.templateto.envand paste yoursessioncookie (or restore viagit-crypt-helper.sh sync-from-enc; maintainers re-encrypt updates withgit-crypt-helper.sh sync-to-enc .env). - Fetch the puzzle and sample inputs:
Verify
make fetch 2026d01 ARGS="--write-sample" # or: uv run aoc fetch 2026d01 --json
input/sample_input_part_1.txtagainst the puzzle description, then enter the expected sample answer inPART1_SAMPLESin the day's script. - Iterate sample-first, solve, and verify:
make run 2026d01 ARGS="-s -d" # Part 1/2 against sample inputs with debug logging make run 2026d01 # Run against real input/input.txt (repeat for Part 2) make check # Confirm codespell, ruff, pyright, and pytest pass
- Author and preview the walkthrough: Create
docs/2026/1.md(addingmathjax: trueto frontmatter if using LaTeX maths), register the entry indocs/_data/navigation.yaml(anddocs/2026/index.mdwhere manual tables are used), preview locally athttp://127.0.0.1:4000viamake docs, and stop the server withmake docs-stop. (When using an AI coding agent in this repo, the.agents/skills/suite —aoc-problem-summary,aoc-solution-support,aoc-create-doc, andaoc-megathread-post— automates these steps.)
This repository is organised by year and solution type. I've taken two main approaches for my solutions:
For most years (e.g. 2015–2022, 2025+), the solutions are Python scripts accompanied by detailed Markdown walkthroughs published at aoc.just2good.co.uk.
- Code: Solution scripts (
.py) live undersrc/AoC_YYYY/dNN/. - Walkthroughs: Companion Markdown files (
.md) live underdocs/YYYY/, built with Jekyll.
For some years (e.g. 2023–2024), solutions use Jupyter Notebooks combining Python code and narrative walkthroughs in a single .ipynb file inside src/AoC_YYYY/.
| Path | Purpose |
|---|---|
docs/ |
Jekyll source for aoc.just2good.co.uk (Midnight AoC custom theme in docs/DESIGN.md, docs/YYYY/ walkthroughs, docs/python/ guides, _config.yml, docker-compose.yml) |
src/AoC_YYYY/ |
Solution folders (d01/..d12/ from 2025+, d01/..d25/ for 2015–2024), or .ipynb notebooks |
src/aoc_common/ |
Shared utility package (aoc_commons.py, runner.py, cli.py: Locations, get_aoc_locations, run_puzzle, Point, Point3D, Grid, algorithms, Rich logging) |
src/template_folder/ |
Starter Python script and Jupyter notebook templates (Template v3) |
src/tests/ |
Offline pytest / unittest suite for aoc_common, runner, and aoc CLI |
scripts/ |
Helper scripts such as create_year.sh |
.github/workflows/ |
CI checks (pr-checks.yml) and Gemini PR/issue workflows |
.agents/rules/ |
Model-triggered AoC retrieval rule (aoc-retrieval.md) |
.agents/skills/ |
Workspace AoC skills (aoc-problem-summary, aoc-solution-support, aoc-create-doc, aoc-megathread-post; SKILL.md.enc encrypted with git-crypt) |
Makefile |
Common targets (install, lint, fix, test, check, list, fetch, run, new-year, docs, docs-build, docs-stop, clean-inputs, clean, sync-secrets) |
pyproject.toml |
Project metadata, dependencies, ruff, codespell, and pyright configuration |
.env.template |
Template environment variables (PYTHONPATH=src, AOC_SESSION_COOKIE) |
AGENTS.md |
Repository guide for coding agents and automated reviewers |
TODO.md |
Project roadmap and improvement backlog |
Shared utilities live in src/aoc_common/aoc_commons.py and have zero dependency on dazbo-commons. Because pyproject.toml includes a [build-system] packaging src/aoc_common editably into .venv, both standalone Python scripts and local Jupyter notebooks import import aoc_common.aoc_commons as ac directly without setting PYTHONPATH=src (and cloud notebooks such as Google Colab install aoc_common straight from GitHub):
- Logging & Output:
setup_logging(configured withRichHandler,force=True, andstderr=Truesupport for--jsonmode),setup_file_logging, andtop_and_tail. - Paths & Input Retrieval:
Locations,get_aoc_locations(safe in both scripts via__file__and Jupyter/Colab notebooks without__file__),get_locations,get_aoc_session_cookie,is_git_crypt_locked,write_puzzle_input_file(with AoCUser-Agentheader enforcement and automatic replacement of lockedgit-cryptblobs), and in-memory HTML/sample parsersfetch_puzzle_pageandparse_puzzle_html. - Runner, Testing & Timing:
run_puzzle(Rich+argparseTemplate v3 CLI orchestration),check_samples(raisesAssertionErrorcleanly withoutsys.exit),validate,format_duration, and thetimercontext manager. - 2D/3D Geometry & Algorithms:
Point,Point3D(slots=True, orthogonal/all neighbours, Manhattan/Chebyshev/Euclidean distances),Vectors,VectorDicts, andGrid(from_text,grid[pt],pt in grid,find_first,find_one,flood_fill,copy,items), sparse point-cloud helpers (bounding_box,render_points), plusbinary_search,lower_bound,upper_bound,merge_intervals,get_factors, andto_base_n.
- 2021–2022 (
dazbo-commonson PyPI): Publisheddazbo-commons-pyas a general-purpose PyPI utility package providingcolorama-basedColouredFormatter/retrieve_console_logger,Locations/get_locations,top_and_tail, and.envloading (get_envs_from_file). - May–Sep 2023 (
type_defs.py→aoc_commons.py): Extracted AoC-specific helpers (Point,Vectors,Grid,binary_search,merge_intervals,to_base_n) into an in-repotype_defsmodule, renamed it toaoc_commons.py, and briefly trialled PyPI packaging before keeping it inside this repository. - May 2024–Oct 2025 (Dual
dc+acera): Scripts and the 2024 notebook imported bothdazbo_commons as dc(for general logging,Locations, andtop_and_tail) andaoc_common.aoc_commons as ac(for AoC geometry and puzzle retrieval). - Dec 2025–2026 (Consolidated
ac+Rich): Replacedcoloramalogging withRich(RichHandler), consolidatedLocations,load_dotenv(), andtop_and_tailback intoaoc_common, enabled editable packaging inpyproject.tomlso scripts and notebooks share a single import path, and moveddazbo-commonsandcoloramainto[project.optional-dependencies] legacysolely so untouched2015–2024solutions remain runnable.
Each solution validates sample inputs via aoc_common.validate (raising AssertionError on mismatch), while aoc_common itself is tested offline via:
uv run pytest src/testsThis repository includes a companion static website featuring walkthroughs, the Python Journey curriculum, and a custom Midnight AoC dark-first theme with persisted Daylight Light toggle (specified in docs/DESIGN.md).
- Website URL: https://aoc.just2good.co.uk/
- Technology: Static site built with Jekyll using custom
_layouts/,_sass/partials, anddocs/assets/js/site.js - Source & Authoring Guide:
docs/anddocs/readme.md - CI Build Check:
.github/workflows/pr-checks.ymlrunsbundle exec jekyll build --traceon pull requests and pushes
You can build and serve the documentation website locally using Docker:
make docs # runs: cd docs && docker compose up
make docs-build # rebuild image after editing docs/Dockerfile or docs/Gemfile
make docs-stop # stop and remove the containerThe site will be available at http://127.0.0.1:4000. If you need to supply JEKYLL_GITHUB_TOKEN, restore docs/.env via git-crypt-helper.sh sync-from-enc (check sync status with make sync-secrets) or copy docs/.env.template to docs/.env.
