AGENTS.md

Agent Guidelines

Build & Development

• Uses Nix flakes: nix develop for dev shell, nix build for building
• Install deps: uv pip install -e . (uv available in dev shell)
• Run server: sendspin-server or python -m sendspin_pulseaudio.server
• Type check: basedpyright sendspin_pulseaudio/
• Lint: ruff check sendspin_pulseaudio/
• No tests exist in this project yet

Code Style

• Python 3.12+, async/await patterns throughout
• Type annotations required on all functions (enforced by ruff ANN rules)
• Use | union syntax (e.g., str | None), not Optional
• Imports: stdlib first, then third-party, then local (relative imports for package)
• Naming: snake_case for functions/variables, PascalCase for classes
• Private members prefixed with _
• Use dataclasses for data structures (see PulseSink in pulse.py)
• Error handling: use logger.exception() in except blocks, don't re-raise unless needed
• Docstrings: module-level and class/method docstrings with Args/Returns sections
• Logging: use module-level logger = logging.getLogger(__name__)
• Constants: UPPER_SNAKE_CASE at module level