elf 0.1dev__tar.gz → 1.1.0__tar.gz

elf-1.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 snally-labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

elf-1.1.0/PKG-INFO

@@ -0,0 +1,477 @@
+Metadata-Version: 2.4
+Name: elf
+Version: 1.1.0
+Summary: Advent of Code helper for Python: fetch and cache inputs, submit answers, and pull private leaderboards.
+Author-email: cak <cak@typeerror.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/cak/elf
+Project-URL: Documentation, https://github.com/cak/elf/
+Project-URL: Repository, https://github.com/cak/elf
+Project-URL: Issue-Tracker, https://github.com/cak/elf/issues
+Keywords: advent of code,aoc,cli,python,puzzles
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Games/Entertainment :: Puzzle Games
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: beautifulsoup4>=4.14.2
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pydantic>=2.12.4
+Requires-Dist: rich>=14.2.0
+Requires-Dist: typer>=0.20.0
+Dynamic: license-file
+
+# elf: Advent of Code helper for Python
+
+<p align="center">
+  <img src="https://snally.com/assets/elf-logo.png" width="200" alt="elf logo">
+</p>
+
+A fast, modern Advent of Code CLI with caching, guardrails, leaderboards, and a lightweight Python API.
+
+Works on macOS, Linux, and Windows. Most networked commands require an AoC session cookie (`AOC_SESSION`).
+
+<p align="center">
+  <img src="https://img.shields.io/pypi/v/elf.svg">
+  <img src="https://img.shields.io/badge/License-MIT-success.svg">
+  <img src="https://img.shields.io/badge/Advent%20of%20Code-Ready-00cc66">
+  <img src="https://img.shields.io/badge/North%20Pole%20API-Compliant-blue">
+</p>
+
+## Why I Built This
+
+Advent of Code has become one of my favorite Christmas traditions. I am never the fastest solver, and some puzzles definitely keep me humble, but the challenges always spark new ideas and mark the start of the holiday season for me.
+
+Thank you to **Eric Wastl**, the creator of [Advent of Code](https://adventofcode.com/). His work brings an incredible community together every December and inspires people around the world to learn, explore new ideas, and enjoy the fun of programming puzzles.
+
+After refining a small helper tool I have used personally for the past few years, I decided to turn it into a package others can benefit from as well. I originally built an early version for my own workflows in [my personal AoC repo](https://github.com/cak/advent-of-code/tree/dc9c02a5a77a36b725a8e01cff18a6de46e0db0d?tab=readme-ov-file#%EF%B8%8F-automating-tasks-with-the-elf-cli).
+
+If Advent of Code is part of your December ritual too, I hope this little elf makes the journey smoother, more fun, and a bit more magical.
+
+## Highlights
+
+- Fetch inputs instantly with **automatic caching**
+- Submit answers safely with **smart guardrails** (duplicate, low, high, locked, cooldown)
+- Explore private leaderboards as **tables**, **JSON**, or **Pydantic models**
+- View your **status calendar** (table, JSON, or model)
+- Inspect your **guess history** with timestamps and per-part details
+- Open any AoC page (puzzle, input, or website) straight from the CLI
+- Use elf as a **CLI tool** or a full **Python API**
+
+## Installation
+
+### Using uv (recommended)
+
+#### Install as a tool
+
+```sh
+uv tool install elf
+```
+
+#### Inside a project
+
+```sh
+uv add elf
+```
+
+### Using pip
+
+```sh
+pip install elf
+```
+
+### Requirements
+
+- Python 3.11 or newer
+- An Advent of Code account
+- `AOC_SESSION` cookie set in your environment for most commands
+
+## Configure your AoC Session
+
+Most features in elf require your Advent of Code session cookie so the CLI can access your personal puzzle inputs and progress.
+
+To get it:
+
+1. Log in to https://adventofcode.com using GitHub, Google, or Reddit.
+2. Open your browser’s developer tools.
+   - Chrome: View → Developer → Developer Tools
+   - Firefox: Tools → Browser Tools → Web Developer Tools
+3. Go to the **Application** (Chrome) or **Storage** (Firefox) tab.
+4. Look for **Cookies** for the domain `adventofcode.com`.
+5. Find the cookie named **`session`**.
+6. Copy the value (a long hex string).
+7. Set it as an environment variable:
+
+```sh
+export AOC_SESSION="your-session-token"
+```
+
+On Windows you can persist the cookie with PowerShell:
+
+```powershell
+$env:AOC_SESSION = "your-session-token"
+setx AOC_SESSION "your-session-token"
+```
+
+Or via CMD:
+
+```cmd
+setx AOC_SESSION "your-session-token"
+```
+
+Most commands require this. You can also pass it via `--session` in the CLI or `session=` in the API.
+
+### Your User-Agent (Recommended)
+
+Elf follows the guidance from Eric Wastl (creator of Advent of Code) to help keep traffic friendly to the site.
+
+If you run tools that make automated requests, you should provide contact information in your User-Agent header so Eric can reach you if something goes wrong with your traffic. This is optional but strongly recommended.
+
+Set your email address in the environment variable `AOC_USER_AGENT`:
+
+```sh
+export AOC_USER_AGENT="you@example.com"
+Windows PowerShell:
+$env:AOC_USER_AGENT = "you@example.com"
+setx AOC_USER_AGENT "you@example.com"
+```
+
+If this variable is not set or does not look like an email address, elf falls back to a safe default and prints a warning.
+Your User-Agent header will look like:
+elf/<version> (you@example.com)
+This helps Eric identify the person sending the traffic while still including the library name.
+
+If the warning fires, elf instead sends `elf/<version> (+https://github.com/cak/elf)` so AoC still sees a recognizable identifier even without your email.
+
+## Quick Start
+
+```sh
+export AOC_SESSION="your-session-token"
+
+elf input        # fetch today's input
+elf answer 2025 1 1 123 # submit answer for part 1
+elf status       # view progress
+elf leaderboard 2025 123456 --view-key ABCDEF
+```
+
+### Saving puzzle input to files
+
+If you prefer to keep your own local copies of puzzle inputs, elf works just like a regular Unix command. You can redirect the output to save any day's input:
+
+```sh
+elf input > input.txt              # save today's input
+elf input 2025 2 > day02.txt       # save a specific day's input
+```
+
+## CLI Documentation
+
+### `elf --help`
+
+```sh
+Usage: elf [OPTIONS] COMMAND [ARGS]...
+
+Advent of Code CLI
+
+Options:
+  --version, -V
+  --debug
+  --install-completion
+  --show-completion
+  --help
+
+Commands:
+  input        Fetch the input for a given year/day
+  answer       Submit an answer
+  leaderboard  Fetch/display a private leaderboard
+  guesses      Show cached guesses
+  status       Show yearly star status
+  open         Open puzzle/input/website
+  cache        Show cache information
+```
+
+Enable detailed tracebacks with `--debug` or `ELF_DEBUG=1` when troubleshooting.
+
+---
+
+## Commands
+
+### `elf input`
+
+Fetch puzzle input with caching. Requires a session cookie.
+
+```sh
+Usage: elf input [YEAR] [DAY]
+
+Options:
+  --session TEXT   AOC session cookie (env: AOC_SESSION)
+```
+
+Defaults:
+
+- `year`: current year
+- `day`: current day in December, otherwise 1 (Dec 1)
+- Caches to `~/.cache/elf/<year>/<day>/input.txt` (or platform equivalent)
+
+### `elf answer`
+
+Submit an answer with safety guardrails. Requires a session cookie. Guardrails use your local guess cache to short-circuit duplicate answers and infer too-high/too-low for integer guesses.
+
+```sh
+Usage: elf answer YEAR DAY PART ANSWER
+
+Options:
+  --session TEXT  AOC session cookie
+```
+
+Behaviors:
+
+- Year and day are required to avoid accidental submissions.
+- Detects locked puzzles (future days or future years) and shows unlock timestamp.
+- Identifies too high / too low / duplicate guesses from local cache
+- Caches cooldown responses locally for ~60 seconds to avoid hammering the site
+- Writes to guess cache automatically (per part)
+
+Exit codes:
+
+- `0` when the answer is correct or already completed on AoC
+- `2` when AoC rate-limits you (cooldown/WAIT)
+- `1` for incorrect/too-high/too-low/unknown guesses
+
+Duplicate guesses reuse cached submissions, so the exit code follows the cached result: e.g., a cached correct/completed guess still exits `0`, while cached incorrect/high/low responses return `1`.
+
+Example errors:
+
+```sh
+❄️ Puzzle YYYY‑MM‑DD not unlocked yet
+1234 is not correct.
+You submitted an answer recently. Please wait...
+12345 is correct. Star awarded.
+```
+
+### `elf guesses`
+
+Display local guess history (per part). Requires a cached `guesses.csv` from previous submissions. Displays all guesses for both parts automatically.
+
+```sh
+Usage: elf guesses [YEAR] [DAY]
+```
+
+Example table:
+
+```sh
+Time (UTC)      Guess  Status
+2025‑12‑05 ...  959    too_low
+2025‑12‑05 ...  6951   correct
+```
+
+### `elf leaderboard`
+
+Fetch private leaderboards. Provide a view key for read-only access or a session cookie for authenticated access. A view key is the read-only share token you can generate on your AoC leaderboard page.
+
+```sh
+Usage: elf leaderboard YEAR BOARD_ID
+
+Options:
+  --view-key TEXT
+  --session TEXT
+  --format table|json|model
+```
+
+Supports:
+
+- **table:** pretty Rich table
+- **json:** raw JSON
+- **model:** structured Pydantic model
+
+### `elf status`
+
+View your Advent of Code star calendar. Requires a session cookie.
+
+```sh
+Usage: elf status [YEAR]
+
+Options:
+  --session TEXT
+  --format table|json|model
+```
+
+Defaults:
+
+- `year`: current year if omitted
+
+Prints stars for each day.
+
+### `elf open`
+
+Opens puzzle pages in your browser.
+
+```sh
+Usage: elf open [YEAR] [DAY]
+
+Options:
+  --kind puzzle|input|website
+```
+
+### `elf cache`
+
+Display cache directory information.
+
+```sh
+Usage: elf cache
+```
+
+Shows:
+
+- Cache root directory (platform-aware)
+- Number of cached files
+- Reminder to delete the directory manually to clear cache
+
+---
+
+## Caching Behavior
+
+- Default cache dir: macOS/Linux `~/.cache/elf`, Windows `%LOCALAPPDATA%\elf`
+- Override location with `ELF_CACHE_DIR` (respects `XDG_CACHE_HOME` on Linux)
+- Inputs stored under: `<cache>/<year>/<day>/input.txt`
+- Guess history stored as `<cache>/<year>/<day>/guesses.csv`
+- Duplicate/high/low guesses are short‑circuited locally when possible
+- Cooldown responses are cached locally for ~60 seconds to avoid hammering AoC
+- Guardrails rely on your local guess history only (new machines/cleared cache = fresh)
+- Delete the cache directory to clear everything
+
+### Concurrency note
+
+The library reuses a process-global `httpx.Client` to keep CLI calls fast. For heavy multi-threaded usage, create separate `elf.aoc_client.AOCClient` instances per thread to avoid sharing the global session.
+
+---
+
+## Library Usage
+
+```python
+from elf import (
+    get_puzzle_input,
+    submit_puzzle_answer,
+    get_private_leaderboard,
+    get_user_status,
+    OutputFormat,
+)
+
+# AOC_SESSION is used automatically if not passed explicitly
+input_text = get_puzzle_input(2023, 5)
+
+result = submit_puzzle_answer(2023, 5, 1, "12345")
+print(result.is_correct, result.message)
+
+leaderboard = get_private_leaderboard(
+    2023, session=None, board_id=123456, view_key=None, fmt=OutputFormat.MODEL
+)
+
+status = get_user_status(2023, fmt=OutputFormat.TABLE)
+print(status)
+```
+
+### Puzzle Helpers
+
+`elf.helpers` includes some small utilities you can use in your own AoC solutions:
+
+```python
+from elf.helpers import parse_input, read_test_input, timer
+```
+
+### Leaderboard Example
+
+```sh
+❯ elf leaderboard 2025 3913340
+              Advent of Code 2025 – Private Leaderboard
+┏━━━━━━┳━━━━━━━━━━━━━━━━┳━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━┓
+┃ Rank ┃ Name           ┃ Stars ┃ Local Score ┃ Last Star (UTC)     ┃
+┡━━━━━━╇━━━━━━━━━━━━━━━━╇━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━┩
+│    1 │ User A         │    45 │         900 │ 2025-12-26 00:53:17 │
+│    2 │ User B         │    45 │         855 │ 2025-12-26 00:53:56 │
+│    3 │ User C         │    36 │         622 │ 2025-12-26 03:29:21 │
+└──────┴────────────────┴───────┴─────────────┴─────────────────────┘
+```
+
+JSON format:
+
+```sh
+elf leaderboard 2025 3982840 --format json
+```
+
+Model format (Pydantic):
+
+```python
+lb = get_private_leaderboard(2025, board_id=3982840, fmt=OutputFormat.MODEL)
+members = sorted(lb.members.values(), key=lambda m: (-m.local_score, -m.stars))
+print(members[0].name, members[0].stars)
+```
+
+### Status Example
+
+```sh
+❯ elf status 2023
+Advent of Code
+  2023 – cak
+(AoC++) [34⭐]
+┏━━━━━┳━━━━━━━┓
+┃ Day ┃ Stars ┃
+┡━━━━━╇━━━━━━━┩
+│   1 │  ★★   │
+│   2 │  ★★   │
+│   3 │  ★★   │
+│   4 │  ★☆   │
+│   5 │  ★☆   │
+│   6 │  ★★   │
+│   7 │  ★★   │
+│   8 │  ★☆   │
+│   9 │  ☆☆   │
+│  10 │  ☆☆   │
+│  .. │  ..   │
+│  25 │  ☆☆   │
+└─────┴───────┘
+```
+
+JSON format:
+
+```sh
+elf status 2023 --format json
+```
+
+Model format:
+
+```python
+status = get_user_status(2023, fmt=OutputFormat.MODEL)
+print(status.days[0].day, status.days[0].stars)
+```
+
+---
+
+## Development / Testing
+
+Run the test suite via:
+
+```sh
+uv run pytest
+```
+
+Alternatively, you can still run:
+
+```sh
+python -m pytest
+```
+
+Running `python -m pytest` directly requires `pytest` to be installed in your environment. Install it via `pip install pytest>=9.0.1` (or use `uv run pytest` / `pip install .[dev]` if you maintain the dev extras) before running the command outside of `uv`.
+
+## Special Thanks
+
+This project exists thanks to the generosity and creativity of others.
+
+Thanks to **Solos** for donating the `elf` PyPI name.