Metadata-Version: 2.4
Name: aoc_mod
Version: 0.2.4
Summary: A library for Advent of Code containing utilities to use while solving problems!
License-File: LICENSE
Author: David Eyrich
Requires-Python: >=3.11
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Requires-Dist: bandit (>=1.8.6,<2.0.0)
Requires-Dist: beautifulsoup4 (>=4.14.2,<5.0.0)
Requires-Dist: markdownify
Requires-Dist: myst-parser (>=4.0.1,<5.0.0)
Requires-Dist: pytest (>=8.4.2,<9.0.0)
Requires-Dist: requests
Requires-Dist: requests-html (>=0.10.0,<0.11.0)
Requires-Dist: sphinx (>=8.2.3,<9.0.0)
Requires-Dist: sphinx-autoapi (>=3.6.1,<4.0.0)
Requires-Dist: sphinxcontrib-programoutput (>=0.18,<0.19)
Project-URL: Homepage, https://aoc-mod.readthedocs.io/en/latest/
Project-URL: Repository, https://github.com/cosmos1255/aoc_mod
Project-URL: changelog, https://github.com/cosmos1255/aoc_mod/blob/main/CHANGELOG.md
Project-URL: issues, https://github.com/cosmos1255/aoc_mod/issues
Description-Content-Type: text/markdown

# Advent of Code Module

[![aoc-mod](https://github.com/cosmos1255/aoc_mod/actions/workflows/build_wheel.yml/badge.svg)](https://github.com/cosmos1255/aoc_mod/actions/workflows/build_wheel.yml)

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](https://www.reddit.com/r/adventofcode/wiki/faqs/automation). 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`

```sh
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](#getting-and-using-the-session_id)).

```sh
# 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`.

```sh
# 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.

```sh
# install the library
poetry install

# build a wheel
poetry build

# run the tests
poetry run pytest
```

Formatting and linting is also available through `ruff`.

```sh
# 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`.

```sh
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:

```bash
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).**