aoc-mod 0.2.5

A library for Advent of Code containing utilities to use while solving problems!

Advent of Code Module

A library for Advent of Code containing utilities to use while solving problems!

If any issues or bugs are discovered, please submit an issue and I'll fix it!

Automation notice for Advent of Code

This library follows the automation guidelines on the /r/adventofcode community wiki. Specifically:

• A maximum of 2 outbound calls will be made for each run of the aoc-mod setup and submission features.
• There will be a 2 minute timeout between setup and submission requests.
• Once puzzle input and instructions are retrieved for a given puzzle day, they will be stored locally and then not pulled again for that day.
• The User Agent contains a link to this repository and my GitHub username. I am the sole maintainer of this library.

Install and use the CLI aoc-mod

pip install aoc-mod

Run the aoc-mod script

To enable full functionality of this script, set an environment variable named SESSION_ID with your authenticated session ID from the browser (see getting and using the session ID).

# access the help menu
aoc-mod -h

# optional: set the session ID to enable full functionality
# on Linux:
export SESSION_ID=[session-id]
# on Windows:
set SESSION_ID=[session-id]

# get puzzle instructions and set up a Python file for solving for the current day
aoc-mod setup

# setup the project for a specific day
aoc-mod -y 2024 -d 2 setup

# submit a challenge (2024, day 2, part A)
aoc-mod -y 2024 -d 2 submit -a [answer] -p 1

Installation with Poetry for development

The build system has been updated to utilize poetry for installation, building, and dependency management. To install/build locally, install the poetry build system through pipx.

# install pipx
sudo apt install pipx

# install poetry
pipx install poetry

Once poetry is installed, the following commands can be used to install, build, and run unit tests locally.

# install the library
poetry install

# build a wheel
poetry build

# run the tests
poetry run pytest

Formatting and linting is also available through ruff.

# run a linter check
poetry run ruff check

# run a linter check and correct issues
poetry run ruff check --fix

# format the code
poetry run ruff format

Some vulnerability scanning is also available with bandit.

poetry run bandit -c pyproject.toml -r .

Documentation

The documentation is managed and built using Sphinx through the Poetry build system. To build the documentation and open it, run the following commands:

poetry run sphinx-build -M html docs/source/ docs/build/
firefox docs/build/html/index.html

Getting and Using the SESSION_ID

The SESSION_ID is necessary to perform advanced operations like getting puzzle input and submitting puzzle answers. Without this variable, the only operations available are getting basic puzzle instructions and setting up a solution template file.

Feature	session-id	no session-id
Get puzzle instructions	full support	partial support
Get puzzle input	full support	no support
Submit puzzle solutions	full support	no support
Setup puzzle solution folder	full support	full support

In order to obtain this variable, authenticate with https://adventofcode.com and then press F12 in the browser and navigate to the Application or Storage Tabs, if they exist, and search the cookies for the session or sessionid value.

NOTE: The session id value is a unique key for your own authenticated session with Advent of Code. You should protect it like a password and never share it (i.e. never push a session id to GitHub or store in an insecure location).