{"id":14405,"library":"advent-of-code","title":"Advent of Code Command-Line Helper","description":"The `advent-of-code` Python library provides a command-line tool (`aoc`) and a programmatic API for Advent of Code. It helps automate fetching inputs, scaffolding solutions, and submitting answers. While the PyPI package (version 2025.6.0) receives active updates, its officially linked GitHub repository (`https://github.com/fornwall/advent-of-code`) has been archived since November 2023. This creates a discrepancy where new PyPI versions are released without publicly updated source code. The library uses a year-ahead versioning scheme (e.g., 2025.x.x versions released in 2024).","status":"maintenance","version":"2025.6.0","language":"en","source_language":"en","source_url":"https://github.com/fornwall/advent-of-code","tags":["advent-of-code","cli","puzzle","automation","helper"],"install":[{"cmd":"pip install advent-of-code","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"note":"Directly import functions from the 'aoc.api' submodule for programmatic use.","wrong":"import aoc.download_input","symbol":"download_input","correct":"from aoc.api import download_input"},{"note":"The top-level 'advent_of_code' package does not directly expose helper functions; use 'aoc.api'.","wrong":"from advent_of_code import submit","symbol":"submit","correct":"from aoc.api import submit"}],"quickstart":{"code":"# 1. Install the library (if you haven't already)\n# pip install advent-of-code\n\n# 2. Set your Advent of Code session cookie as an environment variable.\n#    This is crucial for fetching inputs and submitting answers.\n#    Find your 'session' cookie in your browser's developer tools on adventofcode.com\n# export AOC_SESSION=\"YOUR_SESSION_COOKIE_HERE\"\n\n# 3. Initialize a directory for a specific year (e.g., 2023)\naoc init 2023\n\n# 4. Navigate into the year directory\ncd 2023\n\n# 5. Download input and create boilerplate for a specific day (e.g., Day 1)\naoc download 1\n\n# 6. Your solution code will be in a file like '01.py'. Edit it.\n\n# 7. Run your solution (e.g., for Day 1)\naoc run 1\n\n# 8. Submit your answer for Part 1 (replace <answer> with your actual result)\n# aoc submit 1 1 <answer>\n","lang":"bash","description":"The primary way to use `advent-of-code` is via its `aoc` command-line interface. This quickstart demonstrates how to set up a new year, fetch puzzle inputs, run your solutions, and submit answers, emphasizing the critical `AOC_SESSION` environment variable for authentication."},"warnings":[{"fix":"Be aware that the latest source code may not be publicly available. Consider exploring forks or alternative tools if source visibility is critical for your workflow.","message":"The official GitHub repository for `advent-of-code` (`fornwall/advent-of-code`) has been archived since November 2023. Despite this, the PyPI package continues to receive new versions, leading to a discrepancy where publicly available source code is outdated or missing for recent releases.","severity":"breaking","affected_versions":"2023.0.0 and above"},{"fix":"Set `export AOC_SESSION=\"<your_session_cookie>\"` in your shell environment. Find the 'session' cookie value from `adventofcode.com` in your browser's developer tools.","message":"The `AOC_SESSION` environment variable is mandatory for most `aoc` commands and API calls that interact with the Advent of Code website (e.g., `download`, `submit`). Without it, authentication errors will occur.","severity":"gotcha","affected_versions":"All"},{"fix":"Always initialize your project with `aoc init <year>` and download inputs with `aoc download <day>` within the year's directory to ensure the correct file structure.","message":"The library typically expects a specific directory structure (`<year>/<day_padded>.py`, `<year>/<day_padded>/input.txt`). Commands like `aoc run` and `aoc submit` rely on this structure, usually generated by `aoc init` and `aoc download`.","severity":"gotcha","affected_versions":"All"},{"fix":"Only fetch inputs once per day. If submitting, ensure your answer is correct before attempting multiple submissions. Review Advent of Code's puzzle rules and etiquette.","message":"Repeatedly fetching inputs or submitting incorrect answers too quickly can lead to rate limiting or temporary bans from Advent of Code. Use the tool responsibly.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Change your import statement to `import aoc` or `from aoc.api import ...`.","cause":"Attempting to import the library using the PyPI package name (`advent_of_code`) instead of its internal module name (`aoc`).","error":"ModuleNotFoundError: No module named 'advent_of_code'"},{"fix":"Set the `AOC_SESSION` environment variable with a valid session cookie from `adventofcode.com`. Refresh your browser to get a new cookie if it's expired.","cause":"The `AOC_SESSION` environment variable is either not set or contains an invalid/expired Advent of Code session cookie.","error":"AdventOfCodeError: A session cookie is required to access Advent of Code."},{"fix":"Use `from aoc.api import download_input` and then call `download_input(...)`.","cause":"Attempting to call `aoc.download(...)` directly. The download functionality is exposed via the `api` submodule.","error":"AttributeError: module 'aoc' has no attribute 'download'"},{"fix":"This is a warning, not an error preventing operation. If you need to re-download, delete the existing input file first (e.g., `rm <year>/<day>/input.txt`).","cause":"You tried to run `aoc download <day>` for a day for which input has already been successfully fetched and saved.","error":"Error: Input already downloaded for day X."}],"ecosystem":"pypi"}