Mathew Sir Guest the best
84e7639bf1
Address code review: the previous uv venv + uv pip + uv run sequence could run pytest in a different environment than the matrix Python. Use a single uv run --python ... --with . --with pytest invocation (mirrors noxfile). Also correct the stale Black target-version note in CLAUDE.md. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2.8 KiB
CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
Project Overview
SmileyFace is a Python CLI tool for automating Unreal Tournament 4 (UT4) server administration. It handles building local server instances from custom maps/mutators/configs, deploying them to remote game and redirect servers via rsync/SSH, and managing server lifecycle (start/stop/restart).
Commands
# Install dependencies
poetry install
# Run the tool
python smileyface.py --help
# Format code
black smileyface/
isort --profile black --filter-files smileyface/
# Lint
flake8 smileyface/
# Run pre-commit hooks manually
pre-commit run --all-files
# Run the smoke-test suite on the current interpreter
uv run --with . --with pytest pytest -v
# Run the full Python version matrix (3.8-3.13)
uv run --with nox nox -s tests
Smoke tests live in tests/ (import, CLI --help, and settings checks) and run across the supported Python 3.8-3.13 matrix via nox.
Code Style
- Black formatter: 120 char line length, targets Python 3.8–3.13
- isort: profile black, multi_line_output=3, trailing commas, force_grid_wrap=3
- flake8: 120 char max, ignores E121/E123/E126/E226/E24/E704/W605
Architecture
The app uses Click for CLI dispatch, pydantic-settings for configuration, and stdlib logging for log management.
Entry point: smileyface.py (project root) imports smileyface.start_app() which invokes the Click CLI.
Configuration: AppSettings (settings.py) is a pydantic BaseSettings model. Config is loaded from environment variables (prefix SMILEYFACE_) or a .env file. See .env.example for all available settings.
Context: AppContext (context.py) holds the settings instance and a dict-like log accessor. Passed to all command classes as ctx.
CLI: cli.py defines Click commands that instantiate the context and delegate to class methods.
Key classes:
UT4ServerMachine(hub_machine.py) - Core logic. Each CLI subcommand (generate_instance, upload_server, upload_redirects, etc.) is a method here. This is the largest and most important file.DataLayer(datalayer/datalayer.py) - Lazy SQLite3 connection wrapper.DbFuncs(datalayer/db_ops.py) - Database operations for tracking pak file state (MD5 sums, validation).GameIniSpecial(gameconfig_edit.py) - Generates redirect references in Game.ini for custom pak files.
Deployment flow: oneclickdeploy chains generate_instance -> upload_redirects -> upload_server. The generate step builds a local instance directory with the server binary, configs, maps, and mutators. Upload steps rsync to remote hosts.
Scraping module (scrape_latest/) uses Selenium to scrape pak file listings from ut4pugs.us and utcc.unrealpugs.com for MD5 validation against local files.