2.6 KiB
Repository Guidelines
Project Structure & Module Organization
Source lives in src/audiobooksorter/: ingestion (ingest.py), sorting rules (sorter/series_rules.py), exporting (export.py), and the CLI (cli.py). Config defaults sit in config/, constants in constants.py, and shared logging in logging.py. Sample inputs for quick runs live in samples/. Test suites mirror the package under tests/, with fixtures in tests/conftest.py. Assets that do not execute (icons, mock exports) belong in assets/. Local library fixtures for manual checks live in testdata/.
Build, Test, and Development Commands
Use Python 3.11+. Set up a venv and install dev tooling:
python -m venv .venv && source .venv/bin/activate
python -m pip install --upgrade pip
pip install -e .[dev]
Preview ordering without writing files via python -m audiobooksorter.cli --library ./testdata --dry-run. Run against a JSON export with python -m audiobooksorter.cli --library ./samples/library.json --output ./sorted_library.json. Format and lint with ruff check --fix (plus ruff format if desired). Execute the suite using pytest -q (coverage gates are pre-configured).
Coding Style & Naming Conventions
Follow PEP 8 with 4-space indentation and type hints on public surfaces. Prefer descriptive module names (series_rules.py, ingest.py) and uppercase constants. Use dataclasses for structured audiobook records and the shared logger from logging.py to centralize verbosity control.
Testing Guidelines
Tests target pytest with coverage enforced at 90% (pytest --cov=audiobooksorter --cov-report=term-missing). Name files test_<unit>.py and tests test_<behavior>. Add regression cases whenever sorting order changes—especially around edge series, mixed narrators, or missing metadata—in both tests/ and testdata/ when a folder-based scenario is required.
Commit & Pull Request Guidelines
Commit messages follow the type(scope): summary pattern (e.g., feat(cli): add dry-run preview). Reference issues in bodies (Fixes #ID). Pull requests should include a clear description of user-facing changes, testing evidence (command output is fine), and any migration notes for library paths or naming rules. Request review for sorting rule tweaks to avoid regressions in existing shelves.
Security & Configuration Tips
Do not commit personal Audiobookshelf exports; anonymize anything checked into samples/ or testdata/. Keep secrets (.env, tokens) out of the repo and load them at runtime. Validate file paths before writing outputs to avoid clobbering a user’s library.