This package distributes a library named moorsalin-aoc2023 that exposes a module named aoc and an executable named moorsalin-aoc that, given a day and input, will provide the solution.

moorsalin-aoc 3 my_input.txt

This project is designed to be compatible with a comparative benchmarking pipeline, which explains some of the layout and design decisions.

For comparative benchmarking this also provides an executable named moorsalin-aoc-bench that does not rely on click but is less robust (not relying on click cuts down startup time).

1. python >=3.10, <3.13 (3.12 preferred) (recommended install via pyenv or equivalent)
2. poetry >=1.5.1 or compatible (recommended install via pipx)
3. Optionally just for convenience commands
4. Optionally docker

This project is managed by poetry, so the environment is set up by running poetry install, and packages are managed via poetry update and poetry lock. The poetry.lock should be checked in, as this repo distributes an executable.

You can switch into the context of the created virtualenv by running poetry shell.

Solutions for a given day should be exposed by a module with name day<formatted number>, where <formatted number> is a zero-padded (width 2) integer corresponding to the day (e.g. day05 or day15). The zero-padding is mainly to maintain a sorted ordering visually. These modules should exist directly under the top-level aoc directory (the project module).

Inputs should follow the same naming convention, with inputs located under the top-level inputs directory with the names day01.txt, day01_example.txt, day02.txt, etc.

Tests have no naming restrictions, and are located under the top-level tests directory.

You can either copy the templates and create the input placeholders by yourself, or you can run one of the following. By default, the template that generated this project also generated the day 1 placeholder module/tests/inputs.

# without just
./scripts/new.sh DAY  # where DAY is 1-25

# with just
just new DAY

# with plain poetry
poetry run moorsalin-aoc DAY PATH_TO_INPUT

# with poetry shell activated (or if you just installed the distribution)
moorsalin-aoc DAY PATH_TO_INPUT

# example
moorsalin-aoc 2 inputs/day02.txt

For information on how the CLI works see aoc/cli.py.

Test cases are marked with @pytest.mark.example, @pytest.mark.real, and @pytest.mark.bench to indicate if they are tests against example input, real inputs, or benchmarks, respectively. Tests can be selected or filtered using the normal pytest arguments.

The reason tests are marked differently is to allow for faster test runs while developing by excluding known-slow tests like tests against real inputs and benchmarks.

Filesystem watching support is provided with pytest-watcher.

Benchmark support is provided with pytest-benchmark.

# with plain poetry
poetry run pytest tests --benchmark-group-by=name

# with poetry shell activated
pytest tests --benchmark-group-by=name

# with just
just all

# with plain poetry
poetry run pytest tests -m "not bench and not real"

# with poetry shell activated
pytest tests -m "not bench and not real"

# with just
just unit

# with plain poetry
poetry run pytest tests -m "not bench"

# with poetry shell activated
pytest tests -m "not bench"

# with just
just test

# with plain poetry
poetry run pytest tests -m "bench" --benchmark-group-by=name

# with poetry shell activated
pytest tests -m "bench" --benchmark-group-by=name

# with just
just bench

It's recommended not to run the testing loop with benchmarks and real-input tests because of the potential slowness, but you do you.

# with plain poetry
poetry run ptw . -m "not bench and not real"

# with poetry shell activated
ptw . -m "not bench and not real"

# with just
just watch