Skip to content

Commit 17356fc

Browse files
mbrickerdmbrickerd
committed
Updated README with uv and pre-commit
1 parent 69c11d8 commit 17356fc

File tree

1 file changed

+58
-99
lines changed

1 file changed

+58
-99
lines changed

‎README.md‎

Lines changed: 58 additions & 99 deletions
Original file line numberDiff line numberDiff line change
@@ -6,101 +6,48 @@ Advent of Code is an Advent calendar of small programming puzzles for a variety
66

77
#### Clone the Repository:
88

9-
```
9+
```bash
1010
https://github.com/mbrickerd/advent-of-code-2024
1111
```
1212

1313
#### Install Dependencies:
1414

15-
Poetry is a tool for dependency management and packaging in Python. It allows you to declare the libraries your project depends on and it will manage (install/update) them for you. Poetry offers a lockfile to ensure repeatable installs, and can build your project for distribution.
16-
17-
For more information on how to install Poetry on your operating system, click [here](https://python-poetry.org/docs/#installation).
18-
19-
Once you have Poetry installed, run the following command from the root directory of this project:
20-
21-
```bash
22-
poetry install
23-
```
24-
25-
This command will also create a `.venv` virtual environment within your local project structure. Be sure to activate your newly created virtual environment before beginning with development with the appropriate command:
26-
27-
28-
| Platform | Shell | Command to activate virtual environment |
29-
|----------|-------------|--------------------------------------------------|
30-
| POSIX | bash/zsh | `$ source <venv>/bin/activate` |
31-
| | fish | `$ source <venv>/bin/activate.fish` |
32-
| | csh/tcsh | `$ source <venv>/bin/activate.csh` |
33-
| | PowerShell | `$ <venv>/bin/Activate.ps1` |
34-
| Windows | cmd.exe | `C:\> <venv>\Scripts\activate.bat` |
35-
| | PowerShell | `PS C:\> <venv>\Scripts\Activate.ps1` |
36-
37-
38-
If you need to add additional packages or libraries as you develop, run the following command to update the `pyproject.toml`:
39-
40-
```
41-
poetry add <package_name>
42-
```
43-
44-
## Advent of Code configuration
15+
This project uses `uv` for dependency management and `pre-commit` for maintaining code quality. Follow these steps to set up your development environment:
4516

46-
To interact directly with the Advent of Code platform (e.g., for downloading inputs or submitting answers), this framework requires two configuration files: `aoc_headers.json` and `aoc_session`. These files store essential metadata and session information necessary for authenticated requests.
17+
1. First, install `uv`:
4718

48-
#### `aoc_headers.json`
19+
**On Unix-like systems (Linux, macOS):**
20+
```bash
21+
curl -LsSf https://astral.sh/uv/install.sh | sh
22+
```
4923

50-
This file contains HTTP headers used for all requests made to the Advent of Code platform. The most important header is the User-Agent, which helps identify your automated requests to the Advent of Code servers.
24+
**On Windows:**
25+
```powershell
26+
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
27+
```
5128

52-
The User-Agent should follow this format:
53-
- Project name and version
54-
- URL to your project/GitHub repository (optional)
55-
- Your contact information (email or GitHub username)
29+
For more installation options, visit [uv's installation guide](https://github.com/astral-sh/uv).
5630

57-
Example content:
31+
2. Install project dependencies:
5832

59-
```json
60-
{
61-
"User-Agent": "AdventOfCodeHelper/1.0 ([email protected])"
62-
}
63-
```
64-
65-
OR
66-
67-
```json
68-
{
69-
"User-Agent": "AdventOfCodeHelper/1.0 (+https://example.com; [email protected])"
70-
}
71-
```
72-
73-
This ensures requests conform to the platform's API requirements and helps identify your script to the Advent of Code servers.
74-
75-
#### `aoc_session`
76-
77-
This file stores the session token obtained from the Advent of Code website after logging into your account. It is required for authentication and allows access to personalized inputs and submission capabilities.
78-
79-
To obtain your session token:
33+
```bash
34+
make install
35+
```
8036

81-
1. Log into [Advent of Code](https://adventofcode.com)
37+
This command will:
38+
- Install all project dependencies using `uv`
39+
- Set up pre-commit hooks for code quality
8240

83-
2. Open your browser's Developer Tools:
84-
- Chrome/Edge: Press F12 or Ctrl+Shift+I
85-
- Firefox: Press F12 or Ctrl+Shift+I
86-
- Safari: Enable 'Show Develop menu in menu bar' in Preferences > Advanced, then press Cmd+Option+I
41+
3. Individual development tools can be managed using make commands:
8742

88-
3. Navigate to:
89-
- Chrome/Edge: Application > Cookies > https://adventofcode.com
90-
- Firefox: Storage > Cookies
91-
- Safari: Storage > Cookies
92-
93-
4. Find the cookie named "session"
94-
95-
5. Copy its value into the `aoc_session` file
96-
97-
Example content:
98-
99-
```plaintext
100-
abc123yourlongsessiontokenhere
101-
```
102-
103-
This file provides authentication for downloading your unique puzzle inputs and submitting solutions under your account.
43+
```bash
44+
make help # Show all available commands
45+
make lint # Run ruff linting checks
46+
make format # Format code and organize imports
47+
make type-check # Run mypy type checking
48+
make test # Run pytest
49+
make all # Run format, lint, type-check, and test
50+
```
10451

10552
## Project structure
10653

@@ -115,31 +62,34 @@ This repository is a modular and efficient framework designed to manage and solv
11562
│ ├── __init__.py
11663
│ ├── models
11764
│ │ ├── __init__.py
118-
│ │ ├── base.py # Base class definitions for shared functionality
119-
│ │ ├── file.py # Handles file operations (e.g., input files, test files)
120-
│ │ ├── reader.py # Reads and parses input data for the solution
121-
│ │ ├── submission.py # Logic for submitting answers to AoC
122-
│ │ └── tester.py # Utilities for testing solutions
65+
│ │ ├── authenticator.py # Manages Advent of Code authentication credentials
66+
│ │ ├── base.py # Base class definitions for shared functionality
67+
│ │ ├── file.py # Handles file operations (e.g., input files, test files)
68+
│ │ ├── reader.py # Reads and parses input data for the solution
69+
│ │ ├── submission.py # Logic for submitting answers to AoC
70+
│ │ └── tester.py # Utilities for testing solutions
12371
│ └── utils
12472
│ ├── __init__.py
125-
│ └── initialise.py # Utilities for initializing daily solution files
73+
│ └── initialise.py # Utilities for initializing daily solution files
12674
├── solutions
127-
│ ├── day01.py # Example solution for Day 1
128-
│ └── day02.py # Example solution for Day 2
75+
│ ├── day01.py # Example solution for Day 1
76+
│ ├── day02.py # Example solution for Day 2
77+
│ └── ...
12978
├── templates
13079
│ ├── solutions
131-
│ │ └── sample.py # Template for new daily solution files
80+
│ │ └── sample.py # Template for new daily solution files
13281
│ └── tests
133-
│ └── sample.txt # Template for test cases
82+
│ └── sample.txt # Template for test cases
13483
├── tests
13584
│ ├── __init__.py
136-
│ ├── test_01.py # Tests for Day 1 solutions
137-
│ └── test_02.py # Tests for Day 2 solutions
85+
│ ├── test_01.py # Tests for Day 1 solutions
86+
│ ├── test_02.py # Tests for Day 2 solutions
87+
│ └── ...
13888
├── .gitignore
139-
├── main.py # Main script to manage tasks and run solutions
140-
├── Makefile
141-
├── poetry.lock
142-
├── pyproject.toml
89+
├── .pre-commit-config.yaml # Pre-commit hooks configuration
90+
├── main.py # Main script to manage tasks and run solutions
91+
├── Makefile # Development workflow automation
92+
├── pyproject.toml # Project dependencies and configuration
14393
└── README.md
14494
```
14595

@@ -154,7 +104,7 @@ This is the core package for the project. It includes:
154104

155105
#### `solutions/`
156106

157-
Contains the solution files for each day's challenge. Each file represents a self-contained solution where you implement logic for both parts of the day’s task.
107+
Contains the solution files for each day's challenge. Each file represents a self-contained solution where you implement logic for both parts of the day's task.
158108

159109
#### `templates/`
160110

@@ -178,10 +128,19 @@ The central script to perform various tasks such as:
178128

179129
Provides convenient commands for common development tasks:
180130
- Installing dependencies
181-
- Running code quality checks (black, isort, flake8)
131+
- Setting up pre-commit hooks
132+
- Running code quality checks (ruff, mypy)
182133
- Executing tests
183134
- Formatting code
184135

136+
#### `.pre-commit-config.yaml`
137+
138+
Configures pre-commit hooks that run automatically before each commit to ensure code quality:
139+
- Code formatting
140+
- Import sorting
141+
- Linting
142+
- Type checking
143+
185144
#### `.github/workflows/python-ci.yml`
186145

187146
GitHub Actions workflow configuration that automates:

0 commit comments

Comments
 (0)